CONCEPT Return the best available answer, not an all-or-nothing failure
A multi-tool agent request is rarely one atomic call — it fans out across sub-tasks: search a doc, hit a weather API, query a database, summarize. If one of those legs fails, the naive design throws away the whole turn and returns an error. Graceful degradation is the opposite instinct: complete what you can, drop or stub what you can't, and return a partial result that's clearly marked as degraded — the user gets the four sub-answers that worked instead of zero.
CONCEPT Isolate failures, then label them
Two rules make partial results safe: isolation and honesty.
| Principle | What it means | Anti-pattern it prevents |
|---|---|---|
| Isolate each sub-task | One tool's error doesn't abort the others | A single failed tool_result tanks the whole turn |
Return a tool_result with is_error | Tell Claude the leg failed so it adapts around it | Silently dropping a tool call → mismatched tool_use_id |
| Mark degraded | Flag partial/stale output to the caller | A partial answer read as complete & authoritative |
| Rank by value | Preserve the highest-value legs; drop the optional ones | Losing the core answer to keep a nice-to-have widget |
tool_result with "is_error": true
and an informative message — Claude acknowledges the failure and works around it, rather than the harness silently
dropping the block (which breaks the tool_use/tool_result pairing).DIAGRAM One leg fails, the request survives
is_error:true"| MERGE["Merge available results"] T1 --> MERGE T3 --> MERGE MERGE --> OUT["🟠 Partial answer
marked DEGRADED
(weather unavailable)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class T1 ok; class T3 ok; class T2 bad; class OUT gate;
CODE Partial results with an is_error tool_result
Each leg is isolated; a failure becomes an is_error result, and the response carries a
degraded flag so callers never mistake it for complete.
def run_tools(tool_uses): results, degraded = [], [] for tu in tool_uses: try: content = execute(tu.name, tu.input) results.append({"type": "tool_result", "tool_use_id": tu.id, "content": content}) except ToolError as e: degraded.append(tu.name) # track what we lost results.append({"type": "tool_result", # still return the block! "tool_use_id": tu.id, # id must match the tool_use "content": f"Error: {tu.name} unavailable — proceed without it.", "is_error": True}) # Claude adapts around it return {"tool_results": results, "degraded": bool(degraded), # surface it to the caller "missing": degraded}
TRADE-OFFS Partial result vs. hard fail
✅ Graceful degradation
- User keeps the parts that worked
- One flaky tool can't sink the whole request
- Product stays usable during partial outages
⚠️ All-or-nothing
- Simpler: one success/fail path
- But one leg's failure wastes every other leg
- Unmarked partials mislead downstream consumers
EXAM TRAPS
tool_result with is_error:true and keep the successful results. One failure shouldn't
discard the rest.tool_result for every tool_use — an unmatched tool_use_id is a 400. Return
an error result, don't omit the block.PRACTICE
Q1 · An agent fans out to 4 tools; one returns a 503. What should the turn return?
The three successful results plus a partial answer marked degraded, noting the weather leg
was unavailable. Return the failed tool's tool_result with is_error:true so Claude
adapts around it — don't abort the whole turn.
Q2 · Why not just drop the failed tool_use block entirely?
Every tool_use needs a matching tool_result with the same
tool_use_id; omitting one is a 400 invalid-request error. Return an is_error result
instead — it keeps the pairing valid and tells the model the leg failed.
Q3 · When is graceful degradation the wrong choice?
When the failed leg is a required input and a partial answer would be actively wrong or misleading. Then fail loudly. Degradation is for optional/recoverable sub-tasks where a thinner-but-honest answer still helps.