Shrutam CCA-F Crash › Domain 2 › d2-l08-tool-error-handling English Hinglish →

Error Propagation in Tool Responses

Domain 2 · 20% ~12 min English narration

Scenario anchor

Imagine aap Aaranya IT BFSI ke ek large-scale Claude deployment pe kaam kar rahe hain — ek multi-tool agent jo ASX-India ke real-time trade reconciliation data fetch karta hai. Ek tool ka downstream API timeout ho jaata hai, aur agent quietly ek empty result return kar deta hai. Claude ko laga sab theek hai, aur usne ek faulty reconciliation summary generate kar di jo compliance team tak pahunch gayi. Yeh lesson precisely isi failure mode ko address karta hai — how tool responses must surface errors explicitly, not silently absorb them.

Key Takeaways

Always return a typed error object inside the tool response envelope — include error_code, message, and retryable flag — so Claude can reason about failure rather than hallucinate over a data gap.
Distinguish between hard errors (schema violation, auth failure) and soft errors (partial data, rate-limit) in your tool contract; Claude needs this signal to decide whether to retry, escalate, or degrade gracefully.
Never let a tool silently return success on failure — treating errors as a first-class response type is the MCP equivalent of an API gateway fault contract: explicit, versioned, and machine-readable.
Memory anchor: tool error handling in MCP = api-gateway-fault-contract — your tool's error schema is as load-bearing as its success schema; design both before writing a single line of handler code.

← Previous lesson Same lesson in Hinglish Next lesson → Back to overview