Agent Commerce Readiness

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond those: it is free during LIVE_FREE observation, requires no API key, and never signs or sends a payment. This covers auth, cost, and payment safety, though it does not discuss rate limits or other operational constraints.

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 purpose is front-loaded in the first sentence, followed by a justification sentence and a safety/access sentence. The second sentence is a long list but each item earns its place by clarifying what the tool replaces, and there is little wasted text.

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?

An output schema exists, so return values need not be explained. The description covers purpose, usage context, cost, auth, and payment safety for a read-only audit tool with no siblings, leaving no critical gap for an agent to call 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?

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description mentions x402 resource observation but does not add syntax, format, or usage guidance beyond what the schema provides, making the baseline of 3 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?

States a specific verb ('Audit') and resource ('public HTTP(S) website') with the exact domain ('AI-agent commerce readiness'). It distinguishes itself from manual rebuilding by naming the checks it replaces, so an agent knows precisely what the tool does.

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?

Explicitly says to use this instead of rebuilding UCP discovery, structured-commerce checks, ACP evidence handling, x402 observation, remediation, and verification evidence yourself. It provides clear context for when this tool is appropriate, though it does not state explicit exclusions or prerequisites beyond the read-only/no-key framing.

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 the full safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's job is to add context beyond that. It adds that the result is a 'failing path plus highest-leverage next steps' rather than a score, which is mildly useful, but says nothing about probing behavior, timeouts, or limits of an open-world network call.

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, zero filler, with the core action and the value proposition (failing path + next steps) front-loaded. Nothing is redundant with the schema.

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?

With a 100%-documented schema, full annotations, and an output schema covering return values, the description supplies enough to invoke the tool correctly for a three-parameter diagnostic. What is missing is explicit sibling disambiguation from audit_agent_commerce_readiness and prepare_agent_commerce_upgrade.

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%, including the conditional note that paymentResourceUrl is needed for a meaningful machine_payment_readiness diagnosis, so the schema carries all parameter meaning. The description only repeats the enum choices already documented in the schema, adding no syntax or format detail.

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 verb (diagnose) and resource (agent-commerce path/blocked goal) and enumerates the four goal types the tool operates on. The phrase 'instead of a generic score' implicitly separates it from audit_agent_commerce_readiness, but no sibling is named outright.

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?

'Diagnose why a concrete agent-commerce goal is blocked' gives a clear triggering condition, and 'instead of a generic score' hints at when the sibling audit tool is the wrong choice. However, it never explicitly names an alternative tool or states exclusions, so the routing signal remains indirect.

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, openWorld and non-destructive, so the safety profile is covered. The description adds useful behavior context (deterministic acceptance assertions, verification handoff) but says nothing about authentication needs, rate limits, or what fresh audit evidence means in practice.

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, zero filler, with the outcome (the upgrade plan) front-loaded and the usage condition trailing correctly. The deliverable list is dense but every item distinguishes this tool from a plain scorer.

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?

With rich annotations and an output schema present, the description only needs to cover intent and routing, which it largely does. Minor gaps remain around prerequisites (the site must be public/reachable) and why the optional x402 parameter matters, but nothing an agent needs to invoke it correctly 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 coverage is 100% and both parameters are documented in the schema, so the description is not required to compensate here. It mentions neither 'url' nor 'paymentResourceUrl' or when the optional paid-resource parameter is relevant, leaving the schema to do all the work.

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 transformation (public storefront URL → implementation-ready upgrade plan) and enumerates the deliverables: audit evidence, ordered remediation tasks, acceptance assertions, artifact targets, verification handoff. It also implicitly distinguishes itself from audit_agent_commerce_readiness by framing the output as fixing rather than scoring.

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 second sentence gives a clear selection condition ('when a coding agent needs to fix the site rather than merely score it'), which routes the agent toward this tool and away from the pure-audit sibling. It stops short of naming siblings or stating exclusions like prerequisites or cases where diagnose/probe should run first.

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 open-world, so the safety profile is covered. The description adds meaningful context beyond them: no signing, no payment is sent, and the probe is confined to a single explicit resource.

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 tight sentences with no filler; the safety constraint and action come first, then the usage condition. Every clause carries information.

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?

An output schema exists, so return values need not be described. The definition covers safety, scope, and when-to-use adequately, though it says nothing about error behavior when the resource is not payment-gated.

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% and the single parameter already documents 'Exact public HTTP(S) paid resource to probe.' The description reinforces the singular, explicit nature of the target 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 verb (inspect/probe), an exact resource type (one explicit public machine resource), and the target evidence (x402 v2 HTTP 402). The safety qualifier 'without signing or sending payment' and the 'one explicit resource' scope clearly separate it from the sibling audit/diagnose/verify tools.

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 a clear trigger ('Use when an agent needs to diagnose payment-gating interoperability') and contrasts it against an alternative inference path ('rather than infer x402 from a storefront'). No explicit when-not conditions or named sibling routing, so it falls 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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that this is a comparative re-audit producing resolved/still-open/new blockers, which is useful context, but it does not disclose probe rate limits, what happens if the previous receipt is malformed, or any auth requirements.

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 tight sentences, front-loaded with the action and the return shape, closing with the usage condition. Every sentence carries information and none is redundant.

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?

With an output schema present the description needn't detail return values, yet it usefully names the three blocker categories. Annotations cover the safety profile and the schema documents all params, so the definition is largely self-sufficient; only the undefined 'ACR' term and absent sibling routing leave minor 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 100%, so all three parameters including the nested previous object are documented in the schema. The description adds no format or usage detail beyond that, 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?

States a specific verb (re-audit) and resource (a storefront after changes) plus the comparative action against a prior ACR receipt. It implicitly separates itself from audit_agent_commerce_readiness (a fresh audit) but never names the sibling, so differentiation is inferred rather than explicit.

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?

"Use in audit-fix-rerun coding loops" gives clear contextual usage and the comparison framing implies the prerequisite of a prior receipt. However it names no alternative tool and states no when-not condition, so it falls short of full routing guidance.

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