Search multiple accounts

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered by structured data. The description adds genuine context beyond that: the batch cap of 20 and the per-account result grouping. It omits important behavior for a fan-out call such as partial failures (what happens if one account errors), per-account pagination via pageToken, and rate-limit behavior.

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 front-loaded sentence with no filler; the batch scope and the return grouping both land immediately. It is arguably too terse for a 14-parameter fan-out tool, but that is a completeness problem rather than a structural one.

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 14-parameter, multi-account fan-out operation, the description covers only the account count and result grouping. With 43% schema coverage, an output schema present, and annotations carrying safety, the missing pieces are the ones an agent most needs: per-account pagination semantics, partial-failure behavior, and how the many filter parameters combine with the portable query.

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 only 43% across 14 parameters, so the description is expected to compensate, but it does not. It mentions only the query ('one portable query') and the accounts cap; it says nothing about the accounts[].pageToken field for per-account paging, pageSize behavior across accounts, or how the filter parameters (from/to/subject/folder/starred) interact with the portable query syntax.

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?

The description names a specific verb (search) plus the distinctive scope (up to 20 accounts in one call) and the return shape (one result group per account), which clearly separates it from the single-account search_emails sibling. It never names that sibling explicitly, so the differentiation is inferred 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 'up to 20 accounts' bound implies this is the multi-account variant of search, giving an implied usage condition. However, there is no explicit statement of when to prefer this over search_emails, no guidance on when a batch is inappropriate, and no note on prerequisites (e.g., whether all accountIds must be authorized).

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