archive_email

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

It discloses reversibility and non-destructiveness ('REVERSIBLE', 'content is unchanged'), idempotency ('Safe to repeat'), and that it requires an API key. It also clarifies side effects ('does not mark read, reply, or notify'). This exceeds the annotations, which already claim destructiveHint=false and idempotentHint=true but do not mention the API key requirement or the one-message-per-call constraint. No contradiction with annotations found.

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 a series of seven sentences, each adding distinct information: purpose, usage, safety, side effects, idempotency, requirement, and scope. It is more verbose than the ideal two-sentence example, but every sentence contributes to the agent's understanding without redundancy. The front-loaded opening states the core purpose immediately.

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 tool with a single parameter, no output schema, and minimal annotation coverage, this description is exceptionally complete. It covers the outcome (move to archive), behavior (non-destructive, reversible, no side actions), constraints (requires API key, exactly one message), and repeatability. An agent has all necessary context to invoke the tool correctly.

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?

The parameter 'id' is fully documented in the schema (100% coverage) with the description 'Email ID to archive'. The tool description adds no specific elaboration about the parameter itself, though the note 'Affects exactly one message per call' indirectly confirms it refers to a single email. Given the schema covers the parameter adequately, a baseline of 3 is appropriate.

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 begins with 'Move one email out of the inbox and into the archive', a specific verb+resource that clearly defines the action. It distinguishes from siblings by specifying what it does not do (does not mark read, reply, or notify sender), making it unique from tools like send_email or reply_to_email.

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 'when to use' guidance: 'Use it to clear handled mail from the working inbox.' While it doesn't explicitly name alternative tools or say when not to use it, the behavioral limits (no reply, no notify) imply it is not for those actions. The use case is clear enough for an agent to decide when to apply it.

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