Claude replies with stop_reason: tool_use and one or more tool_use blocks: {id, name, input}.

You append the assistant message unchanged, then a user message whose content is tool_result blocks: {type:"tool_result", tool_use_id, content, is_error?} — one per tool_use, same ids, all in one message, and the tool_result blocks must come first in that message before any text. strict: true on a tool definition makes arguments conform exactly to the schema.

Descriptions are the most important part of a tool definition — say what it does, when to use it, what it returns, and what the arguments mean. Anthropic recommends 3–4+ sentences.

tool_choice: {"type":"auto"} (default, may answer without tools), {"type":"any"} (must call some tool), {"type":"tool","name":"x"} (must call that one — the JSON-schema trick), {"type":"none"} (no tools this turn). disable_parallel_tool_use: true forces one call at a time.

Parallel tool use: several tool_use blocks in one response — return all results in a single user message, in the same order.

Mark failures with is_error: true so Claude retries or explains instead of hallucinating a result.

Tool results can contain text and image blocks; keep them small — they are input tokens on every later turn.

Server tools (web search, web fetch, code execution, MCP connector) run on Anthropic's side; their results come back directly — you never send a tool_result for them. Text editor, bash, computer use and memory are Anthropic-defined client tools you still execute.

Add cache_control: {"type":"ephemeral"} to a block; the cached prefix is everything up to and including that block, in this order: tools → system → messages. Up to 4 breakpoints.

Pricing: cache write ≈ 1.25× base input (5-min TTL) or 2× (1-hour TTL); cache read ≈ 0.1× base input. Break-even after roughly two reads.

Minimum cacheable prefix depends on the model: 512 tokens (Opus 5, Fable 5.x), 1,024 (Sonnet 5, Sonnet 4.5/4.6, Opus 4.8), 2,048 (Opus 4.7), 4,096 (Opus 4.5/4.6, Haiku 4.5). Shorter prefixes are silently not cached.

Any change before the breakpoint (including tool definitions, images, or the model) invalidates the cache — stable content first, volatile content last. For chat, put the breakpoint on the latest message so the growing history is cached incrementally.

You confirm hits via usage.cache_read_input_tokens. Caching cuts cost and time-to-first-token; it never reduces output tokens.

Asynchronous: submit up to 100,000 requests (or ~256 MB), each with a custom_id; results within 24 h, usually much faster; 50% off input and output. Works with caching and tools.

Lifecycle: in_progress → ended; then per-request result type succeeded / errored / canceled / expired. Results are available for 29 days. Order is not guaranteed — always join on custom_id.

Use for evals, backfills, bulk classification, nightly summaries. Never for anything interactive.

invalid_request_error · you · fix the request (roles, max_tokens, schema)

authentication_error · you · check key/env

permission_error · you · key lacks access

not_found_error · you · wrong model id / resource

request_too_large · you · shrink input

rate_limit_error · volume · honour retry-after; backoff; batch

api_error · Anthropic · retry with backoff

overloaded_error · Anthropic · retry with backoff + jitter, degrade gracefully

Rate limits are per organisation per model: requests/min, input tokens/min, output tokens/min; tiers rise with spend. Headers report remaining quota.

The SDK retries 408/409/429/5xx and connection errors twice by default with backoff; tune max_retries and timeout. Make writes idempotent; log request ids (request-id header / _request_id) for support.

Long requests: stream, or the SDK may reject non-streaming calls expected to exceed ~10 minutes.

REGISTRY = {"get_time": get_time, "get_weather": get_weather}

def run(messages, tools, max_iter=8):

for _ in range(max_iter):

r = client.messages.create(model=MODEL, max_tokens=1024, tools=tools, messages=messages)

messages.append({"role":"assistant","content": r.content})

if r.stop_reason != "tool_use":

return r

results = []

for b in r.content:

if b.type == "tool_use":

try:

out = REGISTRY[b.name](**b.input)

results.append({"type":"tool_result","tool_use_id":b.id,"content":str(out)})

except Exception as e:

results.append({"type":"tool_result","tool_use_id":b.id,"content":str(e),"is_error":True})

messages.append({"role":"user","content": results})

raise RuntimeError("tool loop exceeded max_iter")

r = client.messages.create(

model=MODEL, max_tokens=300,

system=[{"type":"text","text": BIG_STABLE_CONTEXT,

"cache_control":{"type":"ephemeral"}}],

messages=[{"role":"user","content":"Question about the context…"}])

print(r.usage.cache_creation_input_tokens, r.usage.cache_read_input_tokens)

raw = client.messages.with_raw_response.create(model="claude-sonnet-5", max_tokens=64,

messages=[{"role":"user","content":"ping"}])

print(raw.headers["anthropic-ratelimit-input-tokens-remaining"])

tools = [{"name":"get_weather",

"description":"Get the current weather for a city. Use whenever the user asks about weather or temperature. Returns a short text summary.",

"input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}]

r = client.messages.create(model="claude-sonnet-5", max_tokens=1024, tools=tools,

messages=[{"role":"user","content":"Weather in Pune?"}])

tu = next(b for b in r.content if b.type == "tool_use")

r2 = client.messages.create(model="claude-sonnet-5", max_tokens=1024, tools=tools, messages=[

{"role":"user","content":"Weather in Pune?"},

{"role":"assistant","content": r.content},

{"role":"user","content":[{"type":"tool_result","tool_use_id":tu.id,"content":"31°C, humid"}]}])

results = []

for b in r.content:

if b.type == "tool_use":

try:

out = REGISTRY[b.name](**b.input)

results.append({"type":"tool_result","tool_use_id":b.id,"content":str(out)})

except Exception as e:

results.append({"type":"tool_result","tool_use_id":b.id,

"content":f"Error: {e}. Check the arguments and retry.","is_error":True})

messages.append({"role":"user","content": results}) # results first, then any text

r = client.messages.create(model="claude-sonnet-5", max_tokens=300,

system=[{"type":"text","text": BIG_STATIC_CONTEXT,

"cache_control":{"type":"ephemeral","ttl":"1h"}}],

messages=[{"role":"user","content":"Summarise section 3."}])

u = r.usage

print(u.cache_creation_input_tokens, u.cache_read_input_tokens, u.input_tokens)

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming

from anthropic.types.messages.batch_create_params import Request

batch = client.messages.batches.create(requests=[

Request(custom_id=f"ticket-{i}", params=MessageCreateParamsNonStreaming(

model="claude-haiku-4-5-20251001", max_tokens=200,

messages=[{"role":"user","content":t}])) for i, t in enumerate(tickets)])

while client.messages.batches.retrieve(batch.id).processing_status != "ended":

time.sleep(30)

for res in client.messages.batches.results(batch.id):

print(res.custom_id, res.result.type)