manage_trash

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

With no annotations provided, the description fully discloses behavioral traits: dry_run defaults to True to prevent accidental deletion, a safety limit on max_deletes, and required flags like apply_to_all and confirm_empty. It also clarifies which parameters are not used for specific actions, ensuring no surprises.

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 appropriately sized and well-structured, with a brief overview followed by a clear list of arguments and return value. Every sentence adds value, and the organization makes it easy to parse.

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?

Given the tool's complexity (11 parameters, multiple actions, safety mechanisms) and the lack of schema descriptions, the description covers all necessary information: all parameters, their interplay, behavioral nuances, and return value. No gaps remain.

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?

Although the input schema has no parameter descriptions (0% coverage), the tool description includes a detailed docstring explaining each parameter's purpose, defaults, and usage conditions. This adds essential meaning beyond the raw schema, fully compensating for the lack of schema-level 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 clearly states the tool's purpose: managing trash operations including deleting emails or emptying trash. It distinguishes from sibling tools by focusing solely on trash-related actions, contrasting with other email manipulation tools like move_email or update_email_status.

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 provides explicit usage guidelines, including when to use dry_run for previews, required confirmation for empty_trash, and safety limits. It also explains which parameters are applicable or ignored for certain actions, offering clear context for choosing this tool over alternatives.

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