Trusteed Agentic Commerce

ucp_update_checkout

Idempotent

Update a UCP checkout session. Send line_items to replace all lines (each line may name a variant_id), and/or fulfillment to set the delivery address (fulfillment.destination, which returns the shipping options) and choose one (fulfillment.selected_option_id, which adds shipping to the totals). Only allowed when status is 'incomplete'. Use ONLY for sessions created with ucp_create_checkout; for the standard flow use create_cart and select_shipping_option. 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).
`currency`	No	ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency.
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`line_items`	No	Replacement line items (replaces all lines). Omit to leave the lines as they are.
`checkout_id`	Yes	UCP checkout session ID (valid UUID)
`fulfillment`	No	Delivery. Send destination first, then selected_option_id (or both in one call).
`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."

Changed5 schema fields changedOct 15, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"REQUIRED for this write unless sent as the `Idempotency-Key` header or `_meta`. Reuse the same value when retrying the same operation."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."

changedInput schema / properties / idempotency_key / maxLength
```
Previous value: -255New value: +128
```
removedInput schema / properties / idempotency_key / minLength
```
Removed value: -1
```
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."

Changed1 schema field changedOct 15, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `_meta`. Reuse the same value when retrying the same operation.",
+  "maxLength": 255,
+  "minLength": 1,
+  "type": "string"
+}

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"
+]

Changed8 schema fields changedOct 1, 2026

changedInput schema / properties / currency / description

Previous value: -"ISO 4217 currency code (e.g. USD)"New value: +"ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency."

addedInput schema / properties / fulfillment

Added value: +{
+  "additionalProperties": true,
+  "description": "Delivery. Send destination first, then selected_option_id (or both in one call).",
+  "properties": {
+    "destination": {
+      "additionalProperties": true,
+      "description": "Delivery address. Sending it loads the shipping options for that destination; the response lists them in fulfillment.options.",
+      "properties": {
+        "address1": {
+          "description": "Street address",
+          "type": "string"
+        },
+        "city": {
+          "description": "City",
+          "type": "string"
+        },
+        "country_code": {
+          "description": "ISO 3166-1 alpha-2 country code (e.g. US, ES)",
+          "type": "string"
+        },
+        "province_code": {
+          "description": "Province or state code (optional)",
+          "type": "string"
+        },
+        "zip": {
+          "description": "Postal / ZIP code",
+          "type": "string"
+        }
+      },
+      "required": [
+        "address1",
+        "city",
+        "country_code",
+        "zip"
+      ],
+      "type": "object"
+    },
+    "selected_option_id": {
+      "description": "Id of one of fulfillment.options. Choosing it adds the shipping amount to the totals.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / line_items / description

Previous value: -"Replacement line items"New value: +"Replacement line items (replaces all lines). Omit to leave the lines as they are."

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"
+}

changedInput schema / required

Previous value: -[
-  "checkout_id",
-  "currency",
-  "line_items"
-]New value: +[
+  "checkout_id"
+]

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."
+}

Changed9 schema fields changedSep 17, 2026
- changedInput schema / 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: +{
+  "checkout_id": {
+    "description": "UCP checkout session ID (valid UUID)",
+    "type": "string"
+  },
+  "currency": {
+    "description": "ISO 4217 currency code (e.g. USD)",
+    "maxLength": 3,
+    "minLength": 3,
+    "type": "string"
+  },
+  "line_items": {
+    "description": "Replacement line items",
+    "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: +[
+  "checkout_id",
+  "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: -{
-  "checkout_id": {
-    "description": "UCP checkout session ID (valid UUID)",
-    "type": "string"
-  },
-  "currency": {
-    "description": "ISO 4217 currency code (e.g. USD)",
-    "maxLength": 3,
-    "minLength": 3,
-    "type": "string"
-  },
-  "line_items": {
-    "description": "Replacement line items",
-    "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: -[
-  "checkout_id",
-  "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.7/5.0

Behavior5/5

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses the state gate, that line_items replaces ALL lines, and the two side effects: destination returns shipping options, selected_option_id adds shipping to totals. That is substantive behavioral context the annotations do not carry, with 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.

Conciseness4/5

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

Front-loaded with the core verb+resource, then progressively details the two payload branches and constraints. Dense but every sentence carries information; the parenthetical asides are informative rather than filler.

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?

No output schema exists, and the description partially compensates by explaining what the two fulfillment branches return/produce and by linking the checkout guide resource. For a 7-parameter nested-object write tool it is nearly complete, though the overall response shape is left to the referenced guide.

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

Parameters4/5

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: replacement semantics of line_items, that a line may name a variant_id, and the ordering relationship between fulfillment.destination and selected_option_id. It stops short of documenting meta, agent_key, or idempotency_key handling.

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 (Update) and resource (UCP checkout session), then enumerates exactly which fields drive which effects (line_items replaces lines, fulfillment sets destination/option). It is clearly distinguished from siblings by naming ucp_create_checkout, create_cart, and select_shipping_option.

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 states the precondition (only when status is 'incomplete'), the scope (use ONLY for sessions created with ucp_create_checkout), and the alternative for the standard flow (create_cart and select_shipping_option), plus a pointer to the checkout guide resource.

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?