Update alert rule

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation trait is disclosed via annotations. The description adds meaningful behavioral detail beyond annotations: the full-replacement semantics and the fact that condition_type and name are required even for single-field updates. This is valuable because update tools often silently partial-patch, and this one does not. No contradictions 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?

Two sentences, front-loaded with the core verb+resource action and a critical behavioral caveat. Every sentence earns its place and there's no fluff. Slightly thin given the tool's complexity of 17 condition-dependent params, but the structure is clean 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?

The tool has 17 parameters, no output schema, and only 29% schema description coverage. The description captures the most important semantic (full replacement and required fields) but does not address condition-parameter coupling—e.g., which params make sense for 'change_pct' vs 'threshold' vs 'serp_feature' conditions. For a complex tool there is no guidance on selecting target_ids/target_type or recipient_ids/channels relationships. It's adequate for basic use but leaves meaningful 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?

Schema description coverage is only 29%, and the description adds value beyond the schema by explaining the replacement semantics affecting required parameters. However, the 17 parameters are largely undocumented in the description—it doesn't explain the condition-specific parameter combinations (e.g., which params apply to which condition_type values). The description covers the critical name/condition_type/rule_id nuance but leaves condition-parameter relationships unexplored for a complex 17-param tool.

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 alert rule by rule id' with a specific verb and resource. It distinguishes the operation from siblings like create_alert_rule and delete_alert_rule by implying a replacement semantics. However, it doesn't explicitly name the sibling alternatives for differentiation, and the 'replaces whole rule configuration' clause overlaps with behavioral transparency.

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 clear guidance that this is a full-replacement operation ('replaces the whole rule configuration'), which is crucial usage context. It implies when not to use it (not for partial updates), though it doesn't explicitly name alternatives like create_alert_rule for new rules. The condition_type and name being required as clues to create-like semantics is helpful.

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