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:
| Field | Required? | What it is |
|---|---|---|
type | Yes | Always the literal "tool_result". |
tool_use_id | Yes | The id of the tool_use block this answers — this is how the API matches a result to its call. |
content | Optional | The result: a plain string, or a list of blocks (text, image, document, search_result). Omit it for an empty result. |
is_error | Optional | Set 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.
DIAGRAM The round trip
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
EXAM TRAPS
assistant message or a special
tool role. → A tool_result lives in a user message. The
Claude API has no tool/function role.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.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.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.