agentic-commerce-readiness

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

The description discloses key behavioral aspects: payment is completed externally by the buyer, the tool never charges or handles credentials, and for the module, the licence key is minted on payment and delivered via success page and email. This adds depth beyond the annotations, though it could have mentioned idempotence more explicitly given the idempotenceHint annotation.

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 concise and well-structured, covering the core purpose, the two offers, and the payment flow in a short paragraph. It front-loads the essential action and URL return, but the licensing details (Pro edition, volume discount) could be trimmed to reduce noise for a general agent.

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?

The description provides sufficient context for a payment-related tool: it explains the external payment flow, licensing specifics, and the two offers. Without an output schema, it tells the agent that the URL is returned, which is the key return value. It could benefit from stating expected return format, but the essential details are present.

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 descriptions for offer_id and quantity are already quite clear (offer_id lists enum values with default, quantity explains licensing per installation). The description adds meaning by explaining what the offers are and how licensing works, particularly the edition (Pro) and volume discount, which helps an agent choose the right parameter values.

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 clearly states the tool's purpose: to create a Stripe Checkout Session and return its URL. It explicitly distinguishes the two offer types (readiness-sprint and module-pro) and clarifies that the tool does not charge a card or take payment credentials, removing ambiguity about its role.

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 explains when this tool is appropriate: for purchasing specific offers (readiness-sprint or module-pro). It contrasts with the sibling tool create_customer_portal_session, which is likely for managing existing subscriptions. However, it does not explicitly mention the sibling or state when not to use this tool.

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?

With no annotations, the description carries the burden of explaining behavior. It does disclose what the returned record contains, such as price, turnaround, deliverables, pricing policy and limits. However, it does not state that the operation is read-only, how errors are handled, or whether any authorization or context is required.

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 a single, focused sentence that front-loads the core purpose and then lists the record contents concisely. Every word adds value, with no filler or repetition of the tool name.

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 simple single-parameter get-by-id tool with no output schema, the description provides enough information about the returned content to be useful. It could be more complete by noting how this differs from the catalog/list siblings, but the core invocation context is sufficiently covered.

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 already documents the single parameter 'id' with a clear example, so schema coverage is high. The description adds only slight context by referring to an 'engagement tier,' but it does not meaningfully expand on the parameter semantics beyond what the schema provides.

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 clearly identifies the tool as returning a full record for one engagement tier, with a specific list of contained fields. It implies a single-record retrieval rather than a list operation, though it does not explicitly differentiate itself from sibling tools such as list_offers or search_catalog.

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 phrase 'for one engagement tier' implies this is for retrieving details of a single offer, which is useful context. However, there is no explicit guidance on when to use this tool instead of list_offers, search_catalog, or lookup_catalog, and no mention of exclusions or prerequisites.

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?

No annotations are provided, so the description carries the full transparency burden. It conveys a read-only, unfiltered enumeration and lists response fields, but it does not mention pagination, ordering, result size, or error behavior.

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 single, front-loaded sentence states the action, scope, and output fields with no filler. Every word earns its place.

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 zero-parameter tool with no output schema, the description tells an agent what resource is returned and which fields to expect. The only gaps are details like the exact shape of 'what it includes' and possible pagination, but these are modest given the tool's simplicity.

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?

There are zero parameters, so no parameter explanation is needed; the schema coverage is complete at 100%. The description's field list adds context beyond the empty schema, supporting the baseline 4.

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 ('List') and names the exact resource ('every Expanding Web engagement tier') plus the returned fields (id, price, currency, what it includes). It is clearly distinguishable from siblings like get_offer, which implies a single-item lookup.

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 word 'every' implies this is the tool for enumerating all engagement tiers, but the description does not explicitly say when to choose this over get_offer, lookup_catalog, or search_catalog, nor does it provide exclusion criteria.

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?

There are no annotations, so the description carries the full behavioral burden. It does convey a read-only mapping behavior and the output category ('product objects'), but it doesn't disclose behavior for unknown or invalid engagement ids, batch semantics, or result shape.

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?

One tightly written sentence front-loads the catalog version and purpose, includes an example, and contains no filler.

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 lookup with no output schema, this is minimally adequate: it names input and output categories. However, it doesn't explain what a 'UCP product object' contains, how missing ids are handled, or which sibling tools should be used instead, so it is not fully complete.

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 already describes ids as 'Engagement ids' (100% coverage), so the schema does most of the work. The description reinforces that these are engagement ids and gives a concrete example ('readiness-sprint'), but adds no deeper semantics such as accepted id formats.

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 names a specific verb ('lookup'), a concrete resource ('UCP catalog'), and the transformation ('resolve engagement ids ... to UCP product objects'), with an example id. It clearly identifies what the tool does, though it doesn't explicitly contrast it with search_catalog or get_offer.

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 implies the tool is for resolving known engagement IDs rather than searching or listing offers, but it never states when not to use it. With siblings like search_catalog and get_offer, an explicit routing condition would materially help.

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?

With no annotations, the description carries the burden of behavioral disclosure, and it does: 'Read by a human' signals the report is not automatically acted on, and 'the only way we learn that an agent failed here' establishes the tool's feedback-only nature. This goes beyond the schema's field descriptions.

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 compact sentences front-load the action and scope, then add the human-read behavior and the fallback rationale. Every sentence earns its place and there is no filler.

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 simple reporting tool with full schema coverage, the description covers the essential context an agent needs: what to report, why it exists, and who reads it. It doesn't describe post-call behavior in detail, but that is a minor gap for a fire-and-forget report action.

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 already covers 100% of parameters, so the baseline is 3. The description adds value by giving concrete scenarios ('a page you could not read, data you could not find, a request that was refused') that map to kind/summary selection, supplementing the enum and descriptions.

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 names a specific action ('Report something') and a precise resource ('on this site or endpoint that stopped you from completing a task'), with concrete examples and the human-read outcome. This clearly differentiates it from the commerce/search sibling 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?

It gives an explicit triggering condition—being blocked from completing a task—and a direct instruction to use it instead of giving up silently. It doesn't spell out exclusions or alternative fallback tools, but the context is clear enough for an agent to route here.

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?

No annotations are present, so the description carries the full transparency burden. It explicitly discloses that the scan is read-only, bounded to three pages, limited to 15 seconds, honors robots.txt, and is rate-limited to five scans per hour.

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 purpose is front-loaded and the constraints are compactly listed, making the definition easy to scan and understand.

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 one-parameter, read-only scan tool, the description is complete enough: it states what the tool does, what it returns, its operational limits, and its rate cap. The low complexity means no further behavioral detail is necessary.

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 already covers the single parameter at 100% with a clear description and example. The tool description adds no new parameter-level meaning, so the baseline score 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 states a specific verb and resource: run an eight-check agent-readiness scan against a live storefront and return verdicts. This clearly separates it from checkout, offer, and catalog sibling 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?

The description gives strong contextual constraints (live storefront, read-only, three pages, 15-second budget, five scans per hour) but does not explicitly state when to choose this tool over a sibling or when not to use it. Usage is implied rather than directly routed.

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?

With no annotations and no output schema, the description must carry the full behavioral burden, but it only discloses the return container. It does not mention whether the operation is read-only, whether results are paginated or ordered, or how errors or empty queries are handled.

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 single, front-loaded sentence with no filler. It packs in the catalog version, scope, return format, and no-query behavior efficiently.

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 tool with one optional parameter, the description covers the main call pattern and return type. However, without an output schema or annotations, it would benefit from clarifying the structuredContent shape, pagination behavior, and the relationship to lookup_catalog.

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%, and the schema already documents the query parameter with examples and the omit-for-everything behavior. The description restates the omit behavior but adds no new parameter-level meaning beyond the schema.

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 clearly identifies the operation ('search'), the resource ('catalog'), and the scope ('over the engagement tiers'), and it states the return type (UCP product objects in structuredContent). However, it does not explicitly distinguish this tool from the sibling lookup_catalog, so it stops short of a 5.

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 provides one direct usage rule: 'Call with no query for the whole catalog.' This gives clear invocation guidance, but it never explains when to prefer this tool over lookup_catalog or the other siblings, nor does it state any exclusions or prerequisites.

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