D2 · Tool Design & MCP › Cluster 1 · Tool Use Fundamentals

1.1 · What Tool Use Is & the Request/Result Flow

The four-step tool loop

CONCEPT Tool use lets Claude call functions you define

Tool use (a.k.a. function calling) lets Claude request an action from your code instead of answering only from its own knowledge. You pass a list of tools alongside your messages; Claude decides — per turn — whether a request maps to one of those tools. When it does, Claude does not run the tool itself. It emits a structured tool_use block describing the call, and your application executes it and hands the result back.

🔑 The Messages API is stateless. There is no hidden "tool session" — you replay the full conversation (including the assistant's tool_use and your tool_result) on every request. Tool use is a structured request/response protocol layered over the ordinary /v1/messages call.

CONCEPT The four-step loop

Every tool call is the same round trip. Memorize the sequence — the exam tests each edge of it.

StepWho actsWhat happens
1 · SendYouCall the API with tools=[…] and the user messages.
2 · RequestClaudeResponds with stop_reason: "tool_use" and one or more tool_use blocks (each with an id, name, and input).
3 · ExecuteYouRun the tool in your code, then send the result back as a tool_result block inside a user-role message.
4 · ContinueClaudeReads the result and either answers (stop_reason: "end_turn") or calls another tool — repeat until done.
The loop terminates when Claude stops asking for tools — i.e. when stop_reason is end_turn rather than tool_use. That check is what turns a single call into an agentic loop.

DIAGRAM The request/result round trip

sequenceDiagram participant You as Your app participant API as Claude (Messages API) You->>API: 1. tools=[...] + messages API-->>You: 2. stop_reason "tool_use"
tool_use{id, name, input} Note over You: 3. Execute the tool
in YOUR code You->>API: 3. user msg: tool_result{tool_use_id, content} API-->>You: 4. stop_reason "end_turn"
text answer Note over You,API: Loop steps 2-3 until stop_reason != "tool_use"

CODE One full round trip in Python

Define a tool, let Claude call it, run the lookup, and return the result. Note that the assistant's response.content is appended verbatim and the result goes back in a user turn.

import anthropic, json
client = anthropic.Anthropic()

tools = [{
    "name": "get_weather",
    "description": "Get the current weather for a given location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
    },
}]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# 1. Send. 2. Claude returns stop_reason "tool_use".
resp = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                               tools=tools, messages=messages)
tool_use = next(b for b in resp.content if b.type == "tool_use")

# 3. Execute in YOUR code, then return a tool_result in a USER message.
result = "15 °C, partly cloudy"  # your real lookup goes here
messages += [
    {"role": "assistant", "content": resp.content},
    {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": tool_use.id, "content": result}
    ]},
]

# 4. Continue — Claude uses the result to answer (stop_reason "end_turn").
final = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                                tools=tools, messages=messages)

TRADE-OFFS Hand-write the loop vs. let the SDK run it

✅ SDK Tool Runner

  • client.beta.messages.tool_runner(...) drives steps 2–4 for you
  • Less boilerplate; schemas generated from function signatures
  • Still exposes per-turn hooks for approval / interception

⚠️ Manual loop

  • You own every step — maximum control over transport & shape
  • Needed for control the runner doesn't expose, or to avoid a beta dependency
  • More code, and easy to drop a tool_result or mis-order turns
Both approaches call the same /v1/messages endpoint. The loop is identical; the only question is who writes it.

EXAM TRAPS

Trap: "Claude runs the tool." → No. Claude only requests a client tool via a tool_use block; your code executes it and returns the tool_result. (Server tools are the exception — see 1.5.)
Trap: Returning the tool_result in an assistant message. → Tool results always go in a user-role message. The assistant turn holds the tool_use; the user turn holds the tool_result.
Trap: Thinking the loop ends after one call. → It repeats until stop_reason is no longer "tool_use". A single request can trigger many tool-use turns.
Trap: Assuming the API remembers prior turns. → It's stateless. Resend the full history — including the assistant's tool_use and your tool_result — on every request.

PRACTICE

Q1 · What stop_reason signals that Claude wants to call a tool?

stop_reason: "tool_use". The response then contains one or more tool_use blocks. You execute them and reply with tool_result blocks; the loop continues until stop_reason is "end_turn".

Q2 · In which message role does a tool_result go, and why?

In a user-role message. From Claude's perspective, the tool output is new information coming from the environment/user side of the conversation, not something the assistant produced. The assistant turn carries the tool_use; the user turn carries the tool_result.

Q3 · Name the four steps of the tool loop in order.

(1) Send tools + messages; (2) Claude requests a tool via stop_reason: "tool_use"; (3) you execute and return a tool_result in a user message; (4) Claude continues, either answering or calling another tool. Repeat until stop_reason != "tool_use".