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

Annotations only cover the safety profile (readOnly/idempotent/openWorld); the description goes far beyond by disclosing that results mix indexed and provider matches, explaining nextCursor semantics (the cursor may advance provider traversal even when messages is empty), pendingAccountIds, semanticPending, and the bounded nature of waitForFresh. This is exactly the extra 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?

Purpose is front-loaded, but the body is a dense, run-on block: the retry-with-identical-filters-and-waitForFresh:false instruction is effectively stated twice, and the semanticPending/pendingAccountIds/freshness distinctions are repeated. Much of it earns its place given the async indexing model, but it is bloated and could be tightened considerably.

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?

With no output schema, the description carries the return-value burden and does so: it describes compact summaries, messages/nextCursor, pendingAccountIds, semanticPending, failures, and stale/refreshing flags, and warns that stale or pending results are not proof of an empty mailbox. Nothing critical for correct invocation is missing.

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 only 25%, so the description must compensate and largely does for the hardest parameters: folderId/accountId coupling, cursor continuation rules, waitForFresh and the cached/partial deadline behavior. However, the filter-style params (to, from, subject, after/before, isRead, isStarred, hasAttachments) remain undocumented in both the schema and the description, leaving a 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 and resource ('Search connected mailboxes') and immediately distinguishes its role from the sibling get_email ('Results are compact summaries; use get_email to read a message'). An agent can tell what this returns versus what get_email returns without opening either schema.

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 guidance on when and how to use it: default scope is Inbox when folderId is omitted, accountId defaults to all connected mailboxes, and searching Sent/Drafts requires first calling list_mail_folders and passing that folderId with the same accountId. It also explicitly states there is no all-folders selector and tells the agent to prefer cursor continuation over a new search.

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