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

The annotations already convey read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds unique transparency about the unknown case: it says `unknown` when nothing independent is on record, and explicitly reports absence of evidence as absence rather than treating it as a safety record. This is valuable behavioral disclosure beyond what the annotations provide.

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 information-dense but compact, with each sentence adding a distinct fact: the core question, the money-path scope, the no-component fallback, the unknown/absence semantics, and the free cost. The most important idea is front-loaded, and no sentence is wasted.

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 two-parameter, no-required-arguments read-only tool, the description covers the main usage scenarios, scope limitations, optional-component behavior, and the meaning of an unknown result. An output schema exists, so return-value details do no need to be in the description. The only minor ambiguity is the exact meaning of "recently," but overall the description gives an agent enough to select and invoke the tool confidently.

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 documents `component` with an example but leaves `to_version` without a description. The tool description compensates partially by explaining that a named component plus version is checked against evidence, and that omitting `component` causes every recent commerce change to be checked. It does not clarify what happens when `component` is provided but `to_version` is omitted, nor does it specify version formats or defaults, so there is still a small semantic gap.

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 opens by answering a precise question: whether a store's checkout/payment change is known to have broken revenue elsewhere. It names the exact resource (checkout/payment path), the action (risk check against public evidence), and the two timing contexts (before applying or after explaining). It also explicitly separates this from general plugin-update safety, which distinguishes it from a generic version-safety tool.

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 clearly states when to use the tool: before a payment-path change is applied, or when explaining an already-made change. It also gives a when-not by excluding general plugin update safety. However, it never names sibling tools such as diagnose_revenue_incident or get_checkout_health_snapshot as alternatives, so the agent must infer the boundary from context rather than being pointed to a specific alternative.

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