mcp-gateway

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

Beyond the annotations, the description reveals that a payment mandate is required even though the schema lists only cart_id as required, and that mismatched currency or over-cap mandates are denied. It also documents credential setup, optional skyfire-token behavior, and the absence of human login. These details significantly exceed what the annotations provide, and there is no contradiction with readOnlyHint=false, destructiveHint=false, or idempotentHint=true.

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 first sentence front-loads the core purpose, and the labeled paragraphs (SKYFIRE TOKEN, PAYMENT MANDATE, CREDENTIAL) are scannable and mostly non-redundant. It is long, but the tool has unusually complex auth prerequisites. Some header/argument alternatives are repeated from the parameter descriptions, so it is not perfectly concise, but every block 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 tool with 6 parameters and hidden requirements, the description covers setup order, mandatory mandate fields, currency-matching and cap-enforcement failure conditions, header fallbacks, and the no-human-login policy. Since an output schema exists, return-value details do not need to be spelled out. The only omissions are minor edge cases such as discount conflicts, which are not needed to invoke 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?

Although the schema already describes every parameter, the description adds crucial meaning: payment_mandate is actually mandatory and must match the cart currency with cap enforcement; agent_key is a create_sandbox_key credential; discount_code is required unless source is ucp_identity; and identity_token pairs with source='ucp_identity'. It also introduces the skyfire-pay-id header option, going beyond the schema's field 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 opens with a specific verb and resource: 'Apply a discount or promo code to the cart.' This clearly distinguishes it from checkout/payment siblings like complete_checkout and preview_checkout, and the later mention of UCP identity discounts clarifies the alternative input mode. An agent can understand exactly what the tool does without inspecting 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 gives strong operational guidance: it explicitly tells the agent to call create_sandbox_key first, to pass the key as agent_key or Authorization header, and not to attempt human login. It also explains when to use the payment_mandate argument versus the X-Payment-Mandate header. It does not formally state exclusions like 'use complete_checkout instead,' but the preconditions and alternative paths are clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'product counts' and the 'all categories' scope, which is useful but does not disclose behavior such as pagination, ordering, or response size. This meets the baseline without exceeding it.

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 filler. The main action and resource appear first, and the useful detail about product counts is included without verbosity.

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 zero parameters, a rich annotation set, and an output schema present, the description fully equips an agent to select and invoke this tool correctly. Nothing about when to call it or what to expect is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are 0 parameterschers, so no parameter explanation is needed. The baseline of 4 applies because the description compensates for the absence of parameters by clarifying exactly what will be returned.

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'), a clear resource ('all product categories'), and a meaningful detail ('with product counts'), within the context of Demo Store. This distinguishes it from sibling tools that search or retrieve individual products or pages.

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 this is the tool for browsing the full category listing in Demo Store, which provides enough context for when to use it. It does not explicitly name alternatives or exclusions, but none are necessary for such a straightforward no-parameter listing 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?

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds meaningful behavioral context by specifying that it produces a normalized attribute table and a best-value recommendation, going beyond the minimal safety profile. It does not contradict any annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence that front-loads the action ('Compare') and immediately states the key constraints and outputs. Every word earns its place with no redundancy or 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?

With a single parameter, full schema coverage, annotations covering the safety profile, and an output schema present, the description gives enough for correct invocation. It could have mentioned that the product IDs must reference existing products, but this is a minor gap given the output schema will define the result structure.

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 parameter description already states 'Array of product IDs to compare (2-5)'. The tool description repeats the 2-5 range but does not add extra meaning about ID formats, source, or preprocessing requirements, so the schema carries the weight.

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 ('Compare'), a specific resource ('products'), an explicit range ('2 to 5'), and the output type ('normalized attribute table and best-value recommendation'). This clearly differentiates it from single-product tools like get_product_details and search tools like 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 implies when to use the tool—when comparing 2 to 5 products side-by-side—but does not explicitly mention alternatives, exclusions, or when not to use it. It provides no direct routing guidance against sibling tools like get_product_details or search_products_enriched.

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 only state idempotentHint=true and destructiveHint=false. The description goes far beyond by detailing idempotency behavior (replay keyed on checkout_session_id, returns existing order without re-charging), error cases (missing/invalid token), enforcement of payment mandate caps, and credential requirements. This is substantial behavioral disclosure that annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Though long, every sentence carries essential information. It is front-loaded with the core purpose and idempotency, then logically groups token, mandate, and credential requirements. No filler or redundancy; the structure aids scanning and comprehension.

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 complexity of 9 parameters, nested objects, an output schema, and the need for credentials/mandates, the description covers all critical aspects: idempotency, token validation, mandate enforcement, credential acquisition, reconfirmation, and error handling. It also references the create_sandbox_key tool in the same list. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For example, it explains idempotency_key's role in short-circuiting, kyapay_token's required claims and precedence over header, payment_method's defaults and ACP behavior, payment_mandate's purpose and header alternative, agent_key's use when headers unavailable, and reconfirmed_state_hash's condition for use. This is far beyond schema 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?

States a specific verb+resource ('Complete the purchase') and distinguishes itself from siblings like preview_checkout and ucp_* checkout tools by focusing on the final completion step. It also clarifies it collects buyer contact info via elicitation, adding specificity.

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?

Provides explicit when-to-use instructions, including calling create_sandbox_key first, when Skyfire token is required (KYAPAY) vs not (MOCK, PAYPAL), and that no human login exists. It also explains the idempotency key usage and the reconfirmation requirement, giving clear conditions for correct invocation.

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?

Goes well beyond the annotations by disclosing required payment-mandate headers (and their currency-match denial rule), optional Skyfire trust-token effects, credential requirements, and the absence of human login. It also warns that invalid tokens proceed with a neutral trust score and that the max_amount cap is enforced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the SKYFIRE TOKEN / PAYMENT MANDATE / CREDENTIAL labels make it scannable, and the core purpose is front-loaded. Nearly every sentence carries operational information; only the incorrect `agent_key` reference keeps it from being fully reliable and tidy.

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 state-changing tool with auth and mandate requirements, it covers a great deal: prerequisites, headers, trust-score effects, and downstream usage. However, the central credential-preservation step is inaccurate (`agent_key` vs the schema's actual parameters), and it never explains how the agent determines the cart's currency to satisfy the mandate's currency-match rule.

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 has 100% description coverage, so baseline would be 3, but the description introduces an `agent_key` argument that does not exist in the input schema, which has additionalProperties: false. An agent following this instruction would submit an invalid tool call; the description does not map the create_sandbox_key output to the actual `agent_token`, `display_context`, or `agent_session_id` 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?

Opens with a specific verb and resource: 'Create a shopping cart in Demo Store,' and distinguishes itself from checkout/shipping siblings by stating it returns a cart_id for use with get_shipping_rates, preview_checkout, and complete_checkout. This is unambiguous and separates it from create_sandbox_key and the ucp_* checkout tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit execution context: call create_sandbox_key first, pass the returned credential (or Bearer header), and do not attempt human login. It also places the tool in a sequence with get_shipping_rates, preview_checkout, and complete_checkout. It stops short of naming alternate cart/checkout tools or exclusion conditions, so it is strong but not a full when/when-not guide.

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, and it does so thoroughly. It states validity duration (24h), that payments are simulated, that the credential settles nothing, that it works only on the demo store, and that no human login is involved. These are meaningful behavioral traits beyond the mere fact of creating a key.

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 three sentences and every sentence earns its place: purpose and validity, two usage methods with a clear conditional, and important limitations. The most essential information is front-loaded, and there is no redundancy or 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?

Given that the tool takes no parameters and an output schema exists to describe the return value, the description covers everything an agent needs: what the credential is, how long it lasts, exactly how to present it, and what its limitations are. The sibling context confirms checkout tools exist, so the reference to `agent_key` is actionable.

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 has 100% coverage of that fact, so the baseline is 4. The description adds relevant contextual guidance about how the returned credential should be used, even though it does not define any input parameters because none exist.

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 action ('Get') and the resource ('temporary sandbox credential'), and gives concrete purpose: authenticating to the demo store. It distinguishes itself from all sibling tools by being the only credential/authentication tool in the list, rather than a cart, checkout, product, or search 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?

It provides explicit, actionable usage instructions: present the credential as an `Authorization: Bearer` header, or pass it as the `agent_key` argument to checkout tools when headers cannot be set. It also sets expectations about scope ('works only on the demo store') and simulation ('settles nothing'), making the correct invocation context clear.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context beyond those: the merchant is determined by the endpoint, no parameter selects it, and the returned profile covers specific data domains. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The core action and resource are front-loaded, the critical no-parameter constraint is explicit, and the cross-merchant instruction is placed last 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 read-only, zero-parameter tool with rich annotations and an output schema, the description covers everything needed to call it correctly: what is returned, how the merchant is determined, why no arguments are required, and how to target another merchant.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters and the description proactively explains why, preventing an agent from inventing a merchant ID or store slug argument. This is stronger than the baseline for parameterless tools because it resolves the most likely confusion.

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 and resource: getting the complete merchant profile, and lists the concrete content categories (trust score, policies, compliance, protocol support). It is distinct from sibling tools focused on products, carts, checkout, or content pages.

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 explains when to use the tool and the unusual zero-parameter model, including how to handle a different merchant by calling the same tool on that merchant's endpoint. It does not explicitly name sibling exclusions, but the resource scope makes the intended use clear.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds useful behavioral detail beyond the schema: the special semantics of page='blog' and the expectation that slugs come from get_site_map. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler. The core purpose is front-loaded, followed by parameter guidance and the prerequisite use of get_site_map. 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?

For a single-parameter, read-only tool with rich annotations and an output schema, the description is complete. It tells the agent what slugs look like, how to discover them, and the special blog-listing behavior, so nothing essential is missing 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents the page slug and the 'blog' special value. The description largely repeats the schema's parameter explanation rather than adding new semantic meaning, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Read the content of a specific page on Trusteed.' It clearly distinguishes itself from siblings like get_site_map (which discovers slugs) and get_product_details (which returns product data), and adds the special 'blog' listing behavior.

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 instructs to 'Use get_site_map first to discover available slugs,' which routes the agent to the correct precursor tool. It gives clear context for when this tool is appropriate, though it does not spell out explicit when-not-to-use exclusions against other 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by specifying the scope of details (variants, sizes, colors, availability), which goes beyond annotations. No contradiction is present, and the description aligns with the read-only nature.

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, well-structured sentence. It front-loads the core action and resource, then expands with the detail categories. There is no filler or redundancy; every element 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 read-only tool with one parameter and an output schema, the description is largely complete. It states the tool's scope and the kind of data returned. The only gap is the lack of explicit routing to sibling tools (e.g., how to obtain product_id), but given the schema already covers that, the overall context is sufficient.

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 the product_id parameter well (including the instruction to use the id field from search_products). The description does not add any additional parameter-level information; it relies entirely on the schema. 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 ('Get detailed information') and the specific resource ('a specific product in Demo Store'), and even enumerates the details include variants, sizes, colors, and availability. It distinguishes from the search sibling tools (which return lists) by focusing on a single product, though it does not name an alternative explicitly.

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 use this tool versus alternatives. It does not mention that search_products should be used first to find product IDs, nor does it note any exclusions (e.g., 'not for listing multiple products'). Usage context is entirely implied by the tool name and description.

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 description goes well beyond the annotations by disclosing mandatory payment mandate requirements, denied-outright conditions on currency mismatch, max_amount_cents enforcement, optional token behavior, credential prerequisites, address elicitation, and the fact that there is no human login. These are exactly the operational behaviors an agent needs to know and are absent from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with labeled sections for token, payment mandate, and credential. It is front-loaded with the core purpose, and each section earns its place given the integration complexity, though some redundancy with schema descriptions could be trimmed.

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 authentication, payment mandate, and credential prerequisites, the description is remarkably complete: it covers required headers, argument alternatives, failure conditions, prerequisite tool calls, and the no-human-login rule. An output schema exists, so the lack of return-format detail is acceptable.

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?

Even though schema description coverage is 100%, the description adds meaningful parameter-level meaning: payment_mandate may be sent as an argument or X-Payment-Mandate header, its currency must match the cart or the call is denied, and its cap is enforced against the cart total. It also clarifies that agent_key can be passed as an argument or Bearer header and that create_sandbox_key must be called first.

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 opening sentence, 'Get available shipping rates for the cart,' names a specific verb and resource, and clearly distinguishes this from siblings like select_shipping_option and preview_checkout. The additional note about address elicitation further sharpens the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear prerequisite guidance — call create_sandbox_key first, provide a payment mandate, optionally include a skyfire token — but it does not explicitly say when to use this tool versus siblings such as select_shipping_option or preview_checkout. Usage is implied by the purpose statement rather than explicitly contrasted with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating the tool returns the complete site map and that it is a discovery/pre-navigation step. It does not contradict annotations. A small gap is that it doesn't mention whether the optional category filter changes the completeness of the returned map, but the schema covers the filter.

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 core function and scope; the second gives the usage context and names the next tool. Every clause 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 tool is simple (one optional parameter, no required params) and has a rich output schema plus annotations covering safety. The description explains the purpose and the workflow context. It could mention that the category filter is optional, but the schema already marks it as not required, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single optional category parameter. The description mentions categories in the body ('docs, blog, integrations, legal, marketing') but does not add meaning beyond the schema's enum list. Baseline 3 is appropriate because the schema does the heavy lifting.

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 ('Returns'), a specific resource ('complete site map of Trusteed'), and the organizational principle ('all public pages organized by category'). It also names the sibling tool it is meant to precede ('get_page_content'), which distinguishes it from the other browsing/search tools in the sibling list.

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 when to use this tool: 'Use this to discover what sections are available... and find the right path before calling get_page_content.' This gives a clear workflow directive and names the alternative/next step, which is strong usage 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?

The description discloses important state-changing behavior beyond the annotations: it advances the session state, requires a payment mandate, and denies the call outright if the mandate currency does not match the cart's currency. It also clarifies the optional token behavior ('request proceeds normally if omitted') and that there is no human login. This goes well beyond the sparse annotation hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then uses clear uppercase section labels for token, mandate, and credential requirements. It is long, but the length is justified by the complex authentication and mandate rules. Minor redundancy exists in repeating the 'if your client cannot set headers' condition for both payment_mandate and agent_key.

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 this many auth-related conditions, the description covers everything needed: purpose, state transition, optional token, mandatory mandate fields, currency rule, credential acquisition via create_sandbox_key, header alternatives, and the absence of human login. An output schema exists, so return-value details do not need to be in the description. The tool is fully callable from the description alone.

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 baseline is 3. The description adds meaningful semantics for payment_mandate and agent_key, including required subfields, header alternatives, currency-matching enforcement, and the max_amount_cents cap. It adds less for cart_id, but that parameter is already simple and well described in 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 opens with a specific verb and resource: 'Preview the complete order summary before payment.' It also states the key side effect, 'Advances the session to ready-for-payment state,' which clearly separates it from siblings like complete_checkout and ucp_create_checkout. This is a clear, distinct purpose.

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 clear contextual sequencing: this is for previewing before payment and advancing to ready-for-payment, which implies use before complete_checkout. It also provides explicit prerequisite guidance such as 'Call the create_sandbox_key tool first.' However, it does not explicitly name alternatives or state when not to use the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: full-text search, coverage across documented types, relevance ranking, and the 'public' nature of the material.

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, front-loaded with the core action and scope, followed by expected output and usage examples. 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 simple read-only search tool with an output schema, 100% parameter coverage, and clear sibling separation, the description fully equips an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description does not need to add parameter details. It broadly aligns with the 'type' enum by mentioning pages, blog posts, and FAQ entries, but does not add 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?

States a specific verb ('search') and a clear resource ('all Trusteed public documentation: pages, blog posts, and FAQ entries'), and names the result type ('ranked results by relevance'). This clearly distinguishes it from product-search siblings like 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?

Provides clear usage context ('Use this to find answers about protocols, pricing, integration guides, trust scores, and more') and the scope of what it searches. It does not explicitly name alternatives or exclusions, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the compact flag's effect on output, the field_mask's context-saving behavior, and the cursor's strict validity constraint (rejected if replayed against different filters). This goes beyond the annotations and 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 front-loaded with the core purpose and return value, then dives into parameter-specific behavior. It is somewhat long, but every sentence adds meaningful detail about output shaping and pagination constraints. The structure is logical: purpose first, then output highlights, then parameter nuances.

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 (9 parameters, output schema, rich annotations), the description covers the key behavioral nuances an agent needs: pagination cursor validity, compact vs. field_mask interaction, and trust-field preservation. It doesn't explicitly describe the output schema structure, but the output schema exists and the description references key fields. Minor gap: no explicit statement about when to prefer search_products_enriched, but overall complete for 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 the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that 'compact' trims the text reply and drops widget payloads while preserving trust fields, and that 'field_mask' drops carousel/UI payloads and always includes 'id'. It also clarifies the cursor's strict binding to the same query/filters. This is more than the schema alone 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 states a specific verb ('Search') and resource ('products in Demo Store'), and immediately distinguishes the tool from siblings by noting it returns prices, images, availability, and direct links, plus data for a visual carousel artifact. This clearly differentiates it from search_products_enriched and get_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 implies usage for searching and listing products, and the sibling list includes search_products_enriched, which suggests a more enriched alternative, but the description does not explicitly state when to use this tool vs. search_products_enriched or get_product_details. It gives clear context for what it returns but no explicit exclusions or alternative routing.

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 description adds substantial behavioral detail beyond the readOnly/idempotent annotations: matching is keyword/substring-based on specific fields, ordering is rating-then-review, and crucially it warns that ratings/review counts are merchant-asserted and not verified by Trusteed. This is meaningful, honest behavioral disclosure.

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 sentences, each earning its place: the enriched-data scope, the matching/ordering behavior with the trust caveat, and the when-to-use guidance. It is front-loaded with the primary purpose and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety semantics, the description sufficiently covers what an agent needs to select and call this tool: result richness, search behavior, ordering caveat, and input context. No critical operational behavior is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying what the query parameter actually does ('keyword/substring-based (title, description, tags, vendor)') and reinforcing the intended use of category and price-range filters. It does not describe every parameter but adds 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 states a specific verb and resource ('Search products') and clearly differentiates this tool by its enriched result data: 'structured attributes, variants, GTIN, and images.' It also states the intended use ('comparison and detailed product discovery'), making its purpose distinct from the simpler sibling 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?

It gives explicit guidance on when to use the tool: 'Use this when you have concrete keywords, a category, or a price range.' It does not explicitly name alternatives or exclusion cases, so it stops short of the fullest when/when-not guidance, but the context is clear.

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 description goes well beyond the annotations by disclosing authentication requirements, the mandatory payment mandate, currency-matching enforcement, the max_amount_cents cap, and the optional skyfire token behavior. It also clarifies that the call is denied outright on currency mismatch. This is strong behavioral context; a slight deduction is warranted because it does not describe the mutation effect on the cart or any idempotency-relevant behavior beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear all-caps sections and front-loaded purpose. Every section carries actionable detail, but it could be tightened; for example, the header-vs-argument alternatives are stated multiple times for both agent_key and payment_mandate. Still, it remains focused and scannable.

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 authentication, a payment mandate, and prerequisite calls, the description is remarkably complete: it covers the prerequisite sequence, credential acquisition, header/argument alternatives, mandatory mandate contents, denial conditions, and the lack of human login. With an output schema present and full input schema coverage, an agent has everything needed to invoke this 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 coverage is 100%, so the baseline is 3, but the description adds meaningful meaning to agent_key and payment_mandate by explaining how to obtain the credential via create_sandbox_key, when to use arguments versus headers, and the required mandate fields/currency rule. This exceeds schema-only documentation, though cart_id and shipping_handle receive no additional explanation 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 opens with a specific verb and resource: 'Select a shipping method for the cart.' It clearly distinguishes the tool from the sibling get_shipping_rates by requiring that tool to be called first, and the shipping_handle parameter is explicitly tied to get_shipping_rates output. This leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear workflow guidance: call get_shipping_rates first, then select a shipping option, and for credentials call create_sandbox_key first. It also states that no human login exists. However, it does not explicitly say when not to use this tool, such as 'use complete_checkout instead when finalizing the purchase,' so it falls short of fully explicit alternative routing.

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

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

Annotations already mark the tool as destructive and idempotent, and the description adds substantial behavioral context beyond that: the payment mandate requirement, the header-vs-argument delivery option, the mandatory fields, the currency-match denial condition, and enforcement of max_amount_cents against the cart total. This is exactly the kind of non-obvious runtime behavior an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then covers the mandatory payment mandate details. It is a bit dense, especially the uppercase PAYMENT MANDATE section, but every sentence serves a functional purpose given the hidden requirement and denial conditions.

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 that an output schema exists and annotations cover safety, the description provides complete operational context: what happens on cancel, what is not cancellable, how the required payment mandate must be supplied, and what conditions cause denial. No critical calling information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds critical semantics not fully visible in the schema: payment_mandate is actually required (though the schema lists it as optional) when not supplied as a header, its fields are enforced, its currency must match the cart, and the cap is enforced. This goes well beyond the schema's generic property 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 states a specific verb and resource: 'Cancel a UCP checkout session.' It adds a concrete state transition ('Transitions to canceled status') and a distinguishing constraint ('Cannot cancel already completed checkouts'), which clearly separates this from sibling tools like complete_checkout or ucp_update_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 clear context for when to use the tool (cancel a UCP checkout) and an explicit exclusion (not already completed checkouts). It does not name alternatives such as complete_checkout for completed sessions, so it stops short of fully explicit when-not/alternative 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?

Beyond annotations, it discloses the mandatory payment mandate, the ability to send it as an argument or header, the hard denial on currency mismatch, and the max_amount cap enforcement. These are operationally critical constraints that annotations alone do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and each sentence carries information. The Payment Mandate section is longer than ideal and partly overlaps schema descriptions, but it is justified because it clarifies a non-obvious required field and hard failure conditions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and rich field schemas, the description covers the critical missing context: return status, mandate requirements, and enforcement behavior. It is slightly vague about how 'cart total' and 'cart currency' are derived, but not enough to block 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%, but the description adds important meaning for payment_mandate: the required embedded fields, the header alternative, the currency-match hard stop, and cap enforcement. It does not add much to currency or line_items, but the schema already documents those fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create a UCP checkout session from line items.' It also clarifies the expected return state ('status incomplete'), which distinguishes it from sibling tools like complete_checkout or preview_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?

It gives clear context for use (creating an initial checkout from line items and supplying a payment mandate), and the 'status incomplete' detail signals this is the creation step. It does not explicitly name alternatives or exclusion conditions, but the intended usage is unambiguous.

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

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

Beyond the readOnly/idempotent hints, the description discloses that a payment mandate is mandatory even for this read, specifies the required fields, and gives exact denial conditions (currency mismatch, cap enforcement). This is material behavioral context an agent could not infer from annotations or schema alone.

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?

Every sentence earns its place: purpose, state returned, mandate requirement, transport alternatives, field requirements, and validation consequences. The structure front-loads the primary action and then gives the critical auth constraint.

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-checkout read with an output schema present, the description covers the essential call requirements, including the non-obvious mandate and validation rules. Nothing needed to correctly invoke the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds significant meaning to payment_mandate: the exact fields it must carry, the header-vs-argument alternatives, and the currency/cap enforcement rules. It thus goes well beyond the schema's generic 'Payment mandate with fields' 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 opens with a specific verb and resource ('Retrieve a UCP checkout session by ID') and clarifies it returns the current state. This clearly differentiates it from sibling mutation tools like ucp_create_checkout, ucp_update_checkout, and ucp_cancel_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 intended use is clear from the retrieval semantics for a single checkout by ID, but the description does not explicitly name alternative tools or exclusion conditions. It does give concrete invocation guidance for the required payment mandate, which helps an agent use it 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?

The description goes well beyond the annotations by explaining that a payment mandate is required, how to send it via body or header, the exact fields it must carry, and that currency mismatch causes outright denial. It also clarifies the cap enforcement against the cart total, providing rich behavioral context.

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 efficiently structured: the core purpose is front-loaded, followed by a clearly flagged payment-mandate section. Every sentence carries operational value, and the formatting makes the critical warning easy to notice.

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 of this complexity, the description covers the essential operational context: replacement semantics, status precondition, payment mandate requirements, and validation behavior. The existence of an output schema covers return-value expectations, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful semantic context beyond the schema, especially around payment_mandate: how to pass it, what it must contain, and the currency-matching rule. This elevates it above the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear, specific action: 'Update a UCP checkout session by fully replacing all line items.' This distinguishes it from sibling tools like ucp_create_checkout and complete_checkout, and the resource and operation are 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 description provides a concrete usage condition ('Only allowed when status is incomplete') and details critical operational requirements like the payment mandate. It does not explicitly name alternative tools or say when not to use it, so it stops just short of a perfect score.

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