Skip to main content
Glama

ucp_create_checkout

Idempotent

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

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": {
      "currency": "<currency>",
      "line_items": "<line_items>"
    },
    "name": "ucp_create_checkout"
  }
}

Input Schema

NameRequiredDescriptionDefault
metaNoUCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters).
buyerNoBuyer contact and consent (UCP buyer_consent).
labelNoOptional label for additional identifiers (e.g. external order ref, multi-PSP reference)
intentNoIntent context for relevance and personalization
currencyYesISO 4217 currency code (e.g. USD)
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
line_itemsYesLine items for the checkout
idempotency_keyNoREQUIRED 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.
xyz.trusteed.shopping.buyer_intentNoOptional. What the person asked for, as structured constraints with who said each one (user_stated or agent_inferred) and the substitution policy. Safe to send: where the store compares it with the cart, a purchase that differs can stop before anything is charged. It is the agent's account of the request, not proof of what the person said.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / xyz.trusteed.shopping.buyer_intent / description
      Previous value: -"Optional. What the person asked for, as structured constraints with who said each one (user_stated or agent_inferred) and the substitution policy. The store may compare it with the cart when it enables this; it never proves what the person said."New value: +"Optional. What the person asked for, as structured constraints with who said each one (user_stated or agent_inferred) and the substitution policy. Safe to send: where the store compares it with the cart, a purchase that differs can stop before anything is charged. It is the agent's account of the request, not proof of what the person said."
  2. Changed2 schema fields changed
    • addedInput schema / properties / buyer
      Added value: +{
      +  "additionalProperties": true,
      +  "description": "Buyer contact and consent (UCP buyer_consent).",
      +  "properties": {
      +    "consent": {
      +      "additionalProperties": {},
      +      "description": "UCP buyer_consent: map of purpose id (dev.ucp.consent.analytics|marketing|preferences|sale_or_sharing) to {granted, source: 'platform'|'business', segments?}. Send `source: platform` only for what the buyer actually said. Omit to leave consent unchanged.",
      +      "type": "object"
      +    },
      +    "email": {
      +      "description": "Buyer email",
      +      "type": "string"
      +    },
      +    "phone": {
      +      "description": "Buyer phone number",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / xyz.trusteed.shopping.buyer_intent
      Added value: +{
      +  "description": "Optional. What the person asked for, as structured constraints with who said each one (user_stated or agent_inferred) and the substitution policy. The store may compare it with the cart when it enables this; it never proves what the person said."
      +}
  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: -"Required by the checkout bucket (UUID-v4 or bounded ASCII token). Choose one per purchase attempt and reuse it to retry safely. Alternatively send it as the Idempotency-Key header or params._meta[\"trusteed/idempotency-key\"]."New value: +"REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
    • addedInput schema / properties / idempotency_key / maxLength
      Added value: +128
    • addedInput schema / properties / idempotency_key / pattern
      Added value: +"^[A-Za-z0-9._:/-]{1,128}$"
    • addedOutput schema / properties / next_step / description
      Added value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method."
  7. Changed17 schema fields changed
    • 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. Changed3 schema fields changed
    • 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. Changed1 schema field changed
    • 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)."
      +}
  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. Changed1 schema field changed
    • 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. Changed5 schema fields changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "Required by the checkout bucket (UUID-v4 or bounded ASCII token). Choose one per purchase attempt and reuse it to retry safely. Alternatively send it as the Idempotency-Key header or params._meta[\"trusteed/idempotency-key\"].",
      +  "type": "string"
      +}
    • addedInput schema / properties / line_items / items / properties / variant_id
      Added value: +{
      +  "description": "Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedOutput schema / properties / fulfillment
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "destination": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "city": {
      +          "type": "string"
      +        },
      +        "country_code": {
      +          "type": "string"
      +        },
      +        "province_code": {
      +          "type": "string"
      +        },
      +        "zip": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "city",
      +        "country_code",
      +        "zip"
      +      ],
      +      "type": "object"
      +    },
      +    "options": {
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "authoritative": {
      +            "type": "boolean"
      +          },
      +          "estimated_delivery": {
      +            "type": "string"
      +          },
      +          "id": {
      +            "type": "string"
      +          },
      +          "price": {
      +            "additionalProperties": true,
      +            "properties": {
      +              "amount": {
      +                "type": "number"
      +              },
      +              "currency": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "amount",
      +              "currency"
      +            ],
      +            "type": "object"
      +          },
      +          "source": {
      +            "enum": [
      +              "platform",
      +              "merchant_policy",
      +              "estimated"
      +            ],
      +            "type": "string"
      +          },
      +          "title": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "title",
      +          "price",
      +          "source",
      +          "authoritative"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "selected_option_id": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / line_items / items / properties / variant_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / line_items / items / properties / variant_title
      Added value: +{
      +  "type": "string"
      +}
  15. Changed3 schema fields changed
    • 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"
      +}
  16. Changed2 schema fields changed
    • 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"
      +}
  17. Changed2 schema fields changed
    • 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."
  18. Changed1 schema field changed
    • 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."
      -}
  19. Changed1 schema field changed
    • 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"
      +}
  20. Changed1 schema field changed
    • 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."
  21. Changed1 schema field changed
    • 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."
      +}
  22. Changed10 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / intent / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / line_items / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / extensions / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / extensions / properties / warnings / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / intent / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / line_items / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / line_items / items / properties / price / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / totals / items / additionalProperties
      Previous value: -falseNew value: +true
  23. Added
  24. Removed
  25. 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: +{
      +  "currency": {
      +    "description": "ISO 4217 currency code (e.g. USD)",
      +    "maxLength": 3,
      +    "minLength": 3,
      +    "type": "string"
      +  },
      +  "intent": {
      +    "additionalProperties": false,
      +    "description": "Intent context for relevance and personalization",
      +    "properties": {
      +      "action": {
      +        "description": "Intent action (e.g. 'purchase', 'gift', 'compare')",
      +        "type": "string"
      +      },
      +      "context": {
      +        "description": "Natural language context for personalization",
      +        "type": "string"
      +      },
      +      "locale": {
      +        "description": "ISO locale",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "action"
      +    ],
      +    "type": "object"
      +  },
      +  "label": {
      +    "description": "Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)",
      +    "type": "string"
      +  },
      +  "line_items": {
      +    "description": "Line items for the checkout",
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "price": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "amount": {
      +              "description": "Price in smallest unit (cents)",
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "currency": {
      +              "description": "ISO 4217 currency code",
      +              "maxLength": 3,
      +              "minLength": 3,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "amount",
      +            "currency"
      +          ],
      +          "type": "object"
      +        },
      +        "product_id": {
      +          "description": "Product identifier",
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "quantity": {
      +          "description": "Quantity",
      +          "exclusiveMinimum": 0,
      +          "type": "integer"
      +        },
      +        "title": {
      +          "description": "Product title",
      +          "minLength": 1,
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "product_id",
      +        "title",
      +        "quantity",
      +        "price"
      +      ],
      +      "type": "object"
      +    },
      +    "minItems": 1,
      +    "type": "array"
      +  }
      +}
    • addedInput schema / required
      Added value: +[
      +  "currency",
      +  "line_items"
      +]
  26. 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: -{
      -  "currency": {
      -    "description": "ISO 4217 currency code (e.g. USD)",
      -    "maxLength": 3,
      -    "minLength": 3,
      -    "type": "string"
      -  },
      -  "intent": {
      -    "additionalProperties": false,
      -    "description": "Intent context for relevance and personalization",
      -    "properties": {
      -      "action": {
      -        "description": "Intent action (e.g. 'purchase', 'gift', 'compare')",
      -        "type": "string"
      -      },
      -      "context": {
      -        "description": "Natural language context for personalization",
      -        "type": "string"
      -      },
      -      "locale": {
      -        "description": "ISO locale",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "action"
      -    ],
      -    "type": "object"
      -  },
      -  "label": {
      -    "description": "Optional label for additional identifiers (e.g. external order ref, multi-PSP reference)",
      -    "type": "string"
      -  },
      -  "line_items": {
      -    "description": "Line items for the checkout",
      -    "items": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "price": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "amount": {
      -              "description": "Price in smallest unit (cents)",
      -              "minimum": 0,
      -              "type": "number"
      -            },
      -            "currency": {
      -              "description": "ISO 4217 currency code",
      -              "maxLength": 3,
      -              "minLength": 3,
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "amount",
      -            "currency"
      -          ],
      -          "type": "object"
      -        },
      -        "product_id": {
      -          "description": "Product identifier",
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "quantity": {
      -          "description": "Quantity",
      -          "exclusiveMinimum": 0,
      -          "type": "integer"
      -        },
      -        "title": {
      -          "description": "Product title",
      -          "minLength": 1,
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "product_id",
      -        "title",
      -        "quantity",
      -        "price"
      -      ],
      -      "type": "object"
      -    },
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -}
    • removedInput schema / required
      Removed value: -[
      -  "currency",
      -  "line_items"
      -]
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "created_at": {
      -      "type": "string"
      -    },
      -    "currency": {
      -      "type": "string"
      -    },
      -    "extensions": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "warnings": {
      -          "items": {
      -            "additionalProperties": false,
      -            "properties": {
      -              "code": {
      -                "type": "string"
      -              },
      -              "disclosure_url": {
      -                "type": "string"
      -              },
      -              "message": {
      -                "type": "string"
      -              },
      -              "severity": {
      -                "enum": [
      -                  "info",
      -                  "caution",
      -                  "critical"
      -                ],
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "code",
      -              "message",
      -              "severity"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "id": {
      -      "type": "string"
      -    },
      -    "idempotency_key": {
      -      "type": "string"
      -    },
      -    "intent": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "action": {
      -          "type": "string"
      -        },
      -        "context": {
      -          "type": "string"
      -        },
      -        "locale": {
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "action"
      -      ],
      -      "type": "object"
      -    },
      -    "label": {
      -      "type": "string"
      -    },
      -    "line_items": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "id": {
      -            "type": "string"
      -          },
      -          "price": {
      -            "additionalProperties": false,
      -            "properties": {
      -              "amount": {
      -                "type": "number"
      -              },
      -              "currency": {
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "amount",
      -              "currency"
      -            ],
      -            "type": "object"
      -          },
      -          "product_id": {
      -            "type": "string"
      -          },
      -          "quantity": {
      -            "type": "number"
      -          },
      -          "title": {
      -            "type": "string"
      -          }
      -        },
      -        "required": [
      -          "id",
      -          "product_id",
      -          "title",
      -          "quantity",
      -          "price"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "status": {
      -      "enum": [
      -        "incomplete",
      -        "requires_escalation",
      -        "ready_for_complete",
      -        "complete_in_progress",
      -        "completed",
      -        "canceled"
      -      ],
      -      "type": "string"
      -    },
      -    "totals": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "amount": {
      -            "type": "number"
      -          },
      -          "currency": {
      -            "type": "string"
      -          },
      -          "label": {
      -            "type": "string"
      -          }
      -        },
      -        "required": [
      -          "label",
      -          "amount",
      -          "currency"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "updated_at": {
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "id",
      -    "status",
      -    "currency",
      -    "line_items",
      -    "totals",
      -    "created_at",
      -    "updated_at"
      -  ],
      -  "type": "object"
      -}New value: +null
  27. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare this is a non-read-only but non-destructive, idempotent, closed-world write. The description adds genuine context beyond that: the session is created in an 'incomplete' state and the two flows must not be mixed on one purchase. It stops short of describing what the checkout object contains or any expiration/lifecycle behavior, which would push it higher.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Four short sentences with the action and return state front-loaded, followed by flow routing and a pointer to further documentation. Nothing repeats the schema and every sentence carries decision-relevant information.

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 9-parameter write tool with nested objects and no output schema, the description covers the essential facts: what is created, the resulting state, which flow it belongs to, and where the guide lives. The lack of any hint about the checkout object's contents or follow-up steps is a minor gap given the rich schema and referenced guide.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter, including the idempotency key and variant_id semantics, is already documented in the schema. The description only mentions 'line items' generically and adds no format, currency, or idempotency detail beyond the structured fields, so the baseline of 3 applies.

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

Purpose5/5

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

The opening sentence names a specific verb and resource ('Create a UCP checkout session from line items') and immediately states the resulting state ('status incomplete'). It also distinguishes itself from the sibling create_cart by naming the two competing flows, so an agent can pick correctly without opening either 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 (UCP flow), when-not ('Do not mix the two flows on the same purchase'), and a named alternative ('for the standard flow use create_cart instead'). It further routes the agent to the checkout guide resource, leaving little to inference.

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