D1 · Agentic Architecture › Cluster 3 · Tool Use

3.1 · The Tool Request/Result Cycle

The full round-trip: tool_use → run → tool_result → follow-up call

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.

StepWhoWhat happens
1 · RequestYouPOST /v1/messages with the user turn plus a tools list.
2 · tool_useClaudeResponds with stop_reason: "tool_use" and a tool_use block {id, name, input}.
3 · RunYouExecute the real function with input; capture its output.
4 · tool_resultYouAppend the assistant turn, then POST again with a user turn carrying a tool_result.
🔑 Because the API is stateless, you must append the whole 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.
The tool description is the single most important field for reliability. Claude reads the 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

sequenceDiagram participant App as Your code participant API as Messages API participant Tool as get_weather() App->>API: POST /v1/messages
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."
The agent loop (1.3) is just this round-trip repeated: keep calling until stop_reason is end_turn instead of tool_use.

EXAM TRAPS

Trap: Thinking Claude "runs" the tool. → Claude only emits a request. The API is stateless; your code executes the function and returns the result. Nothing runs server-side.
Trap: Forgetting to append the assistant's 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.
Trap: Under-writing the 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.