# Print citations (if any)
verbose_source = (
    True  # Change to True to display the contents of a source
)
if response.message.citations:
    print("CITATIONS:\n")
    for citation in response.message.citations:
        print(
            f"Start: {citation.start}| End:{citation.end}| Text:'{citation.text}' "
        )
        print("Sources:")
        for idx, source in enumerate(citation.sources):
            print(f"{idx+1}. {source.id}")
            if verbose_source:
                print(f"{source.tool_output}")
        print("\n")
```

The model first determines that it needs to find out the capital city of Brazil. Once it has this information, it proceeds with the next step in the sequence, which is to look up the temperature of that city.

This is reflected in the model's response, where two tool calling-result pairs are generated in a sequence.

Example response:

```mdx wordWrap
TOOL PLAN:
First, I will search for the capital city of Brazil. Then, I will search for the temperature in that city. 

TOOL CALLS:
Tool name: get_capital_city | Parameters: {"country":"Brazil"}
==================================================
TOOL RESULT:
[{'capital_city': {'brazil': 'brasilia'}}]
TOOL PLAN:
I have found that the capital city of Brazil is Brasilia. Now, I will search for the temperature in Brasilia. 

TOOL CALLS:
Tool name: get_weather | Parameters: {"location":"Brasilia"}
==================================================
TOOL RESULT:
[{'temperature': {'brasilia': '28°C'}}]
RESPONSE:
The temperature in Brasilia, the capital city of Brazil, is 28°C.
==================================================
CITATIONS:

Start: 60| End:65| Text:'28°C.' 
Sources:
1. get_weather_p0dage9q1nv4:0
{'temperature': '{"brasilia":"28°C"}'}
```

**State management**

In a multi-step tool use scenario, instead of just one occurence of `assistant`-`tool` messages, there will be a sequence of `assistant`-`tool` messages to reflect the multiple steps of tool calling involved.

```mermaid
%%{init: {'htmlLabels': true}}%%
flowchart TD
    classDef defaultStyle fill:#fff,stroke:#000,color:#000;

    A["<div style='color:black;'><b>USER</b><br />Query</div>"]
    B1["<div style='color:black;'><b>ASSISTANT</b><br />Tool call step #1</div>"]
    C1["<div style='color:black;'><b>TOOL</b><br />Tool result step #1</div>"]
    B2["<div style='color:black;'><b>ASSISTANT</b><br />Tool call step #2</div>"]
    C2["<div style='color:black;'><b>TOOL</b><br />Tool result step #2</div>"]
    BN["<div style='color:black;'><b>ASSISTANT</b><br />Tool call step #N</div>"]
    CN["<div style='color:black;'><b>TOOL</b><br />Tool result step #N</div>"]
    D["<div style='color:black;'><b>ASSISTANT</b><br />Response</div>"]

    A -.-> B1
    B1 -.-> C1
    C1 -.-> B2
    B2 -.-> C2
    C2 -.-> BN
    BN -.-> CN
    CN -.-> D

    class A,B1,C1,B2,C2,BN,CN,D defaultStyle;
```

## Forcing tool usage

<Note>
  This feature is only compatible with the 

  [Command R7B](https://docs.cohere.com/v2/docs/command-r7b)

   and newer models.
</Note>

As shown in the previous examples, during the tool calling step, the model may decide to either:

* make tool call(s)
* or, respond to a user message directly.

You can, however, force the model to choose one of these options. This is done via the `tool_choice` parameter.

* You can force the model to make tool call(s), i.e. to not respond directly, by setting the `tool_choice` parameter to `REQUIRED`.
* Alternatively, you can force the model to respond directly, i.e. to not make tool call(s), by setting the `tool_choice` parameter to `NONE`.

By default, if you don’t specify the `tool_choice` parameter, then it is up to the model to decide whether to make tool calls or respond directly.

```python PYTHON {5}
response = co.chat(
    model="command-a-03-2025",
    messages=messages,
    tools=tools,
    tool_choice="REQUIRED" # optional, to force tool calls
    # tool_choice="NONE" # optional, to force a direct response
)
```

**State management**

Here's the sequence of messages when `tool_choice` is set to `REQUIRED`.

```mermaid
%%{init: {'htmlLabels': true}}%%
flowchart TD
    classDef defaultStyle fill:#fff,stroke:#000,color:#000;

    A["<div><b>USER</b><br />Query</div>"]
    B["<div><b>ASSISTANT</b><br />Tool call</div>"]
    C["<div><b>TOOL</b><br />Tool result</div>"]
    D["<div><b>ASSISTANT</b><br />Response</div>"]

    A -.-> B
    B -.-> C
    C -.-> D

    class A,B,C,D defaultStyle;
```

Here's the sequence of messages when `tool_choice` is set to `NONE`.

```mermaid
%%{init: {'htmlLabels': true}}%%
flowchart TD
    classDef defaultStyle fill:#fff,stroke:#000,color:#000;

    A["<div><b>USER</b><br />Query</div>"]
    B["<div><b>ASSISTANT</b><br />Response</div>"]

    A -.-> B

    class A,B defaultStyle;
```

## Chatbots (multi-turn)

Building chatbots requires maintaining the memory or state of a conversation over multiple turns. To do this, we can keep appending each turn of a conversation to the `messages` list.

As an example, here's the messages list from the first turn of a conversation.

```python PYTHON
from cohere import ToolCallV2, ToolCallV2Function

messages = [
    {"role": "user", "content": "What's the weather in Toronto?"},
    {
        "role": "assistant",
        "tool_plan": "I will search for the weather in Toronto.",
        "tool_calls": [
            ToolCallV2(
                id="get_weather_1byjy32y4hvq",
                type="function",
                function=ToolCallV2Function(
                    name="get_weather",
                    arguments='{"location":"Toronto"}',
                ),
            )
        ],
    },
    {
        "role": "tool",
        "tool_call_id": "get_weather_1byjy32y4hvq",
        "content": [
            {
                "type": "document",
                "document": {"data": '{"temperature": "20C"}'},
            }
        ],
    },
    {"role": "assistant", "content": "It's 20°C in Toronto."},
]
```

Then, in the second turn, when provided with a rather vague follow-up user message, the model correctly infers that the context is about the weather.

<CodeBlocks>
  ```python PYTHON
  messages.append({"role": "user", "content": "What about London?"})

  response = co.chat(
      model="command-a-03-2025", messages=messages, tools=tools
  )

  if response.message.tool_calls:
      messages.append(response.message)
      print(response.message.tool_plan, "\n")
      print(response.message.tool_calls)
  ```

  ```bash cURL
  curl --request POST \
    --url https://api.cohere.ai/v2/chat \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header "Authorization: bearer $CO_API_KEY" \
    --data '{
    "model": "command-a-03-2025",
    "messages": [
      {
        "role": "user",
        "content": "What'\''s the weather in Toronto?"
      },
      {
        "role": "assistant",
        "tool_plan": "I will search for the weather in Toronto.",
        "tool_calls": [
          {
            "id": "get_weather_1byjy32y4hvq",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\":\"Toronto\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "get_weather_1byjy32y4hvq",
        "content": [
          {
            "type": "document",
            "document": {
              "data": "{\"temperature\": \"20C\"}"
            }
          }
        ]
      },
      {
        "role": "assistant",
        "content": "It'\''s 20°C in Toronto."
      },
      {
        "role": "user",
        "content": "What about London?"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "gets the weather of a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "the location to get the weather, example: San Francisco."
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'
  ```
</CodeBlocks>

Example response:

```mdx wordWrap
I will search for the weather in London. 

[ToolCallV2(id='get_weather_8hwpm7d4wr14', type='function', function=ToolCallV2Function(name='get_weather', arguments='{"location":"London"}'))]
```

**State management**

The sequence of messages is represented in the diagram below.

```mermaid
%%{init: {'htmlLabels': true}}%%
flowchart TD
    classDef defaultStyle fill:#fff,stroke:#000,color:#000;

    A["<div><b>USER</b><br />Query - turn #1</div>"]
    B["<div><b>ASSISTANT</b><br />Tool call - turn #1</div>"]
    C["<div><b>TOOL</b><br />Tool result - turn #1</div>"]
    D["<div><b>ASSISTANT</b><br />Response - turn #1</div>"]
    E["<div><b>USER</b><br />Query - turn #2</div>"]
    F["<div><b>ASSISTANT</b><br />Tool call - turn #2</div>"]
    G["<div><b>TOOL</b><br />Tool result - turn #2</div>"]
    H["<div><b>ASSISTANT</b><br />Response - turn #2</div>"]
    I["<div><b>USER</b><br />...</div>"]

    A -.-> B
    B -.-> C
    C -.-> D
    D -.-> E
    E -.-> F
    F -.-> G
    G -.-> H
    H -.-> I

    class A,B,C,D,E,F,G,H,I defaultStyle;
```