list_mailboxes

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds context about returning mailboxes, folders, and label IDs, which is useful but not critical beyond the safety profile already declared.

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?

Two concise sentences: the first states the purpose, the second provides usage guidelines. No wasted words, front-loaded with key information.

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 no parameters, no output schema, but rich annotations, the description fully covers the purpose and usage. It hints at return values (mailboxes, folders, label IDs), making it complete for a simple list operation.

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 input schema has 0 parameters with 100% description coverage. Baseline is 4 per guidelines as no compensation is needed. The description does not need to add parameter information.

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 states 'List the mailboxes, folders, and label IDs in the connected Fastmail account,' which is a specific verb and resource. It also distinguishes from siblings by noting not to use for recent messages or inbox contents, and suggests alternatives.

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 explicitly provides when to use: 'when the user wants mailbox names, wants to choose a destination for moving or labeling email, or asks what folders exist.' It also gives clear when-not and alternatives: 'Do not use when the user wants recent messages or inbox contents; use get_recent_emails, list_emails, or search_emails instead.'

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