“Tool failed” is not an error message.
It is a debugging tax.
When an AI agent queries a database through MCP, failures need to be structured enough for the agent to recover and specific enough for humans to audit.
A database tool can fail because:
- user lacks tenant or role scope
- query exceeds row/time/cost budgets
- requested metric is not approved
- data source is stale or unavailable
- result was partially returned
- write requires approval before execution
Those should not all collapse into the same generic error.
A useful MCP database error explains:
- what happened
- what was protected
- whether the request was denied, partial, stale, redacted, or too broad
- what narrower/safe retry is allowed
- the audit ID for review
Longer version: MCP tool errors for AI database agents
The happy path demos well. The unhappy path is what makes the system operable.