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.
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.