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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description earns credit by explaining the blast radius ("pricing rules can affect many listings") and the user-confirmation gate, which is the context an agent needs before a destructive write, though it says nothing about rollback or reversibility.

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 short sentences, front-loaded with the operation and scope, then the gating requirements. No filler; only the trailing "Requires HGRApi Header channel" clause is cryptic enough to cost a 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?

Output schema exists and full annotation coverage is present, so the description only needs to carry intent and guardrails, which it largely does. The gaps are the unresolved channelOAuthId sourcing and no pointer to hgr_get_pricing_rules as the source of the RuleId referenced in the body.

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 the reason the two confirmation booleans exist (high-impact changes across many listings). However, "ChannelOAuthId resolved internally" sits awkwardly against a schema that marks channelOAuthId as a required caller-supplied parameter, creating ambiguity about who supplies it.

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 concrete verb and resource ("Updates a pricing rule") plus scope ("for one visible store"), which cleanly separates it from hgr_add_pricing_rule, hgr_delete_pricing_rule and hgr_get_pricing_rules. It never names those siblings explicitly, so an agent must infer the distinction from the verb alone.

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?

Gives usable preconditions: both confirmed and impactConfirmed must be true before the call, and the operation is scoped to a single visible store. It stops short of naming when to prefer a sibling (e.g. add vs. update) or that the rule id should come from hgr_get_pricing_rules.

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