The server provides 3 tools with reasonable names (send_email, search_emails, read_email) that follow verb_noun conventions. Descriptions are present for all tools and most parameters, but they lack detail about constraints, error cases, and output structure. Schemas are properly typed in the source but lack explicit output documentation. Error handling is minimal, tools return generic strings instead of structured error messages with recovery guidance. No tool annotations (readOnlyHint/destructiveHint) are present. The send_email tool lacks critical security guidance (no mention of attachment path validation or potential injection vectors). Parameter descriptions are present but sparse, no mention of valid email formats, limits on attachment sizes, or what happens when attachments fail to read.

• Add explicit output schema documentation for all tools. Define the structure of returned data: 'send_email returns {success: bool, message_id: string, timestamp: string}'; 'search_emails returns {query: string, matches: [{uid: string, from: string, subject: string, date: string, url: string}], total: number}'; 'read_email returns {uid: string, from: string, to: list, cc: list, subject: string, body: string, html: bool, attachments: list}'.
• Add tool annotations to FastMCP decorators: @mcp.tool(annotations={'destructiveHint': True}) for send_email; @mcp.tool(annotations={'readOnlyHint': True}) for search_emails and read_email. This lets agents reason about side effects.
• Implement structured error responses instead of plain strings. Return JSON objects like {error: string, recovery: string, retryable: bool}. Examples: send_email backend failure → {error: 'Backend not configured', recovery: 'Run 'uvx claude-gmail-mcp-auth <credentials.json>'', retryable: false}; search_emails with invalid query → {error: 'Invalid Gmail search syntax', recovery: 'Consult Gmail search operators: from:, subject:, is:unread, etc.', retryable: false}.
• Add pagination to search_emails. Accept offset/limit parameters (default limit=10, max 50). Return total count and next_cursor. Document max_results as capped at 50 to prevent context window exhaustion.
• Expand parameter descriptions with validation rules: to/cc/bcc → 'RFC 5322 email address or comma-separated list. LLMs must pass valid emails.'; max_results → 'Integer between 1 and 50 (default 10). Controls how many emails to fetch per query.'; attachments → 'List of local file paths. Max 10 files per email. Supported: pdf, doc, docx, txt, jpg, png. Max 25 MB total. Files that cannot be read are logged and skipped.'; html → 'If true, body is interpreted as HTML; if false, sent as plain text. Default false.'.