mcp-gateway

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It says 'Apply' (mutation), but does not disclose what happens on success, whether an existing discount is overwritten, whether the discount is reversible, or whether the code is validated before mutating the cart. The TEST*/WELCOME* hint suggests test codes but doesn't explain side effects.

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 compact, front-loaded sentence with a useful parenthetical. There is zero filler and the core action is clear. The code format hint is included without adding bloat.

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?

This is a write operation with no annotations and no output schema. The description is slim, and an agent cannot determine what response to expect, whether a bad code raises an error or just returns false, or whether applying a discount to a cart is reversible. For a mutation tool, this is a meaningful completeness gap.

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 documents all four parameters. The description adds the promotional-code family hint, but it doesn't explain the relationship between source, discount_code and identity_token beyond what the schema already says. Baseline 3 is appropriate because the schema does most of 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?

The description states a clear action ('Apply a discount code to the cart') plus a concrete example of code families. The purpose is specific enough to understand what the tool does, though it doesn't explicitly contrast with sibling tools like preview_checkout or ucp_update_checkout. The example codes (TEST*/WELCOME*) add useful detail.

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 implies when to use it: when a discount code should be applied to a cart. It also hints at an alternative path via source='ucp_identity', but doesn't name sibling tools or exclusions. The schema further clarifies the two modes (promo code vs loyalty identity), giving clear usage context without explicit when-not-to-use guidance.

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 are absent, so the description carries the full behavioral burden. It adds context beyond the tool name by stating the retry-after-transient-failure scenario, which implies idempotent or resumable behavior. However, it does not disclose side effects on the cart, failure outcomes, or whether the identity can be replaced once attached.

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 with no filler: the action is front-loaded first, followed by the precise usage conditions. Every phrase earns its place, and no information from the schema is redundantly repeated.

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 only 2 fully-documented required parameters and no nested objects or enums, the complexity is low and the description covers what the tool does and when to invoke it. The only gap is that no return value or follow-up action is hinted at, but this is a minor omission for a straightforward attach operation.

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 parameters are already fully documented in the schema (cart_id provenance and the JWS signing algorithm plus enforcement-rule rationale for agent_token). The description adds no additional parameter meaning beyond the schema, so 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?

The description uses a specific verb-resource pair ('Attach agent identity attributes to an existing Shopify cart') and clearly targets carts, which none of the 48 siblings do. It is immediately distinguishable from create_cart, complete_checkout, and the verification tools without opening the schema.

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 the tool: 'when create_cart was called without agent_token, or to retry after a transient failure.' It gives concrete triggering conditions, though it doesn't name an explicit alternative tool or when-not-to-use scenario.

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 for behavioral context. It communicates that this is a read-style browse operation over the full catalog and frames it as a feed with pagination. However, it does not disclose what the response contains, whether the feed spans all product data, or any behavioral constraints beyond the 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?

The description is short, front-loaded, and identifies the key capabilities: browsing, category filtering, and pagination. The parenthetical 'ACP feed capability' is somewhat cryptic and not strictly necessary, which prevents a perfect score.

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 listing tool with four optional parameters, this is minimally adequate. However, there is no output schema and no description of return values, and the sibling list contains several closely related catalog/search tools, so more contextual guidance about how this tool differs would improve completeness.

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 parameters are already fully documented. The description adds only the context that the feed operates over the 'full product catalog,' but it does not clarify or extend the meaning of page, limit, category, or in_stock_only beyond what the schema already 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 specifies a clear action and resource: 'Browse the full product catalog,' with optional category filtering and pagination. This distinguishes it from category-only tools at a basic level, though it does not explicitly differentiate it from search_products or search_products_enriched.

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 implies when to use it: when an agent needs to browse the full product catalog, optionally filtered by category or stock status. However, it provides no explicit guidance about when not to use it or which sibling tools like search_products, browse_categories, or ucp_get_catalog should be preferred instead.

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 present, the description carries the full burden. The word 'List' strongly implies a read operation and 'with product counts' discloses part of the output, but no explicit safety or read-only statement is made. The description also doesn't mention authentication, scoping specifics, or pagination behavior beyond 'for a merchant'.

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 concise sentence, front-loaded with the primary verb and resource. It contains no filler, redundant information, or restatement 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?

Given the low complexity (no parameters, no output schema, no annotations), the description is nearly complete in conveying what the tool does with merchant-specific scope and product counts. However, it lacks explicit exclusions or a hint on relationship with category-related siblings, which would make it fully unambiguous.

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 tool has zero parameters and the schema is empty, so the description doesn't need to explain any parameter behavior. This meets the baseline of 4 for zero-parameter tools and adds slight context that operation targets 'available product categories' of the merchant.

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 ('List') and resource ('product categories') plus a distinctive output feature ('with product counts'). This clearly sets it apart from siblings that cover catalog browsing or search because it focuses on category listing, not feeds or product details.

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 no guidance on when to use this tool rather than a sibling like browse_catalog_feed or ucp_get_catalog. There is no 'instead of' language, no context of user goals, and no mention of when not to use it.

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 provided, the description carries the full burden for disclosure, but 'Cancel an active payment mandate' only states the action. It does not explain what happens to linked transactions, whether cancellation is reversible, what permissions are required, or what side effects might occur.

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 two-sentence description with zero filler. Every word contributes to the core action, and the most important part, 'cancel', is placed immediately.

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 tool is simple and the schema covers its parameters well, so the description is minimally viable. However, with no output schema and no annotations, it lacks any indication of return behavior, error conditions, or effects beyond cancellation.

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%, with store_id clearly described as 'Merchant store ID' and instruction_id as 'VIC instruction ID to cancel'. The description adds no parameter meaning beyond the schema, so the baseline 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 tool description uses a specific verb ('Cancel') with a clear resource ('active payment mandate'), which precisely distinguishes it from sibling tools like create_payment_mandate and update_payment_mandate. It is not a tautology and leaves little ambiguity about the operation.

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 no explicit guidance on when to use this tool over related tools, no prerequisites or exclusion conditions beyond the word 'active', and no mention of alternatives like update_payment_mandate. An agent would have to infer usage context from the tool name alone.

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 disclosure burden. 'Check' implies read-only behavior and the resource names suggest a safe query, but the description does not explicitly confirm that no state changes or charges occur, nor what happens if consent is missing. It also does not mention authentication or rate-limit implications.

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 one concise, information-dense sentence with no filler. It front-loads the verb and resource. It could define MCAP or hint at response shape, but as conciseness it 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 simple two-required-parameter look-up, the description is minimally adequate: it names the subject and input schema is fully documented. However, there is no output schema and the description never states the specific returned shape, such as consent status enum or spending-limit value, so an agent cannot fully anticipate the result.

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 the two parameters, including the authenticated-customer constraint on customerId and the agent_key_id purpose. The description adds no parameter detail beyond the resource context, so baseline scoring 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?

The description uses a clear verb ('check') and names a specific resource: MCAP agent payment consent status and spending limits. This makes it distinguishable from payment-processing and mandate-management siblings, though the acronym 'MCAP' is unexplained and the description does not explicitly differentiate it from similar lookups.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description does not say to call this before process_agent_payment or after creating a mandate, and it does not mention alternative tools. A user must infer from the verb and domain context.

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 provided, the description bears the burden of behavioral disclosure. It usefully adds that attributes are normalized and a bestValue recommendation is included, but it does not state whether the operation has side effects, whether it is read-only, or how invalid product IDs 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?

The description is one focused sentence that front-loads the tool's purpose and includes the most important behavioral details. Every word adds value, 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 tool with a single parameter and 100% schema description coverage, the description provides enough for reasonable invocation. It would be even more complete if it briefly noted what kind of output the agent should expect beyond 'bestValue recommendation,' but overall it is adequate.

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 parameter is already well-documented. The description largely repeats the 2-5 product constraint and does not add new semantic detail about ID formats or how products must be provided.

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 ('comparison'), a clear resource (products), and a notable differentiator: normalized attributes and a bestValue recommendation. This clearly distinguishes it from sibling tools like get_product_details and search_products.

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 'side-by-side comparison of 2-5 products' implies when to use the tool, but it does not explicitly state when not to use it or recommend alternatives such as get_product_details for deep individual product information. The usage context is inferred rather than stated.

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 full behavioral burden. It does reveal two important traits: human confirmation is required and the operation is idempotent. However, it omits significant side effects like potential payment capture, failure outcomes, or human-confirmation workflow behavior, leaving much to inference for a payment-facing 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?

Three short sentences with no filler: the operation, the merchant adapter scope, a human-confirmation constraint, and idempotency guarantee are all front-loaded. Every word earns its place and the structure is easily parsed by an 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?

This is a high-complexity payment-completing tool with no output schema, no annotations, and many behavioral nuances (default payment method, ACP caveats, real-world side effects). The description is too thin to fully prepare an agent for safe invocation. It fails to clarify what the agent should expect as a result or what prompts the human confirmation.

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 itself already provides rich semantics for every parameter, including idempotency_key replay behavior and payment_method differences. The tool description adds no parameter-level information, so it neither helps nor hurts beyond the schema 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 uses the specific verb 'Complete' with the resource 'checkout' and clarifies it happens 'via merchant adapter'. It conveys the core operation clearly, though it does not explicitly differentiate itself from siblings like ucp_complete_checkout or complete_visa_payment, relying partly on the name.

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?

No guidance is provided about when to choose this tool over alternatives such as ucp_complete_checkout, preview_checkout, or process_agent_payment. The requirement for human confirmation is mentioned but not elaborated into actionable direction, and there are no exclusions or context triggers.

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 must disclose behavioral context on its own. It only says it completes a payment flow; it does not mention whether this finalizes a charge, whether it is idempotent, whether the mandate is consumed, or what side effects result. This is minimal transparency for a payment-related mutation.

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 short, but it is under-informative rather than economically helpful. It essentially restates the tool name with an added prepositional phrase, so the conciseness comes from missing content rather than distilled clarity.

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 no annotations, no output schema, and a payment-related action that is a finalization step, the description is too incomplete for an agent to understand the operation's effect or why it exists. It also lacks any mention of preconditions led by create_payment_mandate.

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 covers 100% of parameters, including the source of instruction_id from create_payment_mandate. The description itself adds no parameter semantics, but the schema documentation is sufficient to invoke the tool correctly.

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 gives a concrete verb and object: it completes a Visa Agent Toolkit payment flow. However, 'payment flow' is generic, and with many siblings in the same domain it is not clearly differentiated from process_agent_payment or complete_checkout.

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 no explicit guidance on when to use this tool versus the many related payment and mandate tools. The schema implies a dependency on create_payment_mandate via the instruction_id description, but the description itself provides no positive condition or exclusions.

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 provided, the description carries the full transparency burden. It reveals meaningful behavior: the create isn't unconditional — stock is validated and fraud detection runs, so cart creation may fail. However, it doesn't describe what happens on failure, whether the cart is persisted, or how the resulting cart can be used.

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 short sentences, front-loaded with the verb and resource. Every word earns its place, and it is highly scannable for an agent choosing whether to open 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?

No output schema is provided and there are no annotations, so the description should specify response expectations or next-step flow. It doesn't mention whether a cart ID is returned, how to attach it to until later steps, or what a denied cart looks like. The rich schema mitigates the gaps, but the description remains minimal for a cart-creation flow within a large sibling family.

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 description coverage is 100%, and the agent_token parameter already includes rich behavior (JWS signed, Shopify enforcement rules, offline verification). The description adds little about the parameters beyond 'validates stock' touching the items array, 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 an explicit action ('Create a shopping cart') and a clear resource, and adds two behavioral differentiators (stock validation, fraud detection) that separate it from generic cart or checkout tools. It doesn't explicitly name sibling tools, but the resource and validation hints make the purpose fairly unambiguous.

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?

No guidance is given on when to invoke this tool versus the many nearby checkout and payment tools, such as ucp_add_items_to_checkout or complete_checkout. An agent cannot tell from the description whether to call this before checkout flow starts or how it fits into the merchant workflow.

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 transparency burden. It only says 'Create', which implies a side-effecting write, but it does not disclose whether the mandate is immediately active, whether it can be updated or canceled, whether funding sources or customer consent are required, or what the API returns. This is a significant gap for a mutation 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 a single sentence with no filler or redundant content. It is front-loaded with the core action 'Create a payment mandate'. It earns a high conciseness score, though not a 5 because it is so terse that it leaves out important context.

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 tool has 9 parameters, a nested shipping_address object, required fields, and no output schema or annotations. The one-sentence description only conveys the general purpose and does not explain the creation flow, dependency on enrollment_id, possible side effects, or return value. The schema handles parameter format, but contextual gaps remain substantial.

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 covers 100% of parameters with meaningful descriptions, including format, currency, frequency, and required fields. The description itself adds no parameter-level meaning, but because the schema already provides strong semantic coverage, 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 states a specific verb and resource: 'Create a payment mandate', and adds a qualifier that it is for 'agent-initiated payments'. This distinguishes it from obvious sibling tools like update_payment_mandate and cancel_payment_mandate, though it could more clearly differentiate it from related payment-processing tools such as process_agent_payment.

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 'agent-initiated payments' hints at the intended context, but the description gives no explicit guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent would not know, for example, whether this should be called before process_agent_payment or what role enrollment_payment_method plays.

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 burden of disclosing behavioral traits. It only says 'enroll' without describing what happens during enrolment, whether it saves card details, whether consent is needed, if it can be reversed, or what the result is. This is a significant gap for a mutation-type 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 a single, front-loaded sentence with no wasted words. It states the action and purpose succinctly, though it is so brief that it leaves out behavioral context.

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 3 parameters, full schema coverage, but no output schema or annotations, the description is minimally sufficient to call the tool with concrete parameters. However, it omits important operational context: what the enrollment returns, if it requires existing payment details, and how it differs from other payment actions, leaving an agent to rely on surrounding tools to infer the full flow.

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 already have meaningful descriptions in the schema. The tool description adds no extra parameter context, but it also does not need to repeat the schema; the connection between 'for future agent payments' and the consumer_id/card_label parameters is reasonable but not specified.

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 clear action ('Enroll') and resource ('a payment method') with an explicit purpose ('for future agent payments'), which makes the basic function understandable. It distinguishes from retrieval operations like get_payment_methods, though it does not explicitly differentiate it from similar payment setup tools like create_payment_mandate.

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?

There is no guidance about when to use this tool versus the many payment-related siblings. The phrase 'future agent payments' implies a setup workflow but no explicit alternatives, exclusions, prerequisites, or steps on how to choose this over create_payment_mandate or process_agent_payment.

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?

Describes an informational onboarding/exploration behavior rather than a mutation or state-changing operation. Clearly frames the tool as returning knowledge about the store launch experience, even though it doesn't literally say 'read-only'. For a no-annotation tool, this is sufficient disclosure of expected 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?

Two efficient sentences, front-loaded with the purpose and content, and ending with the crucial 'call first' directive. Every phrase earns its place; 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?

A single optional parameter with full schema coverage, an enumerated list of return contents, and explicit sequencing instruction make this complete. The agent knows what it will get, what depth controls, and when to invoke it relative to other tools.

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 fully documents the depth parameter with enum values and descriptions, so no additional parameter explanation is necessary. The description could map 'quick' vs 'full' to its listed content, but the schema already covers the distinction.

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 action ('explore store') and a concrete resource: the store's agent-facing capabilities. Lists the exact outputs (capability matrix, recommended journeys, discovery endpoints, score), which distinguishes it from sibling tools like get_store_trust or browse_categories. The instruction to call it first gives it a unique onboarding 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?

Explicitly says to call this FIRST on any new store, which is clear prescriptive usage timing. It does not enumerate alternatives or when-not-to-use scenarios, but the priority and store context are strong enough for an agent to route correctly.

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 behavioral burden. It does signal a read operation ('Retrieve') and discloses the high-level returned fields, which is useful. However, it does not mention default limiting, ordering, how optional filters interact, pagination, 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?

The description is two short sentences with no filler. The first sentence identifies the operation and scope, and the second sentence summarizes the output, making it easy to scan.

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?

There is no output schema, so the return-value summary is helpful, and the parameters are simple. However, the description is thin on behavioral detail like default limit use, sorting, and how order_id interacts with status/limit, so it is adequate but not 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?

Schema description coverage is 100%, so the schema already documents limit, status, and order_id. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 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?

The description clearly states a specific operation and resource: 'Retrieve ACP orders placed via this store,' and it summarizes the returned content. It stops short of a 5 because it does not explicitly differentiate this tool from similar sibling order tools such as onx_get_orders.

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?

There is no guidance on when to use this tool versus alternatives, and no exclusions or conditions are stated. With many sibling order-related tools, the agent must infer the tool's intended niche solely from 'ACP' and 'this store.'

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 burden. The verb 'Get' indicates a read-only retrieval, which is useful, but the description does not disclose output structure, errors, authentication requirements, or any other behavioral context beyond that verb.

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, tight sentence that front-loads the verb and resource, then enumerates the distinct data categories with no filler. Every word contributes to the intent.

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 parameterless read-only tool, the description is reasonably complete: it states what the tool returns. It might benefit from indicating whether current merchant context is assumed and from describing result packaging, but these are minor gaps given the simplicity of the interface.

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 tool has 0 parameters, so the schema already completely describes inputs; no parameter clarification is needed. The description therefore need not add parameter-level meaning.

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?

Names a specific resource ('merchant profile') and lists concrete data elements: trust score, verification level, return policies, and shipping SLA. This is clear and lets an agent pick it out from most siblings, though it does not explicitly distinguish itself from get_store_trust, which may overlap on trust data.

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?

Implied usage is present: use this when you need merchant trust, verification, return, and shipping information. However, the description gives no explicit when-not-to-use guidance and does not mention alternatives such as get_store_trust or get_product_details.

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 present, the description must carry the burden of behavioral disclosure. It essentially restates the tool name without adding behavioral details such as the format of returned content, how errors are handled, or the special 'blog' behavior that is only partially captured in the parameter schema. There is no contradiction, but the description adds minimal non-schema information beyond 'retrieve content.'

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 clear sentence with no fluff. It is concise and front-loaded, though the 'by URL' phrase is slightly misleading given the parameter is actually a slug, preventing a perfect score.

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?

This is a simple single-parameter tool with no output schema and no annotations. The description establishes the primary purpose and the schema fully documents the parameter, but the lack of detail about what 'content' means or what the response looks like leaves some ambiguity for an agent deciding whether this is the right tool.

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 covers the single parameter fully, including the accepted slug values and the special 'blog' case, so the description does not need to add much. The 'by URL' phrase in the description adds no semantic value and is slightly confusing given the parameter description expects a slug. With 100% schema coverage, baseline 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 clear action ('Retrieve content') and a specific resource ('a specific store page'), which tells an agent what the tool does. However, the phrase 'by URL' is slightly inconsistent with the schema's expectation of a page slug, and it does not differentiate from siblings like get_site_map or browse_catalog_feed.

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 no guidance on when to choose this tool over sibling tools such as get_site_map, explore_store, or get_product_details. It only states the basic purpose, leaving the agent to infer the appropriate context without any exclusions or alternative recommendations.

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?

Without annotations, the description carries the disclosure burden. 'List' signals a read-only action, 'with instruments per rail' clarifies the return shape, and 'really accepts' defines scope. It does not cover rate limits or authorization, but for a zero-parameter read-only tool this is a minor gap.

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 with no filler. The first sentence states the action and output; the second adds timing and purpose. Each phrase—'really accepts,' 'instruments per rail,' 'before checkout'—adds meaningful value.

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-input, low-complexity read tool, this description is complete: it states what is returned, the merchant scope, and when to call it. Even without an output schema, the agent knows to expect payment rails and their instruments.

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 no parameters, so the description has nothing to explain at the parameter level. Per the rubric, zero-parameter tools receive a baseline of 4, and the description correctly sets no parameter expectations.

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 resource exactly: 'payment rails the merchant really accepts,' with a concrete output detail ('with instruments per rail'). This is specific enough to distinguish it from payment-execution siblings like process_agent_payment or enroll_payment_method.

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 explicit timing and intent: 'Call before checkout to negotiate a settleable rail.' This is clear context for when to use it, but it does not explicitly name alternatives or state when not to use it, so it stops just 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?

The verb 'Retrieve' strongly implies a read-only operation, which is a meaningful behavioral disclosure given that there are no annotations. However, the description does not cover output structure, error/not-found behavior, or what the merchant trust score represents. For a no-annotation tool, this is adequate but not fully transparent.

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?

This is one efficient, front-loaded sentence with no filler. It states the action, the resource, and the relevant output categories while remaining compact.

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 tool, the definition is largely complete: it states the purpose, enumerates the data returned, and the schema gives strong guidance on how to supply the product_id. It loses a small amount because there is no output schema and no explicit comment about error/not-found behavior, so the agent must infer the exact return shape.

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?

Since schema description coverage is 100%, the baseline is 3 even without parameter info in the tool description. The schema's product_id description is valuable because it defines the format, gives an example, and explicitly says 'Do not invent IDs,' but the tool description itself adds no parameter-level meaning.

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 ('Retrieve') and a concrete resource ('full product information'), and enumerates included categories: price, variants, policies, and merchant trust score. It is clear and useful on its own, though it does not explicitly distinguish itself from sibling tools such as get_merchant_profile, compare_products, or get_store_trust.

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?

There is no explicit guidance about when to use this tool versus alternatives. The schema's product_id description tells the agent to source ID from search_products or nlweb_ask and not to invent IDs, which is helpful, but the description itself does not state when to choose this over other product-, merchant-, or trust-related 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 provided, the description carries the full behavioral disclosure burden. It does reveal a key behavior: the tool uses elicitation to collect missing addresses, which warns the agent that omitting shipping_address may trigger an interactive prompt. It leaves other behavior implicit, such as whether the operation is read-only and whether a cart session is required—though the schema hints at the latter.

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 two concise sentences with no wasted words. It front-loads the core purpose first and adds a meaningful trade-off/prerequisite note second—exactly what an agent needs without repeating schema contents.

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 cart-retrieval tool, this description is nearly complete: the agent knows the primary action, the address can be elicited if omitted, and the schema provides all parameter details. The main gap is that no output schema exists and the description does not explicitly list the returned objects, so the agent may not know whether 'shipping rates' includes carrier names or just prices.

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 has 100% description coverage: cart_id is marked as the ID returned by create_cart, and the nested shipping_address has exact structure and a clear note about omitting it for elicitation. The top-level description adds no new parameter meaning, so the schema baseline of 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?

The description captures a specific verb-resource pair, "Get shipping rates for a cart," which clearly expresses the primary function and differentiates it from the sibling tool select_shipping_option. The scope is precise enough that an agent can infer this is the rate lookup step before choosing a shipping option.

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 implicitly tells when to use this tool (when rates for a cart are needed) and includes the important interaction note that the tool can elicit the address. However, it does not explicitly name alternatives or state when not to use it, so an agent may need to infer the exact decision boundary based on other tool names.

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 burden of behavioral disclosure. However, it only restates the tool's purpose and does not describe behavior such as whether the returned site map is hierarchical, whether the category parameter affects the response, or what the output looks like.

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 concise, front-loaded sentence that communicates the core purpose with no wasted words or redundant 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?

The tool is simple and the schema covers its only parameter, but with no output schema or behavioral notes, the description does not fully prepare the agent for what the site map call returns or how it should be used. Moderate gaps remain around return format and default behavior.

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%, so the optional category parameter is already fully documented. The description adds no additional meaning about how the parameter interacts with the returned site map, but the schema alone is sufficient for basic parameter understanding.

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 verb ('get') and resource ('the store's site map'), and adds a purpose ('for navigation discovery'). It is understandable on its own and distinct enough from sibling tools like browse_categories, though it does not explicitly position itself against those alternatives.

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 navigation discovery' gives some context for when to use the tool, but the description does not state when not to use it or mention alternatives. Given siblings like explore_store and browse_categories exist, more explicit routing guidance would be beneficial.

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 provided, the description carries the disclosure burden. It openly describes what the tool returns (score, per-signal data quality, confidence, detached JWS) and signals that the numeric score is not authoritative on its own, requiring offline verification. This gives an AI agent a meaningful, actionable model of expected 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?

Both sentences earn their place: the first delivers all essential functional detail, and the second reinforces a critical operational caution. There is no redundant filler, and the most important information is placed first.

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 tool has no output schema and no annotations, so the description must carry the interpretive load. It covers the score, format, version, range, and verification mechanism. It does not describe edge cases like error conditions or stale data, but for a straightforward getter with no parameters, the description is adequate.

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 tool has zero parameters, so there is no parameter-level ambiguity. The description correctly focuses on outputs and behavior rather than input semantics. The schema confirms no inputs, and the description adds useful interpretation about what the result contains.

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 verb and resource: 'Get the store's signed trust score'. It adds specific detail about the version (v4.1), value range (0-100), and composed content (per-signal data quality, confidence, detached JWS), which makes it distinctly identifiable from sibling tools like get_merchant_profile or get_tool_details.

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 conveys a clear use context: when you need the store's trust score and supporting verification material. The 'Don't trust the number — verify it' line adds practical guidance, though it does not explicitly name alternative tools or conditions for 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?

No annotations are provided, so the description carries the behavioral burden. The word 'Retrieve' implies a read-only operation, but the description does not explicitly state that there are no side effects, permissions, or rate limits. It is minimally transparent for a schema-fetching 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?

Two short sentences, front-loaded with the core action and scope. Every sentence earns its place, and the usage note is placed at the end without bloating the description.

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 one-parameter meta-tool, the description covers the core purpose and the workflow context. It does not describe the exact output shape, but no output schema exists and the promise of 'full JSON schema and details' is reasonably complete for this tool.

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?

Input schema coverage is 100% because the single 'name' parameter is described as 'Exact tool name to fetch full schema for'. The description adds little beyond the schema, so baseline 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 ('Retrieve') and resource ('full JSON schema and details for a specific tool by name'), and it names search_tools as the preceding step, which distinguishes it from sibling tools. An agent can tell this tool from search_tools without opening schemas.

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 after search_tools identifies relevant candidates' provides clear sequencing and context for when to call this tool. It does not explicitly list exclusion criteria or alternative tools, but the guidance is sufficient for correct orchestration.

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 behavioral burden. It usefully reveals the output format (Schema.org Products) and the routing layer (NLWeb), which helps set expectations, but it does not explicitly state whether the call is read-only, whether auth is needed, or whether any side effects are possible.

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 front-loaded: the core concept comes first, followed by a short statement of the return type. Every word adds value, and there is no fluff or repetition.

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 search tool with a rich input schema, the description is nearly sufficient: it clearly states the result type and avoids overexplaining what the schema already covers. It does not fully resolve how to choose this tool over the many similar search-related siblings, which is the main completeness gap.

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 description does not need to explain parameters. Each parameter already has meaningful descriptions, including the enum for mode, limits, and prev for follow-up context. The description adds no new parameter detail, but none is needed.

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 concrete action: natural language product search through the NLWeb Discovery Layer, returning Schema.org Products. It is clearly a search-style tool, though it does not explicitly name or differentiate itself from nearby siblings like search_products or search_products_enriched.

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 'natural language product search' implies when this tool is useful, but the description gives no explicit guidance on when to prefer it over siblings such as search_products or search_products_enriched. It does not state exclusions or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals two major side effects: it requires human confirmation and can trigger a refund if the order was captured. This is notable for a mutating tool and goes beyond a generic 'cancel order' statement.

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 short sentences, each earning its place: what it does, the process constraint, and the financial side effect. No filler, no redundant restating of the button name, and the key restriction is front-loaded.

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 2-parameter mutation tool with no output schema and no annotations, the description covers the essential operational risks: cancellation only applies to unfulfilled orders, human confirmation is required, and refunds are a possible consequence. It does not detail return values or explicit behavior when the order is already fulfilled, but it is sufficient for most agent invocation decisions.

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 parameter names and descriptions document orderId and reason already. The description adds the important semantic constraint that the order must be unfulfilled, but it does not otherwise enrich 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 names a specific verb ('Cancel'), a specific resource ('order'), and a precise scope ('unfulfilled'), which cleanly distinguishes this from sibling tools like onx_get_orders and onx_create_return. The action is immediately understandable and unambiguous.

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 'unfulfilled' implies a clear restriction on when this tool applies, but the description does not explicitly route the agent to alternatives for fulfilled orders, such as onx_create_return. It gives a useful condition but not explicit when-to-use vs. when-not-to-use guidance.

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 full burden of behavioral disclosure. It discloses useful side effects and constraints: the operation requires human confirmation and validates the return policy window. It does not describe what happens after success or whether the action can be reversed, but the disclosed behaviors are substantive.

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 two short sentences with zero filler. Every sentence contributes a distinct fact: the action, the human-in-the-loop requirement, and the policy validation behavior.

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 operation with fully documented schema, the description provides the essential process context: it is only an initiation and requires human confirmation. It lacks only a description of the result or return value, which is not fully specified anywhere.

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 input schema already explains orderId and lineItems/quantity/reason. The description adds no additional parameter-level guidance, 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 uses a specific verb and resource ('Initiate a return request') and adds two distinguishing facets: human confirmation and return policy window validation. This clearly separates it from sibling tools like onx_cancel_order and onx_get_returns.

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 implies when the tool is used ('return request' requires human confirmation and policy validation) and gives an important condition: human confirmation. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools.

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 provided, the description carries the burden. The verb 'Get' indicates a read-only operation, and 'with tracking info' signals what output to expect. However, it does not disclose what happens when an order has no fulfillment records, whether empty results are possible, or any pagination behavior, leaving some ambiguity.

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 effective sentence. It front-loads the action and resource, uses no filler words, and does not repeat what belongs in the schema. Every word contributes to the meaning.

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 tool with 100% schema coverage and no output schema, this is nearly complete: it names the resource and the scope of usage. However, given several unrelated 'onx_get_*' sibling tools, an explicit usage or differentiation sentence would make it 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 schema description coverage is 100% for the orderId parameter, so the description does not need to add much. The phrase 'for an order' simply re-states what the schema already says, providing no extra meaning or constraints beyond the schema's 'Order ID to retrieve fulfillment/tracking details for'.

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 ('Get'), a specific resource ('fulfillment records with tracking info'), and the scope ('for an order'). It is distinguishable from siblings like onx_get_orders and onx_get_returns, but the title is null and no explicit comparison is made, so a small deduction is taken for not naming the differing sibling resources.

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?

There is no statement of when to use this tool versus alternative sibling tools like onx_get_orders or onx_get_returns. It does not provide context such as 'Use this for shipment tracking' or 'For order summary instead use onx_get_orders', leaving the agent to infer the intended use.

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 burden of behavioral disclosure. It only implies a read via 'Get' and adds a vague freshness qualifier ('current'), but it does not disclose what happens when all three optional parameters are omitted, whether results are real-time or cached, or any access requirements. Minimal transparency, and the tool relies entirely on this one sentence.

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 tight sentence with the verb front-loaded and zero wasted words. 'Current' adds freshness, 'per product and location' adds scoping — every token earns its place. Nothing is repetitive or verbose.

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 no annotations and no output schema, the description is the only source of behavioral context, but it fails to explain critical behaviors: whether a call with no filters returns the full inventory snapshot, whether locationId is required for either filter to work, or what fields the counts represent (on-hand vs available). For a query tool with three optional parameters, this one-liner before it is under-specified.

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's 'per product and location' loosely maps to sku/productId/locationId, confirming they act as filters, but it adds no detail about how the parameters combine or what a partial-parameter call produces. The schema already carries the meaning, so the description earns no extra credit here.

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 ('Get') and resource ('current inventory levels') with an explicit scope: 'per product and location.' Among the large sibling list, no other tool targets inventory stock (the onx_* siblings cover orders, returns, fulfillments), so this tool is naturally distinguishable without ambiguity.

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 no guidance about when to choose this tool versus alternatives like get_product_details, onx_get_fulfillments, or search_products_enriched. There are no exclusions, no 'use when...' conditions, and no mention of what to do when another tool is more appropriate. The purpose is stated, but selection guidance is absent.

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 transparency burden. It only says 'Retrieve orders with filters,' which gives a minimal read-only implication, but it does not disclose pagination behavior, date-range semantics, response shape, or what happens when no filters are supplied.

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 one concise, front-loaded sentence with no irrelevant filler. It loses a point because the parenthetical filter list is partly inaccurate and incomplete, not because of 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?

With no annotations and no output schema, the description must supply more operational context, but it only offers a one-line summary. An agent still cannot determine how this tool differs from get_acp_orders, whether responses are paginated consistently, or what order-related data it can rely on being returned.

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 covers 100% of parameters in detail and already explains status, date range, pagination, and orderId, so the description needed to add little. Instead, it advertises a nonexistent 'customer' filter and omits orderId and pagination semantics, making the parameter information it adds misleading rather than useful.

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 a specific verb and resource: 'Retrieve orders' with filters. However, it does not distinguish this tool from the sibling get_acp_orders, and the mention of a 'customer' filter is misleading because no customer parameter exists in the schema.

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 provides no when-to-use or when-not-to-use guidance. It does not explain how to choose between onx_get_orders and related sibling tools such as get_acp_orders, onx_cancel_order, or onx_get_returns.

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 present, the description carries the full burden. It discloses the read-only nature through 'Retrieve' and indicates the data returned, but it does not mention pagination, behavior with no parameters, 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 description is a single, front-loaded sentence with no filler. Every word contributes: the action, the resource, and the important response fields.

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 getter with two optional parameters, this description is nearly sufficient. However, because there is no output schema and no guidance about what happens when neither parameter is provided, an agent lacks full clarity on response shape and filtering modes.

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?

Both parameters are fully described in the input schema (100% coverage), so the schema already provides the parameter semantics. The description adds no extra detail beyond what the schema states.

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 ('Retrieve') on a specific resource ('return requests') and lists the key data facets (status, refund, label URLs). It is clear enough to distinguish from the sibling onx_create_return, though it does not explicitly name 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?

The description implies when to use the tool: whenever return requests need to be fetched. It does not explicitly state when not to use it, nor does it name alternatives like onx_create_return, limiting guidance for an agent that must choose among many siblings.

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 behavioral burden. It does disclose a non-obvious trait: even though the tool is named 'preview', calling it actually mutates or advances the cart status. However, it lacks coverage of side effects, prerequisites, idempotency, or failure 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?

One front-loaded sentence with no filler; it names the action and the resulting state, then stops. A little more context about ordering or side effects could be added, but the structure is appropriately tight.

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 1-param, no-output-schema tool, the essential state change is described. Missing context includes what the call returns and how it fits with siblings like create_cart or complete_checkout, which an agent must infer from the name and other state.

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 param software_id is already well documented by the schema with 100% coverage, including its source ('returned by create_cart'). The description adds no extra param context, 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?

Description uses a specific verb ('Finalize') and identifies a precise resource/effect: it advances the cart to the READY_FOR_PAYMENT state. This clearly distinguishes it from siblings like full_checkout, which finalizes payment beyond the ready-to-pay stage.

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?

Usage is implied by the stated state transition: call this to move a cart into READY_FOR_PAYMENT. There is no explicit mention of alternatives, prerequisites, or when to skip directly to complete appearance, so some inference is still required.

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 burden of behavioral disclosure. It mentions Ed25519 HTTP signatures but does not say whether funds are captured or authorized, whether the operation is reversible, what side effects occur, or how failures are reported.

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 one front-loaded sentence with no wasted words. It efficiently communicates the operation, the resource, and the distinguishing protocol detail.

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?

As a payment operation with no output schema and no annotations, the description is incomplete. It does not explain what a successful call returns, what optional fields do, or how it interacts with the checkout flow, leaving an irreversible high-stakes side effect ambiguous.

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 covers roughly 71% of parameters with usable descriptions, including amount units, store ID format, and token format. The description itself adds no parameter-level meaning, and currency and merchant_category remain underdefined, so parameter understanding relies mostly on 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?

States a specific verb and resource: 'Process a Mastercard Agent Pay (MCAP) payment.' The MCAP brand and Ed25519 signature detail clearly differentiate it from sibling tools like complete_visa_payment or complete_checkout.

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 MCAP reference implies when to use it: for processing an agent-initiated Mastercard Agent Pay payment. However, it does not explicitly state a preferred-use condition or provide when-not-to-use guidance relative to alternatives such as complete_visa_payment.

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. It does reveal that the tool runs autonomously and returns structured pass/fail results with evidence. However, it does not disclose potential side effects: scenarios like checkout or full might actually trigger real operations or payments, and the agent is left unsure whether this is a safe sandbox or a live-action runner. That ambiguity prevents a higher score.

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 elaboration. The first sentence states the action and expected output, the second gives when-to-use guidance. The enum list is compactly inlined. It is extremely concise and front-loaded, with every word contributing.

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 simple enum parameter and no output schema, the description gives the essential behavior and purpose. It could go deeper on what each scenario actually does or whether side effects occur, especially since 'checkout' and 'full' sound like they could mutate state, but overall the description is complete enough for an agent to 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?

Schema description coverage is 100%, so the baseline is 3. The description redundantly lists the scenario enum values but adds limited semantic context: scenario names correspond to capabilities being verified. It doesn't explain what each scenario does or how to choose between them, so there's only minor added value over 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 states a specific verb ('Run') and precise resource ('autonomous test scenario') and enumerates the exact scenario values. It clearly frames this as a verification/test tool, distinguishing it from the many operational sibling tools that actually perform the underlying actions, such as checkout or catalog browsing.

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 explicit context for when to use the tool: 'Use to verify capabilities before relying on them.' It clearly positions this as a pre-verification step. It doesn't spell out explicit exclusions or name alternatives, but the guidance is strong enough for an agent to know when to choose this tool over the direct execution tools.

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 burden of behavioral disclosure. It only says 'search' and gives no details about result format, pagination, access constraints, or whether it covers only publicly available docs. This is minimally informative but not misleading.

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, direct sentence with no filler. The action and resource are front-loaded, so the high-level purpose is immediately clear without clutter.

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 tool is relatively simple, but with no output schema and no annotations, the description should explain what kind of matches are returned and how to use the results. It does not cover those points and also does not differentiate fully from sibling search-related tools.

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 documents all three parameters completely with descriptions, examples, and defaults (100% coverage). The description adds little semantic meaning beyond the schema, so a baseline 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 combines a specific verb ('Search') with a clear resource ('merchant documentation and policy pages'), so an agent immediately knows what the tool does. It does not explicitly name sibling tools that also handle documentation, but the search-focused wording is distinct enough from retrieval-oriented siblings like get_page_content.

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 no indication of when to use this tool over alternatives such as get_site_map, get_page_content, or search_tools. It states only the basic operation, leaving the agent to infer the appropriate use case without any exclusions or conditions.

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 burden of behavioral disclosure. It communicates a read-oriented search operation, but it does not mention pagination behavior, result shape, the fact that cursor is query-scoped, or the important discrepancy that stock/trust filters are not actually available in the 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?

The description is a single concise sentence with no redundant filler. It front-loads the primary action and resource, but the misleading filter list prevents a perfect score because the inaccuracy adds confusion rather than useful structure.

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 schema already documents all parameters, the description does not need to repeat them. Still, the description omits any comparison to search_products_enriched, overclaims unsupported filters, and does not mention pagination or return behavior, leaving an agent with a slightly distorted model of the tool.

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%, which normally raises the baseline to 3. However, the description adds misleading parameter-related claims: it lists stock and trust score as filters even though the schema has only category, min_price, and max_price for filtering. This reduces confidence in the description as a semantic complement to 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 states a specific verb ('search') and resource ('products') and adds scope ('across verified merchants'), which distinguishes it from some siblings like browse_catalog_feed. However, it claims filters by 'stock' and 'trust score' that are not present in this tool's schema, which obscures the actual capability and could mislead an agent.

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?

There is no guidance on when to use this tool instead of alternatives. In particular, the sibling search_products_enriched likely covers richer or different filters, but the description does not clarify which tool should be chosen for specific search needs or exclusions.

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 provided, the description carries the full behavioral burden. It does disclose that the results include attributes, variants, GTIN, and multiple images; however, it does not disclose pagination behavior, result ordering, matching rules, or any performance/side-effect considerations. This is minimal—not misleading, but not deeply transparent.

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 sentence with the main action front-loaded, followed by a concise colon-separated list of enriched data fields. No redundant words, no echoes of the schema, and the structure supports rapid parsing.

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 five parameters and their constraints are fully covered by the schema, and the description tells the caller what enriched fields to expect. However, given there is no output schema and no explicit guidance on when to choose this over 'search_products', the description leaves a notable gap for an agent deciding between sibling tools.

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 description coverage is 100%, so parameter semantics are already fully documented. The tool description adds no additional parameter-specific guidance beyond what the schema supplies, 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 the exact operation ('search products') and uniquely qualifies it with 'enriched data: attributes, variants, GTIN, multiple images.' This clearly distinguishes it from the sibling 'search_products' by listing the enhanced content fields. The verb-resource-object structure is explicit and unambiguous.

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 'enriched data' implies that this tool should be used when callers need attributes, variants, GTIN, or multiple images, but the description doesn't explicitly contrast it with 'search_products' or say when NOT to use this tool. No alternatives or exclusion conditions are mentioned.

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 provided, the description carries the burden of behavioral disclosure. It does disclose that results include only matching names and brief descriptions, which is useful. However, it does not describe behavior like pagination, result ordering, empty-result handling, or the effect of the limit parameter.

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 focused sentences with no filler. The first sentence states the core function and output; the second gives the recommended usage. The information is front-loaded and every sentence 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?

The description adequately explains the return format (names and descriptions only) and the intended use case. With no output schema provided, this return-value disclosure is important and included. It could mention how to access full tool definitions for matched tools, but the description remains sufficient for correct invocation.

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 only 50%; query has a description in the schema and the tool description reinforces it. The limit parameter is not described in the description or schema, but its min/max/default values provide some structural guidance. The description adds some meaning but does not fully compensate for the other undocumented parameter.

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 action (search) on a specific resource (available tools) using a keyword, and clearly distinguishes the return value (tool names and brief descriptions). This is unambiguous and differentiates the tool from siblings like search_docs and search_products.

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 says to use this tool "instead of loading all tool definitions upfront when the catalog is large," which gives a clear contextual trigger. It does not explicitly name when not to use it or alternatives like get_tool_details, but the guidance is directly actionable.

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 full burden falls on the description. It explicitly reveals an important side effect—recalculating cart totals—which is helpful. However, it does not disclose authentication needs, whether the operation irreversibly modifies the cart, expected response contents, or error conditions.

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 one efficient sentence with two clear parts: the action and the resulting side effect. There is no filler, repetition, or unnecessary detail.

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 two-parameter tool with no output schema, the description conveys the core behavior adequately. It is minimally viable but does not situate the operation in the checkout flow—such as being a step between get_shipping_rates and complete_checkout—and provides no information about return values or failure cases.

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 both parameters already have meaningful descriptions, especially shipping_handle, which references get_shipping_rates. The tool description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline of 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?

The description uses a specific verb and resource ('Select a shipping option') and states the resulting behavior ('recalculate cart totals'). This distinguishes it from sibling tools like get_shipping_rates, which only retrieve options, and complete_checkout, which finalizes the order.

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 no guidance on when to use this tool versus alternatives. It does not say that it should be called after get_shipping_rates, before complete_checkout, nor mention which sibling tools would be inappropriate here. The usage context must be inferred entirely from the tool name and schema hints.

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 provided, the description carries the burden of behavioral disclosure. It clearly explains the merge behavior (existing product_id increments quantity, new product_ids are appended) and that the checkout must be incomplete. This is meaningful behavioral context beyond what the schema reveals, though it does not mention side effects or error conditions.

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 convey exactly what is needed: what the tool does, how it behaves, and when to choose it over a sibling. Every sentence earns its place; nothing 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?

Given the tool's complexity (2 params, moderate merge semantics, no annotations, no output schema), the description is quite complete. It covers the core behavior and the key distinction from the sibling. It does not mention return value or failure modes, but that is not essential for selecting and invoking the tool 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 the baseline is 3. However, the description adds value by explaining the behavior attached to the line_items parameter: existing product_ids get quantity incremented and new ones are appended. This gives semantic meaning beyond the schema's field-level 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 clearly states a specific verb ('Append') and a specific resource ('line items to an existing incomplete UCP checkout session'). It also differentiates from the sibling tool ucp_update_checkout by referencing the alternative by name, allowing an agent to distinguish the two without opening either schema.

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 tells when to use this tool over the alternative: 'Use instead of ucp_update_checkout when you want to preserve existing items.' It also implies the tool is for existing incomplete sessions, which sets a condition on when it applies.

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 behavioral burden. It does disclose a meaningful side effect—released held inventory—but it does not mention irreversibility, authorization needs, or behavior when the checkout is already completed.

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, tight sentence with no filler or redundancy. It front-loads the action and immediately communicates the key outcome, making it easy for an agent to parse.

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?

This is a relatively simple operation: one required parameter, no nested objects, and a clear action. The description plus schema are sufficient for invocation. A small gap is the absence of any indication of what the response will look like, especially since no output schema exists.

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 documents all parameters with 100% coverage, including checkout_id as a UUID, reason, and idempotency_key. The description adds no parameter-level guidance, so it stays at the baseline for well-documented schemas.

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 ('Cancel') and resource ('UCP checkout session') and adds a concrete consequence ('release held inventory'). This clearly distinguishes the tool from sibling operations like ucp_complete_checkout, ucp_get_checkout, and onx_cancel_order.

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 implies when to use the tool: when a UCP checkout session needs to be cancelled and held inventory released. It does not explicitly call out alternatives or provide when-not-to-use instructions, 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.

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

No annotations are provided, so the description carries the burden of disclosure. It clearly discloses the state transition to 'completed' and explicitly calls out idempotent behavior with retry safety, which is important operational context. It does not describe side effects like whether payment is processed or whether the operation is irreversible, but the disclosed information is substantive.

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 two short sentences with zero filler. The primary action and target are front-loaded, and the idempotency disclaimer is concise but essential.

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 state-transition tool with two fully described parameters, the description covers action, target, resulting status, and idempotency behavior. It does not mention what happens on invalid checkout IDs or whether the operation can be undone, but neither is essential for safely selecting and invoking this tool.

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 JSON schema already provides excellent parameter descriptions for both checkout_id and idempotency_key, so the schema does most of the work. The description adds value by explaining that retrying with the same key is safe, which reinforces the idempotency_key semantics beyond the schema text.

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: "Complete a UCP checkout session." It also states the resulting state transition to 'completed' status, which clarifies the tool's purpose and distinguishes it from cancellation or creation tools. However, it does not explicitly differentiate itself from the sibling tool 'complete_checkout', so it is not a full 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?

The description implies the tool is used when a UCP checkout session should be completed, and the note about idempotent retries gives some guidance for retry scenarios. But it does not explicitly state when not to use it, how it compares to 'complete_checkout' or 'ucp_cancel_checkout', or any preconditions that must be met before completing a checkout.

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 must carry the full burden of behavioral disclosure. It only reveals a creation operation and does not describe whether the session is immediately payable, whether side effects are irreversible, what is returned, or whether follow-up actions like ucp_complete_checkout are 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, front-loaded sentence with no filler. It expands the UCP acronym and includes the core input condition without repeating details that already exist in the input 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?

This is a nested, state-changing tool with no annotations and no output schema, yet the description omits return value, session lifecycle, idempotency, and follow-up actions. The schema documents parameters well, but the description alone is not enough for an agent to confidently understand the full impact of calling it.

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 provides 100% coverage for the parameters, including nested descriptions for line items, price, currency, and intent. The description adds no substantial parameter meaning beyond the schema, so the high schema coverage 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 clearly states the action (Create) and resource (UCP checkout session), and it mentions the key input (line items). It does not explicitly distinguish itself from siblings such as ucp_add_items_to_checkout or ucp_update_checkout, so differentiation relies mostly on the tool name.

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?

No explicit guidance is given about when to use this tool versus alternatives like ucp_add_items_to_checkout, ucp_complete_checkout, or create_cart. There are also no stated prerequisites, lifecycle steps, or conditions that would help an agent confirm this is the right 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?

No annotations exist, so the description carries the full behavioral burden. It adds the 'real-time' trait, but says nothing about side effects, pagination, response shape, or whether prices/inventory are session-scoped or system-wide. For an unannotated read tool this is minimal transparency.

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 short, front-loaded single sentence with no wasted words. It could be improved structurally by replacing the vague 'via UCP catalog capability' phrasing with more concrete scope or behavior, but it is otherwise economical.

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 no output schema and no annotations, this description is too sparse. It does not explain what the response contains, how pagination and product_ids relate, or how to choose this over sibling browsing/search tools. An agent can infer basic invocation from the schema but not confidently choose or interpret the tool.

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?

Input schema covers 100% of parameters with detailed descriptions for limit, cursor, and product_ids. The description itself adds no parameter meaning, but it does not need to because the schema is already informative, so the baseline of 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?

The description states a clear verb and resource: 'Get real-time product prices and inventory via UCP catalog capability.' It conveys the core purpose, but the phrase 'UCP catalog capability' is fuzzy and it does not explicitly distinguish this tool from siblings like browse_catalog_feed, get_product_details, or onx_get_inventory.

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?

There is no guidance about when to use this tool versus alternatives. Sibling tools such as browse_catalog_feed, search_products, and get_product_details overlap semantically, but the description gives no conditions, exclusions, or routing hints.

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 full responsibility for behavioral disclosure. 'Retrieve' implies a read-only operation, but the description does not mention expected behavior, preconditions, response details, authentication, or side-effect-free guarantees, leaving significant behavioral context unstated.

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, direct, front-loaded sentence with no wasted words. For a simple retrieval tool with one required parameter, this is appropriately concise.

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, one-parameter retrieval tools, the description and schema together provide enough information to invoke it correctly: the checkout_id is required and the description identifies the resource type. More detail about preconditions or return shape could improve it, but it is not essential for correct invocation.

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 only parameter is described in the schema as 'UCP checkout session ID (valid UUID)'. The description simply mirrors that concept with 'by ID' and adds no new meaning or format details 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 states a specific verb ('Retrieve'), a specific resource ('UCP checkout session'), and the lookup mechanism ('by ID'). This distinguishes it from sibling checkout operations like ucp_create_checkout, ucp_update_checkout, ucp_cancel_checkout, and ucp_complete_checkout.

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 implicitly tells the agent to use this tool when a checkout session needs to be retrieved using an existing checkout ID. However, it does not explicitly say when not to use it or name alternative tools for similar or adjacent operations, so usage guidance is implied rather than explicit.

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?

The phrase 'Replace all' makes it clear that existing line items are overwritten, so the mutation behavior is at least stated. However, with no annotations to lean on, the description does not elaborate on business consequences, whether the operation is reversible, or whether any checkout state restrictions apply.

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 short sentence that front-loads the core action and scope. It contains no redundant wording or unstructured padding.

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 mutation tool with no annotations and no output schema, the description gives the basic effect but leaves out operational context such expectations about an existing checkout, the effects of replacement on prior items, and whether currency applies uniformly to all replacement items. The input schema covers the parameter shape well, so this is adequate but not rich.

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 checkout_id, currency, and line_items are already fully documented by the input schema. The description adds a little semantic context by saying the line items are replacement values, but it does not need to restate the parameters.

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 very specific action: 'Replace all line items' in a 'UCP checkout session.' It mentions the resource and the exact scope of the change, and it clearly differs from siblings like ucp_add_items_to_checkout through the word 'replace.'

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 implies that this tool is for replacing the full set of line items rather than adding to an existing set, which gives some usage guidance. However, it does not explicitly state when to prefer this over the sibling ucp_add_items_to_checkout or warn against using it when only partial modification is needed.

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 bears the full burden of behavioral disclosure, but 'update' only communicates mutation. It does not state whether the update replaces the whole mandate or only the supplied fields, what happens to the existing mandate, or whether additional permissions or approvals are 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, tightly worded sentence with no filler. It slightly loses clarity with the vague phrase 'limits or scope', but overall it is efficient and front-loaded.

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 tool has five parameters and no output schema, but all parameters are documented in the schema itself. The description does not mention that only new_* fields are optional, nor does it clarify common constraints like whether new_effective_until must be in the future, leaving an agent to infer important invocation details.

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 documents each parameter. The description's 'limits or scope' only loosely maps to new_amount, new_frequency, and new_effective_until, and it adds no new semantic value 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 names a specific action ('Update'), resource ('existing payment mandate'), and target ('limits or scope'), making the tool's purpose immediately clear. It also instantly distinguishes the tool from its create_payment_mandate and cancel_payment_mandate siblings.

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 'existing' implies this applies to already-created mandates, and the sibling list makes the alternative obvious. However, the description does not explicitly state when to prefer this over create_payment_mandate or cancel_payment_mandate, nor does it mention any prerequisites such as the mandate needing to be active.

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 full burden of behavioral disclosure. It does convey a request/poll two-phase behavior, but it omits important traits such as whether the buyer is prompted in an external EUDI Wallet flow, whether results persist or expire, and what the returned outcome looks like.

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 one short sentence with no filler. The action, resource, and scope are front-loaded and every word contributes to the meaning.

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?

Although the tool is a simple-looking verification operation, it is asynchronous ('request or poll'), has no output schema, and has no annotations describing side effects, result format, or failure modes. The description leaves an agent without enough information to correctly interpret the result or recover from an expired or failed verification.

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 documents all three parameters. The description adds some semantic context by naming the protocol trait 'age_equal_or_over.N' and tying it to the buyer, but it does not meaningfully explain how cart_id and verification_id relate to the request/poll distinction beyond what the schema already says.

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 operation ('request or poll') and a specific resource ('EUDI Wallet age verification (age_equal_or_over.N)') scoped to the buyer. It is clearly distinct from sibling verification tools like verify_residence_country and verify_legal_person_authorization, though it does not explicitly contrast itself with them.

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 'request or poll' implies two calling modes, but the description gives no guidance on when to create a new verification versus poll an existing one. It also does not mention prerequisites such as an existing cart, checkout state, or when this verification is needed.

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 must carry the behavioral disclosure burden. It reveals the dual create/poll modes but does not disclose side effects, whether user consent is triggered, how the EUDI Wallet interaction occurs, or what happens to the cart after verification. For a tool involving verification workflows, this is a notable gap.

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 that clearly expresses the tool's core function and its two modes without wasted words. Every element contributes to understanding.

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 no output schema and no annotations, the description leaves an agent uncertain about return values, asynchronous results, failure modes, or whether the verification can be reused. For a tool involving external EUDI Wallet interaction, more context is needed.

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 explains both parameters. The description adds minimal extra meaning by framing the two modes in plain English, but does not go beyond the schema's provided descriptions. 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?

The description clearly states the action ('Request or poll') and the specific resource ('EUDI Wallet verification that the buyer is authorized to act for a legal person'). This distinguishes it from the other verify_* siblings such as verify_age_over_n and verify_residence_country, though it does not explicitly name those alternatives.

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 implies when to use the tool: whenever the buyer's authorization to represent a legal person must be verified. However, it provides no exclusions or explicit comparison against sibling verification tools, and it does not clarify when to request a new verification versus poll an existing one. This is adequate but not explicit.

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 alone must disclose behavioral traits. It states that the tool can initiate or poll verification and mentions the EUDI Wallet context, but it does not clarify whether verification is asynchronous, how long polling may last, what authorization is needed, or what the response contains. The schema's parameter descriptions hint at flow but the tool description itself is thin.

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 sentence with focused wording and no filler. It is easy to parse and front-loaded with the operation type, though it is so terse that it leaves some important context to be inferred. Acceptable conciseness but borderline under-specified.

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 tool has no output schema, no annotations, and both parameters are optional. The description does not clarify whether the parameters are mutually exclusive, whether at least one must be passed, or what the caller should expect after requesting or polling. An external identity-check process with zero descriptive context is incomplete for reliable invocation.

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 already document their meaning (verification_id polls an existing verification instead of creating one). The tool description effectively restates the request/poll dichotomy but does not introduce new semantic details about parameter values. Baseline 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 clearly states a specific action pair ('Request or poll') on a specific resource ('EUDI Wallet residence-country verification for the buyer'). This immediately distinguishes it from sibling verification tools like verify_age_over_n and verify_legal_person_authorization.

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 conveys the general context—verifying a buyer's country of residence—and the request/poll modes that align with the parameters. However, it does not explicitly state when to use this tool instead of alternatives, nor does it explain how to choose between cart_id and verification_id. No alternative/exclusion guidance is provided.

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