Trusteed Agentic Commerce

ucp_create_checkout

Idempotent

Create a UCP (Universal Commerce Protocol) checkout session from line items. Returns a UCP checkout object with status 'incomplete'. Starts the UCP flow (ucp_* tools); for the standard flow use create_cart instead. Do not mix the two flows on the same purchase. Checkout guide: read the MCP resource trusteed://guides/checkout.

Input Schema

Name	Required	Description
`meta`	No	UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters).
`label`	No	Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)
`intent`	No	Intent context for relevance and personalization
`currency`	Yes	ISO 4217 currency code (e.g. USD)
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`line_items`	Yes	Line items for the checkout
`idempotency_key`	No	REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta["trusteed/idempotency-key"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 17, 2026

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": true,
-  "properties": {
-    "approval_url": {
-      "type": "string"
-    },
-    "created_at": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "expires_at": {
-      "description": "ISO-8601 UTC instant at which this checkout SESSION stops being usable. It is not a stock reservation and not a price guarantee.",
-      "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"
-    },
-    "extensions": {
-      "additionalProperties": {},
-      "description": "`warnings[]` with `code`, `message`, `severity`.",
-      "type": "object"
-    },
-    "fulfillment": {
-      "additionalProperties": {},
-      "type": "object"
-    },
-    "id": {
-      "type": "string"
-    },
-    "idempotency_key": {
-      "type": "string"
-    },
-    "intent": {
-      "additionalProperties": {},
-      "type": "object"
-    },
-    "label": {
-      "type": "string"
-    },
-    "line_items": {
-      "items": {
-        "additionalProperties": true,
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "price": {
-            "additionalProperties": true,
-            "properties": {
-              "amount": {
-                "type": "number"
-              },
-              "currency": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "amount",
-              "currency"
-            ],
-            "type": "object"
-          },
-          "product_id": {
-            "type": "string"
-          },
-          "quantity": {
-            "type": "number"
-          },
-          "title": {
-            "type": "string"
-          },
-          "variant_id": {
-            "type": "string"
-          },
-          "variant_title": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "product_id",
-          "title",
-          "quantity",
-          "price"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "next_action": {
-      "additionalProperties": {},
-      "description": "Only when a person must approve or pay: `url`, `kind`, `retry`.",
-      "type": "object"
-    },
-    "next_step": {
-      "description": "Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, preview_ucp_checkout, review_not_available_in_ucp.",
-      "type": "string"
-    },
-    "next_step_message": {
-      "type": "string"
-    },
-    "payment_options": {
-      "description": "When present, ask the person which option they want; never choose for them.",
-      "items": {
-        "additionalProperties": {},
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "status": {
-      "enum": [
-        "incomplete",
-        "requires_escalation",
-        "ready_for_complete",
-        "complete_in_progress",
-        "completed",
-        "canceled"
-      ],
-      "type": "string"
-    },
-    "totals": {
-      "items": {
-        "additionalProperties": true,
-        "properties": {
-          "amount": {
-            "type": "number"
-          },
-          "currency": {
-            "type": "string"
-          },
-          "label": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "label",
-          "amount",
-          "currency"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "updated_at": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id",
-    "status",
-    "currency",
-    "line_items",
-    "totals",
-    "created_at",
-    "updated_at"
-  ],
-  "type": "object"
-}New value: +null

Changed1 schema field changedOct 16, 2026

changedOutput schema / properties / next_step / description

Previous value: -"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, review_not_available_in_ucp."New value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, preview_ucp_checkout, review_not_available_in_ucp."

Changed1 schema field changedOct 16, 2026

changedOutput schema / properties / next_step / description

Previous value: -"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method."New value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, review_not_available_in_ucp."

Changed4 schema fields changedOct 15, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Required by the checkout bucket (UUID-v4 or bounded ASCII token). Choose one per purchase attempt and reuse it to retry safely. Alternatively send it as the Idempotency-Key header or params._meta[\"trusteed/idempotency-key\"]."New value: +"REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."

addedInput schema / properties / idempotency_key / maxLength
```
Added value: +128
```
addedInput schema / properties / idempotency_key / pattern
```
Added value: +"^[A-Za-z0-9._:/-]{1,128}$"
```

addedOutput schema / properties / next_step / description

Added value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method."

Changed17 schema fields changedOct 14, 2026

changedOutput schema / properties / extensions / additionalProperties
```
Previous value: -trueNew value: +{}
```

addedOutput schema / properties / extensions / description

Added value: +"`warnings[]` with `code`, `message`, `severity`."

removedOutput schema / properties / extensions / properties

Removed value: -{
-  "warnings": {
-    "items": {
-      "additionalProperties": true,
-      "properties": {
-        "code": {
-          "type": "string"
-        },
-        "disclosure_url": {
-          "type": "string"
-        },
-        "message": {
-          "type": "string"
-        },
-        "severity": {
-          "enum": [
-            "info",
-            "caution",
-            "critical"
-          ],
-          "type": "string"
-        }
-      },
-      "required": [
-        "code",
-        "message",
-        "severity"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  }
-}

changedOutput schema / properties / fulfillment / additionalProperties
```
Previous value: -trueNew value: +{}
```

removedOutput schema / properties / fulfillment / properties

Removed value: -{
-  "destination": {
-    "additionalProperties": true,
-    "properties": {
-      "city": {
-        "type": "string"
-      },
-      "country_code": {
-        "type": "string"
-      },
-      "province_code": {
-        "type": "string"
-      },
-      "zip": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "city",
-      "country_code",
-      "zip"
-    ],
-    "type": "object"
-  },
-  "options": {
-    "items": {
-      "additionalProperties": true,
-      "properties": {
-        "authoritative": {
-          "type": "boolean"
-        },
-        "estimated_delivery": {
-          "type": "string"
-        },
-        "id": {
-          "type": "string"
-        },
-        "price": {
-          "additionalProperties": true,
-          "properties": {
-            "amount": {
-              "type": "number"
-            },
-            "currency": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "amount",
-            "currency"
-          ],
-          "type": "object"
-        },
-        "source": {
-          "enum": [
-            "platform",
-            "merchant_policy",
-            "estimated"
-          ],
-          "type": "string"
-        },
-        "title": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "id",
-        "title",
-        "price",
-        "source",
-        "authoritative"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "selected_option_id": {
-    "type": "string"
-  }
-}

changedOutput schema / properties / intent / additionalProperties
```
Previous value: -trueNew value: +{}
```

removedOutput schema / properties / intent / properties

Removed value: -{
-  "action": {
-    "type": "string"
-  },
-  "context": {
-    "type": "string"
-  },
-  "locale": {
-    "type": "string"
-  }
-}

removedOutput schema / properties / intent / required
```
Removed value: -[
-  "action"
-]
```
changedOutput schema / properties / next_action / additionalProperties
```
Previous value: -trueNew value: +{}
```

addedOutput schema / properties / next_action / description

Added value: +"Only when a person must approve or pay: `url`, `kind`, `retry`."

removedOutput schema / properties / next_action / properties

Removed value: -{
-  "actor": {
-    "const": "buyer",
-    "type": "string"
-  },
-  "do": {
-    "enum": [
-      "approve",
-      "pay"
-    ],
-    "type": "string"
-  },
-  "instruction": {
-    "type": "string"
-  },
-  "reuse_arguments": {
-    "items": {
-      "enum": [
-        "checkout_session_id",
-        "checkout_id",
-        "idempotency_key"
-      ],
-      "type": "string"
-    },
-    "type": "array"
-  },
-  "then_call": {
-    "maxLength": 64,
-    "minLength": 1,
-    "type": "string"
-  },
-  "url": {
-    "type": "string"
-  }
-}

removedOutput schema / properties / next_action / required

Removed value: -[
-  "actor",
-  "do",
-  "url",
-  "instruction"
-]

removedOutput schema / properties / next_step / const
```
Removed value: -"ask_user_payment_method"
```

addedOutput schema / properties / payment_options / description

Added value: +"When present, ask the person which option they want; never choose for them."

changedOutput schema / properties / payment_options / items / additionalProperties
```
Previous value: -trueNew value: +{}
```

removedOutput schema / properties / payment_options / items / properties

Removed value: -{
-  "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"
-  }
-}

removedOutput schema / properties / payment_options / items / required

Removed value: -[
-  "id",
-  "label",
-  "rail",
-  "funding_source",
-  "available"
-]

Changed1 schema field changedOct 13, 2026
- addedOutput schema / properties / payment_options / items / properties / charges_without_approval
```
Added value: +{
+  "const": true,
+  "type": "boolean"
+}
```

Changed3 schema fields changedOct 13, 2026

changedOutput schema / properties / payment_options / items / properties / id / enum

Previous value: -[
-  "demo_card",
-  "demo_wallet",
-  "own_wallet",
-  "merchant_card",
-  "kyapay"
-]New value: +[
+  "demo_card",
+  "demo_wallet",
+  "own_wallet",
+  "merchant_card",
+  "paypal",
+  "kyapay"
+]

changedOutput schema / properties / payment_options / items / properties / rail / enum

Previous value: -[
-  "stripe",
-  "x402",
-  "kyapay"
-]New value: +[
+  "stripe",
+  "x402",
+  "kyapay",
+  "paypal"
+]

changedOutput schema / properties / payment_options / items / properties / reason_unavailable / enum

Previous value: -[
-  "coming_soon",
-  "not_enabled",
-  "currency_not_supported"
-]New value: +[
+  "coming_soon",
+  "not_enabled",
+  "currency_not_supported",
+  "unsupported_on_this_tool"
+]

Changed1 schema field changedOct 11, 2026

addedInput schema / properties / meta

Added value: +{
+  "description": "UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters)."
+}

Changed2 schema fields changedOct 10, 2026

addedOutput schema / properties / expires_at

Added value: +{
+  "description": "ISO-8601 UTC instant at which this checkout SESSION stops being usable. It is not a stock reservation and not a price guarantee.",
+  "type": "string"
+}

addedOutput schema / properties / expires_in_seconds

Added value: +{
+  "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"
+}

Changed1 schema field changedOct 10, 2026

changedOutput schema / properties / payment_options / items / properties / reason_unavailable / enum

Previous value: -[
-  "coming_soon",
-  "not_enabled"
-]New value: +[
+  "coming_soon",
+  "not_enabled",
+  "currency_not_supported"
+]

Changed1 schema field changedOct 5, 2026

changedOutput schema / properties / payment_options / items / properties / id / enum

Previous value: -[
-  "demo_card",
-  "demo_wallet",
-  "own_wallet",
-  "kyapay"
-]New value: +[
+  "demo_card",
+  "demo_wallet",
+  "own_wallet",
+  "merchant_card",
+  "kyapay"
+]

Changed5 schema fields changedOct 1, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Required by the checkout bucket (UUID-v4 or bounded ASCII token). Choose one per purchase attempt and reuse it to retry safely. Alternatively send it as the Idempotency-Key header or params._meta[\"trusteed/idempotency-key\"].",
+  "type": "string"
+}

addedInput schema / properties / line_items / items / properties / variant_id

Added value: +{
+  "description": "Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply.",
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / fulfillment

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "destination": {
+      "additionalProperties": true,
+      "properties": {
+        "city": {
+          "type": "string"
+        },
+        "country_code": {
+          "type": "string"
+        },
+        "province_code": {
+          "type": "string"
+        },
+        "zip": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "city",
+        "country_code",
+        "zip"
+      ],
+      "type": "object"
+    },
+    "options": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "authoritative": {
+            "type": "boolean"
+          },
+          "estimated_delivery": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "price": {
+            "additionalProperties": true,
+            "properties": {
+              "amount": {
+                "type": "number"
+              },
+              "currency": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "amount",
+              "currency"
+            ],
+            "type": "object"
+          },
+          "source": {
+            "enum": [
+              "platform",
+              "merchant_policy",
+              "estimated"
+            ],
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "price",
+          "source",
+          "authoritative"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "selected_option_id": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / line_items / items / properties / variant_id
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / line_items / items / properties / variant_title
```
Added value: +{
+  "type": "string"
+}
```

Changed3 schema fields changedSep 28, 2026

addedOutput schema / properties / next_step

Added value: +{
+  "const": "ask_user_payment_method",
+  "type": "string"
+}

addedOutput schema / properties / next_step_message
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / payment_options

Added value: +{
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "available": {
+        "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",
+          "kyapay"
+        ],
+        "type": "string"
+      },
+      "label": {
+        "type": "string"
+      },
+      "rail": {
+        "enum": [
+          "stripe",
+          "x402",
+          "kyapay"
+        ],
+        "type": "string"
+      },
+      "reason_unavailable": {
+        "enum": [
+          "coming_soon",
+          "not_enabled"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "label",
+      "rail",
+      "funding_source",
+      "available"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed2 schema fields changedSep 27, 2026

addedOutput schema / properties / approval_url
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / next_action

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "actor": {
+      "const": "buyer",
+      "type": "string"
+    },
+    "do": {
+      "enum": [
+        "approve",
+        "pay"
+      ],
+      "type": "string"
+    },
+    "instruction": {
+      "type": "string"
+    },
+    "reuse_arguments": {
+      "items": {
+        "enum": [
+          "checkout_session_id",
+          "checkout_id",
+          "idempotency_key"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "then_call": {
+      "maxLength": 64,
+      "minLength": 1,
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "actor",
+    "do",
+    "url",
+    "instruction"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedSep 24, 2026

changedInput schema / properties / line_items / items / properties / price / properties / amount / description

Previous value: -"Price in smallest unit (cents)"New value: +"Ignored: the catalogue price is used and returned per line. Any non-negative integer is accepted."

changedInput schema / properties / line_items / items / properties / title / description

Previous value: -"Product title"New value: +"Ignored: the catalogue title is used. Any non-empty string is accepted."

Changed1 schema field changedSep 22, 2026

removedInput schema / properties / payment_mandate

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": {},
-      "type": "object"
-    },
-    {
-      "type": "string"
-    }
-  ],
-  "description": "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` (your agent id) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). Use this when your client cannot set an `X-Payment-Mandate` header."
-}

Changed1 schema field changedSep 22, 2026

addedInput schema / properties / agent_key

Added value: +{
+  "description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.",
+  "type": "string"
+}

Changed1 schema field changedSep 21, 2026

changedInput schema / properties / payment_mandate / description

Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."New 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` (your agent id) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). Use this when your client cannot set an `X-Payment-Mandate` header."

Changed1 schema field changedSep 20, 2026

addedInput schema / properties / payment_mandate

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "type": "object"
+    },
+    {
+      "type": "string"
+    }
+  ],
+  "description": "Payment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."
+}

Changed10 schema fields changedSep 17, 2026
- changedInput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedInput schema / properties / intent / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedInput schema / properties / line_items / items / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / extensions / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / extensions / properties / warnings / items / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / intent / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / line_items / items / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / line_items / items / properties / price / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / totals / items / additionalProperties
```
Previous value: -falseNew value: +true
```
AddedSep 9, 2026
RemovedSep 1, 2026

Changed4 schema fields changedAug 24, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties

Added value: +{
+  "currency": {
+    "description": "ISO 4217 currency code (e.g. USD)",
+    "maxLength": 3,
+    "minLength": 3,
+    "type": "string"
+  },
+  "intent": {
+    "additionalProperties": false,
+    "description": "Intent context for relevance and personalization",
+    "properties": {
+      "action": {
+        "description": "Intent action (e.g. 'purchase', 'gift', 'compare')",
+        "type": "string"
+      },
+      "context": {
+        "description": "Natural language context for personalization",
+        "type": "string"
+      },
+      "locale": {
+        "description": "ISO locale",
+        "type": "string"
+      }
+    },
+    "required": [
+      "action"
+    ],
+    "type": "object"
+  },
+  "label": {
+    "description": "Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)",
+    "type": "string"
+  },
+  "line_items": {
+    "description": "Line items for the checkout",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "price": {
+          "additionalProperties": false,
+          "properties": {
+            "amount": {
+              "description": "Price in smallest unit (cents)",
+              "minimum": 0,
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217 currency code",
+              "maxLength": 3,
+              "minLength": 3,
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        },
+        "product_id": {
+          "description": "Product identifier",
+          "minLength": 1,
+          "type": "string"
+        },
+        "quantity": {
+          "description": "Quantity",
+          "exclusiveMinimum": 0,
+          "type": "integer"
+        },
+        "title": {
+          "description": "Product title",
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "product_id",
+        "title",
+        "quantity",
+        "price"
+      ],
+      "type": "object"
+    },
+    "minItems": 1,
+    "type": "array"
+  }
+}

addedInput schema / required

Added value: +[
+  "currency",
+  "line_items"
+]

Changed5 schema fields changedJul 10, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedInput schema / additionalProperties
```
Removed value: -false
```

removedInput schema / properties

Removed value: -{
-  "currency": {
-    "description": "ISO 4217 currency code (e.g. USD)",
-    "maxLength": 3,
-    "minLength": 3,
-    "type": "string"
-  },
-  "intent": {
-    "additionalProperties": false,
-    "description": "Intent context for relevance and personalization",
-    "properties": {
-      "action": {
-        "description": "Intent action (e.g. 'purchase', 'gift', 'compare')",
-        "type": "string"
-      },
-      "context": {
-        "description": "Natural language context for personalization",
-        "type": "string"
-      },
-      "locale": {
-        "description": "ISO locale",
-        "type": "string"
-      }
-    },
-    "required": [
-      "action"
-    ],
-    "type": "object"
-  },
-  "label": {
-    "description": "Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)",
-    "type": "string"
-  },
-  "line_items": {
-    "description": "Line items for the checkout",
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "price": {
-          "additionalProperties": false,
-          "properties": {
-            "amount": {
-              "description": "Price in smallest unit (cents)",
-              "minimum": 0,
-              "type": "number"
-            },
-            "currency": {
-              "description": "ISO 4217 currency code",
-              "maxLength": 3,
-              "minLength": 3,
-              "type": "string"
-            }
-          },
-          "required": [
-            "amount",
-            "currency"
-          ],
-          "type": "object"
-        },
-        "product_id": {
-          "description": "Product identifier",
-          "minLength": 1,
-          "type": "string"
-        },
-        "quantity": {
-          "description": "Quantity",
-          "exclusiveMinimum": 0,
-          "type": "integer"
-        },
-        "title": {
-          "description": "Product title",
-          "minLength": 1,
-          "type": "string"
-        }
-      },
-      "required": [
-        "product_id",
-        "title",
-        "quantity",
-        "price"
-      ],
-      "type": "object"
-    },
-    "minItems": 1,
-    "type": "array"
-  }
-}

removedInput schema / required

Removed value: -[
-  "currency",
-  "line_items"
-]

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "created_at": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "extensions": {
-      "additionalProperties": false,
-      "properties": {
-        "warnings": {
-          "items": {
-            "additionalProperties": false,
-            "properties": {
-              "code": {
-                "type": "string"
-              },
-              "disclosure_url": {
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              },
-              "severity": {
-                "enum": [
-                  "info",
-                  "caution",
-                  "critical"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "code",
-              "message",
-              "severity"
-            ],
-            "type": "object"
-          },
-          "type": "array"
-        }
-      },
-      "type": "object"
-    },
-    "id": {
-      "type": "string"
-    },
-    "idempotency_key": {
-      "type": "string"
-    },
-    "intent": {
-      "additionalProperties": false,
-      "properties": {
-        "action": {
-          "type": "string"
-        },
-        "context": {
-          "type": "string"
-        },
-        "locale": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "action"
-      ],
-      "type": "object"
-    },
-    "label": {
-      "type": "string"
-    },
-    "line_items": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "price": {
-            "additionalProperties": false,
-            "properties": {
-              "amount": {
-                "type": "number"
-              },
-              "currency": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "amount",
-              "currency"
-            ],
-            "type": "object"
-          },
-          "product_id": {
-            "type": "string"
-          },
-          "quantity": {
-            "type": "number"
-          },
-          "title": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "product_id",
-          "title",
-          "quantity",
-          "price"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "status": {
-      "enum": [
-        "incomplete",
-        "requires_escalation",
-        "ready_for_complete",
-        "complete_in_progress",
-        "completed",
-        "canceled"
-      ],
-      "type": "string"
-    },
-    "totals": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "amount": {
-            "type": "number"
-          },
-          "currency": {
-            "type": "string"
-          },
-          "label": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "label",
-          "amount",
-          "currency"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "updated_at": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id",
-    "status",
-    "currency",
-    "line_items",
-    "totals",
-    "created_at",
-    "updated_at"
-  ],
-  "type": "object"
-}New value: +null

First observedApr 28, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the write/idempotency profile is covered. The description adds genuinely new behavioral context: the returned object has status 'incomplete' (i.e. this is only the first step of a multi-call flow) and that the UCP flow must not be interleaved with the cart flow. It does not describe failure modes or what invalidates the session.

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?

Five short sentences, each carrying a distinct fact (purpose, return state, flow routing, cross-flow warning, guide pointer) with the purpose front-loaded. Nothing is padded or repeated.

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 7-parameter nested-object write tool with no output schema, the description covers the essential flow context and the returned status. The only slight gap is next-step guidance (e.g. that ucp_complete_checkout finalizes the session), which the agent can infer from the sibling names.

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 every parameter — including the ignored price/title fields, the variant_id requirement, and the idempotency_key — is already documented in the schema. The description only gestures at 'line items' and adds no syntax or format detail beyond it, so baseline 3 applies.

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?

States a specific verb and resource ('Create a UCP checkout session from line items') and names the sibling it competes with ('for the standard flow use create_cart instead'). An agent can distinguish it from create_cart and the other ucp_* tools without opening a schema.

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?

Explicitly routes the agent: use this to start the UCP flow, use create_cart for the standard flow, and do not mix the two on the same purchase. It also points to the checkout guide resource for further context.

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 tools Inspect

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

Need Help?