“Database error” is not enough information for an AI agent.
Was the input invalid? Was access denied? Did a pool timeout happen before execution? Did a mutation commit before the connection disappeared?
Those failures require different recovery behavior.
Return a stable error envelope with:
- code and category
- retryable: true or false
- bounded retry delay when relevant
- outcome: not_started, not_committed, committed, or unknown
- correlation ID
- a sanitized user message
Do not expose raw SQL, stack traces, connection strings, topology, or sensitive values.
The most important distinction is often transient failure versus unknown outcome.
A read query that never started may be safe to retry with backoff and jitter. A write that lost its response after commit must be reconciled with an idempotency key or execution receipt before another mutation runs.
Machine-readable policy should drive recovery. Human prose should explain it. The model should not infer retry safety from an exception sentence.
Full guide: MCP database tool error contracts
Top comments (0)