This guide outlines the difference in model behavior for [single-step](https://docs.cohere.com/fern/pages/v2/tool-use/tool-use-overview.mdx#step-3---the-developer-can-then-execute-the-tool-calls) and [multi-step](https://docs.cohere.com/docs/tool-use-usage-patterns#multi-step-tool-use) tool use. This is a mode that can be toggled in the Chat API by providing `tools` and setting the `force_single_step` parameter.

## Single Step Tool Use

Single step tool use is enabled by setting `force_single_step=True` and providing a list of tools through the Chat API. This forces the model to make just _one_ set of tool calls, after which it will provide a final answer. In single-step tool use, the model cannot make a sequence of tool calls and reason over them.

Note that "single _step_" doesn't mean "single _tool_." In single-step tool use the model _can_ still call multiple tools by calling them in parallel. Whet this happens, the model will output multiple tool calls in the `tool_results` part of the response.

## When Should I Use Single-step Tool Use?

You should operate in single-step mode when you want the model to answer a question after one step. With a query like "Is there a reservation available at Johnny's Pizza or Alfredo's Pizza at 9PM," for example, the model would query the APIs for Johny's Pizza and Alfredo's Pizza, in parallel.

### Code example

For the sake of this illustration, we'll assume a developer is building a chatbot to assist with sales-related questions. The chatbot has access to two tools to answer user questions: a daily sales report tool which holds data on sales volumes, and a product catalog which contains information about each product being sold.

Here is a walkthrough of what a relevant single-step tool use workflow would look like.

#### Step 1

The developer provides the sales database and the products database to the model using the `tools` parameter.

Observe that, for each tool, the developer describes the tool name, description, and inputs. Each input can have a type and can be marked as required.

```python PYTHON
import cohere

co = cohere.Client(api_key="<YOUR API KEY>")

# tool descriptions that the model has access to
tools = [
    {
        "name": "query_daily_sales_report",
        "description": "Connects to a database to retrieve overall sales volumes and sales information for a given day.",
        "parameter_definitions": {
            "day": {
                "description": "Retrieves sales data for this day, formatted as YYYY-MM-DD.",
                "type": "str",
                "required": True,
            }
        },
    },
    {
        "name": "query_product_catalog",
        "description": "Connects to a a product catalog with information about all the products being sold, including categories, prices, and stock levels.",
        "parameter_definitions": {
            "category": {
                "description": "Retrieves product information data for all products in this category.",
                "type": "str",
                "required": True,
            }
        },
    },
]

# preamble containing instructions about the task and the desired style for the output.
preamble = """
## Task & Context
You help people answer their questions and other requests interactively. You will be asked a very wide array of requests on all kinds of topics. You will be equipped with a wide range of search engines or similar tools to help you, which you use to research your answer. You should focus on serving the user's needs as best you can, which will be wide-ranging.

## Style Guide
Unless the user asks for a different style of answer, you should answer in full sentences, using proper grammar and spelling.
"""

# user request
message = "Can you provide a sales summary for 29th September 2023, and also give me some details about the products in the 'Electronics' category, for example their prices and stock levels?"

response = co.chat(
    message=message,
    tools=tools,
    force_single_step=True,
    preamble=preamble,
    model="command-a-03-2025",
)
```

#### Step 2

The model's response contains the list of appropriate tools to call in order to answer the user's question, as well as the appropriate inputs for each tool call.

```python PYTHON
print("The model recommends doing the following tool calls:")
print("\n".join(str(tool_call) for tool_call in response.tool_calls))

# An example output:
# cohere.ToolCall {
#   name: query_daily_sales_report
#   parameters: {'day': '2023-09-29'}
#   generation_id: 4807c924-9003-4d6b-8069-eda03962c465
# }
# cohere.ToolCall {
#   name: query_product_catalog
#   parameters: {'category': 'Electronics'}
#   generation_id: 4807c924-9003-4d6b-8069-eda03962c465
# }
```

#### Step 3

Now, the developer will query the appropriate tools and receive a tool result in return.

```python PYTHON
tool_results = []
# Iterate over the tool calls generated by the model
for tool_call in response.tool_calls:
    # here is where you would call the tool recommended by the model, using the parameters recommended by the model
    output = functions_map[tool_call.name](**tool_call.parameters)
    # store the output in a list
    outputs = [output]
    # store your tool results in this format
    tool_results.append({"call": tool_call, "outputs": outputs})


print("Tool results that will be fed back to the model in step 4:")
print(json.dumps(tool_results, indent=4))
# Tool results that will be fed back to the model in step 4:
# [
#    {
#        "call": {
#            "name": "query_daily_sales_report",
#            "parameters": {
#                "day": "2023-09-29"
#            },
#            "generation_id": "4807c924-9003-4d6b-8069-eda03962c465"
#        },
#        "outputs": [
#            {
#                "date": "2023-09-29",
#                "summary": "Total Sales Amount: 10000, Total Units Sold: 250"
#            }
#        ]
#    },
#    {
#        "call": {
#            "name": "query_product_catalog",
#            "parameters": {
#                "category": "Electronics"
#            },
#            "generation_id": "4807c924-9003-4d6b-8069-eda03962c465"
#        },
#        "outputs": [
#            {
#                "category": "Electronics",
#                "products": [
#                    {
#                        "product_id": "E1001",
#                        "name": "Smartphone",
#                        "price": 500,
#                        "stock_level": 20
#                    },
#                    {
#                        "product_id": "E1002",
#                        "name": "Laptop",
#                        "price": 1000,
#                        "stock_level": 15
#                    },
#                    {
#                        "product_id": "E1003",
#                        "name": "Tablet",
#                        "price": 300,
#                        "stock_level": 25
#                    }
#                ]
#            }
#        ]
#    }
# ]
```

### Step 4

Call the chat endpoint again with the tool results to get the final model answer. Note that this is done through the `tool_results` parameter, with the other parameters operating as expected.

```python PYTHON
response = co.chat(
    message=message,
    tools=tools,
    tool_results=tool_results,
    preamble=preamble,
    model="command-a-03-2025",
    temperature=0.3,
)


print("Final answer:")
print(response.text)


# Final answer:
# On the 29th of September 2023, there were 250 units sold, with a total sales amount of 10,000.


# The Electronics category contains three products:
# - Smartphone: 500 (price), 20 (stock level)
# - Laptop: 1000 (price), 15 (stock level)
# - Tablet: 300 (price), 25 (stock level)
```

In this step, the model cites which tool results were used to generate the final model answer! These citations make it easy to check where the model’s generated response claims are coming from.

## When Should I Use Multi-step Tool Use?

For more complex queries, such as those that require multiple steps, it's probably better to operate in multi-step mode. You can do this by setting `enable_multistep=True` and providing a list of tools through the Chat API. In multi-step mode, the model can reason across steps and select multiple tools to answer a question completely.

To illustrate, imagine you give the Chat API a query like "What was the weather where I was yesterday," along with a location tool (to return the user’s location given a timestamp) and a weather tool (to return the weather at a given location). Here's what happens:

- First, the model will make a plan, which consists in first calling the location tool (step 1), and then calling the weather tool (step 2) based on the output of the location tool.
- Then, the model receives the results of these tool calls and the underlying model's reasoning.
- In a subsequent call, the model will determine that it still doesn’t have all the information required to answer, and select another tool.
- Etc.

In the next section, there's a code snippet demonstrating how to do this programmatically.

### Multi-step Code Examples

Here, we'll walk through a couple of different ways of using multi-step tool use in order to answer questions about the weather.

```bash
curl --location 'https://api.cohere.ai/v1/chat' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "model": "command-a-03-2025",
    "enable_multi_step": true,
    "message": "What was the weather where I was yesterday?",
    "tools": [
        {
            "name": "get_weather",
            "description": "Gets the weather for a given location",
            "parameter_definitions": {
                "location": {
                    "description": "The city and state, e.g. San Francisco, CA",
                    "type": "str",
                    "required": true
                }
            }
        },
        {
            "name": "get_location",
            "description": "Gets the users current location",
            "parameter_definitions": {
                "time": {
                    "description": "The date in format YYYY/MM/DD",
                    "type": "str"
                }
            }
        }
    ]
}'
```

In the response below, the model selects a tool _and_ returns a message containing its reasoning.

```bash
{
    "response_id": "6d6978b1-fdf7-4802-9b5d-953336466d8b",
    "text": "I will find the user's location and then use that to find the weather there yesterday.",
    "generation_id": "5c38b246-4f58-4ccf-b85d-09b25ad506fa",
    "chat_history": [
        {
            "role": "USER",
            "message": "What was the weather where I was yesterday?"
        },
        {
            "role": "CHATBOT",
            "message": "I will find the user's location and then use that to find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_location",
                    "parameters": {
                        "time": "2024/05/09"
                    }
                }
            ]
        }
    ],
    "finish_reason": "COMPLETE",
    "meta": {
        "api_version": {
            "version": "1"
        },
        "billed_units": {
            "input_tokens": 52,
            "output_tokens": 35
        },
        "tokens": {
            "input_tokens": 980,
            "output_tokens": 35
        }
    },
    "tool_calls": [
        {
            "name": "get_location",
            "parameters": {
                "time": "2024/05/09"
            }
        }
    ]
}
```

In this next request, we'll send the model the tool result and the reasoning message through the `chat_history` parameter to get the next tool step. If you're going to use this approach, make sure to include the reasoning message, as it helps the model select the right tool.

```bash
curl --location 'https://api.cohere.ai/v1/chat' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "model": "command-a-03-2025",
    "enable_multi_step": true,
    "chat_history": [
        {
            "role": "USER",
            "message": "What was the weather where I was yesterday?"
        },
        {
            "role": "CHATBOT",
            "message": "I will find the user'\''s location and then use that to find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_location",
                    "parameters": {
                        "time": "2024/04/30"
                    }
                }
            ]
        }
    ],
    "tool_results": [{
          "call": {
              "name": "get_location",
              "parameters": {
                  "time": "2024/04/25"
              }
          },
          "outputs": [
              {
                  "location": "Toronto, Ontario"
              }
          ]
    }],
    "tools": [
        {
            "name": "get_weather",
            "description": "Gets the weather for a given location",
            "parameter_definitions": {
                "location": {
                    "description": "The city and state, e.g. San Francisco, CA",
                    "type": "str",
                    "required": true
                }
            }
        },
        {
            "name": "get_location",
            "description": "Gets the users current location",
            "parameter_definitions": {
                "time": {
                    "description": "The date in format YYYY/MM/DD",
                    "type": "str"
                }
            }
        }
    ]
}'
```

And here's the response. As you can see, the model outputs another reasoning step and another tool call request. Again, make sure to include the model reasoning step in the next request via the `chat_history`.

```bash
{
    "response_id": "58897e19-5a63-4781-b9a6-1039e9b76ab4",
    "text": "The user was in Toronto, Ontario yesterday. Now I will find the weather there yesterday.",
    "generation_id": "ca6c183f-43d6-4194-a309-6d61a5ced7be",
    "chat_history": [
        {
            "role": "USER",
            "message": "What was the weather where I was yesterday?"
        },
        {
            "role": "CHATBOT",
            "message": "I will find the user's location and then use that to find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_location",
                    "parameters": {
                        "time": "2024/04/30"
                    }
                }
            ]
        },
        {
            "role": "TOOL",
            "tool_results": [
                {
                    "call": {
                        "name": "get_location",
                        "parameters": {
                            "time": "2024/04/25"
                        }
                    },
                    "outputs": [
                        {
                            "location": "Toronto, Ontario"
                        }
                    ]
                }
            ]
        },
        {
            "role": "CHATBOT",
            "message": "The user was in Toronto, Ontario yesterday. Now I will find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_weather",
                    "parameters": {
                        "location": "Toronto, Ontario"
                    }
                }
            ]
        }
    ],
    "finish_reason": "COMPLETE",
    "meta": {
        "api_version": {
            "version": "1"
        },
        "billed_units": {
            "input_tokens": 83,
            "output_tokens": 28
        },
        "tokens": {
            "input_tokens": 1083,
            "output_tokens": 28
        }
    },
    "tool_calls": [
        {
            "name": "get_weather",
            "parameters": {
                "location": "Toronto, Ontario"
            }
        }
    ]
}
```

In this final request, the tool results for `get_weather` are passed to the model along with the text containing the model's reasoning text, so that the final text can be generated.

```bash
curl --location 'https://api.cohere.ai/v1/chat' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "model": "command-a-03-2025",
    "enable_multi_step": true,
    "chat_history": [
        {
            "role": "USER",
            "message": "What was the weather where I was yesterday?"
        },
        {
            "role": "CHATBOT",
            "message": "I will find the user'\''s location and then use that to find the weather there yesterday",
            "tool_calls": [
                {
                    "name": "get_location",
                    "parameters": {
                        "time": "2024/04/30"
                    }
                }
            ]
        },
        {
            "role": "TOOL",
            "tool_results": [
                {
                    "call": {
                        "name": "get_location",
                        "parameters": {
                            "time": "2024/04/25"
                        }
                    },
                    "outputs": [
                        {
                            "location": "Toronto, Ontario"
                        }
                    ]
                }
            ]
        },
        {
            "role": "CHATBOT",
            "message": "The user was in Toronto, Ontario yesterday. Now I will find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_weather",
                    "parameters": {
                        "location": "Toronto, Ontario"
                    }
                }
            ]
        }
    ],
    "tool_results": [{
          "call": {
              "name": "get_weather",
              "parameters": {
                  "time": "Toronto, Ontario"
              }
          },
          "outputs": [
              {
                  "temperature": "18 celsius", "weather": "cloudy"
              }
          ]
    }],
    "tools": [
        {
            "name": "get_weather",
            "description": "Gets the weather for a given location",
            "parameter_definitions": {
                "location": {
                    "description": "The city and state, e.g. San Francisco, CA",
                    "type": "str",
                    "required": true
                }
            }
        },
        {
            "name": "get_location",
            "description": "Gets the users current location",
            "parameter_definitions": {
                "time": {
                    "description": "The date in format YYYY/MM/DD",
                    "type": "str"
                }
            }
        }
    ]
}'
```

And in the final response, the model completes a sequence of tool calls and outputs the final message.

```bash
{
    "response_id": "8ea52e5f-f376-4d06-b308-3318296ecebb",
    "text": "Yesterday, in Toronto, Ontario, the weather was cloudy and the temperature was 18°C.",
    "generation_id": "67190a18-3cee-490a-95fc-ddd22b611672",
    "chat_history": [
        {
            "role": "USER",
            "message": "What was the weather where I was yesterday?"
        },
        {
            "role": "CHATBOT",
            "message": "I will find the user's location and then use that to find the weather there yesterday",
            "tool_calls": [
                {
                    "name": "get_location",
                    "parameters": {
                        "time": "2024/04/30"
                    }
                }
            ]
        },
        {
            "role": "TOOL",
            "tool_results": [
                {
                    "call": {
                        "name": "get_location",
                        "parameters": {
                            "time": "2024/04/25"
                        }
                    },
                    "outputs": [
                        {
                            "location": "Toronto, Ontario"
                        }
                    ]
                }
            ]
        },
        {
            "role": "CHATBOT",
            "message": "The user was in Toronto, Ontario yesterday. Now I will find the weather there yesterday.",
            "tool_calls": [
                {
                    "name": "get_weather",
                    "parameters": {
                        "location": "Toronto, Ontario"
                    }
                }
            ]
        },
        {
            "role": "TOOL",
            "tool_results": [
                {
                    "call": {
                        "name": "get_weather",
                        "parameters": {
                            "time": "Toronto, Ontario"
                        }
                    },
                    "outputs": [
                        {
                            "temperature": "18 celsius",
                            "weather": "cloudy"
                        }
                    ]
                }
            ]
        },
        {
            "role": "CHATBOT",
            "message": "Yesterday, in Toronto, Ontario, the weather was cloudy and the temperature was 18°C."
        }
    ],
    "finish_reason": "COMPLETE",
    "meta": {
        "api_version": {
            "version": "1"
        },
        "billed_units": {
            "input_tokens": 120,
            "output_tokens": 21
        },
        "tokens": {
            "input_tokens": 1184,
            "output_tokens": 21
        }
    },
    "citations": [
        {
            "start": 14,
            "end": 30,
            "text": "Toronto, Ontario",
            "document_ids": [
                "get_location:0:2:0"
            ]
        },
        {
            "start": 48,
            "end": 54,
            "text": "cloudy",
            "document_ids": [
                "get_weather:0:4:0"
            ]
        },
        {
            "start": 79,
            "end": 83,
            "text": "18°C",
            "document_ids": [
                "get_weather:0:4:0"
            ]
        }
    ],
    "documents": [
        {
            "id": "get_location:0:2:0",
            "location": "Toronto, Ontario",
            "tool_name": "get_location"
        },
        {
            "id": "get_weather:0:4:0",
            "temperature": "18 celsius",
            "tool_name": "get_weather",
            "weather": "cloudy"
        }
    ]
}
```

## Best practices

Use single step when you want to force the model to answer the user query using a single tool. Otherwise, the model may take more steps than necessary to provide an answer.

## Summary of Key Differences

|                                                               | Single step tool use | Multi step tool use |
| ------------------------------------------------------------- | -------------------- | ------------------- |
| Model outputs reasoning                                       | No                   | Yes                 |
| Max number of tool call steps before final answer is produced | 1                    | 15                  |

## Related pages

- [Changelog](../changelog.md)
- [Cohere](../index.md)
- [Cohere API](./cohere-api-index.md)
- [Cohere Labs](./cohere-labs-index.md)
- [Cohere Platform](./cohere-platform-index.md)
- [Cookbooks](./cookbooks-index.md)
- [Deployment Options](./deployment-options-index.md)
- [Embeddings (Vectors, Search, Retrieval)](./embeddings-vectors-search-retrieval-index.md)
- [Get Started](./get-started-index.md)
- [Going to Production](./going-to-production-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.