Facet UCP Shopping

get_payment_requirements

Turn a quote_token from get_quote into a seller-signed payment offer to authorize. Returns requirements (escrow address, asset, exact atomic amount, network) — sign it LOCALLY with your own wallet (e.g. @bosonprotocol/x402-client handle402 for coin/boson-escrow, producing an X-PAYMENT string). Facet never holds your key and cannot sign for you, which is why paying is two steps and not one. The offer binds to the quote_token's sealed landed total and ship-to, so the amount is the merchant's, not one you name. REQUIRES IDENTITY: same Facet KYA as get_quote, and the SAME aid — the offer path rejects a quote_token issued to a different agent than the caller.

Input Schema

TableJSON Schema

Name	Required	Description
`qty`	No	Must match the quote_token. Default 1.
`amount`	Yes	The landed total in ATOMIC units. Must equal the quote_token's sealed total.
`rail_id`	Yes	Settlement rail, e.g. "coin/boson-escrow" (escrow: funds release on fulfilment) or "coin/usdc-base". See /v1/payments/capabilities for what this merchant registers.
`site_id`	No	Usually omitted — this Terminal's bound site is used.
`product_id`	Yes	Must match the product the quote_token sealed.
`quote_token`	Yes	The signed token from get_quote.

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, description fully discloses key behaviors: the offer must be signed locally, the amount is fixed to quote token's sealed total, identity requirements, and that Facet cannot sign. It also explains the return format (escrow address, asset, amount, network). No contradictions.

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

Conciseness4/5

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

Description is well-structured with front-loaded purpose, but slightly verbose. Each sentence adds necessary context—workflow steps, identity requirements, and parameter constraints. Could potentially be trimmed slightly, but overall efficient.

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

Completeness5/5

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

Given 6 parameters, 4 required, no output schema, and no annotations, the description is remarkably complete. It covers the overall workflow, all parameter constraints, behavioral nuances (local signing, fixed amount), and even hints at the output format. No significant gaps.

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

Parameters4/5

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

Schema coverage is 100%, so baseline 3. Description adds value beyond schema by explaining constraints (amount must equal sealed total, product_id must match sealed product, rail_id purpose). It references related tools (get_quote) and clarifies default for qty.

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

Purpose5/5

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

Description starts with a specific verb ('turn') and resource ('quote_token into a seller-signed payment offer'), clearly stating what the tool does. It distinguishes itself from siblings like get_quote, get_order, and get_payment_capabilities by specifying that it transforms a quote token into a payment offer.

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

Usage Guidelines4/5

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

Clearly explains when to use (after get_quote, to authorize payment) and prerequisites (same identity and aid as get_quote). It also explains why paying is two steps and notes constraints like 'Facet never holds your key and cannot sign for you.' No explicit mention of when not to use, but context is clear.

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

All Facet UCP Shopping tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.6/5.0

Disambiguation3/5

Most tools map to a distinct lifecycle step, and the detailed descriptions separate discovery, cart, checkout, payment, order, and wishlist concerns well. However, get_product and lookup_catalog are largely the same lookup by identifier, discover_products and search_catalog overlap across scope, and update_checkout is actually a read-only no-op.

Naming Consistency4/5

The set overwhelmingly follows a verb_noun pattern: create_cart, get_checkout, cancel_checkout, complete_checkout, search_catalog. Minor deviations are the wishlist_* resource-first subgroup and the misleading update_checkout, which does not perform an update.

Tool Count3/5

At 23 tools, this sits at the heavy end of the range, though the broad commerce lifecycle does justify substantial surface area. The count is inflated by redundant product lookup tools and a no-op update_checkout, so a more trimmed set in the low-to-mid teens would be healthier.

Completeness4/5

The server covers the full shopper lifecycle well: discovery, product lookup, cart, checkout, payment, order placement, order read, refunds, and wishlist. Gaps are minor and workable, such as update_checkout not actually supporting updates and no explicit order-cancellation path once a checkout is complete.

Resources

Need Help?