Define a stable error contract for MCP tools

Goal

Let MCP clients choose a safe, predictable next action from the error type.

Steps

1. List possible argument errors, permission denials, unavailable dependencies, and unexpected exceptions. [mcp-errors] [mcp-tools]
2. Raise ToolError for recoverable tool failures; raise MCPError(code, message, data) for protocol-level rejection. [mcp-errors] [mcp-tools]
3. Do not return an error string; inspect CallToolResult.is_error, and keep unexpected crash details in server logs. [mcp-errors] [mcp-tools]
4. Log a controlled diagnostic ID server-side and keep full internal exceptions in protected logs. [mcp-errors] [mcp-tools]
5. Inject each failure class and verify client response, retry behavior, and log redaction. [mcp-errors] [mcp-tools]

How to verify

Every error class has a predictable response; stacks, tokens, and connection details appear in neither client responses nor ordinary logs.

Troubleshooting

If internal details leak, sanitize the exception mapping and separate protected server logs from client errors.