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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: names are case-sensitive and vary per user, and the return includes a 'writable' flag, informing the agent about potential permissions. This goes beyond the annotation signals.

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 short sentences plus a return type line. Each sentence adds distinct value: purpose, usage guidance with example, and return format. No filler or repetition of structured fields.

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 zero-parameter, read-only listing tool, the description fully covers purpose, usage timing, case-sensitivity, and return structure. The output schema is simple and explicitly shown. The annotations cover safety, so nothing is missing.

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 tool takes zero parameters, so the baseline is 4 per the rubric. The description correctly omits parameter details since there are none, and the return shape is described, which is useful.

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 verb and resource: 'List every calendar configured in macOS Calendar.app.' This is specific and distinguishes it from the sibling mail tools by naming the macOS Calendar.app. It also mentions the exact scope ('every calendar') and purpose.

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?

It explicitly instructs to call this before apple_calendar_create_event to obtain the exact calendar_name, explaining that names are case-sensitive and user-specific. This provides clear when-to-use guidance and rationale, even though no alternative tools are listed (which is fine as no alternatives exist among the siblings).

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

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

The description discloses the critical limitation (no ability to send email), the deliberate UI behavior, the instruction to inform the user, and the return shape. Annotations are all false and do not contradict; the description adds significant behavioral context beyond them.

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 three short paragraphs: function, limitation plus user guidance, and return shape. Every sentence earns its place with no filler or unnecessary repetition.

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?

With no output schema, the description provides the return object shape. It also clarifies the no-send behavior, which is essential for safe use. Combined with complete schema coverage, this is fully adequate for a tool of this complexity.

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?

All 5 parameters already have schema descriptions (100% coverage). The description only echoes recipients/subject/body in prose without adding format or constraint details beyond what the schema already provides, so the baseline 3 applies.

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 opens with a specific verb and resource: 'Open a new compose window in Mail.app pre-filled with recipients, subject and body.' This clearly distinguishes the tool from sibling list/search/get tools by being the only compose action.

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 clearly states when to use the tool and what to expect: it cannot send email, leaves the window open for the user to review and send by hand, and says to mention this to the user. It provides strong usage context but does not explicitly name alternative sibling tools.

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

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

Despite strong annotations (readOnlyHint, idempotentHint), the description adds important behavioral context: body truncation at max_chars, the body_truncated flag, and a security warning that message bodies are untrusted. This goes well beyond what annotations convey.

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 efficiently structured: a one-line purpose, a short truncation note, a security warning, and a concise return-field list. Every sentence contributes meaning without unnecessary 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 read-only fetch tool with no output schema, the description fully documents return fields, truncation behavior, and security considerations. Together with the annotations and schema, it gives an agent everything needed to invoke and interpret 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?

Schema coverage is 100%, so both parameters are already well-documented. The description reinforces the handle source and max_chars default/truncation behavior, but does not add major new meaning beyond the schema. This is a solid baseline score.

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 opens with a specific action ('Fetch one message in full') and names the exact resource (a message identified by a handle from apple_mail_search_messages). It clearly distinguishes this read tool from sibling tools like search, list, and compose.

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 clearly indicates the tool is used after apple_mail_search_messages, providing a concrete workflow. It does not explicitly state when not to use it or mention alternatives like apple_mail_unread_summary, but the context is sufficiently clear for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the return structure including `mail_running` boolean, which signals whether Mail.app is running, and the detailed account object fields, providing value beyond the 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?

The description is highly concise: three short sentences that each serve a distinct purpose (what it does, when to use it, what it returns). It is front-loaded with the core action and avoids any filler or repetition.

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?

This is a simple list tool with rich annotations and an output schema. The description provides the essential return format and usage context, making it fully self-contained for an agent to select and invoke correctly. The guidance about other tools taking names verbatim completes the contextual picture.

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 tool has zero parameters, and the schema coverage is 100% (effectively no schema to document). Per the guidelines, a baseline of 4 is appropriate. The description does not need to explain parameters because there are none, and it does not introduce any ambiguity.

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 'List every email account configured in macOS Mail.app' with a specific verb and resource. It also distinguishes itself from siblings by noting that other tools take account names verbatim, positioning this as the entry point.

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 says 'Start here when you do not yet know the exact account names — every other tool takes those names verbatim.' This gives clear when-to-use guidance and implies that alternatives require the output of this tool, even though no specific sibling is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful context about localisation and case-sensitivity, and indicates that unread counts are included, which are behaviors not captured by 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 concise sentences front-load the core purpose, then provide a usage tip and a return format. Every sentence earns its place, and the localisation examples are valuable without being verbose.

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 list tool with one optional parameter, the description covers what it does, when to use it, and the return structure. The output schema and annotations cover the rest, making this complete.

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 covers the lone 'account' parameter fully with a clear description, so the baseline is 3. The description only adds 'optionally for one account,' which partially restates the optional nature but adds little beyond the schema.

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 a specific verb and resource: 'List mailboxes (folders) with their unread counts, optionally for one account.' This clearly distinguishes it from sibling tools like apple_mail_list_accounts and apple_mail_search_messages.

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?

It explicitly advises 'Use before searching a non-inbox folder' and explains why (case-sensitive, localized names). However, it does not mention when not to use the tool or explicitly compare it to alternatives like apple_mail_unread_summary.

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

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

Beyond annotations (readOnlyHint, idempotent), the description discloses the refuse-rather-than-hang behavior for max_scan, the default since_days=30, ordering (newest first), use of an opaque handle, and the never-search-body limitation. This gives the agent a rich model of runtime behavior.

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?

Well-organized with clear sections (Cost model, Note, Returns, Examples). Every sentence provides distinct value; the Returns block enumerates fields compactly and the examples are illustrative without bloat. Front-loaded with purpose and usage.

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 10 params and complex cost/safety behavior, the description covers purpose, usage guidance, return format, failure mode, performance implications, and relationship to sibling tools. The embedded Returns block serves as an output schema, and the examples cover realistic scenarios.

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 already documents all 10 params (100% coverage), but the description adds substantial meaning: which params are primary cost controls (since_days, max_scan), how query vs from differ in scope, and concrete example mappings. This goes far beyond the baseline of 3 for covered schemas.

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?

Description opens with 'Search message HEADERS across one or more Mail.app mailboxes' – a specific verb, resource, and scope. It explicitly contrasts with sibling tools by stating the output is metadata plus an opaque handle, and that apple_mail_get_message is needed for bodies.

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?

Provides explicit when-to-use guidance: cost model, filter pushdown, TOO_MANY_MATCHES recovery ('add filters rather than raising max_scan'), and examples mapping natural language requests to parameter combinations. Also states that body text is not searched, steering users to get_message.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false. The description adds valuable behavioral traits: mailboxes with zero unread are omitted, it reads counters only (fast on large mailboxes), and it returns a specific structured summary. These traits are not in annotations, and there is no contradiction.

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 three sentences, each earning its place: the first states purpose, the second explains filtering and performance, and the third gives the return format. There is no filler or repetition; it is front-loaded with the most important 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 the tool's simple scope (one optional param), strong annotations, and an inline return schema in the description, everything needed to decide and invoke the tool correctly is present. The description covers purpose, behavior, and output format without missing critical information.

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 already describes the only parameter 'account' with 100% coverage, including examples and the note that omitting it spans all accounts. The description does not add parameter-level detail beyond that, so the schema itself carries the information. This aligns with the baseline 3 for high schema coverage.

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: 'Unread counts per account and mailbox' with a concrete verb and resource. It distinguishes itself from message-level tools by calling it the 'cheapest way to answer what's waiting for me', implying a summary query rather than message retrieval.

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 clear context on when to use it (quick unread summary) and explicitly contrasts with scanning messages ('does not scan messages'), implying search or get message tools for content. However, it doesn't name alternative tools explicitly in the description, so it stops short of full exclusion guidance.

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