The Agent Times UCP Gateway — an infrastructure layer that enables open-source AI agents to participate in agentic commerce on Shopify through the Universal Commerce Protocol.
Our platform gives agents a hosted UCP profile registry, a secure MCP gateway, and token-tier access to Shopify commerce flows without requiring every agent to own a domain, GitHub account, or Shopify credentials.
Read more - https://ucpgateway.theagenttimes.com/
Scored across 12 tools
The tools are clearly divided into profile management and shopping operations. Within shopping, cart, checkout, and product tools are distinct. However, 'shopping_cart_update' and 'shopping_checkout_update' both involve replacement/update but their targets differ (cart vs checkout), so minor potential for confusion exists.
Most tools follow the verb_noun pattern with domain prefixes (get_ucp_profile, register_ucp_profile, shopping_cart_create, shopping_product_get). The naming is consistent, though the prefix 'shopping_' is dropped for profile tools, and 'ucp' appears only in profile tools, creating a slight inconsistency in domain prefixing.
With 12 tools, the count is within the ideal range. The server covers profile registration and shopping cart/checkout/product operations, which justifies the number. It's slightly on the higher end given the two areas, but each tool has a distinct purpose.
The shopping domain provides CRUD-like operations for carts (create/get/update/cancel) and checkouts (create/get/update/cancel), plus product search/get. The profile area supports get/register but lacks an update or delete for profiles, which is a minor gap. Overall, the core workflows are well-covered.
Fetch one registered UCP profile by namespace and agent_id.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| namespace | No | Public profile namespace for hosted UCP profiles. Usually 'openclaw'; use lowercase letters, numbers, underscores, or hyphens. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True for successful tool execution; false for structured tool errors. |
| error | No | Structured tool error. |
| message | Yes | Human-readable result summary or recovery message. |
| profile | No | Hosted public UCP profile JSON. Contains only public key material; private keys must stay local. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds the constraint that the profile must be 'registered', which is useful context but does not significantly expand on behavioral traits.
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 9-word sentence that front-loads the verb and resource. Every word earns its place, with no wasted text. It is optimally concise for a simple retrieval tool.
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 only 2 parameters with strong schema descriptions and an output schema, the description is sufficient for a simple fetch operation. It covers the core purpose, though it does not mention handling of non-existent profiles or default behavior for optional namespace.
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 input schema has 100% coverage with descriptions for both parameters. The tool description does not add new meaning beyond what is already in the schema, merely restating that it fetches by namespace and agent_id. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'fetch' and the resource 'one registered UCP profile' by the criteria 'namespace and agent_id'. It distinguishes itself from sibling tools like register_ucp_profile (which is for creating) and shopping tools (different domain).
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 this tool is for retrieving a specific profile when you have the agent_id and optionally namespace. It does not explicitly state when to avoid it or mention alternatives, but the purpose is clear enough for an agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a public hosted UCP agent profile and receive agent_id/profile_url. Default path: send agent_name plus public_key_jwk and the gateway builds the canonical UCP profile with default Shopping capabilities. Re-registering the same public_key_jwk in the same namespace is idempotent and returns the existing agent_id. Do not build a capability map for normal registration. Create local ./.ucpgateway/ files; keep private_key.jwk local and save returned agent_id/profile_url/profile_json to ./.ucpgateway/agent.json.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | No | Optional public metadata for the generated profile, such as homepage or runtime. Do not include secrets, tokens, passwords, payment data, private keys, or buyer PII; server-owned fields are overwritten. | |
| namespace | No | Public profile namespace for hosted UCP profiles. Usually 'openclaw'; use lowercase letters, numbers, underscores, or hyphens. | |
| agent_name | Yes | Human-readable public agent name, max 120 characters. | |
| skill_name | No | Optional public skill/package name, e.g. 'ucp-gateway-skill'. | |
| description | No | Optional public agent description, max 500 characters. | |
| profile_json | No | Advanced/legacy only. Public UCP profile JSON for callers that already know the full UCP profile format. Normal SKILL.md-only agents should omit profile_json and send public_key_jwk instead; the gateway builds default Shopping capabilities. If supplied, profile_json must contain ucp.version, ucp.capabilities using exact supported keys (dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, dev.ucp.shopping.catalog, dev.ucp.shopping.cart, dev.ucp.shopping.checkout), ucp.payment_handlers, and only public signing_keys. 'shopping' and 'dev.ucp.shopping' are invalid shorthand. Never include private JWK fields d, p, q, dp, dq, qi, or k. | |
| skill_version | No | Optional public skill/package version, e.g. '0.2.0'. | |
| public_key_jwk | No | Default registration public key. Send an EC P-256 public JWK object (kty='EC', crv='P-256', x, y, optional kid/alg/use). Never include private JWK fields d, p, q, dp, dq, qi, or k; keep private_key.jwk local. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True for successful tool execution; false for structured tool errors. |
| error | No | Structured tool error. |
| created | No | True when a new profile row was created; false when an existing active profile was reused for this namespace and public key fingerprint. |
| message | Yes | Human-readable result summary or recovery message. |
| profile | No | Hosted public UCP profile JSON. Contains only public key material; private keys must stay local. |
| agent_id | No | Registered UCP Gateway UUID. Save it to ./.ucpgateway/agent.json and include it in every Shopping tool call. |
| namespace | No | Public profile namespace for hosted UCP profiles. Usually 'openclaw'; use lowercase letters, numbers, underscores, or hyphens. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| profile_url | No | Hosted public UCP profile JSON URL for this agent. |
| profile_json | No | Hosted public UCP profile JSON. Contains only public key material; private keys must stay local. |
| registry_url | No | Public registry page URL. |
| gateway_mcp_url | No | Canonical UCP Gateway MCP endpoint URL to save in ./.ucpgateway/agent.json. |
| existing_profile | No | True when registration was idempotent and returned an existing active profile without creating a new row. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the annotations: idempotency on re-registration, creation of local files (.ucpgateway/), and privacy warnings (keep private_key.jwk local). It also explains the two registration paths with different requirements. There is no contradiction with annotations (readOnlyHint=false, destructiveHint=false).
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 (four sentences) and front-loaded with the core purpose. However, it could be improved by breaking the two registration modes into separate sections for clarity. The current block format is dense but still efficient.
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 complexity (8 params, nested objects, two registration modes), the description covers outcomes (returns agent_id/profile_url), file handling, idempotency, and security. An output schema exists, so return value details are structured elsewhere. The description provides sufficient context 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?
The input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the relationship between parameters (e.g., oneOf for public_key_jwk vs profile_json) and reinforcing security guidance (never include private JWK fields). This integration of schema and description enhances understanding.
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: 'Register a public hosted UCP agent profile and receive agent_id/profile_url.' It specifies two registration modes (default and advanced/legacy) and distinguishes itself from sibling tools like get_ucp_profile by focusing on creation rather than retrieval.
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 usage guidance such as 'Do not build a capability map for normal registration' and notes idempotency for re-registration. However, it does not explicitly compare with sibling tools or state when not to use this tool, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a merchant cart using an idempotency key.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | Provider cart ID to cancel. | |
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| idempotency_key | No | Optional UUID idempotency key for the cancel request; reuse only for retrying the same cancellation. | |
| 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. |
| 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. |
| cart | No | Safe provider cart summary including id, status, continue_url, totals, line_items, and messages when provided. |
| error | No | Structured tool error. |
| message | Yes | Human-readable result summary or recovery message. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| merchant_domain | No | Resolved merchant domain. |
| commerce_session_id | No | Internal gateway commerce session UUID when one was created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'cancel', implying a destructive action, but annotations set destructiveHint=false, creating a contradiction. Additionally, no details about side effects or error scenarios are provided.
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, front-loaded sentence that conveys the core action efficiently. However, it could be slightly more detailed without becoming verbose.
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 output schema exists, return values are not required. However, the description omits prerequisites (e.g., cart must exist) and error cases, making it minimally adequate.
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 description highlights the idempotency key, which is already documented. The description adds minimal extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (cancel), the resource (merchant cart), and a key detail (idempotency key). It differentiates from siblings like shopping_cart_create/get/update and shopping_checkout_cancel.
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 use for canceling a cart but does not explicitly state when to use vs. alternatives (e.g., shopping_checkout_cancel) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a merchant cart after the buyer/operator confirms selected variants.
| Name | Required | Description | Default |
|---|---|---|---|
| buyer | No | Optional buyer contact summary for cart creation; never include payment data. | |
| context | No | Optional buyer/search context for catalog, cart, or checkout tools. | |
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| line_items | Yes | 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. |
| 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. |
| cart | No | Safe provider cart summary including id, status, continue_url, totals, line_items, and messages when provided. |
| error | No | Structured tool error. |
| message | Yes | Human-readable result summary or recovery message. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| merchant_domain | No | Resolved merchant domain. |
| commerce_session_id | No | Internal gateway commerce session UUID when one was created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description consistently labels the operation as 'create'. The description adds the behavioral context of requiring confirmation but does not disclose other traits like idempotency, rate limits, or side effects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the essential purpose and condition. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (six parameters, nested objects, output schema), the description is minimal. It adequately covers the core action but lacks mention of prerequisites (e.g., UCP profile registration) or failure conditions. However, with full schema coverage and annotations, it is sufficient for an AI agent.
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 baseline is 3. The overall description does not provide additional parameter-specific meaning beyond what is already in the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and resource 'merchant cart'. It distinguishes from sibling cart tools by specifying the condition 'after the buyer/operator confirms selected variants', implying this is for initial creation, not updates or cancellations.
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 clear guidance on when to use the tool ('after the buyer/operator confirms selected variants'), but does not explicitly state when not to use it or mention alternative tools like shopping_cart_update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh a merchant cart state.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | Provider cart ID returned by shopping_cart_create or shopping_cart_update. | |
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| 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. |
| 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. |
| cart | No | Safe provider cart summary including id, status, continue_url, totals, line_items, and messages when provided. |
| error | No | Structured tool error. |
| message | Yes | Human-readable result summary or recovery message. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| merchant_domain | No | Resolved merchant domain. |
| commerce_session_id | No | Internal gateway commerce session UUID when one was created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds no additional behavioral traits beyond what annotations provide, such as side effects or auth requirements, but does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, efficiently stating the tool's function. It is front-loaded with the verb 'refresh'. While it could be slightly more informative about the return value, it is appropriately sized for a simple read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the existence of an output schema, and the annotations, the description is fairly complete. It does not explain the return value, but the output schema covers that. The description could mention that it requires a valid cart_id, but that is in the 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 parameters are fully documented in the schema. The description does not add any extra meaning or context beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'refresh' to imply retrieving current state, which aligns with the tool name 'get'. It mentions 'merchant cart state' clearly. However, it does not explicitly differentiate from sibling tools like shopping_cart_update or shopping_cart_cancel, but the verb 'refresh' hints at a read-only operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context for use, or scenarios where other shopping cart tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a merchant cart with the full desired cart state.
| Name | Required | Description | Default |
|---|---|---|---|
| cart | Yes | Full replacement cart state. Include the complete desired line_items list, not a patch. | |
| cart_id | Yes | Provider cart ID returned by cart tools. | |
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| 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. |
| 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. |
| cart | No | Safe provider cart summary including id, status, continue_url, totals, line_items, and messages when provided. |
| error | No | Structured tool error. |
| message | Yes | Human-readable result summary or recovery message. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| merchant_domain | No | Resolved merchant domain. |
| commerce_session_id | No | Internal gateway commerce session UUID when one was created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false. The description says 'Replace,' implying mutation, but does not add behavioral details beyond annotations (e.g., permissions, reversibility). No contradiction found.
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 concise sentence, front-loaded with the key action, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, nested objects) and existing output schema, the description is minimal. It covers the core functionality but omits higher-level context like error handling or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema; it only restates the replacement intent.
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 'Replace a merchant cart with the full desired cart state,' specifying a concrete verb and resource, and distinguishes from siblings like shopping_cart_create and shopping_cart_cancel.
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 no explicit guidance on when to use this tool versus alternatives (e.g., shopping_cart_create or shopping_checkout_update). It lacks when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel an active merchant checkout using an idempotency key.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| checkout_id | Yes | Provider checkout ID to cancel. | |
| idempotency_key | No | Optional UUID idempotency key for the cancel request; reuse only for retrying the same cancellation. | |
| 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. |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false and destructiveHint=false. The description says 'cancel', which implies state change, but does not explain side effects, idempotency behavior beyond the key, or what happens if already cancelled. With annotations present, the description adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every word adds essential meaning.
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 has an output schema, so return values are covered. However, the description lacks details about prerequisites (e.g., checkout must be active), idempotency behavior, and what constitutes success/failure. It is minimally adequate but not comprehensive.
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 parameters. The description only adds 'using an idempotency key', hinting at that parameter but not adding significant meaning beyond 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 clearly states the tool cancels an active merchant checkout using an idempotency key. It uses a specific verb and resource, and the context distinguishes it from checkout create/get/update 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?
The description mentions using an idempotency key but does not explicitly state when to use this tool versus alternatives like shopping_cart_cancel or how to ensure the checkout is active. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| 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. |
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.
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.
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.
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.
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.
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.
Refresh merchant checkout state.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| checkout_id | Yes | Provider checkout ID returned by shopping_checkout_create or shopping_checkout_update. | |
| 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. |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. The description adds the term 'Refresh,' which implies re-fetching, but adds little 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?
The description is a single, short phrase that is front-loaded with the key action. While very brief, it is not wasteful, though it could be slightly more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with good annotations and full schema coverage, the description is minimally adequate. It does not explain the output or any additional behavior, but an output schema exists to cover return values.
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 all three parameters have clear descriptions. The description does not add any additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Refresh' and resource 'checkout state,' clearly indicating it retrieves checkout state. It distinguishes from sibling operations like create, update, and cancel by being a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., shopping_checkout_update, shopping_checkout_cancel). The description does not specify context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| 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. |
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.
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.
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.
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.
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.
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.
Get product details by provider product or variant ID.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. | |
| selected | No | Optional selected variant option pairs to resolve a product variant. | |
| product_id | Yes | Provider product ID or variant ID returned by shopping_product_search. The current adapter returns Shopify GIDs. | |
| merchant_domain | No | Merchant host such as 'outboundpower.com' or 'example.myshopify.com'. Do not include a URL scheme, localhost, private IP, file URL, or ftp URL. |
| 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. |
| offers | No | Offers or variants returned by the provider when available. |
| message | Yes | Human-readable result summary or recovery message. |
| product | No | Normalized provider product record. Shape may vary by provider endpoint. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
| merchant_domain | No | Resolved merchant domain when available. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds no extra behavioral context (e.g., error handling, auth needs, rate limits). It merely restates the read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no wasted words. While concise, it could include slight guidance on parameter usage without becoming verbose.
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, the description lacks context on how parameters interact (e.g., when to use variant ID vs product ID, or the role of selected). It is insufficient for an agent to use correctly without additional knowledge.
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 description adds minimal extra meaning beyond the schema. It mentions 'by provider product or variant ID' but doesn't clarify the relationship between product_id and selected or the format of merchant_domain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and resource (product details) with the key identifier (provider product or variant ID). It effectively distinguishes from siblings like shopping_product_search.
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 you have a product or variant ID but provides no explicit guidance on when to use this tool versus alternatives like shopping_product_search, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the product catalog through The Agent Times UCP Gateway.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum products to return; integer from 1 to 10. | |
| query | Yes | Natural-language product search query, e.g. 'portable battery powered air conditioner'. | |
| cursor | No | Pagination cursor returned by a previous search response; omit for the first page. | |
| context | No | Optional buyer/search context for catalog, cart, or checkout tools. | |
| filters | No | Optional product search filters. | |
| agent_id | Yes | Registered UCP Gateway UUID returned by register_ucp_profile; required for every Shopping tool. |
| 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. |
| products | No | Normalized provider products returned by search. |
| warnings | No | Non-fatal search warnings. |
| next_step | Yes | Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and destructiveHint=false, establishing safe read operation. Description adds no further behavioral context (e.g., pagination, performance, or response structure). Adequate given annotation coverage.
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?
One concise sentence, though it includes the gateway context which may be unnecessary for the agent. Front-loaded with action and resource. No wasted words.
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?
Complex tool with 6 parameters, nested objects, and an output schema. Description is brief and does not explain usage patterns, filtering guidance, or return value semantics. However, output schema exists and schema covers all parameters, so baseline completeness is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The tool description adds no additional parameter meaning beyond what the schema already provides. 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?
Clearly states verb 'Search' and resource 'product catalog' with context 'through The Agent Times UCP Gateway'. Distinguishes from siblings like shopping_product_get (single product) and shopping_cart_* (cart management).
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 on when to use this vs. alternatives. The name implies search, but no mention of when not to use (e.g., for fetching a single product, use shopping_product_get). Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
shopping_checkout_cancel3 fields changedOutput schema / properties / partial_successAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / requires_escalationAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / upstream_is_errorAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}shopping_checkout_create4 fields changedInput schema / properties / buyer / properties / phone_numberAdded value: +{
+ "description": "Canonical buyer phone alias. Prefer E.164. Equivalent to `phone`; if both are set, phone_number wins.",
+ "type": "string"
+}Output schema / properties / partial_successAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / requires_escalationAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / upstream_is_errorAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}shopping_checkout_get3 fields changedOutput schema / properties / partial_successAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / requires_escalationAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / upstream_is_errorAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}shopping_checkout_update7 fields changedInput schema / descriptionPrevious value: -"Arguments for updating a checkout."New value: +"Arguments for updating a checkout. Provide checkout and/or buyer."Input schema / properties / buyerAdded value: +{
+ "additionalProperties": false,
+ "description": "Buyer-provided checkout contact and shipping details. Never invent PII; omit phone if unavailable.",
+ "properties": {
+ "address_country": {
+ "description": "ISO 3166-1 alpha-2 country code. Use 'US', not 'USA'.",
+ "type": "string"
+ },
+ "address_locality": {
+ "description": "Buyer-provided shipping city/locality.",
+ "type": "string"
+ },
+ "address_region": {
+ "description": "Buyer-provided shipping state/province/region.",
+ "type": "string"
+ },
+ "email": {
+ "description": "Buyer email for merchant checkout contact and order confirmation.",
+ "type": "string"
+ },
+ "first_name": {
+ "description": "Buyer-provided shipping first name.",
+ "type": "string"
+ },
+ "last_name": {
+ "description": "Buyer-provided shipping last name.",
+ "type": "string"
+ },
+ "phone": {
+ "description": "Buyer phone. Prefer E.164, e.g. +15555550100. Non-E.164 values are accepted but may be dropped before reaching the provider and will surface a non-fatal warning.",
+ "type": "string"
+ },
+ "phone_number": {
+ "description": "Canonical buyer phone alias. Prefer E.164. Equivalent to `phone`; if both are set, phone_number wins.",
+ "type": "string"
+ },
+ "postal_code": {
+ "description": "Buyer-provided shipping postal code.",
+ "type": "string"
+ },
+ "street_address": {
+ "description": "Buyer-provided shipping street address.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "email",
+ "first_name",
+ "last_name",
+ "street_address",
+ "address_locality",
+ "address_region",
+ "postal_code",
+ "address_country"
+ ],
+ "type": "object"
+}Input schema / properties / checkout / descriptionPrevious value: -"Full checkout replacement payload accepted by the provider. Use sparingly; prefer E.164 phone and ISO-2 destination country; never include payment credentials."New value: +"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."Input schema / requiredPrevious value: -[
- "agent_id",
- "merchant_domain",
- "checkout_id",
- "checkout"
-]New value: +[
+ "agent_id",
+ "merchant_domain",
+ "checkout_id"
+]Output schema / properties / partial_successAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / requires_escalationAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}Output schema / properties / upstream_is_errorAdded value: +{
+ "description": "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.",
+ "type": "boolean"
+}shopping_product_search1 field changedInput schema / properties / limit / defaultAdded value: +5register_ucp_profile1 field changedOutput schema / properties / gateway_mcp_urlAdded value: +{
+ "description": "Canonical UCP Gateway MCP endpoint URL to save in ./.ucpgateway/agent.json.",
+ "type": "string"
+}register_ucp_profile10 fields changedInput schema / descriptionPrevious value: -"Arguments for registering a hosted UCP profile."New value: +"Arguments for registering a hosted UCP profile. Provide public_key_jwk for default registration, or profile_json for advanced legacy registration, but not both."Input schema / oneOfAdded value: +[
+ {
+ "description": "Default registration: agent_name + public_key_jwk; the gateway builds the canonical UCP profile and default Shopping capabilities.",
+ "required": [
+ "public_key_jwk"
+ ]
+ },
+ {
+ "description": "Advanced/legacy registration: agent_name + a full public UCP profile_json with exact supported capability keys.",
+ "required": [
+ "profile_json"
+ ]
+ }
+]Input schema / properties / metadataAdded value: +{
+ "additionalProperties": true,
+ "description": "Optional public metadata for the generated profile, such as homepage or runtime. Do not include secrets, tokens, passwords, payment data, private keys, or buyer PII; server-owned fields are overwritten.",
+ "properties": {},
+ "required": [],
+ "type": "object"
+}Input schema / properties / profile_json / descriptionPrevious value: -"Public UCP profile JSON. Must contain ucp.version, supported ucp.capabilities, and only public signing_keys; never include private JWK fields."New value: +"Advanced/legacy only. Public UCP profile JSON for callers that already know the full UCP profile format. Normal SKILL.md-only agents should omit profile_json and send public_key_jwk instead; the gateway builds default Shopping capabilities. If supplied, profile_json must contain ucp.version, ucp.capabilities using exact supported keys (dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, dev.ucp.shopping.catalog, dev.ucp.shopping.cart, dev.ucp.shopping.checkout), ucp.payment_handlers, and only public signing_keys. 'shopping' and 'dev.ucp.shopping' are invalid shorthand. Never include private JWK fields d, p, q, dp, dq, qi, or k."Input schema / properties / public_key_jwkAdded value: +{
+ "additionalProperties": true,
+ "description": "Default registration public key. Send an EC P-256 public JWK object (kty='EC', crv='P-256', x, y, optional kid/alg/use). Never include private JWK fields d, p, q, dp, dq, qi, or k; keep private_key.jwk local.",
+ "properties": {},
+ "required": [],
+ "type": "object"
+}Input schema / properties / skill_version / descriptionPrevious value: -"Optional public skill/package version, e.g. '0.1.0'."New value: +"Optional public skill/package version, e.g. '0.2.0'."Input schema / requiredPrevious value: -[
- "agent_name",
- "profile_json"
-]New value: +[
+ "agent_name"
+]Output schema / properties / agent_id / descriptionPrevious value: -"Registered UCP Gateway UUID. Save it and include it in every Shopping tool call."New value: +"Registered UCP Gateway UUID. Save it to ./.ucpgateway/agent.json and include it in every Shopping tool call."Output schema / properties / createdAdded value: +{
+ "description": "True when a new profile row was created; false when an existing active profile was reused for this namespace and public key fingerprint.",
+ "type": "boolean"
+}Output schema / properties / existing_profileAdded value: +{
+ "description": "True when registration was idempotent and returned an existing active profile without creating a new row.",
+ "type": "boolean"
+}get_ucp_profileregister_ucp_profileshopping_cart_cancelshopping_cart_createshopping_cart_getshopping_cart_updateshopping_checkout_cancelshopping_checkout_createshopping_checkout_getshopping_checkout_updateshopping_product_getshopping_product_search
Add one secure layer between your agents and this server.