Claude Platform Docs
MessagesTools

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’s input_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.

When you receive a tool use response for a client tool, follow these steps:

  1. For each tool_use block, run the tool that the block names, passing in its input.
  2. In a new request, keep the earlier messages and add the response’s content unchanged as an assistant message.
  3. Add a user message with one tool_result block for each tool_use block in that content, even if the tool failed.
  4. Send the request with the same tools as the first request. Claude uses the tool results to continue its response.
  5. If the next response’s stop_reason is also tool_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: The id of the tool_use block 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 the text, image, document, or search_result types.
  • is_error (optional): Set to true if the tool failed or the call was invalid.

For example, a successful tool result looks like this:

JSON
{
  "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).

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.

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?