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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not required to re-state safety. It adds workflow behavior: it lists folders to map names to IDs, notes IMAP importance, and provides a warning. It does not describe edge cases like missing folders or pagination behavior, but for a read-only listing tool with these annotations, the added context is sufficient.

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 moderately concise and front-loaded: the first sentence states the core purpose. The subsequent sentences add relevant context (IMAP relevance, ID acquisition via email_list_folders, and the warning). It is a bit dense with mixed instructional fragments, but every sentence contributes meaning and there is no fluff.

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 simple read-only listing tool with no output schema, the description provides purpose and workflow context, but it leaves ambiguity about the input/output contract. The schema has no parameter for a human folder name, yet the description says 'map human names... to exact folder_id' without clarifying that the tool returns a list for the agent to match. The reference to email_list_folders as the source of folder.id is also somewhat confusing about the relationship between the two tools. More explicit guidance on the response shape and how to use the returned data would improve completeness.

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?

Schema description coverage is only 33% (only account_id has a description). The tool description does not mention limit or cursor at all, nor does it add meaning to any parameter beyond the schema. It implies a list operation but does not explain how limit/cursor affect results. With low schema coverage, the description should compensate for undocumented parameters, and it fails to do so.

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 function: listing mailbox folders/labels to map human-readable names to exact folder_id. It identifies the trigger ('before moving/labeling or listing folder messages'), highlights the IMAP relevance, and explicitly warns against passing human names when an ID is required. This distinguishes it from siblings like email_list_folders and email_get_folder by focusing on the resolution workflow.

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 context on when to use the tool ('before moving/labeling or listing folder messages') and emphasizes the IMAP case. It also includes a clear exclusion: 'Never pass: human folder name such as Inbox when an ID is required,' and points to email_list_folders as the source of folder.id. It could be more explicit about when not to use this tool (e.g., when an ID is already known), but the guidance is strong.

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