Claude Opus 4.8 tool use changes how you architect agent loops. The model emits multiple tool_use blocks in a single assistant turn and recovers from tool errors without collapsing the conversation. This guide gives an ordered path to ship parallel invocation and error recovery in production.
Define tools with explicit side-effect semantics
Start with a strict JSON schema. Claude reasons better when each tool declares idempotency and failure modes. Ambiguous parameters cause the model to serialize calls that should be parallel.
{
"name": "fetch_invoice",
"description": "Fetch an invoice by ID. Idempotent read.",
"input_schema": {
"type": "object",
"properties": {
"invoice_id": {"type": "string"},
"currency": {"type": "string", "enum": ["USD", "EUR"]}
},
"required": ["invoice_id"]
}
}Attach tools to the request. Do not overload a single tool with optional branches; separate concerns so the model can pick two independent tools in one pass. A tool that both reads and writes should be split—get_balance and transfer are clearer than account_action.
Prompt for parallelism without forcing it
Claude Opus 4.8 tool use decides call cardinality from context. You can nudge it by stating “fetch all required data before computing” but avoid hard constraints. Forcing parallelism where dependencies exist creates silent failures.
import anthropic
client = anthropic.Anthropic()
resp = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
tools=[fetch_invoice, calc_tax],
messages=[{"role": "user", "content": "Get invoices INV-1 and INV-2, then total tax."}]
)Inspect resp.content for multiple tool_use blocks:
tool_calls = [b for b in resp.content if b.type == "tool_use"]
print(len(tool_calls)) # may be 2The assistant message may contain interleaved text and tool calls. Parse defensively—never assume the first block is a tool call.
Anatomy of a parallel assistant turn
A real response with two independent reads looks like this:
{
"role": "assistant",
"content": [
{"type": "text", "text": "Fetching both invoices."},
{"type": "tool_use", "id": "tu_1", "name": "fetch_invoice", "input": {"invoice_id": "INV-1"}},
{"type": "tool_use", "id": "tu_2", "name": "fetch_invoice", "input": {"invoice_id": "INV-2"}}
]
}Your executor must handle N blocks, not one. This is the core shift from older single-call patterns.
Execute independent tools concurrently
Run independent calls with an async gather. Never block on the first tool if the model emitted others. The risk: tools that share mutable state. Mark those as sequential in the description.
import asyncio
async def run_tool(block):
if block.name == "fetch_invoice":
return await db.get(block.input["invoice_id"])
if block.name == "calc_tax":
return await tax_svc.compute(block.input)
raise ValueError(f"unknown tool {block.name}")
async def execute_parallel(blocks):
return await asyncio.gather(*(run_tool(b) for b in blocks), return_exceptions=True)Using return_exceptions=True keeps one failing tool from killing the batch. You inspect results afterward and convert exceptions to error results.
If a tool depends on another’s output, the model should not have parallelized. Detect violations by checking input references; if calc_tax input includes a value that only fetch_invoice produces, serialize and warn in logs.
Return results with correct tool_use_id
Each tool_result must reference the tool_use_id. Mismatches abort the turn. Batch results into one user message.
results = await execute_parallel(tool_calls)
user_msg = {"role": "user", "content": []}
for b, r in zip(tool_calls, results):
if isinstance(r, Exception):
user_msg["content"].append({
"type": "tool_result",
"tool_use_id": b.id,
"content": f"error: {r}",
"is_error": True
})
else:
user_msg["content"].append({
"type": "tool_result",
"tool_use_id": b.id,
"content": str(r)
})Error recovery: surface failures, don’t raise
Claude Opus 4.8 tool use handles is_error results gracefully. Return the exception as content with is_error: true instead of throwing from your handler. The model will retry with corrected arguments or switch tools.
try:
data = await db.get(block.input["invoice_id"])
except KeyError:
content = "invoice_id not found"
is_error = True
else:
content = str(data)
is_error = False
{"type": "tool_result", "tool_use_id": block.id, "content": content, "is_error": is_error}This keeps the conversation alive. In internal tests we saw the model correct a missing required parameter within one extra turn without explicit instruction. Do not auto-retry inside the tool and also return an error—that double-spends tokens.
Build a retry boundary
Unbounded retries blow token budgets. Track attempts per tool_use_id and cap at 3. After cap, return a structured error forcing the model to pick a fallback tool or ask the user.
attempts = {}
def record_attempt(tid):
attempts[tid] = attempts.get(tid, 0) + 1
return attempts[tid] <= 3
# in executor
if not record_attempt(b.id):
return {"type": "tool_result", "tool_use_id": b.id,
"content": "persistent failure after 3 attempts", "is_error": True}Tradeoff: a hard cap may stop a recoverable task. Expose the cap as config; raise it for idempotent reads, lower it for side-effecting writes.
Fault-injection testing
Validate recovery with a pytest hook that randomly fails a tool.
@pytest.mark.parametrize("fail_rate", [0.3, 0.8])
def test_recovery(fail_rate):
monkeypatch.setattr(db, "get", lambda x: (_ for _ in ()).throw(KeyError) if random() < fail_rate else {"amt": 10})
loop = AgentLoop(model="claude-opus-4-8")
out = loop.run("Get INV-1")
assert "tool_result" in str(out) # model kept goingIf the loop terminates early, your error mapping is wrong.
Common pitfalls and tradeoffs
Hidden dependencies
The model cannot see your DB foreign keys. If calc_tax needs both invoices, but fetch_invoice runs parallel, you may compute on partial data. Mitigate by having the tool itself request missing inputs, or prompt “only call calc_tax after all fetches return.”
Token bloat from verbose results
Parallel calls multiply payload size. Truncate large responses before sending tool_result. Claude does not need full HTML; send extracted fields. A 5-tool parallel turn with 2KB results each is 10KB of context per round-trip—expensive at scale.
Partial failure handling
If one of three parallel tools errors, do not discard the others. Return individual tool_result blocks with per-call error flags. The model can proceed with available data and flag the gap to the user.
Latency versus correctness
True parallelism cuts wall-clock time but increases chance of inconsistent snapshots (e.g., reading accounts during transfers). For financial agents, accept serial calls despite the latency cost. The model will obey a “must serialize” note in the tool description.
Observability
Log each tool_use_id with start/end time and token count of the result. When claude opus 4.8 tool use parallelizes, you should see overlapping spans. If spans are always serial, your prompts or schemas are throttling the model.
Routing and provider fallback
When you deploy this behind an inference gateway, ensure it forwards your model directive and supports fallback. n4n.ai exposes one OpenAI-compatible endpoint covering 240+ models and automatically routes to a healthy provider when Claude Opus 4.8 is rate-limited, so your agent loop keeps running without code changes. Honor cache-control hints to avoid re-paying for long tool schemas on every turn.
Production checklist
- Strict tool schemas with explicit idempotency and side-effect notes.
- Async executor with dependency guard and
return_exceptions. is_errorresults instead of raised exceptions.- Attempt caps per
tool_use_id, configured per tool class. - Truncated, field-level tool results to control token growth.
- Fault-injection tests in CI to prove recovery.
- Gateway fallback for provider degradation.
Ship the loop with these and claude opus 4.8 tool use becomes a reliable backend, not a demo.