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

Annotations indicate it is not read-only, idempotent, or destructive. The description adds behavioral traits: send_now elicits user confirmation, HTML body requires IMAP and has constraints, and body replacement behavior for replies/forwards. 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 description is concise: a short first sentence capturing the core action, followed by a slightly longer second paragraph adding context. It is front-loaded and avoids unnecessary words, though the second paragraph could be trimmed slightly.

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 15 parameters and high schema coverage, the description provides good overall context: modes (fresh/reply/forward), send behavior, HTML constraints, and auto-quote handling. It is complete enough for typical usage, though some error scenarios beyond HTML are not detailed.

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 high (80%), so the baseline is 3. The description adds minimal extra meaning beyond the schema's built-in parameter descriptions; it reiterates the overall purpose but does not significantly enhance individual parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a draft (fresh, reply, or forward) and optionally sends it immediately. It uses a specific verb ('Create') and resource ('draft'), and distinguishes the tool from siblings like update_draft by indicating it is for creation.

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 that the tool is for creating a draft from scratch or from an existing message, with an option to send. While it provides clear context, it does not explicitly contrast with alternative tools (e.g., update_draft for modifications) but the purpose is clear enough for an agent.

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 indicate the tool is mutating (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds 'create' but doesn't disclose side effects or permission requirements. Given annotations cover key traits, the description adds minimal value.

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 that communicates the core purpose without wasted words. It is appropriately front-loaded.

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 lacks important context such as required preconditions (e.g., account must exist), uniqueness constraints on mailbox names, or details about the return value. Given the existence of an output schema and annotations, more behavioral context is expected.

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 itself documents all parameters well. The description does not add additional meaning beyond what the schema provides, earning a baseline score 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 uses a specific verb ('Create') and resource ('mailbox/folder'), clearly stating the action. It distinguishes from siblings like update_mailbox and delete_mailbox, but could be more explicit about the 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 guidance is provided on when to use this tool versus alternatives like list_mailboxes or update_mailbox. There are no prerequisites, conditions, or scenarios mentioned.

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 basic (no read-only, idempotent, or destructive hints). The description adds crucial behavioral traits: confirmation prompts for certain actions, no prompt for others, rule appending behavior, and the meaning of rule_index. 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 description is concise (5 sentences), front-loaded with purpose, and structured logically. Every sentence adds necessary context without 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?

Given the tool's complexity (5 params, nested objects, output schema), the description covers all key behavioral aspects: confirmation, rule ordering, output index meaning. No gaps for safe and 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?

Schema coverage is 100%, so schema already documents parameters well. The description adds value by explaining which actions trigger user confirmation, a behavioral aspect not in the schema. This helps the agent understand the real-world effect of the 'actions' 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 clearly states it creates a new Mail.app rule, with specific verb and resource. It distinguishes from siblings like update_rule, delete_rule, list_rules by detailing creation behavior and rule types.

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 tells when user confirmation is needed (actions that move/forward/delete) and when not (organizational-only). Also explains rule ordering and output semantics (rule_index equals new total count). This helps the agent decide when to use create vs update.

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

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

Beyond annotations, the description adds that recovery is technically possible but the draft becomes non-editable, making it effectively one-way. It also notes no rate limit and local operation, providing useful behavioral context.

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

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

The description is concise (4 sentences) and front-loads the main action. The second sentence ('Lifecycle endpoint for cancellation') adds slight redundancy but does not detract significantly.

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 simple tool with one parameter and existing annotations/output schema, the description covers the action, effective behavior, recovery, rate limit, and local operation, making it fully adequate.

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?

There is one parameter (draft_id) with schema coverage at 100%. The description does not add extra information about the parameter beyond what the schema provides, so it meets 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?

The description begins with 'Delete (move to Trash) an existing draft,' clearly stating the verb and resource. It distinguishes from sibling tools like delete_messages by specifying it's for drafts.

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 usage as a 'lifecycle endpoint for cancellation,' but does not explicitly state when not to use it or list alternatives. However, the context of drafts versus messages provides clear guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds significant behavioral details: it requires IMAP credentials from Keychain, always elicits user confirmation, refuses non-empty mailboxes by default with a cascade option, and returns specific error types for missing credentials or unsupported Gmail paths. No contradiction with annotations; it enriches the agent's understanding.

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

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

The description is moderately long but well-structured with paragraphs for method, behavior, and constraints. Each sentence provides distinct value (e.g., reason for IMAP, credential requirement, cascade behavior, Gmail restriction). 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 destructive nature, multiple constraints (empty check, Gmail paths, credential requirement), the description is thorough. It covers the operation method, prerequisite, user confirmation, and error handling. Since output schema exists, return values don't need explanation. The description is complete for safe and correct tool use.

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 parameter descriptions, but the tool description adds practical context: name is slash-separated for nested mailboxes, account is display name or UUID, and delete_messages defaults to false and cascade-deletes when true. This adds meaning beyond the schema without redundancy.

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 states 'Delete a mailbox via IMAP', which is a specific verb and resource. It distinguishes itself from siblings like 'delete_messages' by explaining why IMAP is used instead of AppleScript, and it's clearly a different operation from 'create_mailbox'.

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 the tool (deleting a mailbox) and provides critical conditions: it refuses non-empty mailboxes by default, requires delete_messages=True to cascade, and unsupported for [Gmail] paths. It also mentions the IMAP credentials prerequisite. While it doesn't explicitly list alternatives, the context and mention of unsupported paths give good guidance.

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

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

The description adds critical context beyond annotations: messages always go to Trash, the 'permanent' parameter is currently a no-op and deprecated, and behavior matches sibling delete tools. This complements the destructiveHint=true annotation with practical details.

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 brief and front-loaded with the core action. The additional note about user confirmation is useful but could be more structured. Still, 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?

Given the presence of annotations, full schema, and output schema, the description sufficiently covers the tool's behavior: it explains the Trash behavior, no-op permanent parameter, and confirmation requirement. No further gaps.

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?

Input schema covers all 4 parameters with descriptions (100% coverage). The description adds value by clarifying that 'permanent' is a no-op, which is not evident from the schema alone. Baseline 3, plus extra context justifies 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 starts with 'Delete messages (always moves to the account's Trash mailbox)', clearly stating the action and specificity (moves to Trash). This distinguishes it from sibling tools like delete_draft, delete_mailbox, etc.

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 notes that the tool is 'Destructive: gated behind user confirmation via MCP elicitation (issue #239)', which provides usage guidance about requiring user confirmation. However, it does not explicitly state when not to use this tool or provide alternatives.

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 destructiveHint and idempotentHint. Description adds that it requires user confirmation and that Mail.app does not version rule history, adding context beyond annotations. No contradiction.

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

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

Two sentences that efficiently convey purpose and key behavioral details. No wasted 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?

Given one parameter, clear annotations, and existence of an output schema, the description is complete for a delete 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?

Single parameter has full schema coverage with description that matches the tool's text. The description does not add new meaning beyond the schema; both specify it's 1-based and from list_rules. 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 verb (delete), resource (Mail.app rule), and method (by 1-based positional index). Distinguishes from sibling tools like delete_draft or delete_mailbox.

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 warns about destructive nature and need for user confirmation, and that action cannot be undone. No guidance on when to avoid using it, but for a delete tool this is sufficient.

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

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

Beyond annotations (destructiveHint=true), the description adds the requirement for user confirmation, which is critical for safe execution. This provides actionable behavioral context not covered by structured fields.

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

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

Two sentences, first stating purpose and second adding behavioral note. Every sentence adds value; no wasted 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?

Despite simplicity, the description fully covers purpose and key behavioral aspect (user confirmation). With an output schema present (not shown), the description is sufficient for correct tool 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?

Schema coverage is 100% with a clear description for the 'name' parameter. The tool description adds no further parameter details, 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?

The description clearly states 'Delete a template by name', specifying the verb (delete), resource (template), and method (by name). It distinguishes from sibling tools like delete_draft, delete_mailbox, etc.

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 notes 'requires user confirmation via MCP elicitation before running', guiding the agent to involve the user for destructive actions. It could be more explicit about when not to use, but given the context, it's 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 readOnly, idempotent, and non-destructive. The description adds context by clarifying no disk write, and hints at supported file types (text, JSON, small PDFs), but could be more explicit about limitations (e.g., size constraints).

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 no extraneous content. The key purpose and usage scenario are front-loaded, and every sentence provides essential information.

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

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

Given the presence of an output schema and annotations, the description adequately covers usage context, behavioral traits, and parameter semantics, leaving no significant gaps for a read 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?

Schema coverage is 100%, but the description adds value by explaining the rationale for account/mailbox (faster IMAP path) and linking attachment_index to sibling tool output, which helps the agent understand parameter relationships.

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 states the action (read content) and resource (attachment), and distinguishes itself by emphasizing 'inline, without writing to disk.' This clearly separates it from sibling tools like save_attachments.

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 a concrete use-case ('triage' workflows) and explicitly contrasts with the alternative workflow of save_attachments + read + cleanup, making it clear when to choose this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns a list of message dicts (possibly length 0 or 1), which is useful but not beyond what annotations imply. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, followed by actionable pairing advice. No unnecessary words, every sentence adds value.

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

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

With an output schema present, the description adequately covers core behavior and pairing context. For a tool with 6 parameters and 1 required, the description is complete enough for agent selection.

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

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

Schema coverage is 100%, so the schema fully documents all 6 parameters. The description does not add significant meaning beyond the schema for parameters, 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?

The description clearly states the tool retrieves full details of messages with bodies, and explicitly distinguishes it from sibling tools search_messages (metadata-only) and get_thread (thread member ids). This provides specific verb+resource 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 description advises pairing with search_messages and get_thread to fetch bodies, providing clear context for use. It does not explicitly state when not to use, but the pairing guidance is effective.

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 and idempotentHint, so safety and idempotency are covered. The description adds transparency about the computational basis ('computed from a single search_messages pass'), the default window, and the truncation behavior (window_fully_covered flag). This provides valuable behavioral context beyond 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 approximately 150 words, well-structured with a clear opening sentence followed by detailed explanations. Every sentence adds value: the first states purpose, the second distinguishes from siblings, the third explains defaults and behavior. No redundant or filler content.

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

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

Given the tool's complexity (8 parameters, output schema), the description is complete. It covers what is returned (volume, counts, ratio, top senders), the truncation indicator, and the relationship to search_messages. The presence of an output schema means return values need not be detailed further.

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 parameters are fully defined. The description adds context: it explains that 'by' groups top senders by 'address' or 'domain', that 'scan_limit' bounds cost, that 'received_within_hours' defaults to 720 (≈30 days), and that 'date_from'/'date_to' compose with the window. This enhances understanding beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it aggregates inbox statistics over a mailbox and time window, specifying exactly what is computed (message volume, read/unread/flagged counts, read ratio, top senders). It also distinguishes itself from the sibling tool list_mailboxes, which provides per-folder unread counts.

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 when-to-use guidance: it is 'the consolidated inbox-stats tool' and notes that per-folder unread counts 'live on list_mailboxes and are not duplicated here', directly naming an alternative. It also explains the default window and how to set explicit ranges.

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, idempotentHint, destructiveHint. The description adds no additional behavioral context beyond what annotations state, such as response format or permissions. Minimal added value.

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?

Single sentence with five words, no redundancy, and front-loaded with the key action and resource. 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?

The tool is simple with one parameter, a well-described input schema, output schema present, and annotations covering safety. The description is sufficient for an agent to understand the tool's purpose and usage.

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 parameter 'name' has a clear description. The description restates that the tool reads by name, but does not add extra 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 clearly states the verb 'Read' and the resource 'template by name', distinguishing it from sibling tools like list_templates (list all) and save_template (create/update).

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 (retrieve a specific template by name) but does not explicitly state when not to use or mention alternatives like list_templates for overview. However, the context from sibling tools is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: sorting by date_received ascending, threading dispatch method (Tiered IMAP, AppleScript fallback), and a known limitation about subject rewrite. 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?

Description is front-loaded with main purpose and then provides technical details. Could be slightly more concise, but every sentence adds value. Good structure.

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 output schema exists for return values, the description adequately covers the tool's behavior, threading algorithm, limitations, and integration with sibling tools. Sufficient for accurate 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?

Schema coverage is 100% for message_id. Description adds context that it is an 'Internal id of any message in the thread' and how it is used as anchor, which adds some value beyond 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?

Description clearly states 'Return all messages in the thread containing the given message.' It details the lookup and reconstruction process, and the tool name 'get_thread' aligns with this purpose. Distinguishes from siblings like get_messages and search_messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how returned ids can be piped into search_messages or get_messages for further processing, providing a usage pattern. However, it doesn't explicitly state when to use this tool vs alternatives 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds return value details but no additional behavioral traits. No contradiction.

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

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

Description is concise, well-structured with sections for return details and an example. Every sentence adds value.

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

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

For a simple list tool with no parameters and an output schema, the description is complete. It explains return fields, includes a stability tip, and provides an example.

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?

No parameters, so schema coverage is 100%. Description adds value by explaining return values and providing an example, meeting the baseline for zero-parameter tools.

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 lists all configured email accounts in Apple Mail, specifies the returned fields (id, name, email addresses, type, enabled state), and distinguishes from sibling tools like list_mailboxes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a usage hint about preferring account IDs over names due to stability, but does not explicitly state when to use this tool vs alternatives. The hint adds practical guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds no behavioral traits beyond the basic function. No contradiction.

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

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

Single sentence, no wasted words, front-loaded purpose. Highly concise.

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?

Simple tool with good annotations and output schema. Description is minimal but sufficient. Could mention obtaining account via list_accounts, but not necessary.

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 parameters with sufficient descriptions (100% coverage). Tool description does not add new information about 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?

Description clearly states verb 'List', resource 'mailboxes', and scope 'for an account'. It distinguishes from sibling tools like list_accounts or list_rules.

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 guidance on when to use this tool versus alternatives (e.g., after listing accounts). Does not mention prerequisites like needing an account name or UUID.

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 and idempotentHint. The description adds value by disclosing return format, uniqueness caveats, and AppleScript limitations beyond what annotations convey.

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

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

Well-structured: immediate purpose, then key caveats, then return format with example. Every sentence adds value, no waste.

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

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

Given zero parameters, good annotations, and output schema, the description fully covers purpose, behavior, return structure, and edge cases (duplicate names, no stable ID).

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?

No parameters exist, so baseline is 4. The description does not need to add parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all Mail.app rules (read-only)' with a specific verb and resource, and distinguishes from sibling mutation tools like create_rule, delete_rule, update_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?

It explicitly notes read-only nature and that mutation is tracked separately, implying when to use. It provides caveats about duplicate names and no stable IDs, but doesn't explicitly state when not to use.

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 (readOnlyHint, idempotentHint, destructiveHint false), the description reveals that templates are stored as files at a specific path and can be overridden via an environment variable. It also describes the return structure (dictionary with name and subject), adding significant behavioral context.

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

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

The description is extremely concise, using only five lines to convey the purpose, location, customization option, and return format. Every sentence provides essential information without 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?

Given the zero parameters and the presence of an output schema, the description fully covers the tool's purpose, storage location, and return structure. No additional information is needed for an agent to correctly select and 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?

No parameters are defined, and the schema coverage is 100%. The description does not need to add param info, so a baseline of 4 is appropriate since it fully covers the input requirements.

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 it lists all stored email templates, with specific verb 'list' and resource 'email templates'. It also details file location and environment variable override, distinguishing it from sibling tools like get_template.

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 guidance on when to use this tool versus alternatives like get_template or other list tools. The context is implied but not stated, leaving the agent to infer from the tool's name and purpose.

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

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

Annotations declare readOnly, idempotent, non-destructive; description adds context on auto-population with message_id and override behavior, no contradictions.

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?

Concise, front-loaded with purpose, uses bullet-like structure for additional details, no extraneous text.

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 output schema existence, description covers side effects, usage flow, and auto-population details, fully meeting completeness requirements.

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 3; description adds meaning by explaining how message_id auto-populates recipient_name, recipient_email, etc., and that vars override auto-fills.

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 renders a template into subject and body text, distinguishing from sibling tools like create_draft and update_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?

Explicitly states no side effects, that caller must pass rendered text to create_draft/update_draft, and when to use send_now=True, providing clear context for usage.

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 indicate idempotentHint=true and destructiveHint=false. The description adds no behavioral context beyond the action itself, such as overwrite behavior or error handling. It does not contradict 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 sentence that is front-loaded and contains no unnecessary words. It efficiently conveys the core function.

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 has an output schema (not shown but known) and detailed parameter descriptions in the schema, the description is minimally adequate. However, it lacks details on behavior (e.g., how missing directories are handled, attachment types) that would fully inform an agent.

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 has 100% description coverage, so the schema already documents all parameters thoroughly. The tool description does not add any additional semantic meaning beyond repeating the action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Save' and resource 'attachments' from a message to a directory. It is specific and distinguishes from sibling tools like 'get_attachment_content' which returns content rather than saving.

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 guidance is given on when to use this tool versus alternatives (e.g., get_attachment_content). It does not provide context for optimal selection or mention any prerequisites or limitations.

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 aligns with annotations (idempotentHint=true, destructiveHint=false) by indicating overwrite behavior. However, it does not disclose any additional side effects or permissions needed beyond what annotations already 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 a single concise sentence. While it is not wasteful, it could be slightly more structured (e.g., adding a note about idempotency) without adding 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 write tool with an output schema, the description is minimally adequate but does not clarify behavior when a template already exists (e.g., overwrite vs error), which is partially covered by the idempotentHint annotation.

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 100% schema description coverage, the schema already documents all three parameters. The description adds no extra meaning or constraints beyond what is in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('create or overwrite') and the resource ('template'). It distinguishes itself from sibling tools like create_draft (drafts) and delete_template (deletion).

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 guidance is provided on when to use this tool vs alternatives, such as render_template or get_template. There is no mention of when not to use it or preconditions.

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 readOnlyHint/idempotentHint annotations, describes that it returns metadata-only rows, includes performance warnings for body_contains/text_contains, and explains include_attachments overhead. No contradictions.

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

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

Well-structured with sections and bullet points, front-loaded with purpose. Slightly lengthy but all content is justified by the tool's complexity. Could be condensed slightly.

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?

Comprehensive coverage of 15 parameters, modes, filtering, performance, and related tools. Output schema exists, so return value explanation is unnecessary. No gaps identified.

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 source/account/mailbox interaction and mode behavior, but individual parameter descriptions are already thorough in schema. Still adds value beyond 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?

Clearly states 'Search for messages matching criteria' and distinguishes two corpus modes. Verb+resource is specific, and sibling differentiation is implicit via mode explanations (e.g., compare to get_messages for full bodies).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use each mode (source=None vs source=list) and when to prefer alternatives like get_messages or get_thread. Provides clear context for filtering composition.

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

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

Beyond annotations (destructive, idempotent), the description reveals the delete-and-recreate implementation, new draft_id return, seed preservation, attachment handling, and limitations with external drafts. This is highly transparent.

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 key facts upfront, then detailed semantics. It is slightly verbose but every sentence adds important information, balancing completeness and readability.

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 (destructive, idempotent, 12 parameters, behavioral nuances), the description covers critical aspects: new ID, merge rules, attachment handling, external draft performance, and HTML limitations. The output schema likely covers return values, making it 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 schema covers 58% of parameters with descriptions, and the description adds global merge semantics and specific behavior for attachment_paths and body_html. It does not detail all 12 parameters individually, but the provided context is valuable.

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 ('Update an existing draft') and the resource ('draft'). It distinguishes from siblings like create_draft by noting it operates on existing drafts and returns a new draft_id, making the purpose unambiguous.

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 implicitly tells when to use (to modify a draft) and provides caveats (e.g., external drafts may be slow), but it does not explicitly contrast with create_draft or delete_draft. However, the context is clear enough for an agent.

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 indicate mutation (readOnlyHint=false) and destructiveness (destructiveHint=true). The description adds details: IMAP credentials required for moves, error types like 'imap_required' and 'unsupported_gmail_system_label', and the AppleScript vs IMAP distinction. This enriches the behavioral model beyond 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 well-structured with bullet points and clear separation of modes. It is slightly long but each sentence adds necessary context. It is front-loaded with the core purpose. Could be slightly more concise, but overall 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?

The description covers the complexity of two operational modes, prerequisites, error conditions, and Gmail-specific restrictions. With an output schema existing (as per context), it does not need to detail return values. All critical aspects are addressed.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains the two operational modes, the conditions for new_name and new_parent (at least one required), and special cases like empty string for new_parent. This greatly aids parameter understanding.

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 'Rename and/or re-parent (move) an existing mailbox,' using specific verbs and resource. It distinguishes from siblings like create_mailbox and delete_mailbox by focusing on modification operations.

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 outlines two delivery paths (rename-only vs move) with distinct mechanisms (AppleScript, IMAP RENAME) and prerequisites (IMAP credentials). It also notes when Gmail system labels are unsupported, providing context for when not to use. It could explicitly state when to use this over alternatives like create_mailbox, but that is implied.

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

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

Annotations indicate idempotent (true) and destructive (true). The description adds atomic behavior, patch semantics, and real-world IMAP order constraints (read/flag before move). It also explains deprecated gmail_mode. This goes beyond annotations, providing valuable behavioral context.

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

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

The description is concise, front-loaded with the core purpose, and each sentence adds value. It efficiently covers atomicity, replacement of old tools, and IMAP considerations without 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?

Given the complexity (8 parameters, output schema present), the description covers purpose, usage context, behavioral details, deprecation, and order of operations. The output schema handles return values, making the description complete for effective tool selection and 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?

Schema coverage is 100% with detailed parameter descriptions. The tool description adds overall context (atomic, patch semantics) but does not significantly enhance individual parameter meaning beyond what the schema already provides. 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?

The description clearly states it updates messages by changing read state, flag, and/or move, all in one atomic call. It specifies the resource (messages) and actions, and distinguishes from siblings like delete_messages by focusing on update operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says it replaces previous separate tools (mark_as_read, move_messages, flag_message) and provides order-of-operations guidance for IMAP. It lacks an explicit statement of when not to use it, but provides sufficient context for typical use.

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 indicate destructive and idempotent, but description adds conditional confirmation, refusal behavior, and patch semantics. No contradiction.

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

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

Long but well-structured; each section adds unique value. Slight redundancy in explaining patch semantics twice, but overall efficient for the complexity.

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 output schema present and 6 params, the description covers all behavioral nuances: patching, confirmation, refusal, and deprecation replacement. No gaps identified.

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

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

Schema coverage is 100%, but description adds vital context: wholesale replacement of conditions/actions, only-set-if-not-None behavior, and the enable/disable shortcut. This is well 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 clearly states 'Update an existing Mail.app rule (patch semantics)' and distinguishes from sibling tools like create_rule and delete_rule with specific verb and resource.

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?

Extensive guidelines: explains patch semantics, when confirmation triggers (conditions/match_logic/dangerous actions), when it skips (flags, name, enabled), and refusal for unsupported actions. Also notes that enable/disable replaces set_rule_enabled.

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