This Gmail watch MCP server demonstrates solid tool organization with clear verb-noun naming (gmail_*) and Zod-based schema validation. However, the implementations reveal significant gaps in parameter descriptions, output schema documentation, and error handling guidance. Most tools lack explicit input schema visibility in parameter metadata, and descriptions, while present, are often too terse to guide LLM selection effectively. The tool composition is reasonable, single-responsibility tools like gmail_watch, gmail_send, gmail_list_watches, and gmail_update_watch are well-separated. However, gmail_send_and_watch combines send + watch creation in one call, which violates single-responsibility; this should be split or the combined behavior justified. Parameter validation is good (email format, enums, min/max constraints via Zod), but descriptions for individual parameters are missing or minimal. Output schemas are not documented in the source, the handler returns formatted JSON strings via `compactJson()` but the schema structure is not declared. Error handling is basic: environment variable checks throw generic errors ('Set GMAIL_WATCH_DEFAULT_WAKE_URL...') without recovery guidance. Security is handled well server-side (secrets via env vars, _hermesOrigin validation), but the `_hermesOrigin` parameter passing is inelegant and not documented for agents. The code uses tool annotations (readOnlyHint, idempotentHint) correctly for gmail_profile and gmail_watch, which aligns with current MCP patterns.

• Document the output schema for every tool. For gmail_send, explicitly state: 'Returns {messageId: string, threadId: string, timestamp: ISO8601}' (or actual fields). This lets LLMs chain to gmail_watch via threadId.
• Split gmail_send_and_watch into two separate tools (gmail_send_watch, gmail_send) with the option to compose them in a prompt, OR justify the atomic behavior in the description with a clear statement: 'Use this when you need send and watch to be race-safe; use separate tools otherwise.'
• Add parameter descriptions to all tools. For gmail_watch: 'labelIds: Array of Gmail label IDs to match (e.g., ["IMPORTANT", "SENT"]). If empty, all labels match.' For gmail_send_and_watch: 'permissions: Array of permission strings (e.g., ["read:email", "write:email"]). Empty array means default permissions.'
• Expand tool descriptions to answer: (1) What does it do? (2) When should I use it instead of similar tools? (3) What does it return? Example: 'gmail_send: Send a single email without setting up a watch. Use this for one-off messages. Returns messageId and threadId. (Unlike gmail_send_and_watch, this does not watch for replies.)'
• Add recovery guidance to error messages. Change: 'Set GMAIL_WATCH_DEFAULT_WAKE_URL and GMAIL_WATCH_DEFAULT_WAKE_SECRET' → 'GMAIL_WATCH_DEFAULT_WAKE_URL and GMAIL_WATCH_DEFAULT_WAKE_SECRET are not configured. Set these environment variables on the server and restart. Then retry this call.'
• Document _hermesOrigin clearly. Either hide it from LLMs by injecting it transparently server-side (remove it from tool parameter schema), or explain it: '_hermesOrigin: Object containing the originating Hermes gateway session metadata (injected automatically; do not provide). Used to link watches back to their originating chat context.'