search_messages

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so safety is covered. The description goes further with behavior annotations don't carry: a ~30-second scan cutoff on slow mailboxes, non-chronological mail order, and pagination instability under concurrent mailbox changes. That is genuinely useful disclosure for an agent driving a scan loop.

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?

Front-loaded with the core purpose, then three compact sentences of caveats, with no filler. The only friction is the 'next_offset' wording that doesn't line up with the schema's 'offset'.

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 7-parameter, no-output-schema search tool the description covers query semantics and scan/pagination caveats well, but leaves scan_limit, unread_only, and mailbox_path unexplained despite zero schema descriptions. Adequate but with clear gaps for an agent building correct calls.

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 description coverage is 0% across 7 parameters, so the description must compensate and largely does not. It clarifies query semantics (subject/sender, empty lists all) and implies pagination via offset, but says nothing about limit, scan_limit, unread_only, account_id, or mailbox_path, and the term 'next_offset' does not match the actual 'offset' parameter name.

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 (search), the fields searched (subject/sender, case-insensitive), and the scope (one mailbox), plus the empty-query behavior. It is clearly distinct from read_message but does not explicitly contrast itself with search_inboxes, leaving the sibling boundary to inference.

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 real operational guidance on continuation ('Continue with next_offset even if this page has no matches'), which is actionable, but never states when to choose this tool over search_inboxes or read_message, and gives no prerequisites. Usage is implied rather than framed.

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