D2 · Tool Design & MCP › Cluster 3 · Tool Results & Error Handling

3.1 · Returning Results (content, is_error)

Shape of a tool_result

CONCEPT A result is a block in a user message

When Claude wants a client tool, it stops with stop_reason: "tool_use" and emits one or more tool_use blocks (each with an id, a name, and an input). You run the tool, then continue the conversation by appending a new message with role: "user" whose content holds a tool_result block. There is no tool or function role in the Claude API — results ride inside the ordinary user/assistant message structure.

The tool_result block has exactly these fields:

FieldRequired?What it is
typeYesAlways the literal "tool_result".
tool_use_idYesThe id of the tool_use block this answers — this is how the API matches a result to its call.
contentOptionalThe result: a plain string, or a list of blocks (text, image, document, search_result). Omit it for an empty result.
is_errorOptionalSet true to tell Claude the execution failed (see 3.2).
🔑 tool_use_id is the join key. Claude parallelizes and interleaves calls, so the API relies on the ID — not position — to line each result up with its call.

CONCEPT content: string, blocks, or nothing

content is flexible. A short scalar answer is just a string ("15 degrees"). Richer results use a list of content blocks — for example a text block plus an image block so Claude can "see" a screenshot the tool produced. You may also return document blocks (PDF/text) or search_result blocks. And a tool that succeeds but has nothing to say can send a tool_result with no content at all.

Return semantic, stable identifiers (slugs, UUIDs) and only the fields Claude needs to pick its next step — the result block becomes part of the transcript and is billed as input tokens on every later turn.

DIAGRAM The round trip

sequenceDiagram participant U as Your app participant C as Claude (Messages API) U->>C: user msg + tools[] C-->>U: assistant: text + tool_use(id, name, input)
stop_reason: "tool_use" Note over U: run the tool locally U->>C: user msg: tool_result(tool_use_id, content) C-->>U: assistant: final text answer
stop_reason: "end_turn"

CODE A successful tool_result (in a user message)

The assistant turn (Claude's tool_use) is echoed back verbatim, then the user turn carries the result. Note the tool_use_id matches the tool_use block's id.

// assistant turn Claude produced (echo it back unchanged)
{ "role": "assistant", "content": [
    { "type": "text", "text": "I'll check the weather." },
    { "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" } }
] }

// the result you send back — a NEW user message
{ "role": "user", "content": [
    { "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",  // must match the id above
      "content": "15 degrees" }        // string — or a list of text/image/document blocks
] }

TRADE-OFFS String content vs. block-list content

✅ Plain string

  • Simplest for scalar/text answers
  • Least token overhead
  • Easy to build and read

🧩 List of content blocks

  • Needed for images, documents, search results
  • Lets you mix a text summary with an image
  • Slightly more structure to assemble
Rule of thumb: string for text, block-list only when the result genuinely carries an image, document, or citation Claude must reason over.

EXAM TRAPS

Trap: Sending the result in an assistant message or a special tool role. → A tool_result lives in a user message. The Claude API has no tool/function role.
Trap: Forgetting tool_use_id, or making one up. → It must equal the id of the tool_use it answers; that ID is the only thing that pairs a result to its call.
Trap: Thinking content is required. → It's optional — a tool that succeeds with nothing to report can send a tool_result with just type and tool_use_id.
Trap: Assuming results must be strings. → content can be a list of text, image, document, or search_result blocks.

PRACTICE

Q1 · What three fields identify and carry a tool result, and which is mandatory to pair it with its call?

type: "tool_result", tool_use_id, and (optionally) content. tool_use_id is the mandatory pairing key — it must match the id of the originating tool_use block.

Q2 · Which message role carries a tool_result, and why not an assistant turn?

A user message. In the Claude API, tool_use blocks come from the assistant and tool_result blocks come back from the user — there is no dedicated tool/function role.

Q3 · Your tool returns a chart image plus a one-line caption. How do you shape content?

As a list of blocks: a text block for the caption and an image block (base64 source) for the chart, inside one tool_result. A plain string can't carry the image.