Structured Error Response Design
CoreImplement structured error responses for MCP tools · Difficulty 3/5
Structured error responses enable agents to make intelligent recovery decisions instead of failing generically or retrying blindly.
The Problem with Generic Errors
Returning "Operation failed" for every error prevents the agent from:
MCP isError Flag
The MCP isError flag pattern communicates tool failures back to the agent, distinguishing errors from successful empty results.
Error Categories
| Category | Examples | Retryable | Agent Action |
|---|
|----------|----------|-----------|--------------|
| Transient | Timeout, service unavailable | Yes | Retry with backoff |
|---|---|---|---|
| Validation | Invalid input, bad format | No | Fix input and retry |
| Business | Policy violation, limit exceeded | No | Inform user, suggest alternative |
| Permission | Unauthorized, forbidden | No | Escalate or request credentials |
Structured Error Metadata
{
"isError": true,
"errorCategory": "business",
"isRetryable": false,
"message": "Refund exceeds $500 policy limit",
"userFriendlyMessage": "This refund requires manager approval. Let me escalate this for you."
}Access Failures vs Valid Empty Results
Critical distinction:
Confusing these leads to either missed data (treating failures as empty) or wasted retries (retrying successful empty queries).
Local Error Recovery
Subagents should handle transient failures locally (retries, fallbacks). Only propagate to the coordinator errors that cannot be resolved locally, along with:
Key Takeaways
- ✓Use the MCP isError flag to distinguish tool failures from successful empty results
- ✓Include errorCategory, isRetryable, and human-readable descriptions in error responses
- ✓Generic 'Operation failed' errors prevent intelligent agent recovery
- ✓Handle transient errors locally in subagents; propagate only unresolvable errors with context