CONCEPT One tool call is a round-trip, not an event
Tool use is not the model "running a function." The Messages API is stateless:
Claude never executes anything. It asks for a tool by emitting a tool_use block; your
code runs the actual function and sends the answer back on the next call. A single tool invocation is a
four-step round-trip that spans two API requests.
| Step | Who | What happens |
|---|---|---|
| 1 · Request | You | POST /v1/messages with the user turn plus a tools list. |
| 2 · tool_use | Claude | Responds with stop_reason: "tool_use" and a tool_use block {id, name, input}. |
| 3 · Run | You | Execute the real function with input; capture its output. |
| 4 · tool_result | You | Append the assistant turn, then POST again with a user turn carrying a tool_result. |
response.content
(the assistant's tool_use block and any text) to messages before you send the result. Drop it
and the next call has no memory of what Claude asked for.description to decide when to call the tool — be prescriptive about the trigger condition,
the inputs, and what it returns. A vague description is the #1 cause of missed or spurious tool calls.DIAGRAM The round-trip in sequence
messages + tools API-->>App: stop_reason: "tool_use"
tool_use {id, name, input} Note over App: append WHOLE response.content App->>Tool: run get_weather(input) Tool-->>App: "18°C, clear" App->>API: POST again (user turn)
tool_result {tool_use_id, content} API-->>App: stop_reason: "end_turn"
final text answer
CODE A single-tool round-trip, end to end
One tool, one round-trip. Note the two create() calls and the whole-content append between them.
# The tool DEFINITION — description tells Claude WHEN to call it. TOOLS = [{ "name": "get_weather", "description": "Get the current weather for a city. " "Call this whenever the user asks about weather, " "temperature, or conditions in a named place.", "input_schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, }] messages = [{"role": "user", "content": "What's the weather in Paris?"}] # --- Request 1: Claude asks for the tool --- resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, ) # resp.stop_reason == "tool_use" # Append the WHOLE assistant turn (stateless API — it has no memory). messages.append({"role": "assistant", "content": resp.content}) # --- Step 3: YOU run the tool the model chose --- tool_use = next(b for b in resp.content if b.type == "tool_use") result = get_weather(**tool_use.input) # -> "18°C, clear" # --- Step 4: return the result in a USER turn --- messages.append({"role": "user", "content": [{ "type": "tool_result", "tool_use_id": tool_use.id, # MUST match the tool_use id "content": result, }]}) # --- Request 2: Claude turns the result into a final answer --- final = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, ) # final.stop_reason == "end_turn"; text = "It's 18°C and clear in Paris."
stop_reason is end_turn instead of tool_use.EXAM TRAPS
tool_use before sending the result. →
The stateless API needs the whole response.content in messages, or the follow-up
call has no context and 400s / drifts.description. → It's the text Claude reads to decide
when to call the tool. Vague descriptions cause missed or spurious calls — no code change fixes that.PRACTICE
Q1 · How many API requests does one tool call take, and why?
Two. Request 1 returns the tool_use block; you run the tool locally; request 2
sends the tool_result so Claude can produce the final answer. The statelessness is why both requests must
carry the full running messages history.
Q2 · Your follow-up call keeps behaving as if the tool was never requested. What did you likely skip?
You skipped appending the assistant turn (response.content with the
tool_use block) before adding the tool_result. The API is stateless — without that block the
tool_result references nothing.
Q3 · Claude never calls your perfectly-coded tool. First thing to check?
The description. Claude decides whether to call based on the description text, not the function body. Make it prescriptive about when to call it.