update_rule

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.