Gmail MCP has clear verb-based naming (gmail_list_messages, gmail_send_message) and reasonable parameter schemas with type definitions. However, descriptions are generic and lack LLM-optimization guidance. Parameter descriptions exist but are minimal (10-30 chars). Output schemas are not formally documented, responses are inferred from code. Error handling returns structured objects but lacks recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Missing idempotency guidance for write operations. Baseline: avg tool description ~194 chars; these average ~60 chars. Avg params per tool: 4 (matches baseline). No pagination support despite list operations.

• Expand tool descriptions to 100-200 chars. Example: 'gmail_list_messages: List Gmail messages matching an optional search query. Use this for broad queries (e.g., is:unread, from:[email protected]). For filtered searches by sender/subject/date, use gmail_search_messages instead. Returns message summaries with ID, sender, subject, date, and unread status.'
• Add formal output schema documentation to each tool. Use JSON Schema format in the tool definition or docstring. Example: 'Returns: {success: bool, count: int, messages: [{id: str, from: str, subject: str, date: str, is_unread: bool}], error?: str}'
• Add tool annotations via FastMCP. Mark gmail_send_message and gmail_mark_as_read with destructiveHint=true. Mark all read-only tools with readOnlyHint=true. This enables agents to reason about side effects.
• Implement pagination: add page_token/next_cursor to list/search responses. Accept page_token parameter in gmail_list_messages and gmail_search_messages. Document: 'Omit page_token for first page; use returned next_cursor to fetch subsequent pages.'
• Enhance error messages with recovery hints. Example: 'Invalid message ID. If you have a subject or sender, try gmail_search_messages() first to find the message ID.' For auth errors: 'Authentication failed. Verify NANGO_CONNECTION_ID and NANGO_INTEGRATION_ID environment variables are set.'