search_messages

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

With no annotations, the description carries full burden. It discloses that content search may trigger full downloads, can time out, and that Mail.app loads all matches into memory before applying the limit, causing slowness on large mailboxes.

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?

Description is informative and well-structured, front-loaded with purpose and then behavioral details. Every sentence adds value, though slightly long.

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?

No output schema, so description should indicate return structure. It omits what the results look like (e.g., message IDs, fields). Missing pagination or ordering info. Adequate but incomplete.

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 100%, baseline 3. The description adds value by explaining which fields are fast vs slow, performance implications, and narrowing strategies, going beyond schema descriptions.

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 it searches messages by subject, sender, or content, with specific verb and resource. It distinguishes between fast metadata fields and slower content search, differentiating it from sibling tools like list_messages.

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?

Provides explicit guidance to prefer 'subject' or 'sender' for fast lookups, warns about content search performance and timeouts, and advises narrowing results with mailboxName and accountName. Lack of explicit alternatives to other tools keeps it from a 5.

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