An AI agent should never guess whether a database retry is safe

“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