UCP Gateway

shopping checkout update

shopping_checkout_update

Update checkout with a typed buyer (recommended for address/phone corrections) and/or a full checkout object. 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.
`agent_id`	Yes	Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool.
`checkout`	No	Optional full checkout replacement payload accepted by the provider. Prefer typed buyer for address/phone corrections; buyer address fields placed here are canonicalized into buyer/context/fulfillment with phone_number. Never include payment credentials.
`checkout_id`	Yes	Provider checkout ID returned by checkout tools.
`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.

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.4/5.0

Behavior4/5

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

Annotations indicate mutation (readOnlyHint=false) and non-destructiveness. The description adds behavioral details: phone format acceptance and warnings, canonicalization of buyer fields, and prohibition of payment credentials. No contradiction.

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, front-loaded with the main action, followed by crucial format notes. No superfluous words; every sentence adds value.

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

Completeness4/5

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

Given the complexity (nested objects, many parameters, output schema exists), the description covers the main usage pattern and format constraints. It could mention that it updates an existing checkout, but that is implicit from name and context.

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%, but the description adds value by explaining the purpose of buyer vs checkout parameters, recommending preference, and specifying constraints like phone_number alias behavior and payment credential exclusion.

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 'Update checkout with a typed buyer and/or a full checkout object,' specifying the action and resources. It distinguishes from create/get by the verb 'update' and the mention of corrections, aligning with sibling tool names.

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?

It recommends using typed buyer for address/phone corrections and provides format constraints (E.164, ISO-2). It does not explicitly state when not to use, but the context is clear. Sibling differentiation is implicit via the action.

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?