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.
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.
| Step | Who acts | What happens |
|---|---|---|
| 1 · Send | You | Call the API with tools=[…] and the user messages. |
| 2 · Request | Claude | Responds with stop_reason: "tool_use" and one or more tool_use blocks (each with an id, name, and input). |
| 3 · Execute | You | Run the tool in your code, then send the result back as a tool_result block inside a user-role message. |
| 4 · Continue | Claude | Reads the result and either answers (stop_reason: "end_turn") or calls another tool — repeat until done. |
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
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_resultor mis-order turns
/v1/messages endpoint. The loop is identical;
the only question is who writes it.EXAM TRAPS
tool_use block; your code executes it and returns the
tool_result. (Server tools are the exception — see 1.5.)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.stop_reason is no longer "tool_use". A single request can trigger many
tool-use turns.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".