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

No annotations are provided, so the description carries the full burden. It says "send" but never discloses that sending is an irreversible external side effect, what account/permission prerequisites apply, or that the tool can silently save a draft or open a review window depending on mode. The schema does cover mode, but the description adds no behavioral context of its own.

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?

A single tight sentence with no filler, and the account scoping is stated up front. It is arguably under-specified rather than concise, but it wastes no words.

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 values need not be explained, and the input schema is rich. However, for a mutation tool with zero annotations and a sibling draft-creator, the description omits the mode-dependent behavior and irreversibility that an agent needs before invoking it.

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 all 10 parameters including cc/bcc/attachments/from_address are already documented with examples and defaults. The description contributes nothing beyond "from a specific account," so the baseline 3 for high schema coverage 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 names a specific verb pair ("compose and send") and resource ("a new email") plus the scoping constraint "from a specific account." It is clear on its own, but it never distinguishes itself from the sibling create_rich_email_draft, which is a near-neighbor given the mode="draft" option.

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?

There is no guidance on when to use this versus reply_to_email, forward_email, or create_rich_email_draft. The mode parameter's "draft" and "open" values overlap directly with the sibling draft tool, and the description does nothing to disambiguate that choice.

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?

With no annotations, the description carries the full behavioral burden. It does disclose meaningful behavior: intermediate path segments are created if needed, and the two nesting approaches are mutually alternative. It says nothing about permission requirements, behavior when the mailbox already exists, or failure modes, leaving real gaps for a mutation tool.

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 short paragraphs, front-loaded with the core action before the nesting detail, and every sentence earns its place. Minor overlap with the schema, which already notes that name may contain '/', keeps it off a 5.

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 values need not be described, and all three parameters are covered by the schema. For a mutation tool with zero annotations, however, the absence of any statement about preconditions, duplicate mailboxes, or error behavior leaves the definition only adequate rather than 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?

Schema description coverage is already 100%, so a 3 is the floor. The description adds value the schema does not: it spells out the interaction between parent_mailbox and the slash-in-name form (e.g., parent_mailbox="Projects" + name="2024" yields Projects/2024, and parent_mailbox may be omitted when a full path is given).

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 ('Create a new mailbox (folder) in the specified account'), which is unambiguous and readily separable from the read-oriented siblings like list_mailboxes and get_mailbox_unread_counts. It does not, however, explicitly name or contrast itself with any sibling, so it stops short of a 5.

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 gives conditional guidance for the two creation idioms ('use parent_mailbox + name' vs. 'pass a full slash-separated path as name and omit parent_mailbox'), which is genuinely useful. But it never says when to create a mailbox versus using an existing one or what preconditions apply, so usage is implied rather than fully framed.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses that the result is unsent, that the artifact is a `.eml` file, that opening in Mail is optional, and warns about the AppleScript literal-markup pitfall — useful beyond structured fields. It omits permission requirements and the protected-location file rules, which are only in the schema.

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 sentences, zero filler, with the core action front-loaded and the differentiating rationale second. Every clause 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?

An output schema exists, so return values need not be explained, and the 100%-covered schema handles parameters. The description adequately frames the tool's purpose and safe-usage context for a file-writing, optionally-opening operation, though it stays silent on permissions and the caveat about save_as_draft lives in the schema rather than here.

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% across 11 parameters, so the schema fully documents recipients, bodies, paths, and flags. The description adds no parameter-level syntax or defaults beyond what the schema already states, making the baseline 3 appropriate.

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?

States a specific verb and resource ('Create a rich-text email draft') and immediately explains the mechanism (generating an unsent `.eml` message, optionally opening it in Mail). The rationale about Mail reliably rendering `.eml` versus AppleScript storing literal markup distinguishes it from compose_email/manage_drafts paths.

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 states this is 'the preferred path for HTML or richly formatted emails,' giving a clear when-to-use condition. It stops short of naming the alternative tools (compose_email, manage_drafts) or stating when NOT to use it, so it's strong but not fully routing.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that files are produced; it omits that writes touch the local filesystem, that some save locations are rejected, what happens on large mailboxes, and whether existing files are overwritten. These are all material for an agent about to invoke a filesystem-writing tool.

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?

A single front-loaded sentence with zero filler, which is structurally sound. It is arguably undersized for a 7-parameter tool, which keeps it from a 5.

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 annotations and a tool that writes to disk, the description leaves out the safety and side-effect profile entirely. The output schema removes the need to explain return values, but the gap in behavioral context is significant for 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?

Schema description coverage is 100%, so every parameter (scope, format, account, mailbox, max_emails, save_directory, subject_keyword) is already documented in the schema, including the scope/subject_keyword dependency and the protected-path rejection. The description adds nothing beyond that, 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?

States a specific verb (export) and resource (emails) plus the destination (files), which is enough to distinguish it from every read/search/compose sibling. It is clear, but adds no differentiation language because no sibling overlaps its function.

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?

"for backup or analysis" hints at intent but gives no when-to-use criteria, no prerequisites, and no alternatives (e.g., search_emails for targeted retrieval vs. this bulk export). An agent gets no routing guidance.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about side effects. It does not state that this sends an irreversible outbound message, what happens when the subject keyword matches multiple emails, or whether the original attachments/content are preserved.

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 single sentence is front-loaded and has zero waste, but for an 8-parameter tool with required subject_keyword targeting it is thin, and the key selection mechanism is buried in the schema rather than surfaced up front.

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 values need no explanation, but for a mutation/send tool with zero annotations and an indirect addressing scheme (subject_keyword lookup) the description should clarify how the target email is chosen and what the send actually does. That context is entirely absent.

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% and all 8 parameters are documented in the schema, including the subtle from_address constraint and the mailbox default. The description adds no parameter meaning beyond that, so the baseline of 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?

States a specific verb and resource: forward an email to recipients. However, it does not reveal the non-obvious mechanism that the target email is located via a subject keyword search, nor does it distinguish this from siblings like reply_to_email or compose_email.

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?

There is no when-to-use guidance and no mention of alternatives such as reply_to_email (respond to sender) or compose_email (new message). The agent is left to infer that 'forward' is the right choice.

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?

With no annotations, the description carries the full burden and does real work: it discloses the mechanism (scan Sent, cross-reference Inbox, match subject from the same recipient), which tells the agent how results are derived. It stops short of noting limitations of subject-matching (false positives/negatives) or that it is a read-only operation.

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, front-loaded with the core purpose before the mechanism. Every sentence contributes; it could be marginally tighter but there is no filler.

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 values need not be described, and the schema fully covers parameters. The description is complete enough to call the tool correctly, with the only real gap being sibling differentiation against get_needs_response.

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 all four parameters (account, days_back, max_results, exclude_noreply) are fully documented in the schema itself. The description adds no parameter semantics beyond that, 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 states a specific verb and resource ('Find sent emails that haven't received a reply yet') and explains the underlying scan. However, it never distinguishes itself from the near-twin sibling 'get_needs_response', leaving the agent unable to tell which to pick without opening both schemas.

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?

'Useful for follow-up tracking' implies a use case but gives no explicit when/when-not conditions and names no alternative, despite the existence of the closely related 'get_needs_response' and 'search_emails' siblings. Usage is left to inference.

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?

With no annotations, the description carries the full burden and does so richly: output sizing (200 KB notes, larger with attachments), the max_bytes cap with an appended truncation marker, that the cap applies after the headers_only filter, and identifier precedence. It also discloses the underlying AppleScript mechanism, which is useful operational context.

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?

Front-loaded with the core purpose in the first sentence, and the sizing/identifier sections are well organized. The 'Implementation note' about Mail.sdef and .partial.emlx is somewhat more internal detail than an agent needs for selection, so it is not maximally tight.

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 description is not required, and the description still covers payload sizing, truncation behavior, and identifier resolution. Nothing an agent needs to call this correctly 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?

Schema coverage is 100%, but the description adds meaning well beyond it: message_id is preferred when both ids are given and is the RFC 822 Message-Id (distinct from Mail.app's internal numeric id), and subject_keyword matches the first message in mailbox whose subject contains the substring. These precedence and matching semantics are not in 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?

States a specific verb and resource ('Return the raw RFC 822 source of a single message') and explicitly distinguishes itself from sibling body-extraction paths that return rendered content. An agent can tell exactly what this produces without opening the schema.

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 gives clear context for when this is the right tool (recovering MIME parts, hrefs, custom headers) and steers toward headers_only for header/URL inspection. It does not name a specific sibling tool as an alternative, but the contrast with rendered-content paths is strong enough to route selection correctly.

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?

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the two-phase strategy (subject-filtered candidates, then header linking) and, importantly, that same-subject messages from other conversations are surfaced separately rather than merged. It omits read-only confirmation, permissions, and failure behavior, keeping it from a 5.

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, front-loaded with the core definition and then the mechanics; no filler. It is slightly more verbose than strictly required, but every sentence conveys real information about how the thread is assembled.

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 description is unnecessary, and the description compensates well for the absent annotations by explaining the linking heuristic and its edge case. Remaining gaps (auth requirements, behavior when no thread is found) are minor for a read-only getter.

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 all four parameters are already documented in the schema. The description's note that candidates are 'found by subject' adds a little color to subject_keyword, but it does not explain the max_messages cap that the schema itself handles in depth. Baseline 3 is appropriate.

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?

States a specific verb+resource ('Get an email conversation thread') and goes further by defining what constitutes a thread (Message-ID linking, not subject sharing). This implicitly separates it from search_emails, though no sibling is named outright, so it stops short of a 5.

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 conveys the scenario it fits (reconstructing a full conversation rather than finding messages by keyword), but it never states when to prefer it over search_emails or get_email_source, nor any prerequisites. Usage must be inferred from the algorithmic explanation.

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?

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait: this is a cross-account aggregate read. It does not state whether it is read-only (though the 'Get'/'overview' framing strongly implies it), nor any cost, freshness, or account-scoping caveats.

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?

A single front-loaded sentence with no wasted clauses. It is efficient, though 'comprehensive overview of your email inbox status' is mildly redundant wording rather than maximally precise language.

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 aggregation tool with an output schema already defining the return shape, the description is nearly sufficient — return values need not be explained. The one real gap is the absence of any routing cue among the several similarly named aggregation siblings.

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 and schema coverage is 100%, so there is nothing for the description to compensate for. Baseline 4 applies; no parameter meaning is required or missing.

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 gives a specific verb ('Get') and resource ('overview of your email inbox status across all accounts'), which is clearer than the bare title. However, it does nothing to distinguish itself from sibling aggregators like inbox_dashboard, get_statistics, or get_mailbox_unread_counts, which could plausibly return overlapping information.

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?

There is no statement of when to use this tool rather than the adjacent aggregation tools (inbox_dashboard, get_statistics) or the more granular list_inbox_emails / get_mailbox_unread_counts. The agent is left to infer the difference between an 'overview' and a 'dashboard' or 'statistics' entirely on its own.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the summary_only behavior change and notes it replaces a former tool, but says nothing about read-only safety, freshness of counts, or account-filtering side effects (e.g., unread counts across all accounts by default). Adequate but incomplete for a zero-annotation tool.

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 sentences, front-loaded with the primary purpose before the mode-specific caveat. Efficient, though the parenthetical about the former tool could be trimmed.

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 an output schema present, return-value detail is unnecessary, and the description covers scope and the summary_only variant. It leaves the account-filter default behavior and relationship to sibling overview/stats tools implicit, which is a minor gap.

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 account and include_zero are already fully documented in the schema. The description adds meaning only for summary_only (flat per-account inbox totals, replacing get_unread_count), which is marginal beyond the schema text. 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?

States a specific verb and resource ('Get unread counts per mailbox') and clarifies scope ('one account or all accounts'), which separates it from list-oriented siblings. It does not explicitly contrast with close siblings like get_inbox_overview or get_statistics, so it stops short of a 5.

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 implies when to use it (per-mailbox unread retrieval) and flags the summary_only mode, but gives no explicit guidance on when to prefer this over get_inbox_overview, get_statistics, or inbox_dashboard. Usage is inferable rather than stated.

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 are absent, so the description carries the full burden. It discloses the filtering logic and prioritisation heuristic, which is meaningful behavioral context. However, it does not state that the operation is read-only or mention authentication, rate limits, or side effects.

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 with the core purpose front-loaded, followed by filtering and prioritisation details. No sentence feels wasted, though the structure could be slightly tighter.

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 values are covered. The description provides enough context about the logic to call the tool correctly, but it omits whether the operation is read-only or if it has any side effects, which would be valuable given no annotations.

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 all four parameters (account, mailbox, days_back, max_results) are documented in the input schema. The description adds no parameter-level information, which is acceptable when the schema does the heavy lifting, 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 clearly states the verb (identify) and the resource (unread emails needing a response), and implies a specific filtering heuristic. However, it does not differentiate from similar siblings like get_awaiting_reply, which an agent might otherwise consider.

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 explains the filtering and prioritisation criteria (excludes newsletters/automated/noreply, prioritises direct emails with question marks), which gives some implied usage context. But it does not state when to choose this tool over alternatives like search_emails or get_awaiting_reply, nor does it provide explicit exclusions or prerequisites.

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?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about being read-only, permission/account requirements, rate limits, or cost of a wide days_back window. "Get" weakly implies a safe read, but nothing is stated explicitly.

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?

A single short, front-loaded sentence with no wasted words, but it is under-specified rather than genuinely concise – brevity comes at the cost of useful detail.

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 values need not be explained, and the input schema is fully documented. However, with no annotations and no sibling differentiation among several analytics tools, the definition is only minimally complete for correct tool selection.

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 schema already documents scope, sender, mailbox, and days_back with defaults and enum-like values. The description adds nothing about the interplay between scope and the optional sender/mailbox params, so 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?

"Get comprehensive email statistics and analytics" names a verb and resource, but "comprehensive" is vague about what is actually returned. It does not distinguish this tool from closely overlapping siblings such as get_inbox_overview, inbox_dashboard, get_top_senders, or get_awaiting_reply, so an agent cannot tell which analytics tool to pick.

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?

There is no when-to-use guidance, no mention of the scope modes, and no routing to or away from sibling analytics tools. The agent is left to infer that this is for aggregate stats rather than per-message or per-mailbox data.

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?

With no annotations, the description carries the full behavioral burden, but it only implies a read ("analyse") without stating read-only safety, permission/auth requirements, or any rate/scope constraints. The use-case framing adds context but no behavioral traits beyond what the name already suggests.

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 short sentences with the core purpose front-loaded and use cases as supporting detail. No filler; sized appropriately for a straightforward analysis tool.

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?

Return values are covered by the output schema and all params are documented, so the description only needs to add behavioral framing. It does not deliver that (no read-only note, no scoping caveats), leaving the definition minimally viable for a no-annotation tool.

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 all five parameters (top_n, account, mailbox, days_back, group_by_domain) are already documented in the schema. The description adds no parameter-level meaning beyond that, 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?

States a specific verb (analyse) and resource (mailbox senders) with a clear outcome: the most frequent senders. It's distinguishable from siblings like search_emails or get_statistics, though it doesn't explicitly contrast itself with any of them.

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 concrete use cases: identifying key contacts, finding high-volume senders to filter, and locating newsletters to unsubscribe from. This is clear when-to-use context, but it names no alternatives or conditions that would select a different tool.

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?

With no annotations, the description carries the full disclosure burden and does meaningful work: it states the return is a UIResource, that it renders only in compatible MCP clients, and that mcp-ui-server is a dependency. That environmental constraint is exactly the kind of non-obvious behavior an agent needs. It does not explicitly confirm the operation is read-only, so not a 5.

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?

Front-loaded with the core purpose, then a scannable bullet list of dashboard contents, then the client-requirement note. Slightly redundant in restating 'interactive dashboard' twice ('interactive dashboard view' / 'interactive UI dashboard'), but otherwise every line 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?

There is no output schema, so the description correctly compensates by describing what the returned UIResource contains. Combined with zero params and explicit client prerequisites, an agent has what it needs to call it. The minor gap is no guidance on failure behavior when the client lacks MCP Apps support.

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 per the rubric the baseline is 4. There is nothing for the description to clarify beyond that, and it correctly avoids inventing parameter semantics.

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?

States a specific verb and resource: 'Get an interactive dashboard view of your email inbox.' The enumeration of contents (unread counts, recent emails, quick actions, search) makes the scope concrete and distinguishes it from data-returning siblings like list_inbox_emails or get_mailbox_unread_counts. It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 5.

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?

Usage context is implied rather than stated: the note that it needs mcp-ui-server and a compatible MCP client signals this is only useful in UI-capable clients, which is a real gating condition. However, there is no explicit 'use this when you want X, use get_inbox_overview instead when Y' routing against the many overlapping inbox/stats 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?

No annotations are provided, so the description carries the burden. "List" implies a read-only operation, but there is no explicit safety statement, no pagination or scoping note. The output schema covers return shape, so the remaining gap is modest, but for a tool with zero annotation coverage this is only adequate.

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?

Front-loaded with the core action in the first sentence, with the rationale following. Slightly verbose in the second sentence but each part earns its place by explaining the practical value.

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 a zero-parameter read tool with an output schema, the description covers what it does and why it's useful. Missing only explicit safety/scope notes, which is minor here since the output schema handles the return contract.

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. There is nothing for the description to disambiguate, and it correctly does not invent parameters.

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?

States a specific verb (list) and resource (configured email addresses for each Mail account), and distinguishes itself from the sibling list_accounts by focusing on addresses rather than accounts. An agent can immediately tell what this returns.

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 a clear motivating use case — mapping a Mail.app display name like "Gmail" or "Work" to actual addresses for integrations. It doesn't explicitly name when to prefer a sibling (e.g. list_accounts), but the context is clear enough to select it.

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?

No annotations are provided, so the description must carry behavioral disclosure. It states only that accounts are listed, without confirming read-only safety, auth requirements, or account scope beyond 'available'.

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?

A single, front-loaded sentence with no wasted words. It is appropriately sized for a simple zero-parameter listing tool.

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 zero parameters and an output schema, the description is nearly complete for invocation. It could still clarify its relationship to sibling account- and mailbox-listing tools.

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 per the rubric the baseline is 4. The description adds no parameter details, but none are needed.

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?

States a clear verb and resource: 'List all available Mail accounts.' An agent can identify the operation. However, it does not distinguish this from sibling listing tools such as list_account_addresses or list_mailboxes.

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 no when-to-use guidance, no prerequisites, and does not mention alternatives among the many sibling list tools. Usage is only implied by the name and purpose.

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?

No annotations are provided, so the description carries the full burden, but it only says it lists attachments. It omits whether the operation is read-only (though 'List' implies it), how max_results bounds the number of matching emails checked, what happens when no email matches, and whether any access permissions are required.

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?

One front-loaded sentence with no filler; every phrase (list, attachments, subject keyword) contributes to tool selection.

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 listing tool with 100% schema coverage and an output schema, the description identifies the resource and filter sufficiently. It could still say more about max_results' effect, but the structured fields cover the call mechanics.

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 account, subject_keyword, and max_results are already documented in the schema. The description reinforces the subject_keyword filter but adds no syntax, default, or constraint beyond the schema, giving the baseline 3.

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?

States a specific verb ('List') and resource ('attachments') plus the filtering condition ('emails matching a subject keyword'), so the agent can distinguish it from save_email_attachment or search_emails. It does not explicitly name a sibling alternative, so it falls short of a 5.

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 no when-to-use or when-not guidance and does not mention alternatives such as search_emails or get_email_source. The subject-keyword filter implies a condition but does not help an agent choose this tool over 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?

With no annotations, the description carries the full behavioral burden, and it discloses little beyond the account+max_emails combination behavior. It omits ordering, pagination, whether spam/trash are included, and how read/unread filtering interacts, though as a pure read list the safety profile is at least self-evident and an output schema covers return shape.

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 short, front-loaded sentences with no filler; the purpose leads and the usage hint follows. The deprecated-tool note is the least load-bearing element but is still useful for agents migrating from the old name.

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 low-risk listing tool with full schema coverage and an output schema, the description covers what is needed to call it correctly. It stops short of routing among the many inbox-related siblings, which would make it fully 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?

Schema description coverage is 100%, so all five parameters are already documented with defaults and formats. The description adds only the combined account+max_emails intent, which is marginal beyond the schema's per-field descriptions.

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?

States a clear verb+resource ("List all emails from inbox") with scope ("across all accounts or a specific account"). It does not explicitly contrast with the live sibling search_emails, which is the closest alternative, so differentiation is only partial.

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?

Gives one concrete usage recipe ("use account + max_emails to get recent emails from a single account") and notes it replaces get_recent_emails, which is migration info rather than live-sibling guidance. It never states when to prefer search_emails or get_inbox_overview, nor any exclusion conditions.

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?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation, but it does not state permissions, rate limits, pagination, or that it is non-destructive, leaving meaningful behavioral context unstated.

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 a single front-loaded sentence with no redundant or wasted phrasing. It is appropriately sized for a simple list tool.

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 low complexity, full schema description coverage, and the presence of an output schema, the description provides enough scope information for an agent to call the tool. It is slightly incomplete because it does not mention the include_counts parameter, though the schema covers that.

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%: both optional parameters have clear descriptions in the schema. The description only echoes the account filtering concept and adds no new semantics beyond what the schema already provides, so this is the 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 states a specific verb and resource ('List all mailboxes (folders)') and a scope ('for a specific account or all accounts'). It is clear, but it does not explicitly differentiate this tool from sibling list tools such as list_accounts or list_inbox_emails beyond the resource name.

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 phrase 'for a specific account or all accounts' implies how to use the optional account filter, but the description gives no explicit when-to-use guidance, exclusions, or alternatives to consider. Usage is only implied.

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?

No annotations are supplied, so the description carries the full disclosure burden, and it does not meet it. It never states that 'send' is an irreversible outbound action, that 'delete' is destructive, whether deletions are recoverable, or what account/permission requirements apply. The action list merely repeats what the schema already enumerates.

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?

A single front-loaded sentence that states the resource first and the supported operations second, with no filler. Nothing could be cut without losing content.

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?

The rich input schema and the presence of an output schema mean the description needn't explain parameters or return values, so it is not badly deficient. But for a nine-parameter, five-action mutation tool with zero annotations, the description should at minimum disambiguate against the compose/create siblings and flag the irreversible actions.

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% and the schema itself is unusually rich, including the from_address fallback behavior and the create/send/open/delete requirements. The description adds no syntax, format, or conditional meaning beyond the schema, 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 names the resource (draft emails) and enumerates the five operations it supports (list, create, send, open, delete), so an agent knows exactly what the tool covers. However, it never differentiates itself from overlapping siblings such as create_rich_email_draft or compose_email, which also produce or send mail, so the boundary is left to inference.

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?

There is no when-to-use or when-not-to-use guidance in the description. The agent is not told when to pick this tool over compose_email, create_rich_email_draft, or reply_to_email, nor that 'send' should follow an 'open' review. The only routing hint ('use open to review before sending') lives in the schema's action description, not here.

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?

With no annotations, the description carries the full burden and does so exceptionally: it discloses that Mail's AppleScript 'delete' only moves to Trash, that delete_permanent and empty_trash usually remove nothing, that results report real before/after mailbox counts rather than call counts, and that permanent emptying must be done in Mail itself. These are non-obvious, high-value behavioral traits an agent could not infer elsewhere.

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 lead sentence is front-loaded and the critical limitation follows immediately. It is somewhat verbose with backticked command names and quotes, but every sentence conveys a distinct, useful fact, so waste is minimal.

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 complex 11-parameter destructive tool, the description covers the essential behavioral caveats, and the existence of an output schema removes the need to explain return values. The only gap is the lack of explicit routing against sibling tools, but otherwise it is complete enough to 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 schema already documents all 11 parameters, establishing a baseline of 3. The description adds useful context by reinforcing the dry_run default and the semantics of the action values, but does not meaningfully extend parameter meaning 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?

States a specific verb+resource: 'Manage trash operations - delete emails or empty trash.' An agent can tell this concerns trash deletion, but the description does not distinguish it from the sibling move_email, which also relocates messages, so sibling differentiation is incomplete.

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 gives clear operational context for the dry_run flag (default preview, set False to act) and explains what each action does, but it never states when to choose this tool over move_email or delete_permanent-style alternatives, nor are any exclusions drawn. Usage is implied rather than explicitly routed.

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?

With no annotations, the description carries the full burden and does disclose real behavior: dry_run previews without acting, message_ids overrides all other filters, and only_read restricts to read mail. It omits whether the destination mailbox must already exist, permission requirements, and whether the move is reversible, which is a meaningful gap for an unannotated mutation tool.

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?

Five short sentences, front-loaded with the core action and then the highest-value usage hints (dry_run, only_read, Archive shorthand, message_ids precedence). Every sentence contributes; there is no filler or repetition of the tool name.

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 values need not be explained, and the description covers the key invocation paths for an 11-parameter mutation tool. It is slightly short of complete because the max_moves safety limit and failure behavior (missing destination mailbox, partial moves) go unaddressed given there are no annotations to cover them.

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 schema already documents all 11 parameters and the baseline is 3. The description restates dry_run/only_read/message_ids semantics that the schema already provides, adding only marginal value (the 'Archive' shorthand and the sibling fast-path reference), so it does not rise above baseline.

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 opening sentence names a specific verb and resource ('Move email(s) ... from one mailbox to another') plus the selection mechanism (filters). It also distinguishes itself from sibling update_email_status by calling out that message_ids uses 'the same fast path', so an agent can route between the two.

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 gives concrete when-to-use guidance: dry_run=True to preview, only_read=True 'useful for archiving', and message_ids for exact-id targeting. It stops short of stating when NOT to use this tool (e.g. versus search_emails or update_email_status for non-move operations), so it is clear context without exclusions.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about the fact that this is a side-effectful send operation by default (send=true), that it can silently save a draft, or what happens if multiple emails match the subject keyword — all of which matter for a mutation tool with zero annotation coverage.

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?

It is a single front-loaded sentence with no filler, which is structurally clean, but for an 11-parameter send operation this is under-specification rather than genuine conciseness — it omits information an agent needs rather than trimming noise.

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 values need not be explained, but the description omits the critical context that this tool sends mail by default, may match multiple emails, and requires a configured account. For a high-complexity side-effectful tool with no annotations, the definition is not complete enough to call safely.

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 all 11 parameters are already documented in the schema (mode, send, reply_to_all, from_address, etc.). The description's only parameter-adjacent content, subject-keyword matching, merely repeats what the schema says, so 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?

States a specific verb and resource ("Reply to an email") plus the selection mechanism ("matching a subject keyword"), which is more precise than a name restatement. However it never distinguishes itself from close siblings like compose_email or forward_email, so an agent gets no help picking between them.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives (compose_email, forward_email, manage_drafts). The only implied usage is that the target email is identified by subject keyword, which is barely a usage condition.

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?

With no annotations, the description carries the full behavioral burden, yet it omits the important traits of a filesystem-writing tool: how the target email is located (subject keyword matching), what happens on multiple matches or missing attachments, and overwrite behavior. Protected-path restrictions appear only in the schema, not the description.

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?

A single front-loaded sentence with zero waste. It is efficient, though arguably under-specified for a 5-parameter, side-effecting tool.

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 values need not be explained, but for a tool that searches by keyword and writes to the filesystem, the description leaves key resolution and failure behaviors undocumented, with no annotations to compensate.

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 schema already documents every parameter including defaults and path restrictions. The description adds no parameter meaning beyond what the schema provides, so the baseline of 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?

States a specific verb (save), resource (attachment from an email) and destination (to disk), so the agent knows exactly what the tool does. It does not differentiate itself from the sibling list_email_attachments, which an agent might reasonably confuse with it, so it stops short of a 5.

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?

There is no guidance on when to use this tool versus alternatives like list_email_attachments or get_email_source. The description is a bare purpose statement with no context, prerequisites, or exclusions.

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?

No annotations are provided, so the description carries the full behavioral burden. It mentions JSON output, pagination, and real date filtering, but omits read-only nature, authorization requirements, and performance implications beyond what individual schema fields already say.

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 tight sentences, front-loaded with scope and capabilities. Every sentence contributes either purpose or differentiation, with no filler.

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?

The schema and output schema cover parameters and return values, so the description need not restate them. However, with 19 parameters and no annotations, the description is thin on when to choose this over list_inbox_emails and on behavioral caveats, leaving notable gaps for a complex search tool.

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 adds only a high-level mapping to subject, sender, body, cross-account, and date filtering, without parameter-specific detail beyond what the schema already provides.

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?

Names a specific verb and resource ('search tool' for emails) and lists the search modes it consolidates: subject, sender, body, and cross-account. This distinguishes it from simple listing tools like list_inbox_emails, though it does not name those siblings explicitly.

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?

Implies use for subject, sender, body, and cross-account searches by saying it consolidates them, but gives no explicit when-to-use or when-not guidance. It also does not name alternatives such as list_inbox_emails, so selection guidance is only implied.

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?

With no annotations, the description carries the full burden and does so richly: it discloses bidirectional push semantics vs receive-only, long-running behavior, the AppleScript timeout wrapper (error -1712), and fire-and-forget semantics after timeout. This is far more behavioral context than annotations would normally supply.

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?

Front-loaded with purpose and usage before the implementation note, and the structure is clear. The implementation note is lengthy and somewhat beyond what an agent strictly needs to invoke the tool, but each part does carry real behavioral value.

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 values need not be explained. Given a single optional param and no annotations, the description supplies everything an agent needs: purpose, timing, push semantics, and timeout behavior.

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% and the single optional param is already documented ('Omit to sync every configured account'). The description's 'account (or every account)' framing mirrors the schema but adds no new syntax or format detail, so the baseline 3 is appropriate.

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?

States a specific verb and resource: force Mail.app to synchronize an account (or all accounts) with its IMAP/Exchange server. It explicitly contrasts with the sibling-ish concept of 'check for new mail', so an agent can distinguish the action from passive polling without opening anything else.

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?

Gives explicit when-to-use guidance ('Use after move_email, update_email_status, or manage_trash when downstream clients need to see the change immediately') and names the relevant sibling tools. It also explains the condition (natural cadence of several minutes) that motivates calling it at all.

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?

With no annotations, the description carries the full behavioral burden, and it only partially delivers: it discloses the message_ids-vs-filters precedence rule. It says nothing about safety limits (max_updates, apply_to_all exist in the schema but their guardrail intent is unexplained), reversibility of the updates, or required permissions.

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 compact sentences, front-loaded with purpose and followed by the precedence behavior; nothing is padded. Slightly more guidance could have been added without waste, but it is efficiently structured.

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 and parameter coverage is complete, so the agent needs little more than purpose plus filter behavior, both of which are present. The absence of any note on the relationship to sibling mutation tools is the only meaningful gap.

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 schema already documents all 11 parameters in detail, making 3 the baseline. The description adds only the filter-precedence nuance and no further parameter-level meaning beyond what the schema provides.

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?

States a specific verb and resource ('Update email status') and enumerates the concrete actions (mark as read/unread, flag/unflag), so an agent knows exactly what it does. It does not, however, differentiate itself from siblings that also mutate message state (e.g. move_email, manage_trash), so it stops short of a 5.

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 one useful routing rule — that supplying message_ids switches to exact-ID matching and ignores other filters — which is genuine conditional guidance. It offers no explanation of when to prefer this tool over its many siblings or when not to use it, leaving usage largely implied.

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