Claude's tool_use and tool_result Content Blocks, End to End

Anthropic's Claude Messages API implements tool use as two content block types and a developer-written loop, not a special mode. The protocol requires echoing tool_use IDs in tool_result blocks, supports multiple tool calls per turn, and returns errors via is_error flags. The full agent loop is: call, check stop_reason, execute tool_use blocks, append assistant turn and tool results, and repeat until stop_reason is not 'tool_use'.

Tool use on the Messages API is not a special mode. It is two content block types and a loop you write yourself, and the entire protocol fits on one page. Tools are declared in a top-level tools array. Each entry has a name, a description, and a JSON Schema describing its input. The description is not documentation — it is the only thing the model has to decide when the tool applies, so it does more work than the schema does. { "model": "claude-opus-4-6", "max tokens": 1024, "tools": { "name": "get deploy status", "description": "Get the status of a deployment by its id. Use when the user asks whether a deploy succeeded, failed, or is still running.", "input schema": { "type": "object", "properties": { "deploy id": {"type": "string", "description": "The deploy id, e.g. dpl 8f21"} }, "required": "deploy id" } } , "messages": {"role": "user", "content": "Did dpl 8f21 go out cleanly?"} } The model does not call anything. It returns a response whose content array contains a block of type tool use , and whose stop reason is "tool use" : { "id": "msg 01Xy…", "role": "assistant", "content": { "type": "text", "text": "Let me check that deploy." }, { "type": "tool use", "id": "toolu 01A9k3…", "name": "get deploy status", "input": {"deploy id": "dpl 8f21"} } , "stop reason": "tool use", "usage": {"input tokens": 412, "output tokens": 68} } id — a toolu -prefixed identifier for this specific call. You must echo it back. It is not the tool name and it is not stable across calls. name — which tool to run. Dispatch on this. input — already-parsed JSON matching your schema, delivered as an object rather than a string. There is no second parse step.Note the text block sitting beside the tool call. A single assistant turn can contain prose and one or more tool calls together, so code that assumes content 0 is the tool call breaks the first time the model narrates what it is doing. Two messages get appended. First the assistant turn, verbatim, including the tool use block. Then a user turn containing the results — tool result is a user-role block, not a role of its own. "messages": {"role": "user", "content": "Did dpl 8f21 go out cleanly?"}, { "role": "assistant", "content": {"type": "text", "text": "Let me check that deploy."}, {"type": "tool use", "id": "toolu 01A9k3…", "name": "get deploy status", "input": {"deploy id": "dpl 8f21"}} }, { "role": "user", "content": { "type": "tool result", "tool use id": "toolu 01A9k3…", "content": "{\"state\":\"failed\",\"stage\":\"migrate\",\"exit code\":1}" } } tool use id must equal the id from the corresponding tool use block. That pairing is what the API validates, and a mismatch is a 400. content may be a plain string or an array of blocks — an array lets you return an image as well as text, which is how screenshot-producing tools work. For a failure, do not invent a fake success and do not drop the block. Return the result with is error set, and let the model decide what to do: { "type": "tool result", "tool use id": "toolu 01A9k3…", "content": "Deploy id not found. Ids look like dpl XXXX.", "is error": true } Send the whole array back — same tools, same model — and the model answers from the tool output, with stop reason back to end turn : { "role": "assistant", "content": {"type": "text", "text": "No — dpl 8f21 failed at the migrate stage with exit code 1."} , "stop reason": "end turn" } The loop is therefore: call, check stop reason , execute any tool use blocks, append assistant turn and tool results, call again. Repeat until stop reason is not "tool use" . That is the entire agent loop, and every framework that offers one is wrapping these four steps. Streaming changes how a tool call arrives, and it is the difference that breaks integrations ported from the buffered path. In a buffered response, input is handed to you as a parsed object. In a stream, it arrives as string fragments across many events: event: content block start data: {"type":"content block start","index":1, "content block":{"type":"tool use","id":"toolu 01A9k3…", "name":"get deploy status","input":{}}} event: content block delta data: {"type":"content block delta","index":1, "delta":{"type":"input json delta","partial json":"{\"deploy "}} event: content block delta data: {"type":"content block delta","index":1, "delta":{"type":"input json delta","partial json":"id\": \"dpl 8f21\"}"}} event: content block stop data: {"type":"content block stop","index":1} Three consequences. First, content block start gives you the id and the name immediately with an empty input — which is enough to show the user “checking deploy status” before the arguments exist, and is the reason streamed agents can narrate what they are about to do. Second, the fragments are not individually valid JSON. {"deploy parses as nothing. You must accumulate the partial json strings for that block index and parse once, at content block stop . Attempting a parse per delta produces an exception on almost every event, and the tempting fix — swallowing those exceptions — hides the real parse failure when there is one. Third, you cannot dispatch early. The arguments are only complete at content block stop , so the earliest safe execution point is there, not on message stop and certainly not mid-stream. If the stream ends with stop reason: "max tokens" before that stop event arrives, the accumulated string is a truncated object and the call cannot be run at all — the correct handling is to treat it as a failed turn rather than to guess at the missing fields. php const partials = new Map ; // index - accumulated json string for await const ev of stream { if ev.type === "content block start" && ev.content block.type === "tool use" { partials.set ev.index, { meta: ev.content block, json: "" } ; } if ev.type === "content block delta" && ev.delta.type === "input json delta" { partials.get ev.index .json += ev.delta.partial json; } if ev.type === "content block stop" && partials.has ev.index { const { meta, json } = partials.get ev.index ; // Empty string is legitimate: a tool with no required inputs. const input = json.length ? JSON.parse json : {}; queue.push { id: meta.id, name: meta.name, input } ; } } Note the empty-string case. A tool whose schema has no required properties can produce a tool use block with no input json delta events at all, and JSON.parse "" throws. The computer-use screenshot action is close to this shape, which is why the bug tends to appear first in agents that take screenshots. tool result without first appending the assistant message that contained the tool use is a 400: the result references an id that is not in the conversation. Append the response content array verbatim rather than extracting the text. tool use blocks. Every one of them needs a matching tool result , and all of those results belong in a A fourth one appears once you turn reasoning on, and it is worth naming because it produces a 400 mentioning a block type you never deliberately created. On a thinking-enabled model the assistant turn that contains the tool use also contains a thinking block, and that block has to be echoed back in the history exactly as it arrived — including its signature field. Stripping it because it looked like debug output, or reserialising it through a formatter that reorders keys, breaks the signature and the request is rejected. The rule that avoids this is the rule that avoids the first failure above: append the response content array verbatim rather than rebuilding a message from the parts you recognise. One design note that pays for itself. The model reads tool result.content as text, so its shape is a prompt-design decision rather than a serialisation detail. Returning a raw stack trace gets you a model that reasons about a stack trace; returning Deploy dpl 8f21 failed at stage "migrate" exit 1 . Logs: … gets you one that answers the question. Errors especially benefit from being written for a reader — an is error result saying what valid input looks like is frequently enough for the model to fix its own call on the next turn, which turns a hard failure into one extra round trip.