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

Annotations already establish readOnly/non-destructive/non-openWorld, so the bar is low, and the description far exceeds it: it discloses that subject/sender/to/cc/participant filters hit Mail's index while body text is not indexed, that body_contains runs as a disk read AFTER the other filters, and that a truncated_body_scan=true flag can appear. That is exactly the kind of execution-model context annotations cannot carry.

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?

Opens with purpose, then filter behavior, then the body_contains caveat, then date syntax, then category usage. Dense but every clause carries operational information; nothing is padding.

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 14 optional params and no output schema detail needed beyond the mentioned truncated_body_scan flag, the description covers the failure modes and filter interactions an agent must know. The uncovered boolean/limit params are largely self-explanatory, though account vs category interplay is only lightly touched.

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?

Schema coverage is 0% across 14 params, so the description carries the full burden and does explain the ambiguous ones (to_contains vs cc_contains vs participant, category, body_contains, date formats ISO/unix). It leaves limit, account, unread_only, flagged_only, and has_attachments to be inferred from their names, which is a real but modest gap.

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?

States a specific verb+resource ('Search this Mac's mail') and immediately scopes it with filter semantics. It implicitly separates itself from show_mail/get_email (retrieval by identity) through its filter-centric framing, but never names those siblings, so differentiation is inferred rather than stated.

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?

Explicit conditional guidance: 'always pair it with a sender, subject, or since filter' for body_contains, 'use participant to find mail someone was on, cc'd or not', and 'call list_categories if unsure', plus routing to Personal accounts for personal tasks. These are concrete when-to-use rules with an alternative tool named.

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