D5 · Context & Reliability › Cluster 6 · Reliability: Degradation & Recovery

6.3 · Graceful Degradation & Partial Results

Some answer beats an error page

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.

🔑 The design question is "what's the most useful thing I can still return?" — not "did everything succeed?" A weather widget that can't reach the forecast API should show yesterday's cached temp with a "stale" badge, not blank out the whole page.

CONCEPT Isolate failures, then label them

Two rules make partial results safe: isolation and honesty.

PrincipleWhat it meansAnti-pattern it prevents
Isolate each sub-taskOne tool's error doesn't abort the othersA single failed tool_result tanks the whole turn
Return a tool_result with is_errorTell Claude the leg failed so it adapts around itSilently dropping a tool call → mismatched tool_use_id
Mark degradedFlag partial/stale output to the callerA partial answer read as complete & authoritative
Rank by valuePreserve the highest-value legs; drop the optional onesLosing the core answer to keep a nice-to-have widget
When a tool leg fails, return its 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).
⚠️ "Degraded" must be visible. An unlabeled partial answer is worse than an error — it looks authoritative while missing data, and someone downstream trusts it.

DIAGRAM One leg fails, the request survives

flowchart TD REQ["Agent turn: fan out"] --> T1["🟢 search_docs → ok"] REQ --> T2["🔴 weather_api → 503"] REQ --> T3["🟢 db_query → ok"] T2 --> ISO{"Isolate the failure"} ISO -->|"return tool_result
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
Degrade for optional or recoverable legs; hard-fail only when a required input is missing and a partial answer would be actively wrong.

EXAM TRAPS

Trap: Aborting the whole turn when one tool fails. → Isolate the leg: return its tool_result with is_error:true and keep the successful results. One failure shouldn't discard the rest.
Trap: Silently dropping a failed tool call. → You must still return a tool_result for every tool_use — an unmatched tool_use_id is a 400. Return an error result, don't omit the block.
Trap: Serving a partial answer as if it were complete. → Always mark it degraded. An unlabeled partial is read as authoritative and propagates missing data downstream.
Trap: Degrading a required input. → If the missing leg makes the answer wrong (not just thinner), fail loudly instead. Degrade optional/nice-to-have legs, not load-bearing ones.

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.