Skip to main content
Glama

preview_checkout

Preview the complete order summary before payment. Advances the session to ready-for-payment state. If you only need the price, call quote_checkout instead: it computes the same total without advancing the session or opening an approval.

PREFER THE CART CARD: if there is an interactive card for this cart, let it compute and show the summary instead of calling this tool yourself — it keeps the flow in one card. Checkout guide: read the MCP resource trusteed://guides/checkout. CREDENTIAL: this store needs one. Call the create_sandbox_key tool first (it is in this tool list and needs no credential), then pass the key you get back as the agent_key argument — or as an Authorization: Bearer header if your client can set headers. Do not ask a person to log in: there is no human login for this store.

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": {
      "cart_id": "<cart_id>"
    },
    "name": "preview_checkout"
  }
}

Input Schema

NameRequiredDescriptionDefault
cart_idYesCart session ID returned by create_cart
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
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.
payment_mandateNoPayment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header.

Output Schema

NameRequiredDescriptionDefault
itemsYes
statusYes
currencyYes
next_stepNo
tax_centsYes
expires_atNo
store_nameYes
tax_statusYes
total_noteYes
approval_idNo
total_centsYes
approval_urlNo
discount_centsYes
shipping_centsYes
shipping_titleNo
subtotal_centsYes
total_is_finalYes
payment_optionsNo
shipping_sourceNo
next_step_messageNo
buyer_intent_matchNo
expires_in_secondsNoWhole seconds left on this checkout SESSION at response time (0 when already past). It is not a stock reservation and not a price guarantee.
approval_status_urlNo
checkout_session_idYes
shipping_authoritativeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / 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. Changed4 schema fields changed
    • addedInput schema / properties / 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."
      +}
    • addedOutput schema / properties / buyer_intent_match
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "alternative": {
      +      "enum": [
      +        "exists",
      +        "none",
      +        "unknown"
      +      ],
      +      "type": "string"
      +    },
      +    "declaration_version": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "diff": {
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "actual": {
      +            "type": "string"
      +          },
      +          "attribute": {
      +            "type": "string"
      +          },
      +          "outcome": {
      +            "enum": [
      +              "mismatch",
      +              "unverifiable"
      +            ],
      +            "type": "string"
      +          },
      +          "provenance": {
      +            "enum": [
      +              "user_stated",
      +              "agent_inferred"
      +            ],
      +            "type": "string"
      +          },
      +          "reason": {
      +            "enum": [
      +              "check_unavailable",
      +              "attribute_not_normalized",
      +              "ambiguous_match",
      +              "currency_mismatch",
      +              "catalog_value_absent"
      +            ],
      +            "type": "string"
      +          },
      +          "requested": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "attribute",
      +          "provenance",
      +          "outcome"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "next_action": {
      +      "type": "string"
      +    },
      +    "reason": {
      +      "enum": [
      +        "check_unavailable",
      +        "attribute_not_normalized",
      +        "ambiguous_match",
      +        "currency_mismatch",
      +        "catalog_value_absent"
      +      ],
      +      "type": "string"
      +    },
      +    "verdict": {
      +      "enum": [
      +        "match",
      +        "mismatch",
      +        "partial",
      +        "unverifiable",
      +        "substitution_allowed",
      +        "substituted_with_approval",
      +        "substitution_without_human_approval",
      +        "empty",
      +        "not_declared",
      +        "no_signal"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "verdict",
      +    "diff",
      +    "alternative",
      +    "declaration_version"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / properties / next_step / const
      Removed value: -"ask_user_payment_method"
    • addedOutput schema / properties / next_step / enum
      Added value: +[
      +  "ask_user_payment_method",
      +  "await_buyer_approval"
      +]
  3. Changed2 schema fields changed
    • changedInput schema / properties / payment_mandate / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": true,
      -    "properties": {
      -      "aud": {
      -        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
      -        "maxLength": 256,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "currency": {
      -        "description": "Three-letter currency code; must match the cart's currency.",
      -        "maxLength": 3,
      -        "minLength": 3,
      -        "type": "string"
      -      },
      -      "exp": {
      -        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      },
      -      "mandate_id": {
      -        "description": "Your identifier for this mandate.",
      -        "maxLength": 128,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "max_amount_cents": {
      -        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      },
      -      "sub": {
      -        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
      -        "maxLength": 256,
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "mandate_id",
      -      "max_amount_cents",
      -      "currency",
      -      "exp",
      -      "sub",
      -      "aud"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": {},
      +    "type": "object"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / payment_mandate / description
      Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."New value: +"Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. Use this when your client cannot set an `X-Payment-Mandate` header."
  4. Changed1 schema field changed
    • changedInput schema / properties / payment_mandate / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": {},
      -    "type": "object"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": true,
      +    "properties": {
      +      "aud": {
      +        "description": "This store's slug (the one in the URL you are calling) — not a domain.",
      +        "maxLength": 256,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "currency": {
      +        "description": "Three-letter currency code; must match the cart's currency.",
      +        "maxLength": 3,
      +        "minLength": 3,
      +        "type": "string"
      +      },
      +      "exp": {
      +        "description": "Expiry as an INTEGER of Unix seconds, in the future — not an ISO 8601 date string.",
      +        "exclusiveMinimum": 0,
      +        "type": "integer"
      +      },
      +      "mandate_id": {
      +        "description": "Your identifier for this mandate.",
      +        "maxLength": 128,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "max_amount_cents": {
      +        "description": "Spending limit the buyer gave you, as an integer in minor units (cents).",
      +        "exclusiveMinimum": 0,
      +        "type": "integer"
      +      },
      +      "sub": {
      +        "description": "The identity you authenticate as — it is compared against it. When the credential tool returns a `mandate_subject`, use that value.",
      +        "maxLength": 256,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "mandate_id",
      +      "max_amount_cents",
      +      "currency",
      +      "exp",
      +      "sub",
      +      "aud"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
  5. Changed1 schema field changed
    • addedOutput schema / properties / payment_options / items / properties / charges_without_approval
      Added value: +{
      +  "const": true,
      +  "type": "boolean"
      +}
  6. 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"
      +]
  7. Changed1 schema field changed
    • 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"
      +}
  8. 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"
      +]
  9. 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"
      +]
  10. 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"
      +}
  11. Changed6 schema fields changed
    • addedOutput schema / properties / approval_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / approval_status_url
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / approval_url
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / expires_at
      Added value: +{
      +  "type": "string"
      +}
    • removedOutput schema / properties / status / const
      Removed value: -"READY_FOR_PAYMENT"
    • addedOutput schema / properties / status / enum
      Added value: +[
      +  "READY_FOR_PAYMENT",
      +  "PENDING_APPROVAL"
      +]
  12. Changed5 schema fields changed
    • addedOutput schema / properties / tax_cents
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / tax_status
      Added value: +{
      +  "enum": [
      +    "included",
      +    "not_calculated"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / total_is_final
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / total_note
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "checkout_session_id",
      -  "store_name",
      -  "items",
      -  "subtotal_cents",
      -  "shipping_cents",
      -  "discount_cents",
      -  "total_cents",
      -  "currency",
      -  "status"
      -]New value: +[
      +  "checkout_session_id",
      +  "store_name",
      +  "items",
      +  "subtotal_cents",
      +  "shipping_cents",
      +  "discount_cents",
      +  "total_cents",
      +  "currency",
      +  "tax_cents",
      +  "tax_status",
      +  "total_is_final",
      +  "total_note",
      +  "status"
      +]
  13. Changed1 schema field changed
    • changedInput schema / properties / payment_mandate / description
      Previous value: -"Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (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."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` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header."
  14. Changed2 schema fields changed
    • addedOutput schema / properties / shipping_authoritative
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / shipping_source
      Added value: +{
      +  "enum": [
      +    "platform",
      +    "merchant_policy",
      +    "estimated"
      +  ],
      +  "type": "string"
      +}
  15. 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."
  16. Changed2 schema fields 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"
      +}
    • 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."
      +}
  17. Changed3 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / items / items / additionalProperties
      Previous value: -falseNew value: +true
  18. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "checkout_session_id": {
      +      "type": "string"
      +    },
      +    "currency": {
      +      "type": "string"
      +    },
      +    "discount_cents": {
      +      "type": "number"
      +    },
      +    "items": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "line_price": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "quantity": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "quantity",
      +          "line_price"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "shipping_cents": {
      +      "type": "number"
      +    },
      +    "shipping_title": {
      +      "type": "string"
      +    },
      +    "status": {
      +      "const": "READY_FOR_PAYMENT",
      +      "type": "string"
      +    },
      +    "store_name": {
      +      "type": "string"
      +    },
      +    "subtotal_cents": {
      +      "type": "number"
      +    },
      +    "total_cents": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "checkout_session_id",
      +    "store_name",
      +    "items",
      +    "subtotal_cents",
      +    "shipping_cents",
      +    "discount_cents",
      +    "total_cents",
      +    "currency",
      +    "status"
      +  ],
      +  "type": "object"
      +}
  19. 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: +{
      +  "cart_id": {
      +    "description": "Cart session ID returned by create_cart",
      +    "type": "string"
      +  }
      +}
    • addedInput schema / required
      Added value: +[
      +  "cart_id"
      +]
  20. 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: -{
      -  "cart_id": {
      -    "description": "Cart session ID returned by create_cart",
      -    "type": "string"
      -  }
      -}
    • removedInput schema / required
      Removed value: -[
      -  "cart_id"
      -]
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "checkout_session_id": {
      -      "type": "string"
      -    },
      -    "currency": {
      -      "type": "string"
      -    },
      -    "discount_cents": {
      -      "type": "number"
      -    },
      -    "items": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "line_price": {
      -            "type": "number"
      -          },
      -          "name": {
      -            "type": "string"
      -          },
      -          "quantity": {
      -            "type": "number"
      -          }
      -        },
      -        "required": [
      -          "name",
      -          "quantity",
      -          "line_price"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "shipping_cents": {
      -      "type": "number"
      -    },
      -    "shipping_title": {
      -      "type": "string"
      -    },
      -    "status": {
      -      "const": "READY_FOR_PAYMENT",
      -      "type": "string"
      -    },
      -    "store_name": {
      -      "type": "string"
      -    },
      -    "subtotal_cents": {
      -      "type": "number"
      -    },
      -    "total_cents": {
      -      "type": "number"
      -    }
      -  },
      -  "required": [
      -    "checkout_session_id",
      -    "store_name",
      -    "items",
      -    "subtotal_cents",
      -    "shipping_cents",
      -    "discount_cents",
      -    "total_cents",
      -    "currency",
      -    "status"
      -  ],
      -  "type": "object"
      -}New value: +null
  21. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations: it discloses the state transition to ready-for-payment, that an approval is opened and bound to the agent credential without verifying a person was present, and the full credential acquisition path via create_sandbox_key. The non-idempotent, non-readonly nature is confirmed rather than contradicted. It stops short of describing what the returned summary contains, but an output schema exists.

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?

Front-loaded with purpose and the sibling alternative before the operational details, and each paragraph (alternative, card preference, guide, credential) carries distinct, actionable information. Minor filler in 'it keeps the flow in one card' does not undermine the structure.

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?

Covers the mutation, the alternatives, the credential requirement and the no-human-login constraint, which is the full set of things an agent needs to invoke this correctly; the return shape is left to the output schema. The one soft spot is that the description does not explain how buyer_intent or payment_mandate should be prioritized on a first call versus a retry.

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 adds sequencing ('call create_sandbox_key first, then pass the key as agent_key — or as an Authorization: Bearer header'), which tells the agent how to obtain and place the credential rather than just what the field is.

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 ('Preview the complete order summary before payment') and immediately distinguishes its effect ('Advances the session to ready-for-payment state') from the sibling quote_checkout, which computes the same total without advancing state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (preparing for payment), an explicit when-not/alternative (price only → quote_checkout, which avoids advancing the session or opening an approval), and a preference rule (use the interactive cart card if one exists). It also points to the checkout guide resource for the broader flow.

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