mail_trash

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

With no annotations, the description carries the full burden and does so well: it flags the operation as destructive, explains the confirm/preview gate, discloses that EVERY copy across folders (INBOX, Sent, Archive) is moved, notes each Message-ID is re-checked before moving, and documents the ~35s bulk cap with a 'remaining' signal plus the re-run remedy. This is exactly the behavioral context an agent needs for a destructive bulk tool.

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?

Front-loaded with purpose and the destructive gate, then the mode semantics and limits. Dense and mostly waste-free, though the streaming clauses make it slightly run-on and some folder examples (INBOX, Sent, Archive) are illustrative rather than essential.

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?

No output schema, and the description compensates by describing the preview report, the 'remaining' field on bulk timeouts, and the per-copy identity re-check. It does not address recovery/undo or permission requirements, but for a move-to-Trash tool with a preview gate the coverage is close to sufficient.

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 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it groups message_id/file_path as 'one message' vs message_ids as 'many', states the 500-item bulk limit and the mail_find source, and notes copies span multiple folders. This meaningfully enriches the parameter contract.

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?

Opens with a specific verb+resource ('Move email to Trash') and immediately scopes the operation as destructive. An agent can distinguish this from siblings like mail_archive and mail_mark without inspecting schemas, and the single-vs-bulk modes are stated up front.

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?

Clearly states the confirm=true prerequisite, that omitting it yields a preview, and when to use the bulk message_ids path vs a single message_id/file_path. It also points to mail_find as the source for IDs. It stops short of naming a sibling alternative (e.g. mail_archive) for non-destructive moves, so it earns a 4 rather than a 5.

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