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

#ai #llm #machinelearning #programming

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.

Step one: the request with tools

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?"}
  ]
}

Step two: the tool_use block

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.

Step three: the tool_result you send back

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
}

Step four: the final answer

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.

The same loop, streamed

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.

The three things that go wrong

Dropping the assistant turn. Sending the 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.
Splitting parallel results across messages. One assistant turn can contain several tool_use blocks. Every one of them needs a matching tool_result, and all of those results belong in a single user message. Splitting them across several messages is accepted by some clients but trains the model away from parallel calls — and omitting one entirely is a hard error. See disabling parallel tool use if you would rather have one at a time.
Returning too much. Tool results are re-sent on every subsequent turn, so a 40,000-token result is paid for once per remaining turn in the conversation. Return the fields the model needs, not the raw payload.

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.