Principle:Anthropics Anthropic sdk python Tool Result Submission

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

Overview

Tool Result Submission is the step where the results of executed tool functions are fed back to the model so it can incorporate the information into its response. This is the critical feedback link in the tool use cycle: the model requests a tool call, the application executes it, and then the application sends the result back in the next API request. The Anthropic Python SDK uses a structured ToolResultBlockParam TypedDict to encode each result with its correlation ID, content, and error status.

Theory: Feeding Tool Execution Results Back to the LLM

After executing one or more tool calls, the results must be sent to the model in a specific format. The API treats tool results as part of the conversation: they are included in a user role message's content array. This design means:

• Tool results appear in conversation history just like other user messages
• The model can reference tool results in its subsequent reasoning
• Multiple tool results can be batched in a single user message
• The conversation maintains a clear request-response pattern (assistant requests tool, user provides result)

The tool_use_id Correlation Pattern

Each tool result must be linked to the specific tool call it answers. This is accomplished through the tool_use_id field, which must exactly match the id field from the corresponding ToolUseBlock in the model's response.

The correlation flow is:

Assistant response:
  content: [
    ToolUseBlock(id="toolu_abc123", name="get_weather", input={"city": "London"})
  ]

User follow-up:
  content: [
    ToolResultBlockParam(tool_use_id="toolu_abc123", content="22 degrees, partly cloudy")
  ]

This ID-based correlation is essential because:

• The model may request multiple tool calls in a single response
• Each tool call gets a unique ID
• The model needs to know which result corresponds to which request
• Out-of-order results are correlated by ID, not position

Error Signaling Through is_error

When a tool execution fails, the result should be submitted with is_error: True. This signals to the model that:

• The requested operation did not succeed
• The content contains an error message, not a successful result
• The model should consider alternative approaches or inform the user about the failure

# Success result
{"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "22 degrees"}

# Error result
{"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "City not found", "is_error": True}

The model generally handles errors gracefully: it may retry with different arguments, try a different tool, or explain the failure to the user.

Conversation Structure

Tool results fit into the standard alternating message pattern:

messages = [
    {"role": "user", "content": "What's the weather in London?"},
    {"role": "assistant", "content": [
        {"type": "text", "text": "I'll look that up for you."},
        {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather",
         "input": {"city": "London"}}
    ]},
    {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": "toolu_abc123",
         "content": "22 degrees, partly cloudy"}
    ]},
    # Model's final response will incorporate the weather data
]

Key rules:

• The assistant message (with tool_use blocks) must be appended to history exactly as received
• The tool result message uses role: "user"
• All tool_use blocks in the assistant message must have corresponding tool_result blocks
• The content field in a tool result can be a plain string or a structured content array (for images, documents, etc.)

Rich Content in Tool Results

Beyond simple strings, tool results can include structured content blocks:

Content Type	Use Case
TextBlockParam	Plain text results
ImageBlockParam	Screenshots, charts, or visual data
SearchResultBlockParam	Structured search results
DocumentBlockParam	Document content (PDFs, etc.)

This allows tools to return rich, multimodal results that the model can interpret and reference in its response.

Related Pages

Implemented By

• Implementation:Anthropics_Anthropic_sdk_python_ToolResultBlockParam