search_messages

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so 'Changes nothing' is largely redundant. The valuable additions are behavioral: results are ordered newest first and carry summaries without bodies, which shapes how an agent consumes output. It still says nothing about pagination behavior or result caps, which matter for a search tool.

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?

A single dense sentence that front-loads the verb and resource, then packs filter scope and return shape into one clause; every clause carries information. The long conjunction chain is slightly hard to parse but wastes no words.

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?

An output schema exists, so return values need no explanation, but with 14 parameters and zero schema descriptions the description should cover pagination (limit/cursor) and the query vs bodyContains split, and it does neither. Adequate for filter discovery, incomplete for correct invocation of paged searches.

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 14 parameters, so the description must carry the semantics, and it does enumerate most filters (sender, recipient, subject, free text, mailbox, date range, unread, flagged, attachment, category), mapping them to the schema properties. However, it never explains limit or cursor, and does not distinguish 'query' from 'bodyContains', leaving two documented-but-ambiguous filters.

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?

Specific verb ('Searches') plus resource ('mail') with an enumerated list of filterable fields and the return shape ('message summaries without bodies'), which lets an agent distinguish it from get_message/get_thread/list_mailboxes by inference. It stops short of naming any sibling explicitly, so it is clear but not maximally differentiated.

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?

Usage is implied: search when you need to find messages, and use get_message (not named) when you need bodies, since results omit them. There is no explicit when-to-use statement, no guidance on combining filters, and no mention of how to page through results.

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