Basic usage of tool use (function calling) ↗

import json

import cohere


def search_docs(query: str, top_k: int = 3):
    # Implement your retrieval logic here (vector DB, keyword search, etc.)
    # For simplicity, we'll return a few hardcoded "documents".
    return [
        {
            "title": "Cohere API v2 - Chat",
            "url": "https://docs.cohere.com/reference/chat",
            "text": "Use the Chat endpoint to generate responses and optionally call tools.",
        },
        {
            "title": "Tool use (function calling) overview",
            "url": "https://docs.cohere.com/v2/docs/tool-use-overview",
            "text": "Tool use connects models to external tools like search engines and APIs.",
        },
        {
            "title": "Structured outputs",
            "url": "https://docs.cohere.com/docs/structured-outputs",
            "text": "Use JSON schema to define structured inputs/outputs for tools and responses.",
        },
    ][:top_k]


functions_map = {"search_docs": search_docs}

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search documentation and return relevant snippets as documents.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query to look up in the docs.",
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "How many documents to return.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

co = cohere.ClientV2("COHERE_API_KEY")

# Step 1: user message
messages = [
    {
        "role": "user",
        "content": "How does tool use work in Cohere? Please cite your sources.",
    }
]

# Step 2: model generates tool calls
response = co.chat(
    model="command-a-03-2025", messages=messages, tools=tools
)

if response.message.tool_calls:
    messages.append(response.message)

    # Step 3: application executes tools and sends tool results back
    for tc in response.message.tool_calls:
        tool_result = functions_map[tc.function.name](
            **json.loads(tc.function.arguments)
        )

        tool_content = []
        for data in tool_result:
            tool_content.append(
                {
                    "type": "document",
                    "document": {"data": json.dumps(data)},
                }
            )

        messages.append(
            {
                "role": "tool",
                "tool_call_id": tc.id,
                "content": tool_content,
            }
        )

# Step 4: model generates a response grounded in tool results (with citations)
response = co.chat(
    model="command-a-03-2025", messages=messages, tools=tools
)

print(response.message.content[0].text)
print(response.message.citations)

    # ! pip install -U cohere
    import cohere

    co = cohere.ClientV2(
        "COHERE_API_KEY"
    )  # Get your free API key here: https://dashboard.cohere.com/api-keys
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Private deployment"></span>
```python
    # ! pip install -U cohere
    import cohere

    co = cohere.ClientV2(
        api_key="",  # Leave this blank
        base_url="<YOUR_DEPLOYMENT_URL>",
    )
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

## Tool definition

Before we can run a tool use workflow, we have to define the tools. We can break this process into two steps:

* Creating the tool
* Defining the tool schema

### Creating the tool

A tool can be any function that you create or external services that return an object for a given input. Some examples:

* A web search engine
* An email service
* A SQL database
* A vector database
* A documentation search service
* A sports data service
* Another LLM.

In this walkthrough, we define a `search_docs` function that returns relevant documentation snippets for a given query. You can implement any retrieval logic here, but to simplify, we'll return a few hardcoded documents.

```python
def search_docs(query, top_k=3):
    # Implement any retrieval logic here (vector DB, keyword search, etc.)
    return [
        {
            "title": "Tool use (function calling) overview",
            "url": "https://docs.cohere.com/v2/docs/tool-use-overview",
            "text": "Tool use connects models to external tools like search engines and APIs.",
        },
        {
            "title": "Chat API reference (v2)",
            "url": "https://docs.cohere.com/reference/chat",
            "text": "Use the Chat endpoint to generate responses and optionally call tools.",
        },
        {
            "title": "Structured outputs",
            "url": "https://docs.cohere.com/docs/structured-outputs",
            "text": "Use JSON schema to define structured inputs/outputs for tools and responses.",
        },
    ][:top_k]
    # Return a string or a list of objects. In Step 3 below, we'll wrap each object into a `document`
    # content block so the model can cite specific tool results.


functions_map = {"search_docs": search_docs}

# Example: String
docs_search_results = "Tool use connects models to external tools like search engines and APIs."

# Example: List of objects
docs_search_results = [
    {
        "title": "Tool use (function calling) overview",
        "url": "https://docs.cohere.com/v2/docs/tool-use-overview",
        "text": "Tool use connects models to external tools like search engines and APIs.",
    },
    {
        "title": "Structured outputs",
        "url": "https://docs.cohere.com/docs/structured-outputs",
        "text": "Use JSON schema to define structured inputs/outputs for tools and responses.",
    },
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search documentation and return relevant snippets as documents.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query to look up in the docs.",
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "How many documents to return.",
                    },
                },
                "required": ["query"],
            },
        },
    },
]

messages = [
    {
        "role": "user",
        "content": "How does tool use work in Cohere? Please cite your sources.",
    }
]

    messages = [
        {
            "role": "user",
            "content": "Find docs about tool use and structured outputs.",
        },
        {
            "role": "assistant",
            "tool_plan": "I will search the docs for tool use and structured outputs.",
            "tool_calls": [
                ToolCallV2(
                    id="search_docs_dkf0akqdazjb",
                    type="function",
                    function=ToolCallV2Function(
                        name="search_docs",
                        arguments='{"query":"tool use","top_k":3}',
                    ),
                ),
                ToolCallV2(
                    id="search_docs_gh65bt2tcdy1",
                    type="function",
                    function=ToolCallV2Function(
                        name="search_docs",
                        arguments='{"query":"structured outputs","top_k":3}',
                    ),
                ),
            ],
        },
    ]
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Plain dictionaries"></span>
```python
    messages = [
        {
            "role": "user",
            "content": "Find docs about tool use and structured outputs.",
        },
        {
            "role": "assistant",
            "tool_plan": "I will search the docs for tool use and structured outputs.",
            "tool_calls": [
                {
                    "id": "search_docs_dkf0akqdazjb",
                    "type": "function",
                    "function": {
                        "name": "search_docs",
                        "arguments": '{"query":"tool use","top_k":3}',
                    },
                },
                {
                    "id": "search_docs_gh65bt2tcdy1",
                    "type": "function",
                    "function": {
                        "name": "search_docs",
                        "arguments": '{"query":"structured outputs","top_k":3}',
                    },
                },
            ],
        },
    ]
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

<AccordionGroup>
  <Accordion title="Directly responding">
The model can decide to *not* make any tool call, and instead, respond to a user message directly. This is described [here](https://docs.cohere.com/docs/tool-use-usage-patterns#directly-answering).
  </Accordion>

  <Accordion title="Parallel tool calling">
The model can determine that more than one tool call is required. This can be calling the same tool multiple times or different tools for any number of calls. This is described [here](https://docs.cohere.com/docs/tool-use-usage-patterns#parallel-tool-calling).
  </Accordion>
</AccordionGroup>

### Step 3: Get tool results

During this step, the actual function calling happens. We call the necessary tools based on the tool call payloads given by the endpoint.

For each tool call, we append the `messages` list with:

* the `tool_call_id` generated in the previous step.
* the `content` of each tool result with the following fields:
  * `type` which is `document`
  * `document` containing
* `data`: which stores the contents of the tool result.
* `id` (optional): you can provide each document with a unique ID for use in citations, otherwise auto-generated

```python
import json

if response.message.tool_calls:
    for tc in response.message.tool_calls:
        tool_result = functions_map[tc.function.name](
            **json.loads(tc.function.arguments)
        )
        tool_content = []
        for data in tool_result:
            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
            tool_content.append(
                {
                    "type": "document",
                    "document": {"data": json.dumps(data)},
                }
            )
        messages.append(
            {
                "role": "tool",
                "tool_call_id": tc.id,
                "content": tool_content,
            }
        )

print(response.message.citations)

for message in messages:
    print(message, "\n")

{   
    "role": "user", 
    "content": "How does tool use work in Cohere? Please cite your sources."
}

{
    "role": "assistant",
    "tool_plan": "I will search the docs for how tool use works in Cohere.",
    "tool_calls": [
        ToolCallV2(
            id="search_docs_1byjy32y4hvq",
            type="function",
            function=ToolCallV2Function(
                name="search_docs", arguments='{"query":"tool use Cohere","top_k":3}'
            ),
        )
    ],
}

{
    "role": "tool",
    "tool_call_id": "search_docs_1byjy32y4hvq",
    "content": [{"type": "document", "document": {"data": "{\"title\":\"Tool use (function calling) overview\",\"url\":\"https://docs.cohere.com/v2/docs/tool-use-overview\",\"text\":\"Tool use connects models to external tools like search engines and APIs.\"}"}}],
}

{   
    "role": "assistant", 
    "content": "Tool use lets models call external tools (like doc search) and then answer using the tool results, with citations."
}