Skip to main content
Glama

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "checkout_id": "<checkout_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "ucp_complete_checkout"
  }
}

Input Schema

NameRequiredDescriptionDefault
ap2NoAP2 mandates extension. Required when the checkout carries ap2.merchant_authorization.
metaNoUCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters).
buyerNoBuyer name and email, needed to request the approval link.
paymentNoUCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token.
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
checkout_idYesUCP checkout session ID (valid UUID)
x402_payloadNox402: signed payment for the server offer (omit to get it).
payment_optionNoPayment 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_keyYesREQUIRED 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_handlerNoPayment handler the store profile publishes. Omit for default.
payment_mandateNoPayment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header.
shared_payment_tokenNoStripe 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.

  1. Changed1 schema field changed
    • addedInput schema / properties / buyer / properties / consent
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "UCP buyer_consent: include EVERY advertised purpose with granted + source ('platform' only for what the buyer said). Omit to leave consent unchanged.",
      +  "type": "object"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / payment_mandate / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": true,
      -    "properties": {
      -      "aud": {
      -        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
      -        "maxLength": 256,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "currency": {
      -        "description": "Three-letter currency code; must match the cart's currency.",
      -        "maxLength": 3,
      -        "minLength": 3,
      -        "type": "string"
      -      },
      -      "exp": {
      -        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      },
      -      "mandate_id": {
      -        "description": "Your identifier for this mandate.",
      -        "maxLength": 128,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "max_amount_cents": {
      -        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      },
      -      "sub": {
      -        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
      -        "maxLength": 256,
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "mandate_id",
      -      "max_amount_cents",
      -      "currency",
      -      "exp",
      -      "sub",
      -      "aud"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": {},
      +    "type": "object"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / payment_mandate / description
      Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header."
  3. Changed1 schema field changed
    • 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
  4. Changed1 schema field changed
    • 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."
  5. Changed1 schema field changed
    • 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."
  6. Changed4 schema fields changed
    • 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."
  7. Changed18 schema fields changed
    • 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"
      -]
  8. Changed1 schema field changed
    • addedOutput schema / properties / payment_options / items / properties / charges_without_approval
      Added value: +{
      +  "const": true,
      +  "type": "boolean"
      +}
  9. Changed4 schema fields changed
    • 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"
      +]
  10. Changed3 schema fields changed
    • 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"
      +}
  11. Changed2 schema fields changed
    • 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"
      +}
  12. Changed1 schema field changed
    • 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"
      +]
  13. Changed2 schema fields changed
    • 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"
      +]
  14. Added
  15. Removed
  16. Changed4 schema fields changed
    • 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"
      +]
  17. Changed5 schema fields changed
    • 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
  18. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false, and the description reinforces idempotency with the specific retry rule ('safe to retry with the same idempotency_key'). It adds genuine behavioral context annotations cannot carry: the mandate is platform-issued and self-written mandates are rejected, and approval is bound to the agent credential without verifying a person was present. It does not describe post-completion side effects such as inventory or cart state, which keeps it below a 5.

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 state transition, then a clearly labeled PAYMENT MANDATE block, then a pointer to the checkout guide. It is dense but every section carries routing or prerequisite information; the only minor cost is length across several distinct concerns packed into one block.

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 12-parameter, nested-object, money-moving mutation with no output schema, the description covers the hard parts: session provenance, idempotency, and the full mandate acquisition flow, plus a guide resource for further detail. It stops short of saying what the completion response contains or what happens to the cart afterward, though the guide reference partly offsets that.

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 goes beyond field definitions: it explains how to obtain payment_mandate, that X-Payment-Mandate is the header alternative, that payment_option must reflect the person's choice ('never choose for them'), and that idempotency_key must be passed as an argument rather than a header. That is procedural meaning the schema text alone does not convey.

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 ('Complete a UCP checkout session') plus the resulting state change ('Transitions to completed status'). It also names the siblings it is not for (ucp_create_checkout, create_cart, preview_checkout, complete_checkout) and gives the routing rule, so an agent can distinguish it from the standard complete_checkout 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?

Explicit when-to-use ('ONLY for a checkout session created with ucp_create_checkout') and when-not ('for the standard flow (create_cart, preview_checkout, complete_checkout) do not call this tool'), with the correct alternative named. The payment_mandate preconditions are spelled out step by step: preview, open approval_url, poll approval_status_url, forward the mandate.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources