Implementation:Anthropics Anthropic sdk python ToolResultBlockParam

Knowledge Sources	Anthropic Python SDK Anthropic Tool Use Docs
Domains	Tool_Use, LLM, Function_Calling
Last Updated	2026-02-15 00:00 GMT

Overview

ToolResultBlockParam is a TypedDict that encodes the result of a tool execution for submission back to the Claude API. Each tool result is correlated to its corresponding tool call via the tool_use_id field and is sent as part of a user role message's content array.

API Definition

class ToolResultBlockParam(TypedDict, total=False):
    tool_use_id: Required[str]
    type: Required[Literal["tool_result"]]
    cache_control: Optional[CacheControlEphemeralParam]
    content: Union[str, Iterable[Content]]
    is_error: bool

Source Location

File: src/anthropic/types/tool_result_block_param.py, lines 19-29

Import

from anthropic.types import ToolResultBlockParam

Fields

Field	Type	Required	Description
tool_use_id	str	Yes	Must exactly match the id field from the corresponding ToolUseBlock in the model's response. This is the correlation key that links a result to its request.
type	Literal["tool_result"]	Yes	Discriminator field, always "tool_result". Distinguishes this block from other content block types in the message array.
cache_control	Optional[CacheControlEphemeralParam]	No	Creates a cache control breakpoint at this content block. Used for prompt caching optimization.
content	Union[str, Iterable[Content]]	No	The result data. Can be a plain string or an iterable of structured content blocks.
is_error	bool	No	When True, signals to the model that the tool execution failed and the content is an error message.

Content Type

The Content type alias (line 16) supports rich, multimodal tool results:

Content: TypeAlias = Union[
    TextBlockParam,
    ImageBlockParam,
    SearchResultBlockParam,
    DocumentBlockParam,
]

This allows tool results to include images, search results, and documents alongside text.

Usage Examples

Simple string result:

result = {
    "type": "tool_result",
    "tool_use_id": "toolu_abc123",
    "content": "The weather in London is 22 degrees, partly cloudy",
}

Error result:

result = {
    "type": "tool_result",
    "tool_use_id": "toolu_abc123",
    "content": "Error: City 'Londn' not found. Did you mean 'London'?",
    "is_error": True,
}

Rich content result (with image):

result = {
    "type": "tool_result",
    "tool_use_id": "toolu_abc123",
    "content": [
        {"type": "text", "text": "Here is the weather chart for London:"},
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/png",
                "data": "<base64-encoded-image-data>",
            },
        },
    ],
}

Submission Pattern

Tool results are submitted as a user role message in the next messages.create() call:

import anthropic
from anthropic import beta_tool

@beta_tool
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get the current weather for a city.

    Args:
        city: The city name
        unit: Temperature unit (celsius or fahrenheit)
    """
    return f"The weather in {city} is 22 degrees {unit}"

client = anthropic.Anthropic()

# Step 1: Initial request
messages = [{"role": "user", "content": "What's the weather in London?"}]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[get_weather.to_dict()],
    messages=messages,
)

# Step 2: Process tool calls and build results
if response.stop_reason == "tool_use":
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = get_weather.call(block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(result),
            })

    # Step 3: Append assistant message and tool results to history
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})

    # Step 4: Send follow-up request with results
    final_response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        tools=[get_weather.to_dict()],
        messages=messages,
    )

Correlation Rules

• Every ToolUseBlock in the assistant's response must have a corresponding ToolResultBlockParam in the follow-up user message
• The tool_use_id must be an exact string match with ToolUseBlock.id
• Multiple tool results are batched in a single user message's content array
• Tool results cannot be sent without a preceding assistant message containing the matching tool_use block

With Cache Control

For applications using prompt caching, a cache control breakpoint can be set on the tool result:

result = {
    "type": "tool_result",
    "tool_use_id": "toolu_abc123",
    "content": "Large dataset result...",
    "cache_control": {"type": "ephemeral"},
}

Related Pages

Implements Principle

• Principle:Anthropics_Anthropic_sdk_python_Tool_Result_Submission