MCP server for analyzing and retrieving emails from macOS Mail application
Two tools with basic verb-noun naming (check_email_for_hours, check_latest_emails) but significant quality gaps. Tool descriptions are present but generic (34-45 chars, below 50-char minimum for clarity). Input schemas visible with type declarations (string, integer, array) but parameter descriptions are minimal and lack actionable constraints. No output schema documented, responses are JSON strings, not structured objects. No error handling guidance; AppleScript failures return raw RuntimeError. No pagination support despite potentially large result sets. Parameter 'hours' is a string (should be integer); 'exclude_subjects' defaults to None but description says 'optional, defaults to SUBJECT_EXCLUSIONS', confusing and contradictory. No tool annotations (readOnlyHint present in metadata but not in schema). Missing per-tool composition guidance.
Get emails from the last specified hours, excluding certain subjects.
Get the latest n emails, excluding certain subjects.
Parameter 'hours' declared as string but semantically an integer. LLM may pass '24' or 'twenty-four' unpredictably. Should be integer type with min/max bounds (e.g., 1 - 8760).
No output schema documented. Tools return JSON strings, not structured objects. LLM cannot plan downstream operations or extract fields reliably. Responses should declare field types (subject: string, sender: string, date_sent: ISO8601, content: string).
Tool descriptions are 34 - 45 characters, below the 50-char minimum for LLM clarity. 'Get emails from the last specified hours, excluding certain subjects' lacks WHEN to use, WHAT it returns, and HOW it differs from check_latest_emails.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 38 | 2026-07-28+ | v2 |
Parameter 'exclude_subjects' description contradicts implementation: says 'defaults to SUBJECT_EXCLUSIONS' but code checks 'if exclude_subjects is None'. Default value in schema is null, not the list. Confusing for LLM.
No error recovery guidance. AppleScript failures raise RuntimeError with stderr. LLM receives 'AppleScript failed: ...' with no actionable next step (retry? check Mail.app? ask user?). Should categorize errors and suggest recovery.