Skip to main content
Glama

ucp_update_checkout

Idempotent

Update a UCP checkout session. Send line_items to replace all lines (each line may name a variant_id), and/or fulfillment to set the delivery address (fulfillment.destination, which returns the shipping options) and choose one (fulfillment.selected_option_id, which adds shipping to the totals). Only allowed when status is 'incomplete'. Use ONLY for sessions created with ucp_create_checkout; for the standard flow use create_cart and select_shipping_option. Checkout guide: read the MCP resource trusteed://guides/checkout.

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>"
    },
    "name": "ucp_update_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).
currencyNoISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency.
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
line_itemsNoReplacement line items (replaces all lines). Omit to leave the lines as they are.
checkout_idYesUCP checkout session ID (valid UUID)
fulfillmentNoDelivery. Send destination first, then selected_option_id (or both in one call).
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. Changed5 schema fields changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"REQUIRED for this write unless sent as the `Idempotency-Key` header or `_meta`. Reuse the same value when retrying the same operation."New value: +"REQUIRED for this write unless sent as the `Idempotency-Key` header or `params._meta[\"trusteed/idempotency-key\"]`. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."
    • changedInput schema / properties / idempotency_key / maxLength
      Previous value: -255New value: +128
    • removedInput schema / properties / idempotency_key / minLength
      Removed value: -1
    • addedInput schema / properties / idempotency_key / pattern
      Added value: +"^[A-Za-z0-9._:/-]{1,128}$"
    • addedOutput schema / properties / next_step / description
      Added value: +"Next-action code, not a tool name: provide_shipping_destination, refresh_shipping_rates, choose_shipping_option, ask_user_payment_method."
  7. Changed1 schema field changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "REQUIRED for this write unless sent as the `Idempotency-Key` header or `_meta`. Reuse the same value when retrying the same operation.",
      +  "maxLength": 255,
      +  "minLength": 1,
      +  "type": "string"
      +}
  8. 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"
      -]
  9. Changed1 schema field changed
    • addedOutput schema / properties / payment_options / items / properties / charges_without_approval
      Added value: +{
      +  "const": true,
      +  "type": "boolean"
      +}
  10. 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"
      +]
  11. 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)."
      +}
  12. 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"
      +}
  13. 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"
      +]
  14. 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"
      +]
  15. Changed8 schema fields changed
    • changedInput schema / properties / currency / description
      Previous value: -"ISO 4217 currency code (e.g. USD)"New value: +"ISO 4217 currency code (e.g. USD). Optional: defaults to the checkout's currency."
    • addedInput schema / properties / fulfillment
      Added value: +{
      +  "additionalProperties": true,
      +  "description": "Delivery. Send destination first, then selected_option_id (or both in one call).",
      +  "properties": {
      +    "destination": {
      +      "additionalProperties": true,
      +      "description": "Delivery address. Sending it loads the shipping options for that destination; the response lists them in fulfillment.options.",
      +      "properties": {
      +        "address1": {
      +          "description": "Street address",
      +          "type": "string"
      +        },
      +        "city": {
      +          "description": "City",
      +          "type": "string"
      +        },
      +        "country_code": {
      +          "description": "ISO 3166-1 alpha-2 country code (e.g. US, ES)",
      +          "type": "string"
      +        },
      +        "province_code": {
      +          "description": "Province or state code (optional)",
      +          "type": "string"
      +        },
      +        "zip": {
      +          "description": "Postal / ZIP code",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "address1",
      +        "city",
      +        "country_code",
      +        "zip"
      +      ],
      +      "type": "object"
      +    },
      +    "selected_option_id": {
      +      "description": "Id of one of fulfillment.options. Choosing it adds the shipping amount to the totals.",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedInput schema / properties / line_items / description
      Previous value: -"Replacement line items"New value: +"Replacement line items (replaces all lines). Omit to leave the lines as they are."
    • addedInput schema / properties / line_items / items / properties / variant_id
      Added value: +{
      +  "description": "Variant (size/colour) id as listed by get_product_details. Required when the product has more than one variant; the price and stock of THAT variant apply.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "checkout_id",
      -  "currency",
      -  "line_items"
      -]New value: +[
      +  "checkout_id"
      +]
    • addedOutput schema / properties / fulfillment
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "destination": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "city": {
      +          "type": "string"
      +        },
      +        "country_code": {
      +          "type": "string"
      +        },
      +        "province_code": {
      +          "type": "string"
      +        },
      +        "zip": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "city",
      +        "country_code",
      +        "zip"
      +      ],
      +      "type": "object"
      +    },
      +    "options": {
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "authoritative": {
      +            "type": "boolean"
      +          },
      +          "estimated_delivery": {
      +            "type": "string"
      +          },
      +          "id": {
      +            "type": "string"
      +          },
      +          "price": {
      +            "additionalProperties": true,
      +            "properties": {
      +              "amount": {
      +                "type": "number"
      +              },
      +              "currency": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "amount",
      +              "currency"
      +            ],
      +            "type": "object"
      +          },
      +          "source": {
      +            "enum": [
      +              "platform",
      +              "merchant_policy",
      +              "estimated"
      +            ],
      +            "type": "string"
      +          },
      +          "title": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "title",
      +          "price",
      +          "source",
      +          "authoritative"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "selected_option_id": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / line_items / items / properties / variant_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / line_items / items / properties / variant_title
      Added value: +{
      +  "type": "string"
      +}
  16. 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"
      +}
  17. 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"
      +}
  18. 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."
  19. 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."
      -}
  20. 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"
      +}
  21. 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."
  22. 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."
      +}
  23. Changed9 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / line_items / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / extensions / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / extensions / properties / warnings / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / intent / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / line_items / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / line_items / items / properties / price / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / totals / items / additionalProperties
      Previous value: -falseNew value: +true
  24. Added
  25. Removed
  26. 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"
      +  },
      +  "currency": {
      +    "description": "ISO 4217 currency code (e.g. USD)",
      +    "maxLength": 3,
      +    "minLength": 3,
      +    "type": "string"
      +  },
      +  "line_items": {
      +    "description": "Replacement line items",
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "price": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "amount": {
      +              "description": "Price in smallest unit (cents)",
      +              "minimum": 0,
      +              "type": "number"
      +            },
      +            "currency": {
      +              "description": "ISO 4217 currency code",
      +              "maxLength": 3,
      +              "minLength": 3,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "amount",
      +            "currency"
      +          ],
      +          "type": "object"
      +        },
      +        "product_id": {
      +          "description": "Product identifier",
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "quantity": {
      +          "description": "Quantity",
      +          "exclusiveMinimum": 0,
      +          "type": "integer"
      +        },
      +        "title": {
      +          "description": "Product title",
      +          "minLength": 1,
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "product_id",
      +        "title",
      +        "quantity",
      +        "price"
      +      ],
      +      "type": "object"
      +    },
      +    "minItems": 1,
      +    "type": "array"
      +  }
      +}
    • addedInput schema / required
      Added value: +[
      +  "checkout_id",
      +  "currency",
      +  "line_items"
      +]
  27. 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"
      -  },
      -  "currency": {
      -    "description": "ISO 4217 currency code (e.g. USD)",
      -    "maxLength": 3,
      -    "minLength": 3,
      -    "type": "string"
      -  },
      -  "line_items": {
      -    "description": "Replacement line items",
      -    "items": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "price": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "amount": {
      -              "description": "Price in smallest unit (cents)",
      -              "minimum": 0,
      -              "type": "number"
      -            },
      -            "currency": {
      -              "description": "ISO 4217 currency code",
      -              "maxLength": 3,
      -              "minLength": 3,
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "amount",
      -            "currency"
      -          ],
      -          "type": "object"
      -        },
      -        "product_id": {
      -          "description": "Product identifier",
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "quantity": {
      -          "description": "Quantity",
      -          "exclusiveMinimum": 0,
      -          "type": "integer"
      -        },
      -        "title": {
      -          "description": "Product title",
      -          "minLength": 1,
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "product_id",
      -        "title",
      -        "quantity",
      -        "price"
      -      ],
      -      "type": "object"
      -    },
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -}
    • removedInput schema / required
      Removed value: -[
      -  "checkout_id",
      -  "currency",
      -  "line_items"
      -]
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "created_at": {
      -      "type": "string"
      -    },
      -    "currency": {
      -      "type": "string"
      -    },
      -    "extensions": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "warnings": {
      -          "items": {
      -            "additionalProperties": false,
      -            "properties": {
      -              "code": {
      -                "type": "string"
      -              },
      -              "disclosure_url": {
      -                "type": "string"
      -              },
      -              "message": {
      -                "type": "string"
      -              },
      -              "severity": {
      -                "enum": [
      -                  "info",
      -                  "caution",
      -                  "critical"
      -                ],
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "code",
      -              "message",
      -              "severity"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "id": {
      -      "type": "string"
      -    },
      -    "idempotency_key": {
      -      "type": "string"
      -    },
      -    "intent": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "action": {
      -          "type": "string"
      -        },
      -        "context": {
      -          "type": "string"
      -        },
      -        "locale": {
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "action"
      -      ],
      -      "type": "object"
      -    },
      -    "label": {
      -      "type": "string"
      -    },
      -    "line_items": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "id": {
      -            "type": "string"
      -          },
      -          "price": {
      -            "additionalProperties": false,
      -            "properties": {
      -              "amount": {
      -                "type": "number"
      -              },
      -              "currency": {
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "amount",
      -              "currency"
      -            ],
      -            "type": "object"
      -          },
      -          "product_id": {
      -            "type": "string"
      -          },
      -          "quantity": {
      -            "type": "number"
      -          },
      -          "title": {
      -            "type": "string"
      -          }
      -        },
      -        "required": [
      -          "id",
      -          "product_id",
      -          "title",
      -          "quantity",
      -          "price"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "status": {
      -      "enum": [
      -        "incomplete",
      -        "requires_escalation",
      -        "ready_for_complete",
      -        "complete_in_progress",
      -        "completed",
      -        "canceled"
      -      ],
      -      "type": "string"
      -    },
      -    "totals": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "amount": {
      -            "type": "number"
      -          },
      -          "currency": {
      -            "type": "string"
      -          },
      -          "label": {
      -            "type": "string"
      -          }
      -        },
      -        "required": [
      -          "label",
      -          "amount",
      -          "currency"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "updated_at": {
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "id",
      -    "status",
      -    "currency",
      -    "line_items",
      -    "totals",
      -    "created_at",
      -    "updated_at"
      -  ],
      -  "type": "object"
      -}New value: +null
  28. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover idempotency, non-destructiveness and closed-world scope, so the description's job is narrower. It still adds real behavior: line_items replaces all lines, sending destination loads shipping options into fulfillment.options, selected_option_id adds shipping to totals, and the incomplete-status gate. Return-shape details for a non-complete update are partial but adequate given the guide pointer.

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

Conciseness4/5

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

Front-loaded with the action, then the two payload modes, then eligibility and alternatives, then the guide link. Dense but every clause carries operational meaning; it is close to a single packed paragraph rather than scannable structure, which is the only deduction.

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?

This is a multi-mode write with nested objects and no output schema, and the description covers the mutation modes, the status gate, the alternatives, and where to read more. The idempotency requirement lives entirely in the schema, so the description is complete enough without repeating it.

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. The description goes beyond it by explaining the replace-all semantics of line_items, that variant_id identifies the variant whose price and stock apply, and the destination-then-selected_option_id sequencing for fulfillment, which is not obvious from the schema alone.

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 ('Update a UCP checkout session') and immediately scopes what update means here (line_items replacement, fulfillment destination/selection). It also names the sibling flows it is not for, so an agent can separate it from create_cart and select_shipping_option without inspecting schemas.

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 preconditions ('Only allowed when status is incomplete') plus explicit routing: use ONLY for sessions created with ucp_create_checkout, otherwise use create_cart / select_shipping_option. It even points to the checkout guide resource, which is exactly the when-to-use guidance an agent needs.

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