A quick reference for defining tools, running the agentic loop, and using the SDK tool runner with Claude.
name, description, and JSON Schema input_schema.stop_reason is tool_use, run the tool and send results back.tool_choice: {type: "tool"} to force a specific tool call instead of asking Claude for structured JSON.content block, including tool_use blocks, back in the next turn or you'll get a validation error.tool_result for a turn in a single message — splitting them across messages trains Claude to stop making parallel calls.input_schemaDefines a tool's inputs as JSON Schema with a name and description.
tools = [{
"name": "get_weather",
"description": "Returns current weather for a given city.",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}]tools parameterPasses the tools array to messages.create() alongside the prompt.
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "Weather in Tokyo?"}]
)description fieldTells Claude exactly when to call the tool, not just what it does.
"description": "Call this when the user asks about current weather."required arrayMarks which input fields Claude must always provide.
"required": ["city"]tool_use stop_reasonSignals Claude wants to call a tool instead of finishing the reply.
if message.stop_reason == "tool_use":
# extract tool calls, run them, send results backextract tool callsFilters the response content for tool_use blocks to find what Claude called.
tool_calls = [b for b in message.content if b.type == "tool_use"]tool_result blockPackages a tool's output with the matching tool_use_id to send back.
tool_results.append({
"type": "tool_result",
"tool_use_id": call.id,
"content": str(result)
})loop until end_turnRepeats the call-execute-respond cycle until Claude stops calling tools.
while message.stop_reason == "tool_use":
message = client.messages.create(...)@beta_toolTurns a plain Python function into a tool with an auto-generated schema.
from anthropic.lib.beta import beta_tool
@beta_tool
def get_weather(city: str) -> str:
"""Returns current weather for a given city."""
return f"Sunny, 22C in {city}"tool_runner()Runs the full call-execute-loop cycle automatically until Claude is done.
runner = client.beta.messages.tool_runner(
model="claude-opus-4-8",
max_tokens=1024,
tools=[get_weather],
messages=[{"role": "user", "content": "Weather in Tokyo?"}]
)until_done()Blocks until the loop finishes and returns Claude's final response.
final_message = runner.until_done()
print(final_message.content[0].text)tool_choice: autoLets Claude decide whether to call a tool; this is the default.
tool_choice={"type": "auto"}tool_choice: toolForces Claude to call one specific named tool on this turn.
tool_choice={"type": "tool", "name": "get_weather"}tool_choice: noneDisables tool calls mid-conversation once you have the data you need.
tool_choice={"type": "none"}disable_parallel_tool_useForces exactly one tool call per turn when call order matters.
tool_choice={"type": "auto", "disable_parallel_tool_use": True}Give the tool a name, a clear description of when to use it, and an input_schema written as JSON Schema. Claude reads the description to decide whether and when to call the tool, so be specific about the trigger condition, not just what the tool does.
The response comes back with stop_reason: "tool_use" and one or more tool_use content blocks containing the tool name, input, and an ID. Execute the tool yourself, then send the result back as a tool_result block with a matching tool_use_id.
Use the tool runner for most custom-tool agents — it handles the call-execute-loop cycle automatically and still gives you hooks for approval gates and logging. Write a manual loop only when you need full control over the request shape or want to avoid the beta dependency.
Set tool_choice to {"type": "tool", "name": "your_tool"} to require that exact tool on the next turn. Use {"type": "any"} to require some tool call, or {"type": "none"} to disable tools mid-conversation.
Yes — by default Claude can request multiple tool calls in a single turn, and your code should execute them and return every result in one combined message. Set disable_parallel_tool_use: true on tool_choice if your workflow needs exactly one tool call per turn.
tool_calls = [b for b in message.content if b.type == "tool_use"]
for call in tool_calls:
print(call.name, call.input, call.id)Build a Weather Tool Loop
Defines a weather tool, sends a prompt, and runs the tool_use loop until Claude returns a final text answer.
import anthropic
client = anthropic.Anthropic()
tools = [{
"name": "get_weather",
"description": "Call this when the user asks about current weather in a city.",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
}]
messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]
message = client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages)
while message.stop_reason == "tool_use":
tool_calls = [b for b in message.content if b.type == "tool_use"]
messages.append({"role": "assistant", "content": message.content})
results = [{"type": "tool_result", "tool_use_id": c.id, "content": "Sunny, 22C"} for c in tool_calls]
messages.append({"role": "user", "content": results})
message = client.messages.create(model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages)
print(message.content[0].text)Always resend the full assistant content block, including tool_use blocks, on the next turn.