Apple Mail MCP Server

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It successfully discloses return format behavior (nested dict vs flat dict) based on the summary_only flag, but omits other behavioral traits like side effects, permission requirements, rate limits, or caching behavior that would be relevant for a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses a clean, standard docstring format with clear Purpose-Args-Returns sections. It is front-loaded with the core purpose and contains no redundant text; every sentence provides specific operational detail or parameter documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 optional parameters, two return formats), the description is comprehensive. It documents all inputs and explains the return structure variations, even though an output schema exists (making the Returns section optional but helpful). It lacks only edge case handling or error condition documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage (only titles). The description fully compensates via the Args section, which clearly explains all three parameters: account as an optional filter, include_zero for zero-count inclusion, and summary_only for toggling between detailed and summary return formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Get[s] unread counts per mailbox for one account or all accounts' with specific verb and resource. It distinguishes granularity from siblings (get_inbox_overview, get_statistics) by emphasizing 'per mailbox' and noting it replaces a former tool, though it doesn't explicitly contrast with all current alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage guidance by explaining the summary_only parameter behavior ('When summary_only=True...'), helping users choose between detailed and summary modes. However, it lacks explicit when-to-use guidance versus sibling tools like get_inbox_overview or get_statistics, and mentions no prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.