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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses meaningful behavior: the partial-update contract and the condition evaluation rule ('All conditions must hold for the rule to match'). The 'Confirm with the user first' instruction reinforces the destructive hint. No contradiction with 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 front-loaded with the essential update semantics before the detailed condition specification. The condition paragraph is dense but contains information available nowhere else, so every sentence earns its place. It is longer than ideal but not bloated.

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

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

For a complex 9-parameter mutation tool with no output schema, the description is thorough: it covers partial-update behavior, the full condition contract including enum values and ranges, the all-conditions-must-hold semantics, and the return value ('Returns the updated rule'). Nothing an agent needs to call it safely and 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%, establishing a baseline of 3. The description adds substantial value by mapping condition types to their required fields – SCORE_* requires category (with enum values) and threshold 0-100, BADGE_* requires a badge slug, IDENTITY_AGE_* requires seconds. This dependency information exists nowhere in the schema, so the description earns an above-baseline score.

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

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

The opening line 'Update an escalation rule' is a specific verb+resource statement that clearly conveys the action. Partial-update semantics ('Pass only the fields to change; omitted fields keep their values') add real precision. It distinguishes itself from siblings implicitly by the action verb (update vs create/delete/get/preview) but never names the alternatives explicitly.

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

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

The description gives clear operational guidance: partial updates leave omitted fields unchanged, and the agent is told to 'Confirm with the user first' – appropriate for a mutation tool. However, it does not explicitly say when to prefer this tool over create_escalation_rule or preview_escalation_rule, leaving the routing to inference.

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