Trusteed Agentic Commerce

ucp_complete_checkout

Idempotent

Complete a UCP checkout session. Transitions to 'completed' status. Idempotent — safe to retry with the same idempotency_key. Use ONLY for a checkout session created with ucp_create_checkout (Universal Commerce Protocol); for the standard flow (create_cart, preview_checkout, complete_checkout) do not call this tool. For a cart built with create_cart use complete_checkout. PAYMENT MANDATE: this tool also requires one, issued by the platform, not written by you. Call preview_checkout for this cart, open the approval_url it returns, poll approval_status_url with your agent credential, and send the mandate you receive as the payment_mandate argument or an X-Payment-Mandate header. The approval is bound to your agent credential and the cart; it does not verify that a person was present. Checkout guide: read the MCP resource trusteed://guides/checkout.

Input Schema

Name	Required	Description
`ap2`	No	AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization.
`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).
`buyer`	No	Buyer name and email, needed to request the approval link.
`payment`	No	UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token.
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`checkout_id`	Yes	UCP checkout session ID (valid UUID)
`x402_payload`	No	x402: signed payment for the server offer (omit to get it).
`payment_option`	No	Payment method THE PERSON chose, when preview_checkout returned payment_options. Ask the person; never choose for them. Card numbers and wallet keys are never sent here: the person approves (and, with own_wallet, signs) on the approval page.
`idempotency_key`	Yes	REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation.
`payment_handler`	No	Payment handler the store profile publishes. Omit for default.
`payment_mandate`	No	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.
`shared_payment_token`	No	Stripe Shared Payment Token (spt_…) granted by the buyer's agent wallet for payment_method=ACP. Issued by Stripe, scoped to this merchant, amount and currency, and consumed when used: it can be charged once. Only honoured when this deployment enables native ACP settlement.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

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

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: -"Unique key to prevent duplicate completions. Generate once per attempt."New value: +"REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 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."

Changed18 schema fields changedOct 14, 2026

changedInput schema / properties / payment_mandate / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "type": "object"
-  },
-  {
-    "type": "string"
-  }
-]New 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"
+  }
+]

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

Changed4 schema fields changedOct 13, 2026

changedInput schema / properties / payment_option / enum

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

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

Changed3 schema fields changedOct 11, 2026

addedInput schema / properties / ap2

Added value: +{
+  "additionalProperties": true,
+  "description": "AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization.",
+  "properties": {
+    "checkout_mandate": {
+      "description": "AP2 Checkout Mandate (SD-JWT chain) the user signed over the exact checkout returned by the last ucp_get_checkout.",
+      "maxLength": 262144,
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_.~-]+$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "checkout_mandate"
+  ],
+  "type": "object"
+}

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

addedInput schema / properties / payment

Added value: +{
+  "additionalProperties": true,
+  "description": "UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token.",
+  "properties": {
+    "instruments": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "credential": {
+            "additionalProperties": true,
+            "properties": {
+              "token": {
+                "description": "AP2 Payment Mandate (SD-JWT chain).",
+                "maxLength": 262144,
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "maxItems": 16,
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

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

Changed2 schema fields changedOct 5, 2026

changedInput schema / properties / payment_option / enum

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

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

AddedOct 2, 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"
+  },
+  "idempotency_key": {
+    "description": "Unique key to prevent duplicate completions. Generate once per attempt.",
+    "type": "string"
+  }
+}

addedInput schema / required

Added value: +[
+  "checkout_id",
+  "idempotency_key"
+]

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"
-  },
-  "idempotency_key": {
-    "description": "Unique key to prevent duplicate completions. Generate once per attempt.",
-    "type": "string"
-  }
-}

removedInput schema / required

Removed value: -[
-  "checkout_id",
-  "idempotency_key"
-]

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

Behavior5/5

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

Annotations already declare non-readOnly and idempotentHint=true, but the description adds substantive context beyond them: the idempotency is tied to reusing the same idempotency_key, the mandate must be platform-issued and forwarded as received, and critically the approval is bound to the agent credential and 'does not verify that a person was present'. That is meaningful behavioral disclosure for a mutation tool.

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 purpose and routing before the dense payment-mandate instructions. Every sentence carries operational weight, though the mandate paragraph is long and would benefit from tighter phrasing. Size is defensible for a 12-parameter high-stakes mutation tool.

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

Completeness5/5

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

Complete for a complex, high-consequence tool: it covers the routing decision, the required prerequisite flow steps, credential/mandate binding, and points to a dedicated checkout guide resource. With no output schema, the stated status transition ('completed') gives the needed return context.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning that the schema can't: it explains that the payment_mandate is obtained via the preview/approval loop and can alternatively travel as an X-Payment-Mandate header, and that idempotency_key must be an argument and not just a header/_meta value. These are cross-parameter usage semantics beyond the field documentation.

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+resource ('Complete a UCP checkout session') plus the resulting state transition ('completed'), and explicitly distinguishes itself from the sibling complete_checkout and from the create side (ucp_create_checkout). An agent can route correctly without opening any 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?

Gives explicit when-to-use ('ONLY for a checkout session created with ucp_create_checkout'), when-not ('for the standard flow... do not call this tool'), and names the correct alternative ('For a cart built with create_cart use complete_checkout'). It further spells out the full payment-mandate acquisition path (preview_checkout → approval_url → poll approval_status_url → submit mandate).

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?