Handle tool calls

This page covers the tool-call lifecycle: reading tool_use blocks from Claude's response, formatting tool_result blocks in your reply, and signaling errors. For the SDK abstraction that handles this automatically, see Tool Runner.

Claude's response differs based on whether it uses a client or server tool.

Handling results from client tools

The response will have 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 will be 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.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-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, you should:

1. Extract the name, id, and input from the tool_use block.
2. Run the actual tool in your codebase corresponding to that tool name, passing in the tool input.
3. Continue the conversation by sending a new message with the role of user, and a content block containing the tool_result type and the following information:
   • tool_use_id: The id of the tool use request this is a result for.
   • content (optional): The result of the tool, as a string (for example, "content": "15 degrees"), a list of nested content blocks (for example, "content": [{"type": "text", "text": "15 degrees"}]), or a list of document blocks (for example, "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). These content blocks can use the text, image, document, or search_result types.
   • is_error (optional): Set to true if the tool execution resulted in an error.

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": "15 degrees"
    }
  ]
}

{
  "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"
          }
        }
      ]
    }
  ]
}

After receiving the tool result, Claude will use that information to continue generating a response to the original user prompt.

Handling results from server tools

Claude executes the tool internally and incorporates the results directly into its response without requiring additional user interaction.

Handling errors with is_error

There are a few different types of errors that can occur when using tools with Claude:

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Next steps