D2 · Tool Design & MCP › Cluster 1 · Tool Use Fundamentals

1.3 · tool_use & tool_result Blocks (the Contract)

Matching ids, roles, ordering

CONCEPT Two block types, joined by an id

Tool use is a contract between two content blocks. Claude emits a tool_use block (in an assistant turn); you reply with a matching tool_result block (in a user turn). The link between them is the id.

BlockRoleKey fields
tool_useassistantid (e.g. toolu_…), name, input
tool_resultusertool_use_id (must equal the tool_use.id), content, optional is_error
🔑 tool_result.tool_use_id must exactly match the tool_use.id it answers. This is how Claude pairs a result to the call that produced it — order alone is not enough.

CONCEPT The four rules the contract enforces

  1. Matching ids. Each tool_result carries the tool_use_id of the call it answers.
  2. User role. tool_result blocks live in a user message — never assistant.
  3. Answer every call. If an assistant turn has multiple tool_use blocks (parallel tool use), your next user message must return a tool_result for every one of them, all in a single user message.
  4. Ordering. tool_result blocks should come first in that user turn, before any other content.
Missing a tool_result for even one of several parallel tool_use blocks — or splitting results across separate user messages — is an error and quietly trains Claude to stop making parallel calls.
On failure, don't drop the result — return a tool_result with "is_error": true and an informative message. Claude reads it and adapts (retry, ask, or route around).

DIAGRAM The id binds the pair

flowchart LR subgraph A["assistant turn"] TU1["tool_use
id: toolu_A1
name, input"] TU2["tool_use
id: toolu_B2
name, input"] end subgraph U["user turn (ONE message)"] TR1["tool_result
tool_use_id: toolu_A1
content"] TR2["tool_result
tool_use_id: toolu_B2
is_error: true"] end TU1 -->|"matched id"| TR1 TU2 -->|"matched id"| TR2 classDef use fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef err fill:#f8d7da,stroke:#dc3545,color:#721c24; class TU1 use; class TU2 use; class TR1 ok; class TR2 err;

CODE A matched tool_use → tool_result exchange

The assistant turn holds the tool_use; the following user turn returns every tool_result — one ok, one flagged is_error — with matching ids.

# --- assistant turn Claude produced (stop_reason: "tool_use") ---
{
  "role": "assistant",
  "content": [
    {"type": "text", "text": "I'll check the weather and the time."},
    {"type": "tool_use", "id": "toolu_A1",
     "name": "get_weather", "input": {"location": "SF"}},
    {"type": "tool_use", "id": "toolu_B2",
     "name": "get_time", "input": {"tz": "Pacific"}}
  ]
}

# --- your reply: ONE user message, a result for EVERY tool_use ---
{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_A1",
     "content": "15 °C, partly cloudy"},
    {"type": "tool_result", "tool_use_id": "toolu_B2",
     "content": "Timezone service unavailable.",
     "is_error": true}      # failed — flag it, don't drop it
  ]
}

TRADE-OFFS Signaling failure two ways

✅ tool_result with is_error: true

  • Claude sees the failure and can recover in-loop
  • Keeps the contract intact (every tool_use answered)
  • The error message steers the next attempt

⚠️ Dropping the result / raising outside the loop

  • An unanswered tool_use breaks the request
  • Claude gets no signal to adapt — it just stalls
  • Server-tool errors are the exception: they arrive as result blocks with an error, not exceptions

EXAM TRAPS

Trap: Using id instead of tool_use_id. → The tool_use block has id; the tool_result references it via tool_use_id. They must be equal.
Trap: Answering only some parallel tool_use blocks. → You must return a tool_result for every tool_use in the turn, all in one user message.
Trap: Splitting results across multiple user messages. → Return them together in a single user turn; splitting silently trains Claude to stop calling tools in parallel.
Trap: Omitting a failed tool's result. → Return it with is_error: true and a message. Silence is worse than a reported error.

PRACTICE

Q1 · How is a tool_result linked to the call it answers?

Via tool_use_id: the tool_result's tool_use_id must exactly equal the id of the tool_use block it responds to. Positional order alone is not the link.

Q2 · Claude returns three tool_use blocks in one turn. What must your reply look like?

A single user message containing three tool_result blocks — one per tool_use_id. Every call must be answered, and all results go in that one user turn (results first, before other content).

Q3 · A tool throws. How do you report it inside the contract?

Return a tool_result for that tool_use_id with "is_error": true and an informative content message. Claude reads the error and adapts — retry, ask for clarification, or take another path. Don't drop the block.