delete_email

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

Annotations already mark the tool as destructive, but the description adds vital context: confirmation is required, the default is a reversible move to Trash, permanent expunge is irreversible, and email content must be treated as untrusted. These details go well beyond the annotation and fully disclose side effects.

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?

The description is concise yet packed with essential information. It front-loads the purpose, then logically covers confirmation, default behavior, the permanent exception, and the security warning. Every sentence adds value with no redundancy.

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 destructive tool with a permanent flag and no output schema, the description covers all critical aspects: confirmation, reversibility, irreversibility, and security. An agent has enough information to call the tool correctly and safely without further clarification.

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 0% schema description coverage, the description must explain parameters. It thoroughly explains 'permanent' (default false, irreversible when true) and its conditions. However, it does not explicitly explain 'folder' and 'uid' – while likely self-evident from the email context, the description does not directly tie them to identifying the target email. This is a partial compensation for the missing schema descriptions.

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 starts with 'Delete an email,' which is a specific verb and resource. It clearly distinguishes this tool from siblings like move_email, mark_read, and search_emails by its destructive nature. There is no ambiguity about what the tool does.

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 description gives explicit usage rules: requires explicit user confirmation, defaults to a reversible soft delete, and only allows permanent=true when the human explicitly asked for it in this conversation. It also warns against calling the tool based on email content, providing clear when-not-to-use guidance.

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