# Claude's tool_use and tool_result Content Blocks, End to End > Source: > Published: 2026-08-12 22:20:58+00:00 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.