This Gmail MCP server demonstrates poor definition quality across multiple dimensions. While tool naming follows verb-noun conventions adequately, descriptions are inconsistent and often too brief. Parameter documentation is sparse, with many parameters lacking detailed descriptions about format, constraints, or expected values. Output schemas are not documented anywhere in the provided source. The tool set shows good conceptual coverage but lacks the rigor expected of production-grade tools. Only 7 of 14 tools have descriptions longer than 50 characters. No per-tool output schemas are visible. Error handling guidance is absent. The average tool score across the 14 tools is approximately 42, placing this server in the 'D' range.
Output schemas not documented. No tool returns a documented schema structure, LLMs cannot infer what fields to expect from responses, preventing downstream planning and data extraction.
Parameter descriptions lack constraint details. Parameters like 'query', 'max_results', 'email_id', 'attachment_id', 'save_path' have minimal descriptions without specifying expected formats, ranges, or validation rules. E.g., max_results accepts integer but no bounds (min/max) are stated.
Document the complete output schema for every tool. For example, list-emails should document: 'Returns {emails: [{id, subject, from, date, snippet, thread_id}], total_count, next_page_token}'. This enables agents to understand what data is available and plan downstream steps.
Expand descriptions to 50-200 characters for every tool. Add WHAT the tool does, WHEN to use it, and any prerequisites. Example: 'Read the full content of a single email by ID. Use after get-unread-emails or search-emails to fetch message details. Returns subject, body, sender, date, and attachments.'
Add constraint details to all parameter descriptions. For max_results, specify 'Integer 1-100; default 20'. For query, add 'Gmail search syntax; e.g., from:[email protected] is:unread label:important'. For attachment paths, state 'Local file paths; must exist and be readable'.
Standardize parameter names across similar tools. Use 'recipient_email' or 'recipient_id' consistently, not both. Similarly, all email identifier params should be 'email_id'.
Implement a confirmation pattern for irreversible operations. Add a 'dry_run: boolean' parameter to send-email, send-email-with-attachment, and trash-email. When true, return what would happen without executing. Require explicit confirmation before actual execution.
Add error recovery guidance. For example, send-email description should include: 'If recipient not found, call search-users() to verify email address. Common errors: invalid_recipient (verify email), quota_exceeded (retry later), auth_expired (refresh credentials).'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↓ 2 points across a rubric change (v1 → v2)
51/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
51
<=2025-11-25
v2
2026-03-09
D
53
-
v1
mark-email-as-read
writeauthsource verified65/100
Marks given email as read
open-emailread onlyauthsource verified63/100
Open email in browser
read-emailread onlyauthsource verified65/100
Retrieves given email content
search-emailsread onlyauthsource verified72/100
Search emails with custom query
send-emailwriteauthsource verified72/100
Sends email to recipient. Do not use if user only asked to draft email. Drafts must be approved before sending.
Inconsistent and brief descriptions. Tools like 'open-email' (35 chars), 'mark-email-as-read' (40 chars), 'read-email' (40 chars), 'list-drafts' (40 chars), 'list-labels' (40 chars) have descriptions under 50 characters, which is below the baseline average of 194 chars. Too short to guide LLM selection or explain when/why to use the tool.
No error handling guidance. Tools do not document what errors can occur, what they mean, or what the LLM should do next. Irreversible operations like send-email and trash-email lack confirmation/dry-run patterns.
Missing pagination documentation. list-emails and list-drafts accept page_size and page_token but do not document return structure (total count, next_cursor). Agents cannot know how many results exist or whether more pages are available.
Parameter naming inconsistencies. 'recipient_id' in send-email vs 'recipient' in create-draft for the same concept. This forces LLMs to reason about field mappings and may cause misuse across similar tools.
No type constraints on query/search parameters. 'query' in search-emails and get-unread-emails accepts arbitrary strings but does not document Gmail query syntax, examples, or valid operators. LLMs may construct invalid queries.
No confirmation pattern for destructive operations. trash-email and send-email (irreversible action) lack dry-run, preview, or explicit confirmation steps. Agents can accidentally delete or send emails without safeguards.
trash-emailsend-emailsend-email-with-attachment
Document pagination behavior. list-emails and list-drafts should explicitly state: 'Returns up to page_size results per call. To fetch all emails, check if next_page_token is present; if so, call list-emails again with the token. Returns total_count to show total available emails.'
Add example Gmail query patterns to search-emails and get-unread-emails descriptions. E.g., 'from:[email protected]', 'subject:urgent', 'is:unread', 'has:attachment'. Link to Gmail search operator documentation.
For attachment-related tools, clarify what formats are supported and any size limits. Example: 'Attachments up to 25 MB; common formats: PDF, DOCX, XLSX, PNG, JPG. Returns file name, MIME type, size in bytes.'
Add idempotency guidance. State which tools are safe to retry (read-email, search-emails) vs which have side effects (send-email, trash-email) that require safeguards against duplicate execution.