Gmail MCP server has 11 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-150 chars, mostly adequate) and input schemas with type definitions. However, output schemas are completely undocumented, LLMs cannot predict what fields to expect from responses, breaking tool chaining. Parameter descriptions lack actionable constraints (no enums for status fields, no format specs for IDs). Error handling is absent from tool definitions. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. Naming is verb-first and generally clear, but some tools like 'summarize_thread' conflate concerns (AI summarization + Gmail read). Missing pagination guidance for list_drafts and search_threads despite potentially large result sets.

• Document output schemas for all 11 tools. Specify field names, types, and whether fields are always present or conditional. Example: search_threads returns {threads: [{id, subject, snippet, timestamp}], total_count, next_cursor}.
• Add tool annotations to schema: mark send_message, create_draft, update_draft with destructiveHint=true; mark all read tools with readOnlyHint=true. This enables LLM retry logic and safety checks.
• Add min/max constraints to numeric parameters: maxResults (1-100), and document defaults in descriptions. Add format/pattern constraints to IDs and paths.
• Enhance error descriptions with recovery guidance. E.g., get_thread_details: 'If thread not found, verify threadId via search_threads(). Common causes: thread archived or deleted.'
• Split summarize_thread into two tools: get_thread_summary (returns cached/stored summary) and generate_thread_summary (calls OpenAI). Document OPENAI_API_KEY as a server-side secret, not a parameter.