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

Annotations are all false (no read-only, idempotency, or destructive hints), so they carry essentially no information and the description must carry the burden. The description does disclose the key behavioral trait — that this can 'send immediately' vs. 'save it for later' — which is meaningful. However, it omits side effects like the user confirmation prompt on send, visibility of saved drafts in Mail.app, or failure modes; the actual behavioral weight is carried by the parameter docs instead.

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?

Four sentences total — one imperative verb-first opener plus a three-sentence framing paragraph — with zero fluff. The core action is front-loaded, and the conceptual paragraph earns its place by giving an agent a mental model for a genuinely complex 15-parameter tool. Every sentence carries weight.

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 15-parameter tool with an output schema (so return values are already documented) and a detailed schema, the description covers the essentials: the three creation modes, the seed-from-original concept, and the save-vs-send distinction. The only real gap is that it doesn't help an agent choose between this and the send_email/reply/reply_all/forward siblings, but given the high schema coverage and output schema, the description is nearly 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 80%, putting this at the high-coverage baseline. The description's 'seeded from an existing message (reply or forward)' conceptually maps to reply_to/forward_of, but the schema already documents those with far more depth (including the RFC 5322 Message-ID forms and mutual exclusivity), so the description adds no syntax or format value. 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, and scope: 'Create a draft (fresh, reply, or forward). Optionally send immediately.' The three modes are enumerated and the conceptual paragraph explains why a draft-creation tool is the right primitive, distinguishing it clearly from anything that just sends. This is a model of a clear operation + scope.

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 explanation that 'every outgoing message is a draft until sent' provides clear conceptual context for when this tool is the right choice (any outbound mail), and the fresh/reply/forward modes plus the save-vs-send duality are explicit. However, it never names the overlapping siblings (send_email, reply, forward) or states when NOT to use this tool in favor of them, so it stops at clear context without explicit 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?

The annotations already convey that this is a non-read-only, non-destructive, idempotent operation. The description adds no behavioral detail beyond the obvious creation action—such as duplicate handling, naming constraints, or account-specific behavior—so it provides little value beyond the structured 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 a single concise sentence with no wasted words, and the core action is front-loaded. While very brief, it earns its place as a clear minimally sufficient summary.

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 creation tool, the combination of schema, annotations, and output schema covers the essential invocation details. The description doesn't need to explain return values or parameter semantics because those are already present in structured fields. It would only be incomplete if behavioral edge cases were not covered, but annotations compensate 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 description coverage is 100%, and the schema already thoroughly documents the 'name', 'account', and 'parent_mailbox' parameters, including UUID stability and nesting semantics. The description itself adds no parameter-level meaning, so the baseline score of 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?

The description uses a specific verb ('Create') and a clear resource ('mailbox/folder'), making the tool's purpose immediately understandable. It is naturally distinguished from sibling tools like list_mailboxes, update_mailbox, and delete_mailbox by the action it performs.

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 explicit when-to-use guidance or mention of alternatives, but the action 'Create a new mailbox/folder' implicitly conveys that this tool is for creating mailboxes. It does not discuss when not to use it or contrast it with update_mailbox/delete_mailbox.

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 thin (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the full load — and it delivers. It flags the counterintuitive fact that a single create can install automation with auto-forward/delete consequences, requires user confirmation for safe execution, and explains why the returned rule_index reflects the new total count. This is exactly the kind of non-obvious runtime behavior agents can't infer. A small deduction for not mentioning what happens if the user declines the confirmation dialog.

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?

Beautifully structured: one line for purpose, two short paragraphs covering warning-worthy behavior and return semantics. The critical gotchas (confirmation prompt, append-to-end behavior) are front and center. A single point off for the cryptic '#222' reference — a dangling artifact that doesn't help an agent executing a task and pollutes the otherwise clean description.

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 5 params, nested objects, and an output schema, this definition is quite complete. The combination of annotations (safety/destructive profile), a rich 100% schema (parameter semantics), and a description that explains the non-obvious behavioral boundaries (confirmation requirement, rule ordering, return value) covers the major risks. What's missing: behavior on confirmation denial, and interaction with the 'enabled' flag. Given the safety-critical nature of the described operations, those two details would make it fully airtight.

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%; every parameter is documented with examples, defaults, and structure. The description stays at the semantic layer — it doesn't try to re-document the schema, which is the right call. The action-type distinction (delete/forward_to/move_to/copy_to) ties the description to the schema's 'actions' param in a way that clarifies selection without duplicating it, but it's marginal value added 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?

Opens with a crisp 'Create a new Mail.app rule.' — a specific verb, a concrete domain resource, and a clear scope. Sibling tools (list_rules, update_rule, delete_rule) make the creation intent unambiguous; no reasonable agent could confuse this with an operation on an existing rule.

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 crisp decision boundary for when the tool is behaviorally different: actions that 'move, forward, or delete mail' trigger a user confirmation prompt, while 'organizational-only' actions do not. This is excellent operational context an agent needs before crafting a risky rule. It doesn't explicitly name alternatives ('use update_rule to modify an existing rule'), but it's clear enough given the parameter docs cover the action vocabulary.

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 adds context beyond the destructiveHint annotation by specifying 'Removes the account entirely,' and it warns about the stability issue with display names. This provides useful behavioral expectations for a destructive 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?

Two concise sentences, purpose first, then a practical tip. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the one parameter, the destructive nature is stated, and the output schema is present, the description covers the essential information for an agent to invoke this tool correctly. It could mention prerequisites or side effects, but it's sufficient for this simple deletion.

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 describes the 'account' parameter as display name or UUID, but the description adds guidance to prefer UUID for stability, which is not in the schema. This enriches the 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?

The description clearly states 'Delete a mail account from Mail.app.' and 'Removes the account entirely from Mail.app.' This is specific to accounts, distinguishing it from sibling delete tools like delete_rule or delete_mailbox. The verb and resource are explicit.

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 does not explicitly contrast with alternatives, but it provides a usage tip: 'Use the account UUID (from list_accounts) for stability across renames.' This suggests when to use this tool is for deleting accounts, but it doesn't say when not to use it or mention alternatives. It's adequate but not explicit.

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 flag destructive and idempotent behavior. The description adds specific consequences (moved to Deleted Messages, no longer editable, recovery possible but effectively one-way) and mentions there is no rate limit, which goes beyond the annotation hints.

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 concise but includes a slightly redundant phrase 'No elicitation (recoverable from Trash)' that could be simplified. Overall it is easy to read and stays on point.

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 delete operation, the description covers the action, side effects, and recovery nuance. It doesn't describe return values, but that is likely unnecessary for this tool; the context is sufficiently 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 only parameter draft_id is fully described as 'Mail.app id of the draft.' Schema coverage is 100%, and the description adds no further details, so it stays at the 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?

Clearly states the verb 'Delete' and the resource 'draft', and clarifies it moves to Trash. This distinguishes it from other draft-related tools like update_draft or send_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?

Describes the lifecycle purpose as 'cancellation' and notes the one-way nature. While it doesn't explicitly list when not to use it, the context makes the intended use unambiguous relative to 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?

The description substantially extends the annotations (destructiveHint=true) by detailing that user confirmation is always elicited, default refusal for non-empty mailboxes, cascade option, Gmail system-label restriction, and the error_type when credentials are missing. This provides a rich behavioral model beyond the boolean hints, covering edge cases and safety measures.

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 structured into logical sections: method, prerequisite, safety behavior, and Gmail exception. It is informative without being excessively verbose, though it could be tightened. The core purpose is front-loaded in the first sentence, which aids quick comprehension.

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 destructive nature and conditional behaviors, the description covers all critical aspects: the IMAP mechanism, credential requirement, default safety refusal, cascade override, and unsupported Gmail paths. With an output schema present, return details are not needed. An agent has sufficient context to decide when and how to call this tool 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 coverage is 100%, so baseline is 3. The description adds context for the delete_messages parameter by explaining the cascade behavior and default refusal, but this largely mirrors the schema descriptions. No significant new parameter-specific information is provided beyond what the schema already states.

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 explicitly identifies the action ('Delete a mailbox') and the method ('via IMAP'), distinguishes it from AppleScript-based operations, and specifies the resource. This clearly differentiates it from sibling delete tools like delete_messages and delete_account.

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 provides strong context on when to use this tool: when a mailbox needs deletion and AppleScript lacks a working primitive, requiring IMAP. It also mentions prerequisites (IMAP credentials) and default behavioral restrictions (refuses non-empty mailboxes). However, it does not explicitly name alternatives or exclusions, such as saying 'use delete_messages for deleting messages.' The resource distinction is implied but not explicitly 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?

Beyond the annotations (destructiveHint=true), the description discloses that deletion is gated behind user confirmation via MCP elicitation and always moves messages to Trash rather than permanently deleting them. This is valuable behavioral context that annotations alone do not provide.

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 two short sentences with the core behavior front-loaded, followed by the important destructive-gating note and a cross-reference to sibling delete tools. Every sentence earns its place, and nothing is redundant.

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 destructive tool with an output schema and fully documented parameters, the description covers purpose, Trash behavior, user-confirmation gating, and relation to sibling delete tools. No critical information needed to call the tool 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 description coverage is 100%, and the per-parameter descriptions in the schema already explain account, source_mailbox, message_ids, and the no-op behavior of permanent. The tool description adds no new parameter-level detail, so the baseline score 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?

The description states a specific verb and resource: 'Delete messages' with the clarifying behavior 'always moves to the account's Trash mailbox.' This distinguishes it from sibling tools like delete_draft, delete_rule, and delete_mailbox without needing to open 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?

The description gives clear context that this tool deletes messages and always sends them to Trash, which is enough for an agent to know when to use it. It does not explicitly list exclusions or alternatives, but the tool name and scope make the primary use case unambiguous.

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?

Explicitly describes destructive nature and irreversibility, supplementing the destructiveHint annotation with actionable context about user confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no redundancy; all information is directly relevant.

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?

Covers the essential operational details (index, destruction, confirmation) and does not need to describe output since an output schema is present.

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 parameter description explains the indexing scheme and its source (list_rules), adding value beyond the raw 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 ('Delete') and resource ('Mail.app rule'), clearly distinguishing it from sibling delete tools like delete_account or delete_draft.

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?

Specifies the operand ('1-based positional index') and notes the requirement for user confirmation, making it clear when this tool is appropriate.

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 repeats the destructiveHint=true that the annotations already encode, but it adds the behavioral detail that MCP elicitation confirmation is required before the deletion runs. This informs the agent of an interaction step it must expect at runtime, which goes beyond the structured metadata. Slight ding because the description doesn't state what is destroyed (user templates vs. system templates) or whether deletion is reversible.

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 verb and object front-loaded, followed by a clearly separated warning paragraph. Just enough whitespace and paragraph structure to separate the operation from the caution. Zero filler 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?

For a single-parameter tool with an output schema and full annotation coverage, the description is nearly sufficient. The main gap is the oddly-phrased 'via MCP elicitation' — it reads as if a template placeholder was left half-substituted, and it doesn't specify whether the confirmation is a simple yes/no or a multi-step interaction. The agent would want to know if deletion is recoverable before invoking this 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 coverage is 100% with a single well-documented parameter, so the baseline of 3 applies. The description echoes the schema's 'by name' language without adding format, case-sensitivity, or wildcard details. No additional value added beyond the schema for the single parameter.

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 uses a specific verb and resource with a scoping qualifier: 'Delete a template by name.' The 'by name' qualifier clarifies the identifier semantics. This is unambiguous even among deletion-heavy siblings like delete_account, delete_rule, and delete_mailbox, since template deletion is clearly the resource being targeted.

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 only extra-tool guidance is the warning that the operation is destructive and requires user confirmation. There is no explicit when-to-use vs. alternatives (e.g., no note to use save_template for edits or get_template for reads). The tool name carries the disambiguation burden, which works here only because the name is descriptive.

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 annotations already establish that the tool is not read-only, not idempotent, and not destructive. The description adds a useful implementation trait by identifying this as a wrapper over create_draft with seed=forward, but it does not disclose other behaviors like account/recipient requirements, how the original message is affected, or the actual side effect of sending immediately. This is moderate transparency but not outstanding.

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 only two sentences and every sentence is informative: the first identifies the operation, the second sets expectations about how it composers with the existing create_draft API. It avoids fluff and is easy to scan.

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?

Combined with a fully documented schema and an output schema, the description provides enough for the core invoke workflow. The wrapper-creating-draft note is valuable context, but the description remains thin on how to choose between forward and sibling tools with overlapping intent, so it is not fully self-sufficient.

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 documents all six parameters with 100% coverage, so the description carries no additional parameter-specific semantics. The 'seed=forward' note adds context but does not clarify individual parameters beyond what the schema already provides. Baseline 3 is appropriate here.

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 uses a clear verb and resource: 'Forward an existing message to new recipients.' It also positions the tool as a convenience wrapper over create_draft with seed=forward, which helps locate it in the API surface. However, it does not explicitly distinguish itself from reply/reply_all or send_email, so it falls just short of full differentiation.

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 'Convenience wrapper over create_draft with seed=forward' gives meaningful usage context: this is the forward-specific version of creating a draft, and the schema's send_now option clarifies immediate sending vs. draft-only. Exclusions or explicit alternatives such as 'use reply when preserving original recipients' are not stated, so it only partially explains when to pick this over 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?

Annotations already cover readOnly/idempotent/destructive safety. The description adds the key behavioral trait (inline read, no disk write) and the implicit size caveat ('small PDF'). Does not mention pagination or truncation, but for a read tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs with zero filler. The core action is front-loaded, and the second paragraph gives a concrete workflow example. Every sentence 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?

With an output schema present (return values are handled there), plus clear usage guidance and annotations for safety, nothing essential is missing for an agent to correctly invoke the 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 covers all four parameters with detailed descriptions (e.g., attachment ordering, message_id provenance). The description adds no new parameter meaning beyond what's already in the schema, so 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?

Clearly states it reads one attachment's content inline without writing to disk, distinguishing it from the sibling save_attachments. Specific verb+resource, no ambiguity.

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 provides when-to-use (triage workflows) and names the alternative save_attachments with an explicit 'instead of' path, making the decision logic crystal clear.

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?

Very thorough. It explains the no-op behavior for empty lists, silent dropping of missing ids (partial-results), the "SELECTED" sentinel resolution, and the IMAP fast-path vs AppleScript fallback tradeoffs. The return type is described as a list of message dicts. The annotations (readOnlyHint=true, destructiveHint=false) reinforce that this is a safe read, and the description even covers optional-parameter side effects like headers_only being ignored on the fallback. This is exactly the kind of behavioral disclosure an agent needs.

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 efficient but loses a point for leaning heavily on the schema and a code reference. It states purpose, scope, and relationships to siblings in two sentences. Adjective: compact, though the schema carries much of the behavioral detail. Not verbose enough to be 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?

Everything an agent needs is present: return format (list of dicts), edge cases (missing ids, empty list, SELECTED sentinel), and fallback behavior. Sibling routing is handled. The output schema understands what comes back. This is complete for a read 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 coverage is 100%, and the schema descriptions are unusually detailed. The 'account' and 'mailbox' parameters get extra context (IMAP fast path semantics) that is not directly inferable from the schema, which adds real value. However, the description text itself doesn't reiterate parameter details — it relies on the schema doing the heavy lifting. A 4 acknowledges the added value from the IMAP fast-path context in the schema, while not being a 5 since the description doesn't extend parameter semantics 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 ('fetch'), resource ('one or more messages'), and scope ('with bodies'). It also explicitly names the sibling tools it is not — search_messages (metadata-only) and get_thread (thread member ids) — so an agent can distinguish them without opening other 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?

Names the alternatives to pair with (search_messages and get_thread) and the condition for picking those, which routes the agent. It doesn't state when to use this tool over the IMAP fast path vs fallback, but the parameter docs carry that context, and the pairing tip is the key usage decision.

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 the tool as read-only, idempotent, and non-destructive. The description confirms it is a read operation, which is consistent and adds no contradiction. However, it adds no extra behavior context (e.g., behavior on missing template, response format) beyond what annotations and schema imply.

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, concise sentence with no filler. It is front-loaded with the verb and resource, making it instantly scannable and efficient.

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 single-read operation with one parameter fully documented in the schema and an output schema present, the description is adequate. It could mention when to use this over list_templates, but that falls under usage guidelines. The minimal description is sufficient for correct invocation.

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 schema description covers 100% of the only parameter, 'name', including format and length. The description adds nothing beyond 'by name' which is already implied. With high schema coverage, 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?

The description states a clear verb ('Read'), a specific resource ('single template'), and a discriminator ('by name'). It easily distinguishes from siblings like list_templates (list all) and save_template/delete_template (write operations). No ambiguity.

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 guidance on when to use this tool versus alternatives. It doesn't mention list_templates for bulk listing or render_template for processing, nor any conditions that would select one over the other. The usage is only implicitly obvious from the name.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the sorting order (date_received ascending), the underlying dispatch mechanism (tiered IMAP threading vs. AppleScript path), and a concrete limitation about missed threads when subject rewrite occurs on the AppleScript fallback. This goes well beyond the annotations and helps the agent anticipate edge cases.

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 logically structured: it starts with the primary purpose, then explains the lookup mechanism, provides usage guidance, and ends with a known limitation. It is a bit longer than necessary but each sentence carries useful information. The front-loaded purpose makes the key intent immediately clear. It earns a 4 for effective organization despite slight verbosity.

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 that an output schema exists to define the return structure, the description does not need to explain return values. It covers the essential behavioral details (sorting, fallback paths, limitation) and provides integration suggestions. While it doesn't mention empty results or error conditions, these are typically not critical for a read-only retrieval tool. Overall, the description is complete enough for an agent to call the tool correctly and interpret the outcome.

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 single parameter message_id is fully documented in the schema (100% coverage), including the note that it is an 'Internal id of any message in the thread (from search_messages or get_messages results).' The description does not add any additional meaning beyond the schema; it simply mentions the anchor message without elaborating on format or constraints. Since the schema already covers semantics, a baseline score of 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?

The description opens with a precise statement: 'Return all messages in the thread containing the given message.' This specifies a clear verb (return), a distinct resource (thread), and a scoping condition (containing the given message). It is easily distinguishable from siblings like get_messages (which likely fetches specific message IDs) and search_messages (which searches by criteria), so an agent can select it without ambiguity.

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 provides explicit follow-up guidance: 'The returned ids can be piped into search_messages(source=[ids]) for filtered metadata or get_messages([ids]) for full bodies.' This tells the agent what to do with the output, which is valuable. It does not explicitly state when NOT to use this tool versus alternatives, but the threading focus and the pipe suggestions imply the intended use case. The known limitation also helps set expectations.

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. The description adds meaningful behavior beyond annotations: it specifies the output fields, the stability of account IDs, and shows an example response. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the field enumeration is concise. The 'Returns: Dictionary containing the accounts list.' line is somewhat redundant with the preceding sentence and example, but it does not significantly bloat the description.

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 list tool, the description is complete: it states the scope, the returned fields, the stable ID behavior, and the response shape via example. The annotations and available output schema cover the remaining context.

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 an empty input schema, so the description does not need to explain parameter meaning. The description adds relevant context about account IDs, but the baseline for zero parameters is 4.

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 specific verb and resource: 'List all configured email accounts in Apple Mail.' It enumerates the returned fields and thereby distinguishes itself from siblings like list_rules and list_mailboxes by resource type.

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 explicit when-to-use or when-not-to-use guidance is given relative to sibling tools. It does provide useful guidance for consuming the result ('Account ids are stable... prefer them over names'), but tool-selection context is only implied by the tool name and description.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the scope ('all') and no additional behavioral detail, which is acceptable for a simple list operation but adds little 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 a single, front-loaded sentence with no wasted words. Every word contributes to the meaning, making it appropriately concise for a simple 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 coverage, existing output schema, and annotations covering safety, the description is complete enough for an agent to invoke the tool correctly. A bit more guidance about prerequisites could push it higher, but nothing critical 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 description coverage is 100%, and the account parameter is well documented with guidance on display names vs UUIDs and stability. The tool description itself does not add parameter detail, but the schema fully handles it, 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 uses a specific verb ('List') and resource ('all mailboxes') with a clear scope ('for an account'). It is unambiguous and distinct from sibling tools like list_accounts and the mailbox mutation tools.

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 conveys when the tool is useful: when all mailboxes for a particular account are needed. It doesn't explicitly state exclusions or alternatives, but no direct alternative for listing mailboxes exists among siblings, so the context is sufficiently clear.

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 the annotations, the description adds meaningful behavioral caveats: rule names are not guaranteed unique and rules have no stable id via AppleScript. This is exactly the kind of context an agent needs to avoid assuming identity or uniqueness.

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 well-structured and front-loaded with the core purpose. The return format and example are useful, and every sentence adds value 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 zero-parameter read-only tool with annotations and an output schema, the description is complete. It covers purpose, return shape, example output, and the key caveats about duplicate names and missing stable IDs.

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, so the schema already fully covers parameter semantics. The description adds no parameter details, but none are needed; the example output clarifies what the call returns.

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: 'List all Mail.app rules (read-only).' It clearly distinguishes this from mutation siblings by emphasizing read-only behavior and noting that mutation is tracked separately.

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 frames this as the read-only listing tool and states that mutation (enable/disable, create, delete) is a separate enhancement. It does not name the exact sibling tools to use instead, but the context is clear enough for an agent to route 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond that by explaining the template storage location (files in ~/.apple_mail_mcp/templates/) and the environment variable override, as well as the exact return structure (name and subject, with null when no subject header). This enriches the behavioral understanding without contradicting 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 multi-paragraph but every part carries useful information: the purpose, the file storage location, the environment override, and the return format. It is front-loaded with the core purpose. It could be trimmed slightly, but the extra context is valuable and not redundant for a tool with no parameters.

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, idempotent operation with an output schema present, the description covers everything an agent needs: the action, the storage source, the return shape, and the environment override. There is no missing element that would prevent correct invocation.

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 defines no properties, so the description cannot add parameter details. However, it does mention the APPLE_MAIL_MCP_HOME environment variable, which influences behavior but is not a tool parameter. With no parameters to document, the description appropriately need not compensate for schema gaps, making the baseline 4 a fair 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 first line 'List all stored email templates' clearly states the action (list) and resource (email templates), distinguishing it from sibling tools like get_template (single retrieval) or save_template (creation). The additional context about file location reinforces the scope without confusion.

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 does not explicitly guide when to use this tool versus alternatives such as get_template or render_template. It relies on the verb 'list all' to imply broad retrieval, but it never states usage conditions, exclusions, or preferred scenarios. Given the numerous template-related siblings, explicit routing would improve clarity.

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 explicitly says 'No side effects,' reinforcing the readOnlyHint/idempotentHint annotations. It also discloses detailed behavior: message_id auto-populates recipient_name, recipient_email, original_subject, and today, while user-supplied vars override auto-fills. This goes beyond the annotations and gives the agent a clear picture of invocation 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?

The description is three dense paragraphs with front-loaded purpose, followed by side-effect posture and auto-fill details. Every sentence carries operational weight, with no filler or redundancy.

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 annotations already covering safety and an output schema present, the description supplies the remaining decision-relevant context: how output should be used downstream, when message_id affects placeholders, and the precedence of vars. An agent has everything needed to call this 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 the baseline is met. The description adds substantial meaning: message_id is not just 'reply context' but drives specific variable auto-fills, and vars override those auto-fills. This is critical semantics that the schema alone does not convey.

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-resource pair: 'Render a template into ready-to-send subject and body text.' It also distinguishes the tool from sending siblings by explicitly framing the output as text for create_draft/update_draft and noting there are no side effects.

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 warns 'No side effects' and instructs the caller to pass rendered text to create_draft or update_draft, including send_now=True for sending. This tells the agent when to use the tool (prepare content) and what it is not responsible for (sending/mutation), distinguishing it from send/reply/forward 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 adds some behavioral context beyond annotations by revealing that the tool is a wrapper over create_draft with seed=reply, clarifying that it creates drafts/reply flow. Annotations already declare readOnly=false and destructive=false, but the description doesn't go into side effects such as immediate sending or reply-all 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?

The description is two short sentences with no filler. It front-loads the core action and then gives a functional relationship to create_draft.

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 a rich parameter schema and an output schema, the description covers the essential behavior and wraps semantics. It misses an explicit distinction from reply_all and its exact sending/draft behavior, though the schema defaults cover the latter.

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 and the description doesn't need to restate parameter meanings. The 'seed=reply' detail gives useful conceptual context, but it doesn't add meaning beyond the schema for individual 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?

The description names the operation with a specific verb and resource ('Reply to an existing message') and reveals its implementation path as a wrapper over create_draft with seed=reply. It does not explicitly differentiate from reply_all or forward, but the 'existing message' target makes the scope reasonably clear.

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 'Convenience wrapper over create_draft with seed=reply' implies a targeted alternative to create_draft, but there is no explicit statement of when to choose this over reply_all or when a fuller create_draft call is preferable. Usage guidance is present only by implication.

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 does not contradict the annotations (readOnlyHint=false, destructiveHint=false). It adds a note about being a convenience wrapper, which implies the same behavior as create_draft but with predefined seed and reply_all flags. However, it does not detail side effects (e.g., sending an email is irreversible) or any requirements beyond what the schema covers. With minimal annotation support, the description provides only modest behavioral transparency.

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 two sentences, front-loaded with the core purpose and the implementation note. No filler or repetition; highly scannable for an agent.

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 tool is a simple wrapper with fully documented parameters in the schema. The description gives the essential intent and relationship to create_draft gradients, which is sufficient for safe use, though it does not mention potential side effects like sending delays or permission requirements, but those are not necessary for a simple send operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters with clear descriptions (e.g., 'Reply body. Auto-quotes original if empty', 'send immediately vs. save as draft'). The description itself does not add additional meaning beyond the schema, so it sits at the baseline of 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?

The description clearly states the tool's function: 'Reply to all recipients of an existing message.' This is a specific verb+resource pairing. It also distinguishes itself from siblings by explicitly naming it a wrapper over create_draft with reply_all=True, indicating a specialized reply-all behavior.

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 frames the tool as a 'Convenience wrapper over create_draft', implying that for more control one should use create_draft directly. This gives clear context on when to use this tool versus the more generic alternative, though it does not explicitly state exclusions or when NOT to use 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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds no behavioral context beyond the action itself—no mention of overwrite behavior, directory creation, or what happens when no attachments exist. It does not contradict annotations, but it also does not enrich 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 a single, front-loaded, grammatically complete sentence: 'Save attachments from a message to a directory.' There is no filler or redundancy, and the core action is immediately clear.

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 strong schema and output schema, the invocation details are well covered. However, the description lacks routing guidance against get_attachment_content and any edge-case expectations, such as handling existing files or missing attachments. It is adequate but not complete for an agent choosing between related 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?

Schema description coverage is 100%, and the schema itself richly documents all parameters, including the IMAP fast-path behavior for account/mailbox and the 0-based attachment_indices. The description adds no parameter-level meaning beyond implicitly indicating a source message and target directory.

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 uses a specific verb ('save') with a clear resource ('attachments from a message') and destination ('to a directory'). This clearly distinguishes it from siblings like get_attachment_content, which implies retrieval rather than writing to disk.

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 guidance about when to use this tool versus alternatives. It does not mention get_attachment_content as the option for retrieving attachment data, nor does it state conditions such as preferring file output over in-memory content. The agent must infer usage solely from the sentence.

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 key behavioral trait of overwriting an existing template, which goes beyond the annotations. This aligns with idempotentHint=true and destructiveHint=false, framing the tool as a safe upsert rather than a one-time mutation.

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 five words with zero filler, and the action verb is front-loaded. It is appropriately sized for a simple write tool and every word 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?

Given the full schema coverage, existing output schema, and clear annotations, 'Create or overwrite a template' is complete for an agent to invoke the tool correctly. The only non-obvious nuance, upsert behavior, is explicitly stated.

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 three parameters, including placeholder tokens, name constraints, and the optional subject. The description itself adds no parameter-level meaning, but the baseline of 3 applies because the schema carries the full burden.

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 the exact operation ('Create or overwrite') and resource ('a template'), making the tool's purpose immediately clear. It also distinguishes it from sibling template tools (list_templates, get_template, delete_template, render_template) by naming the write/upsert behavior.

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 the clear use case: call this tool when you need to create a new template or replace an existing one by name. It doesn't explicitly exclude alternatives, but the resource-specific verb 'save' plus 'create or overwrite' provides enough context to select it over the read/delete/render 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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context such as the 'SELECTED' sentinel behavior, silent dropping of missing IDs with partial results, and the differences in behavior between IMAP and AppleScript paths. Some performance details are implementation-specific and could become stale quickly.

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 well-structured with clear sections and code formatting for the two modes. The performance notes (e.g., 'measured 148s for 100 cold-cache messages') and inline details like issue references (#142) add credibility but slightly extend length. Every sentence adds value, though some performance specifics could be condensed without loss of meaning.

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 complexity (15 params, two modes, interactions with sibling tools like get_thread and get_messages), the description is remarkably complete. It covers mode selection, filter composition, performance trade-offs, and even error behavior like silently vanishing IDs. The presence of an output schema (though not shown in full) further supports the agent in understanding return types.

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 description enhances the parameter semantics significantly by explaining the 'SELECTED' sentinel, performance implications (e.g., body_contains being slow on AppleScript), free vs. costly operations (include_attachments), and composition semantics like 'most restrictive filter wins'. This goes beyond what the schema alone 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?

The description clearly states the tool searches messages and returns metadata-only rows, with a specific verb and resource. It goes further to distinguish two distinct modes (default mailbox search vs. scoped by message IDs), which is specific and actionable. It also differentiates from siblings like get_thread and get_messages by explaining when to use each for thread 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 explicitly outlines when to use the tool versus alternatives, stating 'For thread retrieval, call get_thread(...) to expand an anchor into thread member ids, then optionally pipe those ids into source=[ids] or get_messages([ids])'. It also explains conditions like when account is required (source is None) versus ignored (source is a list), and notes post-filtering behavior.

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 accurately describes the side effect (sending an email) without contradictions. Annotations already indicate it's a write operation and not idempotent, so the description doesn't need to restate that. It adds no misleading information.

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 exceptionally concise: two short sentences that convey the essence of the tool. It includes the primary action, the immediacy, and the relationship to create_draft without any superfluous 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?

The description is complete for the tool's purpose. It clearly states what the tool does and its relationship to a sibling tool. Since an output schema exists, return values need not be explained. No critical information 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 description does not elaborate on any parameters, but the input schema provides full descriptions for all seven parameters with 100% coverage. Per the rubric, a high coverage warrants a baseline score of 3, and the description adds no additional meaning.

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 action: 'Send a new email immediately.' It also distinguishes itself from create_draft by explicitly noting it is a convenience wrapper with send_now=True, which removes ambiguity about its purpose compared to related tools.

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 vs. create_draft by presenting it as a convenience wrapper that sends immediately, but it doesn't explicitly contrast with other alternatives like reply or forward. It provides enough context for an agent to infer the appropriate use case.

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 goes far beyond the annotations by revealing the delete-and-recreate implementation, the return of a NEW draft_id, preservation of threading metadata, attachment merge semantics, and performance caveats. Annotations only flag idempotent/destructive/read-only status; the description provides the operational detail needed to avoid surprising side effects. No contradiction with annotations exists.

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 longer than average but each sentence carries essential information about behavior, edge cases, and performance. The delete-and-recreate fact is front-loaded, and bolded sections for return value and merge semantics aid scanning. Some verbosity around seed recovery could be trimmed, but it is all relevant to correct invocation.

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 12 parameters, destructive semantics, and complexity, the description is remarkably complete. It covers return value, field merge rules, attachment handling, body_html caveats, external-draft performance, and a forward-seed misclassification warning. The only minor gap is template behavior, but that is likely documented in create_draft, which is referenced. An agent has enough context to invoke 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?

With 58% schema description coverage, the description adds valuable global merge semantics: any non-None argument overrides, None preserves, and attachment_paths has special behavior for None, [], and a list. It also clarifies the non-obvious body_html limitation (must be re-passed or lost). This compensates well for parameters like template_name and template_vars that the schema leaves undocumented.

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 identifies the operation as updating an existing draft, and immediately adds the crucial implementation detail that it is delete-and-recreate. This distinguishes it from create_draft and delete_draft, though the name alone could mislead until the description is read. The verb+resource+behavior is specific enough for an agent to know what the tool does.

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 explains when to use this tool: when a saved draft needs mutation, since Mail.app forbids direct editing. It gives guidance for externally-created drafts, warning about slow In-Reply-To scanning and recommending an explicit body for forward seeds. It does not explicitly name sibling alternatives, but the context makes the appropriate usage clear.

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=false, destructiveHint=true, and idempotentHint=true, and the description does not contradict them — the mutation framing is consistent. Beyond the annotations, it adds genuinely useful behavioral detail: the two execution mechanisms (AppleScript vs IMAP RENAME), the imap_required error for missing credentials, and the unsupported_gmail_system_label refusal with its rationale. This is valuable context that structured fields cannot express.

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 front-loaded with the purpose statement and uses headers, bullets, and inline code formatting to keep distinct behaviors scannable. It is longer than average, but every section maps to a concrete operational concern (delivery paths, validation, refusal conditions) so no sentence is wasted. Formatting trades some brevity for readability and earns its length.

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 4 parameters, two execution paths, and multiple edge cases, the description is remarkably complete. It covers prerequisites (IMAP Keychain credentials), the validation rule, both error_type outcomes, and the Gmail system-label distinction between refused and allowed paths. An output schema exists, so return-value prose is appropriately omitted; nothing needed 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%, so per calibration the baseline is 3. The schema already thoroughly documents each parameter (leaf-name sanitization, None semantics, empty-string top-level move). The description adds value by explaining the interaction between new_name and new_parent — how their combination selects the delivery path — which goes slightly beyond the schema, but not enough to exceed 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 description opens with a specific verb-plus-resource statement — 'Rename and/or re-parent (move) an existing mailbox' — that clearly differentiates this from its siblings create_mailbox, delete_mailbox, and list_mailboxes. The two delivery paths further specify the operation's scope without ambiguity.

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 strong conditional guidance: which path executes depending on whether new_name vs new_parent is set, when IMAP credentials are needed, and the validation requirement that at least one parameter be provided. It enumerates the two refusal conditions and their trigger criteria. It stops short of explicitly naming alternative tools or when-not-to-use scenarios, but the path selection logic is thorough enough that an agent can route 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?

Annotations already cover destructiveHint and idempotentHint, so the description adds supplementary operational detail: atomicity, patch semantics (only specified fields change), order of operations (read/flag before move), and the IMAP requirement for STORE before MOVE. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each dense with distinct information: primary action, patch semantics, and ordering/IMAP caveat. No filler, front-loaded with the core purpose, and easy to scan.

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 output schema exists (covering return value), the description addresses the key behavioral aspects: atomicity, patch semantics, ordering for IMAP, and the replacement of old tools. Combined with the highly detailed schema and annotations, an agent has everything needed to invoke 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 covers all 8 parameters at 100%, so the baseline is 3. The description goes beyond the schema by clarifying that specified fields are treated as patch updates (None leaves unchanged, implicitly) and that move operations depend on source/destination mailbox ordering. This adds meaningful context for parameter usage.

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 (update), resource (messages), and enumerates the three action types (read state, flag, move). Explicitly differentiates from its predecessors mark_as_read, move_messages, and flag_message, and by its name stands apart from delete_messages. An agent can immediately know what it does and how it differs.

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?

Clearly tells the agent to use this in place of the three older tools, and explains the patch semantics and atomic call. It also specifies the ordering constraint for IMAP. It does not explicitly call out exclusions like 'use delete_messages for deletion', but the verb distinction and naming make that inference straightforward.

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 flag this as destructive and idempotent, but the description goes far beyond: it spells out replacement-not-merge semantics for conditions/actions, the conditional confirmation trigger (touching conditions/actions or moving/forwarding/deleting), which paths skip confirmation (flags, name/enabled), and the refusal behavior for unsupported actions. This is exactly the behavioral detail an agent needs before calling a destructive mutation, and it exceeds what the 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 long but every sentence earns its place — patch semantics, confirmation triggers, refusal conditions, and the migration note all carry unique information. The section markers ('Patch semantics:', 'Conditional confirmation:') aid parsing, though a stricter use of line breaks or bullets would improve scanability. It's dense but not padded.

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 description fully covers mutation semantics (patch vs replace), conditions for user confirmation, refusal cases, the replacement of the removed enable/disable tool, and correct usage of rule_index. With an output schema presumably present)Skip nothing needed about return values. Given the complexity of a patch tool with safety gates Submission rules, this is complete enough that I can't identify a behavior the agent would have to guess.

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 essentially 100% (every param has a description), but the description adds the decisive semantics: `conditions`/`actions` REPLACE wholesale rather than merge, `rule_index` is 1-based from a specific prior call (list_rules), and the `enabled` path replaces a removed tool call. These semantics are not inferable from the schema field names alone and are exactly what prevents a wrong call.

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?

Lead sentence states the verb (update), object (rule), and the patch model immediately: 'Update an existing Mail.app rule (patch semantics)'. The first paragraph unambiguously defines what is changed and how, and the closing sentence adds the boundary case (refusal for unsupported actions). No ambiguity about what the tool does.

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?

Exceptional. It specifies when confirmation is prompted (matching-scope fields and dangerous actions), when it is skipped (organizational flags, enabled/name), and explicitly tells the agent that the enable/disable path replaces the removed `set_rule_enabled` tool with a concrete call pattern: `update_rule(rule_index, enabled=True|False)`. It also states the refusal condition and the fallback action (edit in UI). An agent has everything needed to decide when to call it safely.

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