Gmail MCP server has basic tool definitions with schemas and descriptions, but significant quality gaps limit production readiness. All 6 tools have input schemas and descriptions present, but descriptions are in Chinese (non-standard for LLM optimization), lack actionable context, and are too brief (avg ~30 chars). Parameters lack type constraints (no enums for label operations, no min/max for max_results). Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors. Destructive operations (trash_gmail_message) lack confirmation patterns. No tool annotations (readOnlyHint, destructiveHint) despite clear risk stratification. Output schemas are not documented in the tool definitions themselves.

• Rewrite all tool descriptions in English, 80-150 characters, following pattern: 'ACTION: [verb] [object]. WHEN: [use case]. RETURNS: [key fields].' Example: 'Retrieve Gmail messages matching a query. Use to search inbox, find specific emails, or list recent messages. Returns message IDs, subjects, and senders with pagination support.'
• Add tool annotations to tool definitions: readOnlyHint=true for list/get tools, destructiveHint=true for trash_gmail_message, idempotentHint=true for get operations. This enables agents to reason about operation safety.
• Convert label_ids parameter in list_gmail_messages from string to array type. Add enum constraints to label operations if label IDs are known (e.g., INBOX, SENT, DRAFT). Document max_results constraint (1-100) in schema, not just code.
• Implement confirmation pattern for trash_gmail_message: add optional 'confirm' boolean parameter (default false). When false, return a confirmation prompt with message preview. Only execute trash when confirm=true. This prevents accidental deletions.
• Add structured error responses with recovery guidance. Example: 'Invalid message_id: "xyz". Message not found. Try list_gmail_messages() to find valid IDs.' Categorize errors as retryable (auth timeout) vs user-fixable (invalid ID) vs fatal (quota exceeded).