Usage patterns for tool use (function calling)

1
def search_docs(query, top_k=3):
2
    # Implement any retrieval logic here (vector DB, keyword search, etc.)
3
    return [
4
        {
5
            "title": "Tool use (function calling) overview",
6
            "url": "https://docs.cohere.com/v2/docs/tool-use-overview",
7
            "text": "Tool use connects models to external tools like search engines and APIs.",
8
        },
9
        {
10
            "title": "Structured outputs",
11
            "url": "https://docs.cohere.com/docs/structured-outputs",
12
            "text": "Use JSON schema to define structured inputs/outputs for tools and responses.",
13
        },
14
        {
15
            "title": "Chat API reference (v2)",
16
            "url": "https://docs.cohere.com/reference/chat",
17
            "text": "Use the Chat endpoint to generate responses and optionally call tools.",
18
        },
19
    ][:top_k]
20
    # Return a string or a list of objects. In Step 3, we'll wrap each object into a `document` content block.
21
22
23
functions_map = {"search_docs": search_docs}
24
25
tools = [
26
    {
27
        "type": "function",
28
        "function": {
29
            "name": "search_docs",
30
            "description": "Search documentation and return relevant snippets as documents.",
31
            "parameters": {
32
                "type": "object",
33
                "properties": {
34
                    "query": {
35
                        "type": "string",
36
                        "description": "The search query to look up in the docs.",
37
                    },
38
                    "top_k": {
39
                        "type": "integer",
40
                        "description": "How many documents to return.",
41
                    },
42
                },
43
                "required": ["query"],
44
            },
45
        },
46
    },
47
]

1
import json
2
3
if response.message.tool_calls:
4
    for tc in response.message.tool_calls:
5
        tool_result = functions_map[tc.function.name](
6
            **json.loads(tc.function.arguments)
7
        )
8
        tool_content = []
9
        for data in tool_result:
10
            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
11
            tool_content.append(
12
                {
13
                    "type": "document",
14
                    "document": {"data": json.dumps(data)},
15
                }
16
            )
17
        messages.append(
18
            {
19
                "role": "tool",
20
                "tool_call_id": tc.id,
21
                "content": tool_content,
22
            }
23
        )

1
def search_docs(query, top_k=3):
2
    # Implement any retrieval logic here (vector DB, keyword search, etc.)
3
    return [
4
        {
5
            "title": "Tool use (function calling) overview",
6
            "url": "https://docs.cohere.com/v2/docs/tool-use-overview",
7
            "text": "Tool use connects models to external tools like search engines and APIs.",
8
        },
9
        {
10
            "title": "Usage patterns for tool use",
11
            "url": "https://docs.cohere.com/v2/docs/tool-use-usage-patterns",
12
            "text": "Common patterns include parallel tool calling, multi-step tool use, and more.",
13
        },
14
        {
15
            "title": "Structured outputs",
16
            "url": "https://docs.cohere.com/docs/structured-outputs",
17
            "text": "Use JSON schema to define structured inputs/outputs for tools and responses.",
18
        },
19
    ][:top_k]
20
21
22
functions_map = {"search_docs": search_docs}

1
tools = [
2
    {
3
        "type": "function",
4
        "function": {
5
            "name": "search_docs",
6
            "description": "Search documentation and return relevant snippets as documents.",
7
            "parameters": {
8
                "type": "object",
9
                "properties": {
10
                    "query": {
11
                        "type": "string",
12
                        "description": "The search query to look up in the docs.",
13
                    },
14
                    "top_k": {
15
                        "type": "integer",
16
                        "description": "How many documents to return.",
17
                    },
18
                },
19
                "required": ["query"],
20
            },
21
        },
22
    },
23
]

1
import json
2
3
# Step 1: Get the user message
4
messages = [
5
    {
6
        "role": "user",
7
        "content": "Explain how tool use works and how to force tool usage. Please cite your sources.",
8
    }
9
]
10
11
# Step 2: Generate tool calls (if any)
12
model = "command-a-plus-05-2026"
13
response = co.chat(
14
    model=model, messages=messages, tools=tools, temperature=0.3
15
)
16
17
while response.message.tool_calls:
18
    print("TOOL PLAN:")
19
    print(response.message.tool_plan, "\n")
20
    print("TOOL CALLS:")
21
    for tc in response.message.tool_calls:
22
        print(
23
            f"Tool name: {tc.function.name} | Parameters: {tc.function.arguments}"
24
        )
25
    print("=" * 50)
26
27
    messages.append(response.message)
28
29
    # Step 3: Get tool results
30
    print("TOOL RESULT:")
31
    for tc in response.message.tool_calls:
32
        tool_result = functions_map[tc.function.name](
33
            **json.loads(tc.function.arguments)
34
        )
35
        tool_content = []
36
        print(tool_result)
37
        for data in tool_result:
38
            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
39
            tool_content.append(
40
                {
41
                    "type": "document",
42
                    "document": {"data": json.dumps(data)},
43
                }
44
            )
45
        messages.append(
46
            {
47
                "role": "tool",
48
                "tool_call_id": tc.id,
49
                "content": tool_content,
50
            }
51
        )
52
53
    # Step 4: Generate response and citations
54
    response = co.chat(
55
        model=model,
56
        messages=messages,
57
        tools=tools,
58
        temperature=0.1,
59
    )
60
61
messages.append(
62
    {
63
        "role": "assistant",
64
        "content": response.message.content[0].text,
65
    }
66
)
67
68
# Print final response
69
print("RESPONSE:")
70
print(response.message.content[0].text)
71
print("=" * 50)
72
73
# Print citations (if any)
74
verbose_source = (
75
    True  # Change to True to display the contents of a source
76
)
77
if response.message.citations:
78
    print("CITATIONS:\n")
79
    for citation in response.message.citations:
80
        print(
81
            f"Start: {citation.start}| End:{citation.end}| Text:'{citation.text}' "
82
        )
83
        print("Sources:")
84
        for idx, source in enumerate(citation.sources):
85
            print(f"{idx+1}. {source.id}")
86
            if verbose_source:
87
                print(f"{source.tool_output}")
88
        print("\n")

1
response = co.chat(
2
    model="command-a-plus-05-2026",
3
    messages=messages,
4
    tools=tools,
5
    tool_choice="REQUIRED" # optional, to force tool calls
6
    # tool_choice="NONE" # optional, to force a direct response
7
)

1
from cohere import ToolCallV2, ToolCallV2Function
2
3
messages = [
4
    {
5
        "role": "user",
6
        "content": "How does tool use work in Cohere? Please cite your sources.",
7
    },
8
    {
9
        "role": "assistant",
10
        "tool_plan": "I will search the docs for how tool use works in Cohere.",
11
        "tool_calls": [
12
            ToolCallV2(
13
                id="search_docs_1byjy32y4hvq",
14
                type="function",
15
                function=ToolCallV2Function(
16
                    name="search_docs",
17
                    arguments='{"query":"tool use Cohere","top_k":3}',
18
                ),
19
            )
20
        ],
21
    },
22
    {
23
        "role": "tool",
24
        "tool_call_id": "search_docs_1byjy32y4hvq",
25
        "content": [
26
            {
27
                "type": "document",
28
                "document": {
29
                    "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."}'
30
                },
31
            }
32
        ],
33
    },
34
    {
35
        "role": "assistant",
36
        "content": "Tool use lets models call external tools (like doc search) and then answer using tool results with citations.",
37
    },
38
]