Tool result format

A tool returns a result that the agent adds to the conversation and sends back to the model. When a custom tool returns a plain value, the SDK wraps it in this structure automatically. Construct the structure yourself when a tool needs to return typed content, mixed content blocks, or an explicit error status. This page documents that structure, the content types it carries, and the conversion rules the SDK applies to return values.

The ToolResult dictionary has three fields:

{
    "toolUseId": str,       # ID of the tool use request. Matches the incoming request.
    "status": str,          # Either "success" or "error"
    "content": list[dict],  # Content items, each in one of the supported formats
}

The toolUseId is optional in a value returned from a decorated function: the @tool decorator fills it in from the originating request.

The ToolResultBlock schema:

{
  type: 'toolResultBlock'
  toolUseId: string
  status: 'success' | 'error'
  content: Array<ToolResultContent>
  error?: Error
}

Content Types

The content field is a list of content blocks. Each block carries one type of output:

text: a string of text output
json: any JSON-serializable data structure

Both SDKs also accept image and document blocks; TypeScript additionally accepts video. A single result can mix block types, for example a text summary alongside a JSON payload.

Response Examples

Python
TypeScript

A success response carries a "success" status and one or more content blocks:

{
    "toolUseId": "tool-123",
    "status": "success",
    "content": [
        {"text": "Operation completed successfully"},
        {"json": {"results": [1, 2, 3], "total": 3}}
    ]
}

An error response carries an "error" status and describes what failed:

{
    "toolUseId": "tool-123",
    "status": "error",
    "content": [
        {"text": "Error: Unable to process request due to invalid parameters"}
    ]
}

A success response carries a 'success' status and one or more content blocks:

{
    "type": "toolResultBlock",
    "toolUseId": "tooluse_xq6vYsQ-QcGZOPcIx0yM3A",
    "status": "success",
    "content": [
        {
            "type": "jsonBlock",
            "json": {
                "result": "The letter 'r' appears 3 time(s) in 'strawberry'"
            }
        }
    ]
}

An error response carries an 'error' status and an optional Error:

{
    "type": "toolResultBlock",
    "toolUseId": "tooluse_rFoPosVKQ7WfYRfw_min8Q",
    "status": "error",
    "content": [
        {
            "type": "textBlock",
            "text": "Error: Test error"
        }
    ],
    "error": Error
}

How Return Values Become Tool Results

Python
TypeScript

The @tool decorator converts a function’s return value into a ToolResult:

A string or other simple value is wrapped as {"text": str(result)}.
A dictionary that already has the ToolResult structure is used directly.
A raised exception is converted to an error response.

The tool() function converts a callback’s return value into a ToolResultBlock:

A value of type string | number | boolean | null | { [key: string]: JSONValue } | JSONValue[] is converted to a ToolResultBlock.
A thrown exception is caught and converted to an error response.