Search Message Snippets

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

Annotations already declare readOnly, idempotent, non-destructive, open-world access, so the safety profile is covered. The description adds genuine context beyond them: results are snippets, not authoritative content, and must be re-read via a read tool before content claims. It does not discuss result ordering or what a snippet contains, which keeps it from a 5.

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?

Two compact clauses, with the core purpose front-loaded and the filter list and follow-up caveat following efficiently. Slight density in the filter enumeration, but nothing is wasted.

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?

For a 21-parameter search tool with an output schema and full annotation coverage, the description supplies the essential framing: it is a snippet search, filters exist, and results must be verified with a read tool. The heavy parameter detail is correctly delegated to the schema. Missing only peripheral behavior such as result ordering or snippet truncation.

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?

With 100% schema description coverage across 21 parameters, the schema already documents every filter precisely, including mailbox_id scoping and ISO 8601 dates. The description only enumerates filter categories (folder_id, keyword/not_keyword, dates, sender/recipient, unread, has_attachment) without adding syntax or semantics beyond the schema, so baseline 3 applies.

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 and resource ('search message snippets by query text'), which is clearly narrower than the message/thread listing siblings. It does not explicitly name an alternative like mailbox_list_messages, so the differentiation is implied by the snippet/search framing rather than spelled out.

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?

Gives concrete narrowing axes and, importantly, a workflow rule: use returned message IDs with a read tool before making content-specific claims. That is a real when-to-use / when-not-to-conclude instruction. It stops short of naming a sibling search/list tool to prefer in other situations.

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