Preview a bulk action

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

Annotations already establish readOnly/idempotent/non-destructive, and the description pays for itself with details annotations cannot carry: the required auth scopes (read + modify, delete for trash) and the per-call caps (50 on Free, 500 paid). It also confirms 'Changes nothing', which is consistent with readOnlyHint.

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?

Six tight sentences, front-loaded with what it selects and what it returns, then safety, then procedure, then constraints. No filler and nothing repeated from the annotations or schema.

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 10-parameter, nested-criteria preview tool with an output schema, the description covers selection mode, ordering, return contents, safety, scopes and quotas — everything needed to call it correctly. Anything omitted (e.g. scan_from continuation, batch reuse) is already documented in the schema.

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 80%, so the baseline is 3, but the description adds semantics not in the schema: the two selection modes (uids vs criteria) and the ordering guarantee ('oldest first'). That ordering detail is meaningful behavior an agent could not infer from the parameter list alone. The uids/criteria mutual exclusivity is only implied, not stated.

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 — selecting the exact messages a bulk action would act on — and pins the selection semantics (explicit uids or criteria, oldest first). It also distinguishes itself from the sibling it feeds by stating it returns a confirm ref for bulk_apply, so an agent can tell bulk_preview and bulk_apply apart 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?

Gives real operating context: 'Changes nothing. Show the preview to the owner' and a required scope (read and modify, delete for trash). The confirm-ref clause implicitly routes to bulk_apply. It stops short of an explicit when-not-to-use or a direct contrast with search_messages, so it is clear context rather than full routing.

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