Woo Revenue Incident Graph

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.

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

Annotations already declare readonly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: it returns `abstained` and charges nothing rather than guessing during an outage, it reports which signaal families could not be collected, and it states it is free while in beta. Nothing in the description contradicts the annotations — it is a pure read/diagnostic operation.

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?

A dense, front-loaded paragraph that opens with the core purpose before moving to signals, output format, and abstention conditions. Every sentence carries operational value, though it is on the longer side and the unknown-cause caveat appears twice (in the output format and in the abstention rationale), so a small trim was possible.

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 diagnostic tool with an output schema and rich annotations, the description covers the prerequisite (snapshot first), the output contract (ranked hypotheses with observations, counterevidence, next steps, verification plan), the abstention conditions, and cost behavior. Nothing an agent needs to invoke it correctly or interpret its result 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 both params are fully documented in the schema (symptom enum with 'Use unknown rather than guessing,' window_seconds min/max/default). The description reinforces the honesty principle behind `symptom` but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 specific diagnostic verb plus resource — 'Answers: what most likely broke this store's checkout or payment path' — and specifies the output shape (up to three ranked hypotheses, counterevidence, verification plan). This clearly distinguishes it from siblings: get_checkout_health_snapshot fetches data, verify_revenue_recovery and check_checkout_change_risk cover verification and risk, while this tool synthesizes a causal diagnosis.

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 explicit workflow sequencing — 'Call get_checkout_health_snapshot first' — and states when the tool should not be used: it abstains when the snapshot is stale, coverage is thin, or signals do not support a cause. It does not, however, explicitly exclude sibling alternatives (e.g., when to prefer verify_revenue_recovery), so the when-not-to-use guidance is partially implied rather than named.

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 read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond those: it is free, it reports data freshness, and it guarantees no customer/order/payment identifiers are returned because the store never sends any. This privacy and cost context is not conveyed by the annotations or schema.

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?

Four sentences, each earning its place: the core question, the return payload list, the ordering guidance, and the data-privacy guarantee. The most decision-relevant fact is front-loaded, and there is no redundant restating of the tool name or title.

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 exists and annotations are rich, the description still adds the missing decision context: it tells when to call this tool, what the expensive alternative depends on, and what identifiers are intentionally absent. An agent can correctly decide to invoke it and interpret its role in the larger workflow.

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 single optional parameter `window_seconds` is fully documented in the schema with default, min, and max (100% schema description coverage). The description mentions 'the window' but adds no new parametric meaning; the baseline of 3 applies because the schema already carries the burden.

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 answers a precise question ('is anything wrong...?') and lists exactly what the tool returns, including the decision flag `diagnosis_recommended`. It stands apart from sibling tools by being the cheap first-call health snapshot rather than a risk check, full diagnosis, or 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?

The description is explicit that this should be called FIRST because it's cheap and tells whether the expensive diagnosis would have anything to work with. This gives a strong ordering rule and a clear when-not-to-call-the-diagnosis condition. It does not, however, name the sibling tools or spell out when to use check_checkout_change_risk or verify_revenue_recovery, so I can't give a full 5.

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 cover readOnly, idempotent, and non-destructive behavior. The description adds substantive beyond-annotation context: the four result statuses, the condition for 'unknown', the data sources compared, and the beta/free status. 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 front-loads the core purpose and is generally tight. Minor redundancy exists: 'which is free' and 'Free while in beta' both convey the same cost information, slightly reducing the score from a perfect 5.

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 read-only verification tool with a comprehensive output schema, the description covers the purpose, input semantics, result interpretation, and edge cases such as insufficient data. Nothing critical is missing for an agent to select and invoke it correctly.

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 provides 100% coverage for both parameters, including types, constraints, and default values. The description only reinforces the conceptual role of these parameters (change time and comparison window) without adding details beyond the schema, so the baseline of 3 is appropriate.

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 the core question the tool resolves ('after a change was made, did this store's revenue signals actually recover?') and specifies the comparison windows and result categories. This makes it easy to distinguish from siblings like diagnose_revenue_incident or get_checkout_health_snapshot, which are about diagnosis/health rather than 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 intended use case is clear: call this after a change has been applied to verify the fix held. It also provides interpretive guidance ('unknown when too little new data has arrived... A quiet ten minutes is not a recovery'). However, it does not explicitly name alternatives or state when NOT to use it, so it stops short of a 5.

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