Agents And Tools Tool Use Overview

Note: Important: Tool results must be formatted correctly to avoid API errors and ensure Claude continues using parallel tools. See our implementation guide for detailed formatting requirements and complete code examples.


For comprehensive examples, test scripts, and best practices for implementing parallel tool calls, see the [parallel tool use section](/en/docs/agents-and-tools/tool-use/implement-tool-use#parallel-tool-use) in our implementation guide.

In this case, Claude may either:

* Use the tools sequentially (one at a time) — calling `get_weather` first, then `get_time` after receiving the weather result
* Use parallel tool calls — outputting multiple `tool_use` blocks in a single response when the operations are independent

When Claude makes parallel tool calls, you must return all tool results in a single `user` message, with each result in its own `tool_result` block.

For example, using the `get_weather` tool above, if you ask Claude "What's the weather?" without specifying a location, Claude, particularly Claude Sonnet, may make a guess about tools inputs:

```JSON
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}
```

This behavior is not guaranteed, especially for more ambiguous prompts and for less intelligent models. If Claude Opus doesn't have enough context to fill in the required parameters, it is far more likely respond with a clarifying question instead of making a tool call.

Here's an example of using a `get_location` tool to get the user's location, then passing that location to the `get_weather` tool:



In this case, Claude would first call the `get_location` tool to get the user's location. After you return the location in a `tool_result`, Claude would then call `get_weather` with that location to get the final answer.

The full conversation might look like:

| Role      | Content                                                                                                                                                                                                                       |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User      | What's the weather like where I am?                                                                                                                                                                                           |
| Assistant | I'll find your current location first, then check the weather there. \[Tool use for get\_location]                                                                                                                            |
| User      | \[Tool result for get\_location with matching id and result of San Francisco, CA]                                                                                                                                             |
| Assistant | \[Tool use for get\_weather with the following input]\{ "location": "San Francisco, CA", "unit": "fahrenheit" }                                                                                                               |
| User      | \[Tool result for get\_weather with matching id and result of "59°F (15°C), mostly cloudy"]                                                                                                                                   |
| Assistant | Based on your current location in San Francisco, CA, the weather right now is 59°F (15°C) and mostly cloudy. It's a fairly cool and overcast day in the city. You may want to bring a light jacket if you're heading outside. |

This example demonstrates how Claude can chain together multiple tool calls to answer a question that requires gathering data from different sources. The key steps are:

1. Claude first realizes it needs the user's location to answer the weather question, so it calls the `get_location` tool.
2. The user (i.e. the client code) executes the actual `get_location` function and returns the result "San Francisco, CA" in a `tool_result` block.
3. With the location now known, Claude proceeds to call the `get_weather` tool, passing in "San Francisco, CA" as the `location` parameter (as well as a guessed `unit` parameter, as `unit` is not a required parameter).
4. The user again executes the actual `get_weather` function with the provided arguments and returns the weather data in another `tool_result` block.
5. Finally, Claude incorporates the weather data into a natural language response to the original question.

Chain of thought prompt

`Answer the user's request using relevant tools (if they are available). Before calling a tool, do some analysis. First, think about which of the provided tools is the relevant tool to answer the user's request. Second, go through each of the required parameters of the relevant tool and determine if the user has directly provided or given enough information to infer a value. When deciding if the parameter can be inferred, carefully consider all the context to see if it supports a specific value. If all of the required parameters are present or can be reasonably inferred, proceed with the tool call. BUT, if one of the values for a required parameter is missing, DO NOT invoke the function (not even with fillers for the missing params) and instead, ask the user to provide the missing parameters. DO NOT ask for more information on optional parameters if it is not provided.
`

When using tools in this way:

* You usually want to provide a **single** tool
* You should set `tool_choice` (see [Forcing tool use](/en/docs/agents-and-tools/tool-use/implement-tool-use#forcing-tool-use)) to instruct the model to explicitly use that tool
* Remember that the model will pass the `input` to the tool, so the name of the tool and description should be from the model's perspective.

The following uses a `record_summary` tool to describe an image following a particular format.