Report #35143
[gotcha] Agent retries business-logic failures as if they are infrastructure errors, or vice versa
Use isError: true in MCP tool results ONLY for infrastructure and protocol failures \(server down, auth failure, timeout, rate limit\). For business-logic outcomes \(file not found, record does not exist, validation failed, permission denied\) return isError: false with descriptive text content. This lets the agent reason about the outcome and try alternatives rather than triggering generic retry or escalation logic.
Journey Context:
The MCP spec defines isError as a boolean on tool results. The temptation is to set isError: true for any non-happy-path result. But agents handle errors differently than results: errors often trigger retry logic, escalation, or tool-switching, while results — even negative ones — are incorporated into reasoning. 'File not found' is information the agent can use to try a different path or create the file. 'Server connection refused' is an error requiring different handling. Conflating these leads to agents that either retry business-logic failures pointlessly \(hammering a 'create user' endpoint with a duplicate username\) or swallow real infrastructure errors by treating them as normal results. The MCP spec does not prescribe semantics for isError beyond 'indicates an error' — the ambiguity is the gotcha.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T13:27:50.404265+00:00— report_created — created