Trusteed Demo Store

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

Annotations already declare readOnly=false, idempotent=true, and destructive=false, so the safety profile is covered. The description adds genuinely useful operational context beyond that: the credential requirement, the absence of human login, and the two ways to supply the 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 purpose is front-loaded in the first sentence, followed by credential mechanics. It is slightly verbose on the credential workflow, but every sentence carries actionable information rather than 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 annotations covering safety semantics, an output schema handling return values, and full schema description coverage, the description's remaining job is the credential/auth workflow, which it explains thoroughly. It is complete enough for an agent to invoke the tool correctly without guesswork.

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 cart_id, agent_key, discount_code, identity_token, source, and idempotency_key in detail. The description largely restates the agent_key mechanism rather than adding format or constraint detail 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 first sentence gives a specific verb and resource: 'Apply a discount or promo code to the cart.' It is unambiguous what operation is performed, though it does not explicitly distinguish itself from cart-mutation siblings like the 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?

It provides a clear prerequisite chain (call create_sandbox_key first, then pass the key as agent_key or an Authorization header) and points to the checkout guide resource. It does not, however, state when to prefer this tool over alternatives or any conditions under which it should not be used.

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 declare mutation/idempotency/openWorld hints, but the description quantifies them: replay is keyed on checkout_session_id, idempotency_key is recorded and short-circuits repeats, and a replayed session returns the same order without re-charging. It additionally discloses PENDING_EXTERNAL_CONFIRMATION semantics, the KYAPAY rejection (PAYMENT_METHOD_NOT_CONFIGURED), KYA token scope, demo-store's non-verified approval, and the payment mandate's header-vs-argument options — all beyond the structured fields.

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?

Purpose and the cart-card preference are correctly front-loaded, but the body is a dense wall of roughly 500 words covering mandate anatomy, KYAPAY, demo-store caveats, and idempotency in a single block. Substantial material (payment mandate fields, KYAPAY rejection, payment_method semantics) is repeated verbatim from the schema descriptions, so several sentences do not earn their place here.

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 12-parameter mutation with heavy nested objects and an output schema, the description covers the pieces an agent needs to succeed: credential acquisition, mandate construction and its two commonly-guessed fields, currency matching, the ACP/KYAPAY/X402/MOCK distinctions, the async approval path, and a pointer to the checkout guide. Return-value explanation is appropriately delegated to the output schema.

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 cross-parameter workflow meaning the schema does not: it tells the agent to populate buyer.name and buyer.email from the conversation even though the schema marks buyer "Optional," and it stresses that idempotency_key is required as an argument rather than only as a header/_meta. The mandate and payment_method explanations largely duplicate their schema descriptions, capping it below 5.

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 "Complete the purchase" states a specific verb and resource, and the card-vs-tool guidance makes the tool's role distinct from the interactive cart card and from preview_checkout. It never explicitly distinguishes itself from the sibling ucp_complete_checkout, which an agent could confuse with it, so it stops short of a 5.

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

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

It gives explicit when-to-use and when-not-to-use rules: "PREFER THE CART CARD... Only call it yourself when there is no interactive card or the buyer explicitly asks you to complete it in chat." It also names the prerequisite ordering (create_sandbox_key first, provide buyer.name/email, ask in chat if missing) and points to the checkout guide resource.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), and the description goes well beyond them by disclosing the credential model, the fact that a Skyfire kya token has no effect here, and the distinction between MCP auth and the REST agent API. This is exactly the auth/permission context annotations cannot carry.

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?

Front-loaded with purpose and downstream routing first, credentials and identity caveats after. The uppercase labels (KYA IDENTITY, CREDENTIAL) aid scanning, though the block is dense enough that it reads more like a runbook than a 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?

An output schema exists so return values need no explanation, and for a 6-parameter write tool the description still covers the credential prerequisite, the identity caveat, the downstream tool chain, and a guide pointer. 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%, so the baseline is 3, but the description adds real semantic glue by documenting how the output value flows into differently-named parameters (cart_id vs checkout_session_id) and by clarifying the agent_key/header relationship. It adds meaning without re-stating the schema's own 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?

States a specific verb+resource ('Create a shopping cart in Demo Store') and names the concrete artifact produced ('Returns a cart_id'). It also disambiguates from the large checkout sibling cluster by mapping its output to the exact parameter names downstream tools expect, so an agent can place it in the workflow without opening other 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?

Explicit ordering and prerequisites: call create_sandbox_key first, then pass the returned key as agent_key or an Authorization header. It also states when-not (no human login exists for this store) and points to the authoritative checkout guide resource, leaving no routing inference to the agent.

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 transparently states the credential's temporary nature (24h), that it settles nothing (simulated payments), that it works only on the demo store, and that no human login is involved. This covers the key behavioral aspects an agent needs to know before invoking the 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 concise, consisting of three sentences that front-load the core purpose and then provide usage and limitations. Every sentence adds value with no redundancy or unnecessary detail. It is well-structured for quick agent 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 that the tool has an output schema (not shown here but indicated), the description does not need to explain the return format. It covers the purpose, usage, validity, scope, and caveats. For a zero-parameter, self-contained tool, the description is complete and sufficient for an agent to use it correctly.

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

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

The tool has zero parameters, and the schema confirms this. The description does not need to explain parameter semantics because none exist. The baseline for 0 parameters is 4, and since there is nothing to add, this score 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 identifies the tool's purpose: fetching a temporary sandbox credential for the demo store. It uses a specific verb ('Get') and resource ('temporary sandbox credential') and distinguishes itself from sibling tools that handle carts, checkout, and product browsing. The 24-hour validity and demo-only scope are explicitly stated, leaving 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 provides explicit instructions on how to use the credential: either as an Authorization: Bearer header or as the agent_key argument, with a clear caveat for clients that cannot set headers. It also sets expectation that payments are simulated and the credential only works on the demo store. While it doesn't name alternatives (none exist among siblings), the usage context is fully specified.

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 non-destructiveness, so the safety profile is covered. The description adds valuable context: the merchant is fixed by endpoint, not by a parameter, and no parameters are accepted—this prevents misuse and clarifies an unusual behavioral trait.

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 pack the essential information with no waste: what the tool returns, why it takes no arguments, and what to do for a different merchant. The most critical fact—'Takes NO parameters'—is front-loaded in the second sentence, and the overall structure is easily 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?

Given the tool has zero parameters, rich annotations covering safety and idempotency, and an output schema, nothing an agent needs to call it correctly is missing. The endpoint-binding behavior is explicitly clarified, which is the main source of potential confusion.

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?

With zero parameters, the schema alone provides no semantic guidance. The description explicitly states 'Takes NO parameters' and explains why the merchant is fixed by the endpoint, which is essential for an agent to avoid inventing arguments, especially since additionalProperties is true.

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 that the tool retrieves the complete merchant profile, including trust score, policies, compliance, and protocol support. It identifies the resource and scope precisely, but does not explicitly differentiate itself from sibling tools like get_trust_receipt, which appears related.

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

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

The description explains when to use the tool: to read the profile of the merchant associated with the current MCP endpoint. It also provides a clear rule for accessing a different merchant's profile by using the same tool on that merchant's endpoint, though it does not mention alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-structured behavior: the response is a summary rather than full page text, and `content_scope` reports what was actually returned. It does not describe truncation limits or pagination of the blog listing, so it falls short of a 5.

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?

Front-loads the single most important fact (it returns a SUMMARY, not the full page) in the first clause, then moves to usage and slug mechanics. It is dense and mostly waste-free, though the slug examples ('for-agents', 'pricing') duplicate the schema and 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?

With an output schema present, the description need not explain return values, and the annotations cover the safety profile. It supplies the remaining pieces an agent needs: the summary scope, the discovery path via get_site_map, and the fallback to the linked URL for full content.

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 inline description of `page` already carries the baseline documentation, which the tool description largely repeats. It does add one non-obvious semantic: passing a blog post slug returns that post's excerpt rather than page metadata, which the schema does not state.

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 (get a summary of a page) and enumerates exactly what the summary contains: title, description, keywords, related tools, and full-page link. The summary-vs-full-text boundary also separates it from genuinely different siblings, so an agent can classify it 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?

Gives explicit when-to-use guidance ('read the linked URL when the whole page is needed') and names the prerequisite alternative ('Use get_site_map first to discover available slugs'). Both routing decisions an agent must make are stated rather than implied.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries no burden for safety traits. What it adds is content scope (variants, sizes, colors, availability) rather than behavioral characteristics like rate limits, errors, or authorization requirements. This is adequate but adds no significant behavioral transparency beyond 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?

A single sentence with no filler, the action is front-loaded, and the included detail modifiers are concise. Every word contributes to understanding the tool's purpose.

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

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

For a one-parameter, read-only tool with an output schema and rich annotations, the description is essentially complete. It doesn't explain when to use it vs alternatives, but that gap is relatively minor for a get-by-ID operation and is somewhat addressed by the schema. Overall, it provides enough for an agent to call it correctly.

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

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

The schema description for product_id is complete (100% coverage) and already instructs using the `id` field from search_products or nlweb_ask and not to invent IDs. The tool description provides no additional parameter-level meaning, 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 clearly states the tool retrieves detailed information for a specific product, listing included attributes (variants, sizes, colors, availability). The verb 'Get' and resource 'specific product' are explicit. It does not explicitly distinguish from sibling tools like search_products or search_products_enriched, but the 'specific product' phrasing implies a lookup-by-ID 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 implies usage when a specific product ID is known, but it does not provide explicit guidance on when to use this tool versus alternatives such as search_products or compare_products. The parameter schema adds the hint to use IDs from search_products or nlweb_ask, but the description itself lacks this 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?

Goes well beyond the annotations: it discloses that authoritative=false rates are estimates rather than final charges, that cheapest_shipping_handle is null when rates cannot be compared in the cart currency, and that each top-level call opens a new card in the transcript. The credential requirement is also documented. Annotations (readOnlyHint=false, non-idempotent) do not cover any of this, and nothing contradicts them.

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?

Front-loads the purpose, then the card preference, then the credential flow, so the important routing rule comes early. It is dense and a little long, with the credential repeated across the description and schema, but nearly every sentence carries operational information an agent needs.

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?

Output schema exists and return values are not restated, yet the one return-field semantic an agent actually needs (authoritative=false meaning estimates) is given. Combined with the address requirement, credential flow, and card-vs-chat decision, nothing needed 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%, so baseline 3 applies, but the description adds real meaning: it states shipping_address must be supplied in the call and that the tool will not prompt for it, and it explains the agent_key credential's purpose and the alternative Authorization header path. That is value 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?

States a specific verb+resource ("Get available shipping rates for the cart") and immediately scopes it against the sibling flow by pointing to select_shipping_option territory via cheapest_shipping_handle. An agent can tell it apart from create_cart or select_shipping_option without opening a 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?

Explicit when-not-to-use guidance: prefer the cart card and let the buyer pick shipping there, only call directly when there is no interactive card or the buyer explicitly asks. It also names the checkout guide resource and the prerequisite create_sandbox_key tool, so the routing decision and the setup path are both 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?

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description goes further by disclosing that the response is cryptographically signed, that the payload contains per-signal quality/confidence data, and that the JWS is detached and meant for offline verification — meaningful context beyond 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?

Two sentences with no filler: the first front-loads what is returned, the second front-loads the verification directive. The second sentence is dense but each named field earns its place by driving an actual verification step.

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

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

An output schema exists, so the description need not enumerate return values, and it still surfaces the security-critical fields an agent needs. For a zero-parameter read tool the coverage is strong; the only gap is the absence of any routing hint against the sibling get_trust_receipt.

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 takes zero parameters, so there is nothing for the description to disambiguate; per the rubric, a 0-parameter tool has a baseline of 4. The description's remaining naming (jwks_snapshot_uri, jws_compact, signing_kid, payload_hash_sha256) belongs to the output shape, not inputs.

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 ('Get Demo Store's signed trust score'), and adds version (v4.1), scale (0-100), and the contents of the payload (per-signal data quality, confidence level, detached JWS). However, it never distinguishes itself from the close sibling get_trust_receipt, so an agent must infer which trust-related tool to call.

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 a clear verification workflow ('download the JWKS..., validate jws_compact..., recompute payload_hash_sha256'), which is useful procedural guidance. It does not, however, state when to call this versus get_trust_receipt or get_merchant_profile, leaving usage selection to inference.

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 and does so: asynchronous issuance, `status: pending` with a retry delay, the distinction between `receipt_pending` and `checkout_in_progress`, and the credential-scoping rule ('Only the credential that made the purchase can read its receipt'). It even warns that a receipt attests the call, not settlement, with `settlement: not_attested` semantics.

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?

Purpose and the prefer-the-card routing rule are front-loaded, and every sentence carries actionable content (status codes, auth, settlement caveat). It is dense and long, but not padded; a slightly tighter grouping of the status-code discussion would improve it.

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?

Despite an output schema existing, the description still frames the payload (receipt id, JWS signature, verification, settlement flag) and covers the async/error paths and auth constraint. For a trust-attestation read tool, an agent has everything needed to call it correctly and interpret 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?

Schema coverage is 100% and both parameters are documented in the schema (including agent_key's sandbox-credential fallback meaning). The description adds no per-parameter syntax or format detail beyond that, 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?

Opens with a specific verb and resource: 'Retrieve the signed trust receipt for a checkout.' It clarifies scope (records the complete_checkout call) and distinguishes itself from get_store_trust and the checkout-completion siblings. An agent can identify the tool 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?

Explicit when/when-not guidance: prefer the interactive cart card, only call when there is no card or the buyer asks later in a new turn. It also states the precondition (read `order_placed` before claiming a purchase) and points to the checkout guide resource, leaving nothing to inference.

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 a non-read-only, non-idempotent mutation, and the description adds genuinely useful context beyond them: it advances the session to ready-for-payment, requires a sandbox credential, and clarifies there is no human login. It doesn't describe what happens on repeated calls or failure modes, but the auth and side-effect disclosure 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?

Front-loads the purpose and state effect in the first sentence, then layers preference, guide, and credential instructions. It is dense and mostly earns its length, though the credential paragraph is long enough that some repetition of the schema's agent_key semantics 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 3-param mutation tool with an output schema (so return values need no explanation) and full annotation coverage, the definition supplies the prerequisite credential flow, the guide pointer, and the card alternative. Complete enough to invoke correctly; only edge-case behavior (repeat calls, failure handling) is unaddressed.

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 every parameter (cart_id, agent_key, payment_mandate with all sub-fields) is fully documented in the schema. The description reinforces the agent_key credential path but adds no format or constraint detail the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('Preview the complete order summary before payment') and adds the state transition it causes ('Advances the session to ready-for-payment state'), which cleanly separates it from complete_checkout and the ucp_* checkout 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?

Gives an explicit alternative ('PREFER THE CART CARD'), points at the checkout guide resource, and spells out the prerequisite order: call create_sandbox_key first, then pass agent_key or an Authorization header. It also rules out the wrong path ('Do not ask a person to log in').

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate the safety profile. It adds useful behavioral context by noting that results are 'ranked by relevance,' though it does not describe pagination limits or result structure; the output schema likely covers the return shape.

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

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

The description is three short sentences, front-loading the operation and resource before giving the return behavior and sample use cases. Every sentence contributes useful context and there is no filler or repetition of schema details.

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

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

For a read-only, idempotent search tool with a full output schema and well-documented parameters, the description is complete enough for an agent to invoke it correctly. It states the document scope, result ordering, and representative use cases without requiring additional clarification.

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 all three parameters already have explanatory descriptions in the schema, so the baseline applies. The description adds modest value by connecting the type values (page, blog, faq) to the listed documentation categories, but it does not substantially expand 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?

The description names a specific operation ('Full-text search'), a clear resource ('all Trusteed public documentation'), and the concrete content types included ('pages, blog posts, and FAQ entries'). This makes the tool easy to distinguish from the product-focused sibling tools like search_products and 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 clear usage context: 'Use this to find answers about protocols, pricing, integration guides, trust scores, and more.' It does not explicitly state when not to use an alternative tool, but the resource scope and the search-oriented wording are enough to guide selection.

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. The description adds value beyond those by revealing that results are structured for generating a visual product carousel artifact and include category filtering. No contradictions 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 concise sentences, front-loaded with the core action and return value, then the artifact-specific detail. No wasted words or redundant rehashing of 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?

With a rich input schema, output schema, and safety annotations, the description is largely complete for invoking the tool correctly. The only notable gap is the lack of any pointer to search_products_enriched when richer results are needed, but that is more of a usage-guidance issue than a completeness failure.

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 fully documents all parameters. The description only lightly touches category filtering soldered and does not need to supplement the schema. 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 and resource ('Search products in Demo Store') and summarizes what is returned: matching products with prices, images, availability, and direct links. It is clear but does not explicitly differentiate itself from the sibling 'search_products_enriched', so an agent must infer which search variant to use.

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 for when to use this tool versus search_products_enriched or browse_categories. The description implies generic product search but provides no exclusions, alternatives, or route-selection logic.

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 annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating a safe, non-mutating operation. The description adds valuable behavioral context by specifying the matching algorithm (keyword/substring-based on title, description, tags, vendor) and the ordering (rating then review count), plus the important caveat that ratings are not verified by Trusteed. This adds transparency beyond annotations, though it could mention pagination or result limits, hence scoring 4.

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 with the main purpose and enriched data context, then follows with technical details and usage guidance. It avoids fluff, but slightly dense in the middle with matching/ordering details; still, every sentence contributes to understanding. Score 4 rather than 5 because the flow could be improved by separating use case from mechanics.

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 (likely describing the enriched data structure) and rich annotations, the description covers the key aspects: what data is returned, how matching works, ordering, and when to use. It doesn't explicitly mention pagination or how to handle empty results, but for a search tool with this complexity, it's adequately complete. Score 4.

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 all parameters are documented. The description reinforces the usage of query, category, and price range (linking to min_price/max_price) and clarifies the search scope. It doesn't introduce entirely new parameter details beyond schema, but given high coverage, baseline is 3, and the description's linking of natural language to parameters adds value, hence 4.

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

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

The description clearly states the tool's purpose: searching products with enriched data (structured attributes, variants, GTIN, images) and specifies the use case ('ideal for comparison and detailed product discovery'). It distinctly differentiates from the sibling tool 'search_products' by emphasizing the enriched data and ideal use case, making it easy for an agent to choose correctly.

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 this tool: 'Use this when you have concrete keywords, a category, or a price range.' It also clarifies the matching mechanism and ordering criteria, and importantly highlights that the ordering is based on merchant-asserted ratings and reviews, which is a key caveat. This provides clear and actionable guidance beyond simple when-to-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?

Annotations declare mutation, idempotency and non-destructive behavior, and the description goes well beyond them: it explains how to shape idempotency keys across retries, that a credential is required and how to obtain it without human login, and that an interactive card is the preferred path. This is exactly the context annotations cannot carry.

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?

Front-loads the action and prerequisite in the first sentence, then the UI preference, then the credential path. Dense but every sentence earns its place; only minor repetition with the schema's idempotency note.

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?

Covers prerequisites, credential acquisition, idempotency semantics, and a preferred UI alternative, and an output schema exists so return values need not be described. An agent has everything required to invoke this 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 baseline is 3, but the description adds real semantics: the retry contract for idempotency_key ('reuse the same key for retries of the same cart and option; use a new key if either changes') and the agent_key sourcing. It does not explain shipping_handle 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?

States a specific verb and resource ('Select a shipping method for the cart') and implicitly contrasts with get_shipping_rates, which it names as a prerequisite. An agent can distinguish this from sibling rate/checkout 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?

Explicit ordering ('Must call get_shipping_rates first'), explicit alternative ('PREFER THE CART CARD ... instead of calling this tool yourself'), and explicit credential path via create_sandbox_key. Names the checkout guide resource to read. Nothing is left to inference.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them: the resulting state ('canceled') and the precondition that already-completed checkouts cannot be canceled. It stops short of noting downstream effects (e.g., whether held inventory/payment auths are released).

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

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

Four short sentences, front-loaded with the action, then the state transition, then the exclusions, then the reference link. No redundancy and every sentence carries distinct routing or behavioral information.

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

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

An output schema exists so return values need no prose. Combining the precondition, the scope exclusion, and a pointer to the checkout guide covers everything needed to call this 1-required-param mutation 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 includes non-obvious details (idempotency-key header alternatives, agent_key fallback), so the schema does the heavy lifting. The description adds no per-parameter detail beyond the implicit checkout_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Cancel a UCP checkout session') and immediately scopes it to the UCP flow, naming the standard-flow siblings (create_cart, preview_checkout, complete_checkout) it is not for. An agent can distinguish it from ucp_complete_checkout and ucp_update_checkout without opening any 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?

Explicit when-to-use ('ONLY for a checkout session created with ucp_create_checkout') plus an explicit when-not-to-use with named alternatives ('for the standard flow ... do not call this tool'). It even routes the agent to the checkout guide resource for deeper 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?

Annotations already declare idempotentHint=true, but the description goes well beyond them: it discloses that a payment mandate is required, the exact six fields it must carry, the two commonly-guessed fields that are rejected outright (exp as Unix integer, aud as store slug), the currency-match requirement, and the semantic framing that the mandate is a self-imposed spending cap, not buyer consent. This is unusually rich behavioral context 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?

Front-loaded with the core purpose and routing before the mandate detail, and labeled sections (PAYMENT MANDATE) aid scanning. It is somewhat verbose and the mandate field explanations are repeated between the top-level paragraph and the schema descriptions, which dilutes conciseness without harming usability.

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 an output schema exists, the description needn't cover return values. It covers the prerequisites, alternatives, payment mandate requirements, authentication identity, and idempotency behavior — everything an agent needs to invoke this 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 schema already documents all 12 parameters including the mandate object fields. The description largely restates the mandate fields (mandate_id, max_amount_cents, currency, exp, sub, aud) that the schema already defines. It adds some value by stressing exp must be an integer and aud is a slug, and the idempotency_key-as-argument nuance, but this is mostly duplicative of 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 ('Complete a UCP checkout session') plus the resulting state transition ('Transitions to completed status'). It explicitly distinguishes itself from the sibling complete_checkout by scoping itself to ucp_create_checkout sessions, so an agent can tell them apart without opening a 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?

Gives explicit when-to-use ('ONLY for a checkout session created with ucp_create_checkout') and when-not ('for the standard flow ... do not call this tool') with the named alternative ('use complete_checkout'). It also names the prerequisite prerequisite flow and points to the checkout guide resource.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the returned status is 'incomplete', this begins a multi-step ucp_* flow, and mixing with the cart flow is prohibited. It does not elaborate on auth/permission requirements or guide the retry semantics further, but the additions are meaningful.

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?

Front-loads the core action and keeps each sentence purposeful: purpose, return status, flow routing, cross-flow warning, guide pointer. The return-status statement is marginally redundant with the existing output schema, but overall it is tight and well-ordered.

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 multi-parameter nested-object tool that already has an output schema and full schema descriptions, the description supplies the missing connective context (which flow this belongs to, that it returns an 'incomplete' session, and where to read the guide). Nothing critical 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?

Schema description coverage is 100%, and the schema itself carries rich parameter notes (idempotency requirements, variant_id conditions, ignored price/title fields). The description adds no per-parameter detail, so the baseline of 3 for schema-dominated documentation is appropriate.

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

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

States a specific verb and resource ('Create a UCP checkout session from line items') and immediately distinguishes itself from the sibling standard flow by naming create_cart. An agent can differentiate it from create_cart, preview_checkout, and the other ucp_* tools without opening a 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?

Explicitly says it 'Starts the UCP flow (ucp_* tools)', names the alternative ('for the standard flow use create_cart instead'), and adds a hard exclusion ('Do not mix the two flows on the same purchase'). When-to-use, when-not-to, and the sibling alternative are all present.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not burdened with that. It adds the meaningful behavioral constraint that this only reads UCP-created sessions and returns current state, plus a pointer to the checkout guide. It stops short of noting auth nuances (e.g. the agent_key fallback for clients without an Authorization header), which the schema covers instead.

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?

Front-loaded with the core action and return in the first two sentences, then the routing exclusion, then a guide pointer. Every sentence carries distinct information with no repetition of the schema or annotations.

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, return-value explanation is unnecessary, and the annotations cover the safety semantics. The description supplies the purpose, the flow-based routing, the prerequisite, and a guide reference, which is everything an agent needs to invoke this 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 checkout_id, meta, and agent_key are already documented in the schema with their formats and constraints. The description adds no syntax or format detail beyond that, which matches the baseline 3 when 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?

States a specific verb and resource ('Retrieve a UCP checkout session by ID') plus scope ('Returns the current state'). It explicitly distinguishes itself from the standard-flow siblings (create_cart, preview_checkout, complete_checkout) and pairs with ucp_create_checkout, so an agent can select it without opening any 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?

Gives an explicit 'Use ONLY for...' condition, names the required prerequisite (a session created with ucp_create_checkout), and states the when-not ('for the standard flow ... do not call this tool'). It even routes the agent to a guide resource for further context, leaving nothing to inference.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real behavior: line_items fully replaces lines, sending destination returns shipping options, and selecting an option mutates totals. It stops short of describing failure modes or what an invalid-status call returns, so not a 5.

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

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

Three tight sentences plus a guide pointer; the core mutation semantics come first, then the precondition, then the alternatives. No filler and nothing 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?

Covers what the tool does, its precondition, its sibling alternatives, and side effects on totals, while an output schema exists so return values need no explanation. Given a nested 7-parameter write tool, this is complete enough to call 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 schema already documents the replace-all semantics of line_items and the destination/selected_option_id sequencing, so the description largely restates structured data. It does clarify the workflow relationship (destination first, then option), but adds little beyond the schema's own field 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?

States a specific verb and resource ('Update a UCP checkout session') and immediately distinguishes itself from siblings by restricting scope to sessions created with ucp_create_checkout versus the standard create_cart/select_shipping_option flow. An agent can route between this and the standard checkout tools without opening a 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?

Explicit when-to-use ('ONLY for sessions created with ucp_create_checkout'), when-not ('for the standard flow use create_cart and select_shipping_option'), and a hard precondition ('Only allowed when status is incomplete'). It also points to the checkout guide resource for deeper context.

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