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. The description adds real behavior beyond that: results are grouped one group per account, and paging is per-account with an independent pageToken per entry, which is a non-obvious contract for a batched read.

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?

Three sentences, front-loaded with the batch scope before the filtering and paging details, with no filler. The only soft spot is the redundant restatement of the query syntax that the schema already documents in full.

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 for a batched read over up to 20 accounts the description omits important operational detail: what happens when one account fails or is unauthorized, whether query and folder combine, and whether results are ordered. These gaps matter more for a batch tool than for a single-account list.

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 67%, so roughly a third of parameters rely on the description. It reinforces query with a concrete example and clarifies that each accounts entry carries its own pageToken, but it offers only "use folder for a folder role" for the undocumented enum parameter, which adds little beyond the enum values themselves, and says nothing about pageSize, includeSnippet or includeSearchContext.

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 ("List or search emails") with an explicit batch scope ("in up to 20 accounts at once, with one result group per account"), which lets an agent distinguish it from the single-account list_emails and from the search-oriented siblings. It stops short of naming those siblings, so the differentiation is inferable 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 multi-account scope implies when to reach for this tool (more than one account), but there is no explicit when-not guidance and no named alternative such as list_emails or search_emails_batch. An agent must infer the routing decision from the phrase "up to 20 accounts at once" alone.

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