UCP Gateway

shopping checkout create

shopping_checkout_create

Create a merchant checkout handoff URL after operator confirmation. Does not accept payment credentials. Buyer phone should be E.164 and country must be ISO-2.

Input Schema

TableJSON Schema

Name	Required	Description
`buyer`	No	Buyer-provided checkout contact and shipping details. Never invent PII; omit phone if unavailable.
`cart_id`	No	Provider cart ID returned by cart tools. Provide either cart_id or line_items.
`agent_id`	Yes	Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool.
`currency`	No	ISO 4217 currency code, e.g. 'USD'.
`append_utm`	No	Whether to append The Agent Times handoff UTM parameters to the merchant continue_url.
`line_items`	No	Selected provider variant line items confirmed by the buyer/operator.
`merchant_domain`	Yes	Merchant host such as 'outboundpower.com' or 'example.myshopify.com'. Do not include a URL scheme, localhost, private IP, file URL, or ftp URL.
`client_action_id`	No	Optional UUID generated once for an explicit buyer/operator-confirmed cart or checkout mutation. Reuse only when retrying the same confirmed action.
`operator_confirmed`	Yes	Set true only after the buyer/operator reviewed the cart summary and explicitly confirmed checkout creation.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	True for successful tool execution; false for structured tool errors.
`raw`	No	Redacted raw provider or registry payload for debugging. Shape may vary by upstream endpoint.
`error`	No	Structured tool error.
`message`	Yes	Human-readable result summary or recovery message.
`checkout`	No	Safe provider checkout summary including id, status, continue_url, totals, line_items, and messages when provided.
`warnings`	No	Non-fatal checkout or handoff warnings.
`next_step`	Yes	Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions.
`merchant_domain`	No	Resolved merchant domain.
`partial_success`	No	True when Shopify flagged the upstream result as an error but returned a usable checkout payload (id plus continue_url or recognized status). The gateway result is still actionable; this is not an order confirmation.
`upstream_is_error`	No	True when the upstream Shopify MCP response set isError/ok:false while still returning a usable checkout payload. Present for debugging; does not make the gateway tool result an error.
`commerce_session_id`	No	Internal gateway commerce session UUID when one was created.
`requires_escalation`	No	True when Shopify requires the buyer to finish a step on the merchant-hosted checkout page (status requires_escalation/requires_buyer_input or escalation warnings). The continue_url is still actionable.

TDQS

A4.3/5.0

Behavior4/5

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

The description goes beyond annotations by clarifying that payment credentials are not accepted and specifying required formats for phone and country. Annotations provide readOnlyHint=false and destructiveHint=false, which the description aligns with. Additional behavioral details (e.g., output is a handoff URL, operator confirmation is required) are implied but not fully spelled out.

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

Conciseness5/5

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

The description is two sentences long, front-loading the core action. Every phrase is meaningful and adds value without redundancy.

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 the complexity (9 parameters, nested objects, output schema available), the description is complete enough. It covers the essential purpose, key constraints, and behavioral traits. The schema and output schema can fill in remaining details.

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

Parameters3/5

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

Schema coverage is 100% with detailed descriptions for all parameters. The description adds modest value by reinforcing format constraints (E.164 phone, ISO-2 country) and noting that the tool does not accept payment credentials. Baseline 3 is appropriate since schema already does the heavy lifting.

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?

The description clearly states the tool's purpose: 'Create a merchant checkout handoff URL after operator confirmation.' It also specifies that it does not accept payment credentials, which distinguishes it from payment-related tools. Combined with the tool name and title, the purpose is unambiguous.

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?

The description indicates that this tool should be used 'after operator confirmation', implying the prior step of cart creation. It mentions buyer phone/country format requirements. However, it does not explicitly state when not to use this tool (e.g., when to use cart tools instead) or list alternatives among siblings.

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

All UCP Gateway 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.8/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose, targeting either UCP profile management or shopping operations (cart, checkout, product). Within the shopping domain, actions are separated by object type (cart vs checkout) and operation (create, get, update, cancel), leaving no ambiguity.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with verb_noun structure (e.g., get_ucp_profile, shopping_cart_create, shopping_product_search). The naming convention is uniform across profile and shopping tool groups.

Tool Count5/5

With 12 tools, the server is well-scoped for its domain. It provides a focused set covering profile registration, cart and checkout lifecycle, and product search without being overwhelming or insufficient.

Completeness4/5

The tool set covers the core shopping flow (cart CRUD, checkout CRUD, product lookup) and profile registration. A minor gap is the absence of profile update or deletion, but registration is idempotent and deletion may be out of scope. Overall, no critical missing operations.

Resources

Need Help?