By AI Blog Editor
Apr 20, 2026 · 1 min read

Tool use in one picture

Four message shapes cover 95% of tool use. See each one as a live JSON conversation — single call, parallel fan-out, agent loop, forced choice.

Most tool-use bugs are shape bugs: the developer has a mental model of the message flow that doesn't match what the API actually exchanges. Once you can picture the four common shapes, the rest is bookkeeping.

All four share the same loop: you send messages, the model replies with a stop_reason, and if that reason is tool_use you execute the tool and feed the result back as another message. What changes between the shapes is how many tools, how many turns, and how much the model gets to choose.

The four shapes

Single. One tool, one result, one final answer. The default and the one you'll use most.

Parallel. Multiple independent tool calls in one turn. You run them in parallel and return a single user message with multiple tool_result blocks keyed by tool_use_id.

Agent loop. Each round's result can trigger more tool calls. Keep looping until stop_reason is end_turn. Put a step budget on it — see the loops article.

Forced choice. You tell the model it must call a specific tool (or any tool, or none). Great for structured extraction where you need the answer in a known schema.

One tool, one turn. Model decides to call it, receives the result, returns a final answer. 95% of tool use looks like this.

USER

{ "role": "user", "content": "What's the weather in Venice?" }

ASSISTANT

model decides to call the tool

{
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Checking..." },
    { "type": "tool_use",
      "id": "tool_01", "name": "get_weather",
      "input": { "city": "Venice" } }
  ]
}

USER

you execute, feed back the result

{
  "role": "user",
  "content": [
    { "type": "tool_result",
      "tool_use_id": "tool_01",
      "content": "12°C, light rain" }
  ]
}

ASSISTANT

{
  "role": "assistant",
  "stop_reason": "end_turn",
  "content": [
    { "type": "text",
      "text": "Venice is 12°C with light rain right now." }
  ]
}

Interactive · switch patterns to see the message shape

Design tools like functions, not like prompts

The tool name should be a verb the model can guess from the task. The description is a full sentence that says when to use it, not a one-word label. The input schema should accept the minimum information needed; extra fields are opportunities for the model to hallucinate values.

A common anti-pattern is one god-tool with a dozen optional fields and branching behaviour. The model will misuse it more often than if you'd given it three small tools with obvious names. One tool, one intent.

Three bugs you'll hit

Wrong shape on tool_result. It has to be a message with role: "user" containing a tool_result block with the correct tool_use_id. Not a plain string. Not an assistant message.

Mismatched IDs. Each tool_use block has an id; the matching tool_result uses it as tool_use_id. Off-by-one on parallel calls is a classic.

Forgetting the loop. After a tool result, the model may decide to call another tool rather than finish. Handle stop_reason === "tool_use" in the response before assuming the answer is text.

Structured output via forced tool choice

If you need JSON with a known shape, don't ask the model to "return JSON in this format". Instead, declare a tool whose input schema is the shape you want, and force the model to call it. You get schema validation for free and no more broken-JSON retries.

The pattern has a name in the docs — forced tool choice for structured output — and it's the cleanest way to get predictable shapes out of Claude.

One-line mental model

Tools are function calls the model initiates; tool results are function returns you send back. Everything else is pagination.

* * *

Thanks for reading. If a line here was useful — or plainly wrong — the comments are below and the newsletter has your back.

Elsewhere in this issue

3 more

Letters

Arguments, corrections, questions. Anonymous comments allowed; be kind, be specific.

The Loop