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

Annotations already establish the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's extra operational context is high-value: enumerating every account 'can be slow on macOS 15+', counts are off by default because they are slow on IMAP, and the provenance of counts (Mail's local index vs Mail.app's live count) is disclosed along with the unread_count_note response field. No contradictions with 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?

Purpose, differentiation, and the sibling alternative are front-loaded in the first paragraph; performance caveats and parameter guidance follow in separate paragraphs. It is on the long side, and the parenthetical explaining count provenance is dense, but nearly every sentence carries decision-relevant 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?

An output schema exists, so return-value documentation is not required, yet the description still ties a response field (unread_count_note) to the include_counts behavior. Combined with scope, sibling routing, and performance notes, an agent has everything needed to decide and call 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema by explaining that account comes from list_email_accounts and, more usefully, what include_counts=true actually yields (unread/total per folder) and where those numbers come from. It does not add format/syntax detail beyond that, so it sits above the baseline rather than at the top.

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?

Opens with a specific verb+resource+scope: 'Lists the full folder (mailbox) tree for Apple Mail (Mail.app) accounts, including nested subfolders.' It immediately differentiates itself from siblings by naming the concrete reason to call it (to discover folder names that move_email and list_emails expect) and by ruling out the m365_list_emails path.

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?

States when to use it (to discover exact folder names for move_email/list_emails), which accounts it covers, and gives an explicit when-not routing rule: 'For a Graph-only Microsoft 365 mailbox not added to Mail.app, use m365_list_emails instead.' It also tells the caller how to scope the call with account=<name> from list_email_accounts.

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