D1 · Agentic Architecture › Cluster 3 · Tool Use

3.2 · The tool_result Contract

Matching ids, user-role turns, and the three ways to earn a 400

CONCEPT The four invariants of a valid tool_result

Returning a tool result looks trivial, but the API enforces a strict contract. Violate any part and you get a hard HTTP 400 — not a soft degradation. Memorize these four invariants; the exam tests them directly.

InvariantRuleViolate it →
Matching idtool_use_id must equal the id of the tool_use block it answers.400
User roleThe tool_result lives in a user turn, never assistant.400
One user messageALL results for one assistant turn go in a single user message.400 / missing result
AlternationRoles must alternate user → assistant → user; no two same-role turns in a row.400
🔑 A tool_result block is shaped {"type":"tool_result", "tool_use_id": <id>, "content": <str or blocks>}. Add "is_error": true to signal the tool failed — Claude reads it as a failure and can retry or adapt, rather than treating the payload as a valid answer.

DIAGRAM The id must match, the role must be user

sequenceDiagram participant App as Your code participant API as Messages API API-->>App: assistant turn
tool_use { id: "toolu_A1", name, input } Note over App: run the tool App->>API: user turn
tool_result { tool_use_id: "toolu_A1" } Note over App: ✅ id matches + role=user API-->>App: end_turn (final answer) App-->>App: ❌ tool_use_id "toolu_XX"? → 400 App-->>App: ❌ put in assistant turn? → 400 App-->>App: ❌ two user turns in a row? → 400

CODE Building the tool_result turn

Success path, the is_error path, and returning results for every tool_use in the same assistant turn in ONE user message.

tool_uses = [b for b in resp.content if b.type == "tool_use"]

results = []
for tu in tool_uses:
    try:
        out = run_tool(tu.name, tu.input)
        results.append({
            "type": "tool_result",
            "tool_use_id": tu.id,          # MUST match the tool_use id
            "content": out,                 # str, or a list of content blocks
        })
    except Exception as e:
        results.append({
            "type": "tool_result",
            "tool_use_id": tu.id,
            "content": f"Error: {e}",
            "is_error": True,              # tells Claude the tool FAILED
        })

# ONE user message carrying ALL results from that assistant turn.
messages.append({"role": "user", "content": results})

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    tools=TOOLS, messages=messages,
)
Do not split results across multiple user messages, and do not drop the result for a tool_use you chose not to run — every tool_use id in an assistant turn must be answered in the next single user turn.

EXAM TRAPS

Trap (400 cause #1): Mismatched id. tool_use_id doesn't equal the tool_use.id it answers (typo, wrong index, stale id). → HTTP 400.
Trap (400 cause #2): Wrong role. Putting the tool_result in an assistant turn. Results are always a user turn. → HTTP 400.
Trap (400 cause #3): Non-alternating roles / split results. Two same-role turns in a row, or spreading one turn's results across multiple user messages instead of one. → HTTP 400.
Trap: Treating a failed tool as success. → A tool that errored should return is_error: true so Claude adapts, not a fabricated "OK".

PRACTICE

Q1 · Claude returned two tool_use blocks. How many user messages should carry the results?

One. All results from a single assistant turn go in one user message, as a list of two tool_result blocks — each with its own matching tool_use_id. Splitting them 400s.

Q2 · Your DB tool timed out. What do you send back?

A tool_result with the matching tool_use_id, an explanatory content, and "is_error": true. Claude then knows the call failed and can retry, choose a different tool, or explain the failure — instead of trusting a fake result.

Q3 · Name the three ways to get a 400 from a tool_result.

(1) Mismatched tool_use_id, (2) wrong role (assistant instead of user), (3) non-alternating roles — including splitting one turn's results across multiple user messages.