Handle tool calls
Parse tool_use blocks, format tool_result responses, and handle errors with is_error.
When Claude’s response contains tool_use blocks, your code runs each tool and sends back tool_result blocks, including any errors. Write this code yourself when you need custom control over tool execution. Otherwise, use the SDK’s tool runner, which runs the tools and sends the results for you.
Claude’s response differs based on whether it uses a client or server tool.
Handling results from client tools
The response has a stop_reason of tool_use and one or more tool_use content blocks that include:
id: A unique identifier for this particular tool use block. This is used to match up the tool results later.name: The name of the tool being used.input: An object containing the input being passed to the tool, conforming to the tool’sinput_schema.
A tool_use block for a member of the computer use or browser use toolset also carries a toolset_name field ("computer" or "browser"). Its name is the member tool Claude is calling, such as screenshot or navigate, so dispatch those blocks on both fields.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}When you receive a tool use response for a client tool, follow these steps:
- For each
tool_useblock, run the tool that the block names, passing in itsinput. - In a new request, keep the earlier messages and add the response’s
contentunchanged as anassistantmessage. - Add a
usermessage with onetool_resultblock for eachtool_useblock in that content, even if the tool failed. - Send the request with the same
toolsas the first request. Claude uses the tool results to continue its response. - If the next response’s
stop_reasonis alsotool_use, repeat these steps. For other values, see the stop reason quick reference.
For these steps as complete programs, see Tutorial: Build a tool-using agent.
Each tool_result block has type set to tool_result, plus these fields:
tool_use_id: Theidof thetool_useblock that this result answers.content(optional): The result of the tool as a string or a list of content blocks. These content blocks can use thetext,image,document, orsearch_resulttypes.is_error(optional): Set totrueif the tool failed or the call was invalid.
For example, a successful tool result looks like this:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}A tool_result that answers a computer use or browser use member block must also echo the same toolset_name value as the tool_use block; a member result that omits it is rejected. Its content is also narrower: a member result may contain only text and image blocks, and a browser use result may add one browser_state block (the tab-management members return only that block).
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}For example, this causes a 400 error:
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}This is correct when the assistant turn calls only client tools:
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}Handling results from server tools
Claude runs the tool internally and incorporates the results directly into its response without requiring additional user interaction.
Handling errors with is_error
When a client tool fails or a call is invalid, send a tool_result block with is_error set to true. Claude might then call the tool again with a new tool_use block, so limit how many retries your loop allows.
If the tool itself throws an error during execution (for example, a network error when fetching weather data), you can return the error message in the content along with "is_error": true:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}Claude can then call the tool again or tell the user what happened. For example, Claude might say “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”
If Claude’s attempted use of a tool is invalid (for example, missing required parameters), it usually means that there wasn’t enough information for Claude to use the tool correctly. The best approach during development is to try the request again with more-detailed description values in your tool definitions.
However, you can also continue the conversation with a tool_result that indicates the error:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude can then call the tool again with the missing information filled in.
Unlike with client tools, you don’t send is_error results for server tools. When a server tool hits an error, such as a network issue during web search, the API returns the error inside the tool’s result block. In most cases, Claude then continues with another approach or an explanation for the user.
For web search error codes, see Web search tool errors.
Next steps
Handle responses where Claude calls several tools in a single turn.
Let the SDK manage the tool_use loop, result formatting, and retries for you.
Write schemas and descriptions that steer Claude toward the right tool.
Was this page helpful?