CONCEPT Rung 2 of the recovery ladder
Retry (6.3) handles transient failures. When a failure is durable — the tool is down, the input is unsupported, retries exhausted — you climb to fallback. A fallback keeps the task moving on a lesser path instead of failing the whole request.
| Fallback | What it does | Use when |
|---|---|---|
| Alternate tool | Route to a second tool that serves the same need | The task still fully achievable another way (e.g. secondary search provider) |
| Skip | Omit the failed step and proceed | The step was optional / enrichment, not load-bearing |
| Degraded path | Return a partial or lower-fidelity result | A worse-but-useful answer beats no answer (e.g. cached data, coarser estimate) |
tool_result with "is_error": true and a short reason. The model then adapts —
tries a different tool, asks for clarification, or answers without that data — instead of hallucinating a result.DIAGRAM Fallback decision flow
retries (6.3)?"} R -->|Yes| OK["🟢 Use result"] R -->|No| A{"Alternate tool
available?"} A -->|Yes| ALT["🔵 Call alternate tool"] A -->|No| S{"Step optional?"} S -->|Yes| SKIP["🔵 Skip · proceed"] S -->|No| D{"Degraded result
acceptable?"} D -->|Yes| DEG["🔵 Degraded path
(cache / partial)"] D -->|No| ESC["🟣 Escalate to human (6.5)"] ALT --> IE["Return tool_result
is_error:true on failure
→ model adapts"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef fb fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef es fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class OK ok; class ALT,SKIP,DEG,IE fb; class ESC es;
CODE Alternate-tool fallback + is_error signal
Try the primary tool; on durable failure try an alternate; if that also fails, hand the model an error result so it can adapt rather than fabricate.
def run_tool(name, args): # Primary → alternate → signal failure to the model. try: return {"content": primary_search(args["q"])} except Exception: try: return {"content": backup_search(args["q"])} # alternate tool except Exception as e: # Degraded/skip: hand the model an ERROR so it adapts. return {"content": f"search unavailable: {e}", "is_error": True} # In the agent loop, attach is_error to the tool_result block: out = run_tool(block.name, block.input) tool_result = { "type": "tool_result", "tool_use_id": block.id, "content": out["content"], "is_error": out.get("is_error", False), # True → Claude sees the failure } messages.append({"role": "user", "content": [tool_result]})
is_error: true, the next turn's model sees "this tool failed"
and can pick another approach or explain the gap — turning a crash into graceful degradation.TRADE-OFFS Fallback vs. failing loudly
✅ Fallback / degrade
- Task still completes (partially) — better UX under partial outage
- Contains blast radius of one flaky dependency
⚠️ Silent fallback risk
- A degraded answer can look authoritative — mask the outage
- Wrong for high-stakes steps (payments, legal) — those should escalate, not silently degrade
- Needs surfacing: log + flag the reduced fidelity
EXAM TRAPS
is_error: true
so the model adapts. A silent empty result invites hallucination.PRACTICE
Q1 · Your primary geocoding API returns 503 after retries. The task can be done by a second provider. Which fallback?
Alternate tool — route to the backup geocoder. The task is still fully achievable, so prefer the equivalent path before skipping or degrading.
Q2 · A tool fails and you can't recover its data. What must you return to the model, and why?
A tool_result with "is_error": true and a brief reason. It tells
Claude the tool failed so it can adapt (different tool, ask the user, or answer without that data) instead of
fabricating a value.
Q3 · When is a degraded path the wrong choice?
For high-stakes or irreversible actions (payments, deletions, legal commitments). A silent degraded result there can cause real harm and look authoritative — escalate to a human instead (6.5).