Woo Revenue Incident Graph

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

Beyond the annotations, it discloses the evidence basis (public release and issue evidence), the scoping behavior when no component is named, and the meaningful epistemic handling of unknown results: absence of reports is reported as absence, not as safety. This is high-value behavioral disclosure for an open-world, read-only tool.

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 dense but not bloated; the core question is front-loaded, and each sentence contributes a distinct behavioral or scoping fact. The parenthetical money-path examples and the final cost note add useful context without wasted words.

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?

Combined with the output schema and the readOnly/openWorld/idempotent annotations, the description covers the tool's scope, fallback behavior, epistemic limitation, and cost. Nothing an agent needs to invoke it correctly or interpret its result seems 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?

The schema describes only 'component'; the description adds that omitting component checks the store's recent changes and that a component/version pair is checked against evidence. It does not detail the format or optionality of 'to_version', but with 50% schema coverage and 0 required parameters, the description meaningfully compensates.

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 with a concrete question and defines the tool as a check of a component/version against public evidence scoped to the checkout or payment money path, including temporal scope ('before it is applied, or when explaining a change that was already made'). It explicitly separates itself from general plugin update safety, and its focus on revenue breakage distinguishes it from the sibling tools around incident diagnosis, health snapshots, and recovery verification.

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?

It clearly states when to use the tool: pre-apply risk assessment or post-hoc explanation of an existing change. It also provides a when-not by saying it is 'not to general plugin update safety.' However, it does not explicitly name sibling tools as alternatives, so the routing guidance is slightly incomplete.

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

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

Beyond the annotations (read-only, idempotent, open-world, non-destructive), the description discloses that the tool reports which signal families were collectable, returns counterevidence and unknowns, abstains without charging when evidence is insufficient, and is free in beta. These are meaningful behavioral details that materially affect how an agent should interpret the response.

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 major section earns its place: purpose, signal coverage, abstention policy, beta status, and prerequisite. The prerequisite instruction at the end is slightly less front-loaded than ideal, but the overall structure is clear and 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?

Given the output schema and annotations, the description is fully complete: it explains return shape, coverage limits, abstention conditions, cost implications, and the required prerequisite call. Nothing an agent needs to decide whether and how to invoke the tool 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 description coverage is 100%, so the schema already fully documents symptom and window_seconds. The description adds no additional parameter-level guidance beyond the existing schema, matching the baseline for high coverage.

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 explicitly states the tool diagnoses what broke a store's checkout/payment path, supplies counterevidence, and advises on verifying a fix. It describes concrete outputs (ranked hypotheses, evidence, verification plan) and clearly distinguishes itself from the sibling get_checkout_health_snapshot by naming it as a prerequisite rather than duplicating it.

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?

It tells the caller to invoke get_checkout_health_snapshot first and explains when the tool abstains (stale snapshot, thin coverage, unsupported signals), which is useful usage context. However, it does not explicitly contrast itself with verify_revenue_recovery or check_checkout_change_risk, so the guidance is strong but not fully explicit about all sibling alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that: cost ('Free, always', 'it is cheap'), data privacy ('returns no customer, order, or payment identifier because the store never sends any'), and data freshness reporting. No contradiction 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?

The description is front-loaded with the core purpose, then adds cost, a compact return-item list, usage ordering, and a privacy note. Each sentence contributes distinct information with no filler or redundancy.

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 single-parameter read-only health snapshot with an output schema, the description covers everything an agent needs: what it does, what it returns, when to call it, cost, and privacy behavior. The optional parameter is fully documented in the schema.

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 only parameter, window_seconds, is fully described in the schema with default, minimum, and maximum. The tool description itself does not add parameter-level meaning beyond the word 'window', so the 100% schema coverage establishes the baseline.

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 explicitly states the tool's purpose: to assess whether anything is wrong with the store's checkout and payment path and whether a full diagnosis is worth running. It also lists the concrete signals returned, which distinguishes it from sibling tools like diagnose_revenue_incident by positioning it as a cheap triage snapshot.

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 direct usage guidance: 'Call this FIRST' and explains that diagnosis_recommended tells whether the expensive call would have anything to work with. This explicitly tells the agent when to use this tool relative to the heavier diagnosis alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: it compares before/after windows, defines the four return states, explains that 'unknown' means too little data, and explicitly warns that quietness isn't recovery. This goes well beyond the structured 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 compact and dense: question, comparison method, return states, caveat, and beta status all fit in three sentences. The key purpose is front-loaded, and every sentence adds information without redundancy or fluff.

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?

Given the tool has only two simple parameters, full annotation coverage, and an output schema, the description covers everything an agent needs: what it measures, when to use it, what results to expect, and the key caveat. No important contextual gap remains.

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 100%, so the baseline is 3. The description adds meaning to 'change_applied_at' by explaining it marks the boundary between the 'before' and 'since' windows. It doesn't add prose for 'window_seconds', but the schema already gives bounds, default, and semantic description, so the marginal value is small.

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 uses a specific verb and resource: it answers whether a store's revenue signals actually recovered after a change, and lists the exact signals compared (paid vs pending vs failed order mix, webhook failures, gateway availability). It clearly distinguishes itself from sibling tools like diagnose_revenue_incident or get_checkout_health_snapshot by focusing on post-change verification.

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 explicitly states when to use this tool: 'after a change was made' and 'did this store's revenue signals actually recover?'. It also warns against a common misuse — interpreting quiet time as recovery — and frames the beta/free context. This effectively tells an agent when to choose it over alternatives.

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