Search all mailboxes

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds two behaviors annotations do not: the search spans all connected accounts, and the return is ids rather than message content, implying a required follow-up call. It omits result caps, pagination, and how cross-account hits are ordered.

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 short sentences, zero padding, with the scope stated before the return-value note. Nothing could be removed without losing information.

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 one-parameter read tool with no output schema, the description covers scope, query dialect, and that the return is ids for fetch. Remaining gaps are pagination and result limits, which matter for a tool that fans out across every connected account.

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 coverage and a single documented parameter, the baseline is 3. The description restates that the query is Gmail syntax, which the schema already says ('Gmail search query'), so it adds little beyond confirming the query language.

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 and adds meaningful scope: 'every connected Gmail account' with Gmail query syntax. It stops short of distinguishing itself from the sibling search_emails, so the cross-account vs. single-account contrast is only implied rather than stated.

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?

The sentence 'Returns result ids for the fetch tool' gives a useful chaining instruction, which is real usage guidance. However, it never states when to prefer this over the sibling search_emails, nor any exclusion or preconditions.

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