Skip to main content
Glama

Trusteed Agentic Commerce

by xyz.trusteed
OverviewDiscussionsAdmin

ucp_preview_checkout

Preview a UCP checkout and move it to ready-for-payment. Call after destination and shipping are set, before ucp_complete_checkout. Use ONLY for a checkout created with ucp_create_checkout. Checkout guide: read the MCP resource trusteed://guides/checkout.

Input Schema

NameRequiredDescriptionDefault
metaNoUCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters).
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
checkout_idYesUCP checkout session ID (valid UUID)
payment_mandateNoPayment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / payment_mandate / anyOf
      Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {
-      "aud": {
-        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
-        "maxLength": 256,
-        "minLength": 1,
-        "type": "string"
-      },
-      "currency": {
-        "description": "Three-letter currency code; must match the cart's currency.",
-        "maxLength": 3,
-        "minLength": 3,
-        "type": "string"
-      },
-      "exp": {
-        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
-        "exclusiveMinimum": 0,
-        "type": "integer"
-      },
-      "mandate_id": {
-        "description": "Your identifier for this mandate.",
-        "maxLength": 128,
-        "minLength": 1,
-        "type": "string"
-      },
-      "max_amount_cents": {
-        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
-        "exclusiveMinimum": 0,
-        "type": "integer"
-      },
-      "sub": {
-        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
-        "maxLength": 256,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "mandate_id",
-      "max_amount_cents",
-      "currency",
-      "exp",
-      "sub",
-      "aud"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "string"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "type": "object"
+  },
+  {
+    "type": "string"
+  }
+]
    • changedInput schema / properties / payment_mandate / description
      Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header."
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": true,
-  "properties": {
-    "approval_id": {
-      "type": "string"
-    },
-    "approval_status_url": {
-      "type": "string"
-    },
-    "approval_url": {
-      "type": "string"
-    },
-    "checkout_session_id": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "discount_cents": {
-      "type": "number"
-    },
-    "expires_at": {
-      "type": "string"
-    },
-    "expires_in_seconds": {
-      "description": "Whole seconds left on this checkout SESSION at response time (0 when already past). It is not a stock reservation and not a price guarantee.",
-      "minimum": 0,
-      "type": "integer"
-    },
-    "items": {
-      "items": {
-        "additionalProperties": true,
-        "properties": {
-          "line_price": {
-            "type": "number"
-          },
-          "name": {
-            "type": "string"
-          },
-          "quantity": {
-            "type": "number"
-          }
-        },
-        "required": [
-          "name",
-          "quantity",
-          "line_price"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "next_step": {
-      "enum": [
-        "ask_user_payment_method",
-        "complete_ucp_checkout"
-      ],
-      "type": "string"
-    },
-    "next_step_message": {
-      "type": "string"
-    },
-    "payment_options": {
-      "items": {
-        "additionalProperties": true,
-        "properties": {
-          "available": {
-            "type": "boolean"
-          },
-          "charges_without_approval": {
-            "const": true,
-            "type": "boolean"
-          },
-          "funding_source": {
-            "anyOf": [
-              {
-                "enum": [
-                  "platform_test_card",
-                  "platform_test_wallet",
-                  "buyer_wallet"
-                ],
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "id": {
-            "enum": [
-              "demo_card",
-              "demo_wallet",
-              "own_wallet",
-              "merchant_card",
-              "paypal",
-              "kyapay"
-            ],
-            "type": "string"
-          },
-          "label": {
-            "type": "string"
-          },
-          "rail": {
-            "enum": [
-              "stripe",
-              "x402",
-              "kyapay",
-              "paypal"
-            ],
-            "type": "string"
-          },
-          "reason_unavailable": {
-            "enum": [
-              "coming_soon",
-              "not_enabled",
-              "currency_not_supported",
-              "unsupported_on_this_tool"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "label",
-          "rail",
-          "funding_source",
-          "available"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "shipping_authoritative": {
-      "type": "boolean"
-    },
-    "shipping_cents": {
-      "type": "number"
-    },
-    "shipping_source": {
-      "enum": [
-        "platform",
-        "merchant_policy",
-        "estimated"
-      ],
-      "type": "string"
-    },
-    "shipping_title": {
-      "type": "string"
-    },
-    "status": {
-      "enum": [
-        "READY_FOR_PAYMENT",
-        "PENDING_APPROVAL"
-      ],
-      "type": "string"
-    },
-    "store_name": {
-      "type": "string"
-    },
-    "subtotal_cents": {
-      "type": "number"
-    },
-    "tax_cents": {
-      "type": "number"
-    },
-    "tax_status": {
-      "enum": [
-        "included",
-        "not_calculated"
-      ],
-      "type": "string"
-    },
-    "total_cents": {
-      "type": "number"
-    },
-    "total_is_final": {
-      "type": "boolean"
-    },
-    "total_note": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "checkout_session_id",
-    "store_name",
-    "items",
-    "subtotal_cents",
-    "shipping_cents",
-    "discount_cents",
-    "total_cents",
-    "currency",
-    "tax_cents",
-    "tax_status",
-    "total_is_final",
-    "total_note",
-    "status"
-  ],
-  "type": "object"
-}New value: +null
  3. Changed2 schema fields changed
    • removedOutput schema / properties / next_step / const
      Removed value: -"complete_ucp_checkout"
    • addedOutput schema / properties / next_step / enum
      Added value: +[
+  "ask_user_payment_method",
+  "complete_ucp_checkout"
+]
  4. Added

TDQS

A4.2/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description is consistent with them by framing the call as a state transition. It adds sequencing and gating context ('after destination and shipping are set', 'before ucp_complete_checkout') that the annotations do not convey. It stops short of describing failure modes or what happens if the preconditions are unmet or the call is repeated.

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?

Three tight sentences: what it does first, then the preconditions and ordering, then the restriction and the pointer to the guide. No filler and nothing buried.

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?

For a non-idempotent checkout-state-transition tool with a fully described schema and no output schema, the description covers the step in the flow, its preconditions, and its exclusivity. It leaves the post-ready-for-payment state and the distinction from the non-prefixed preview_checkout sibling unstated, and there is no output schema to fill that in.

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 description coverage is 100%, so checkout_id and the client-header fallbacks (agent_key, payment_mandate, meta) are already documented in the schema. The description adds no parameter-level detail of its own, so the baseline 3 applies.

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

Purpose4/5

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

The description states a specific verb+resource (preview a UCP checkout) and adds the resulting state change (move it to ready-for-payment), which separates it from a pure read like ucp_get_checkout. It does not, however, explain how it differs from the similarly named sibling preview_checkout, leaving that ambiguity unresolved.

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

Usage Guidelines5/5

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

It gives explicit preconditions (destination and shipping must be set), an explicit ordering relationship (before ucp_complete_checkout), and an explicit scoping restriction (ONLY for a checkout created with ucp_create_checkout). It even routes the agent to a supplementary resource for deeper guidance.

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

All Trusteed Agentic Commerce toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources