Describe the JSON shape of a Claude Opus 4.7 assistant message that calls a tool

Short answer·Medium·4.0 · 0·~3 min·Asked atAnthropic

Attempt it

Walk through what an assistant message looks like at the JSON level when Claude Opus 4.7 calls a tool during a turn, and what the next user turn must contain. Be specific about field names and the block-typed content array.

Free · 2 AI evals / day

**Anthropic's messages API** does not pack everything into a single string. Each message has a role (user, assistant, system) and a content field that is an ARRAY of typed blocks. When Claude Opus 4.7 calls a tool, the assistant turn looks like role 'assistant' with a content array. That array can hold multiple blocks. A typical pattern is one text block holding the model's reasoning, followed by one tool_use block containing the call itself. The tool_use block has three fields beyond its type: an id (a unique string for this specific call), a name (the tool being invoked), and an input (a JSON object holding the arguments). You then run the tool yourself and send the result back. The next message is role 'user', and its content array carries a tool_result block. That block has a type of tool_result, a tool_use_id that matches the assistant's id from the previous turn, and a content field with whatever the tool returned (a string or another list of blocks). The id linkage is the important piece. It is how the model knows which tool result answers which tool call when there are multiple tools in flight. Unlike OpenAI's API, there is no separate 'tool' role; the result rides inside the user message.

**The messages API uses typed-block content arrays**, not flat strings, and tool calls live inside that structure. A tool-calling assistant turn looks like: ``` { "role": "assistant", "content": [ {"type": "text", "text": "I will check the weather first."}, {"type": "tool_use", "id": "toolu_01ABC", "name": "get_weather", "input": {"city": "Tokyo"}} ] } ``` The text block holds any natural-language reasoning. The tool_use block carries three required fields: id (a unique identifier for THIS specific invocation), name (the tool to call), and input (the JSON argument object the model generated). Text and tool_use blocks coexist freely in the same turn, and a single turn can issue multiple tool_use blocks for parallel calls. The next message replies with role 'user' and a tool_result block: ``` { "role": "user", "content": [ {"type": "tool_result", "tool_use_id": "toolu_01ABC", "content": "22 C, clear"} ] } ``` The tool_use_id matches the id from the assistant's tool_use, which is what binds the call to its result. The content can be a string or another typed-block array including images. For fine-tuning, training data must preserve the block-typed structure and the id linkage. Collapsing to flat strings breaks the grounding the model learned in pretraining.

Quick reference

TL;DR

Assistant content is a typed-block array mixing text and tool_use blocks; the next user turn replies with tool_result blocks linked by tool_use_id. No separate tool role.

Memory aid

Easy to grasp

Picture a conversation where each speaker can hand over more than one slip of paper per turn. The assistant might pass a slip with words on it and another slip that says please run this calculation, with a unique sticker number on the calculation slip. On the next turn, the user hands back a slip with the calculation result and the same sticker number, so it is obvious which request the result answers. Nothing is glued together as one long sentence. Each kind of slip has its own format, and the sticker number is what keeps the call and the result linked across turns. That is exactly how the message shape works under the hood.

Key concepts

Tool calling Anthropic messages API Chat template

Detailed answer & concept explanation

~7 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Quick scan · 2–4 min

Everything important, quickly.

4 min: the typed-block content array, the tool_use block fields, the tool_result reply, the id linkage, parallel-call support, and the fine-tuning data implications.

Code example

python

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-4-7-20260101",
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "Lookup current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }],
    messages=[
        {"role": "user", "content": "Weather in Tokyo?"},
    ],
)

# resp.content is the block-typed array.
# For a tool call, you will see something like:
#   [TextBlock(text="Let me check..."),
#    ToolUseBlock(id="toolu_01...", name="get_weather",
#                 input={"city": "Tokyo"})]
for block in resp.content:
    if block.type == "tool_use":
        result = run_tool(block.name, block.input)
        # Reply with a tool_result block under role 'user'
        followup = client.messages.create(
            model="claude-opus-4-7-20260101",
            max_tokens=1024,
            messages=[
                {"role": "user", "content": "Weather in Tokyo?"},
                {"role": "assistant", "content": resp.content},
                {"role": "user", "content": [
                    {"type": "tool_result",
                     "tool_use_id": block.id,
                     "content": result},
                ]},
            ],
        )

Side-by-side

Aspect	Anthropic messages API	OpenAI chat completions
Assistant content	Typed-block array (text, tool_use)	String plus tool_calls field
Tool-call location	Inline tool_use block in content	Separate tool_calls field on message
Result role	'user' with tool_result block	'tool' role with content string
Call-to-result linkage	tool_use_id matches tool_use.id	tool_call_id matches tool_calls[].id
Parallel calls	Multiple tool_use blocks in one turn	Multiple entries in tool_calls array

Real-world examples

Real products, models, and research that use this idea.

Claude Opus 4.7 production deployments at Anthropic customers use this exact block-typed shape for tool-augmented agents calling search, calculator, and code-execution tools.
Anthropic's official SDKs (TypeScript, Python) construct typed-block content automatically when you pass tools to the messages.create call.
Open-source fine-tuning datasets like glaive-toolcall-anthropic emit the block-typed shape directly so SFT preserves tool-call grounding.
Tool-use agent frameworks like Smolagents and PydanticAI generate this exact JSON shape when targeting Claude Opus 4.7 or Claude Sonnet 4.6 backends.
Multi-tool parallel calls in Anthropic's computer-use beta rely on the id linkage to dispatch tool_result blocks back to the right tool_use call in one user message.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QHow does the message shape support parallel tool calls in one assistant turn?

QWhat goes wrong when fine-tuning data flattens the typed-block content into strings?

QWhy does Anthropic use role 'user' for tool results instead of a dedicated 'tool' role?

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Treating assistant content as a single string and putting a tool call into JSON inside that string. The API expects a list of typed blocks; flat strings drop the structured schema and break the model's tool-call grounding.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.