list_emails

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: returns paginated results with metadata (read/unread, flagged, etc.) and mentions the ProtonMail label quirk. This elevates transparency beyond annotations.

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?

Three sentences: first states purpose and return metadata, second gives alternative tool, third addresses ProtonMail nuance. No fluff, front-loaded with most important info. Each sentence earns its place.

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 list tool with 12 parameters fully described in schema, the description covers pagination, metadata format, and a special case. No output schema exists, but return details are adequately described via the metadata mention. Minor gap: doesn't mention total result count or pagination behavior explicitly, but schema provides page/pageSize limits.

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?

Input schema has 100% description coverage across 12 parameters. The description adds minimal extra meaning, primarily clarifying mailbox parameter semantics for ProtonMail (labels as folders). Baseline 3 is appropriate since schema already does most of the work.

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 action: 'List emails in a mailbox with optional filters.' It uses a specific verb ('list') and resource ('emails'), and distinguishes it from siblings like get_email (full content) and search_emails implicitly. The ProtonMail note differentiates usage for label-based email access.

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?

Explicitly tells when to use get_email instead: 'Use get_email to fetch full body content.' Also provides context for ProtonMail: 'use list_labels to discover them, then list_emails with mailbox="Labels/X".' This gives clear guidance on alternatives and prerequisites.

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