Skip to main content
Glama

create_cart

Idempotent

Create a shopping cart in Demo Store. Returns a cart_id. Pass it as cart_id to get_shipping_rates, select_shipping_option, apply_discount and preview_checkout; complete_checkout and get_trust_receipt take the same value as checkout_session_id.

KYA IDENTITY: a Skyfire kya token has no effect on this tool (it grants no trust boost here); KYA identity applies to the REST agent API (Authorization: Bearer), not to the MCP tools. 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": {
      "items": "<items>"
    },
    "name": "create_cart"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYesItems to add to cart
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
agent_tokenNoJWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. A malformed token fails with AGENT_TOKEN_INVALID on any platform. On Shopify stores Trusteed also verifies the signature on receipt against a registered key that must belong to the calling agent (otherwise AGENT_TOKEN_INVALID and no cart is created), and the checkout Function verifies it again offline at payment. On other platforms Trusteed checks its structure only and forwards it to the store.
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.
display_contextNoAgent display capability: webview (browser) or headlessheadless
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.
agent_session_idNoOpaque agent session identifier for cart resume across sessions

Output Schema

NameRequiredDescriptionDefault
itemsYes
statusYes
cart_idYes
currencyYes
next_stepYes
expires_atNoISO-8601 UTC instant at which this checkout SESSION stops being usable. It is not a stock reservation and not a price guarantee.
store_nameYes
session_stateYes
subtotal_centsYes
display_contextYes
agent_session_idYes
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.

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. Changed2 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"
      +}
  3. Changed3 schema fields changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Idempotency key for this cart creation (UUID-v4 or bounded ASCII token, 1-128 chars). Equivalent to the `Idempotency-Key` header — send it here if your client cannot set headers. Retrying with the same key returns the same cart instead of creating a second one."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}$"
  4. Changed1 schema field changed
    • changedInput schema / properties / agent_token / description
      Previous value: -"JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. The token is embedded as a server-authoritative cart attribute — Trusteed does NOT verify the signature here; that is done offline by the Shopify Function WASM."New value: +"JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. A malformed token fails with AGENT_TOKEN_INVALID on any platform. On Shopify stores Trusteed also verifies the signature on receipt against a registered key that must belong to the calling agent (otherwise AGENT_TOKEN_INVALID and no cart is created), and the checkout Function verifies it again offline at payment. On other platforms Trusteed checks its structure only and forwards it to the store."
  5. 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"
      +}
  6. Changed2 schema fields changed
    • addedOutput schema / properties / next_step
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "cart_id",
      -  "store_name",
      -  "items",
      -  "subtotal_cents",
      -  "currency",
      -  "status",
      -  "agent_session_id",
      -  "session_state",
      -  "display_context"
      -]New value: +[
      +  "cart_id",
      +  "store_name",
      +  "items",
      +  "subtotal_cents",
      +  "currency",
      +  "status",
      +  "agent_session_id",
      +  "session_state",
      +  "display_context",
      +  "next_step"
      +]
  7. Changed2 schema fields changed
    • addedOutput schema / properties / items / items / properties / line_price_cents
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / items / items / properties / unit_price_cents
      Added value: +{
      +  "type": "number"
      +}
  8. Changed1 schema field changed
    • addedOutput schema / properties / items / items / properties / image
      Added value: +{
      +  "type": "string"
      +}
  9. 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."
      -}
  10. 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` (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."
      +}
  11. Changed1 schema field changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "Idempotency key for this cart creation (UUID-v4 or bounded ASCII token, 1-128 chars). Equivalent to the `Idempotency-Key` header — send it here if your client cannot set headers. Retrying with the same key returns the same cart instead of creating a second one.",
      +  "type": "string"
      +}
  12. Changed2 schema fields changed
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / items / items / additionalProperties
      Previous value: -falseNew value: +true
  13. Changed4 schema fields changed
    • changedInput schema / properties / items / items / properties / variant_id / description
      Previous value: -"Variant ID (optional)"New value: +"Variant ID (optional). Must match a variant id listed by get_product_details; an unknown id is rejected rather than silently replaced by the default variant."
    • addedOutput schema / properties / items / items / properties / sku
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / variant_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / variant_title
      Added value: +{
      +  "type": "string"
      +}
  14. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "agent_session_id": {
      +      "type": "string"
      +    },
      +    "cart_id": {
      +      "type": "string"
      +    },
      +    "currency": {
      +      "type": "string"
      +    },
      +    "display_context": {
      +      "enum": [
      +        "webview",
      +        "headless"
      +      ],
      +      "type": "string"
      +    },
      +    "items": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "line_price": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "quantity": {
      +            "type": "number"
      +          },
      +          "unit_price": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "quantity",
      +          "unit_price",
      +          "line_price"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "session_state": {
      +      "enum": [
      +        "new",
      +        "resumed"
      +      ],
      +      "type": "string"
      +    },
      +    "status": {
      +      "const": "NOT_READY_FOR_PAYMENT",
      +      "type": "string"
      +    },
      +    "store_name": {
      +      "type": "string"
      +    },
      +    "subtotal_cents": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "cart_id",
      +    "store_name",
      +    "items",
      +    "subtotal_cents",
      +    "currency",
      +    "status",
      +    "agent_session_id",
      +    "session_state",
      +    "display_context"
      +  ],
      +  "type": "object"
      +}
  15. 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: +{
      +  "agent_session_id": {
      +    "description": "Opaque agent session identifier for cart resume across sessions",
      +    "type": "string"
      +  },
      +  "agent_token": {
      +    "description": "JWS compact (EdDSA/Ed25519) signed by the agent. Required for Shopify enforcement rules R001/R002/R004. The token is embedded as a server-authoritative cart attribute — Trusteed does NOT verify the signature here; that is done offline by the Shopify Function WASM.",
      +    "type": "string"
      +  },
      +  "display_context": {
      +    "default": "headless",
      +    "description": "Agent display capability: webview (browser) or headless",
      +    "enum": [
      +      "webview",
      +      "headless"
      +    ],
      +    "type": "string"
      +  },
      +  "items": {
      +    "description": "Items to add to cart",
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "product_id": {
      +          "description": "Product ID",
      +          "type": "string"
      +        },
      +        "quantity": {
      +          "default": 1,
      +          "description": "Quantity",
      +          "minimum": 1,
      +          "type": "integer"
      +        },
      +        "variant_id": {
      +          "description": "Variant ID (optional)",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "product_id"
      +      ],
      +      "type": "object"
      +    },
      +    "minItems": 1,
      +    "type": "array"
      +  }
      +}
    • addedInput schema / required
      Added value: +[
      +  "items"
      +]
  16. 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: -{
      -  "agent_session_id": {
      -    "description": "Opaque agent session identifier for cart resume across sessions",
      -    "type": "string"
      -  },
      -  "display_context": {
      -    "default": "headless",
      -    "description": "Agent display capability: webview (browser) or headless",
      -    "enum": [
      -      "webview",
      -      "headless"
      -    ],
      -    "type": "string"
      -  },
      -  "items": {
      -    "description": "Items to add to cart",
      -    "items": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "product_id": {
      -          "description": "Product ID",
      -          "type": "string"
      -        },
      -        "quantity": {
      -          "default": 1,
      -          "description": "Quantity",
      -          "minimum": 1,
      -          "type": "integer"
      -        },
      -        "variant_id": {
      -          "description": "Variant ID (optional)",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "product_id"
      -      ],
      -      "type": "object"
      -    },
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -}
    • removedInput schema / required
      Removed value: -[
      -  "items"
      -]
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "agent_session_id": {
      -      "type": "string"
      -    },
      -    "cart_id": {
      -      "type": "string"
      -    },
      -    "currency": {
      -      "type": "string"
      -    },
      -    "display_context": {
      -      "enum": [
      -        "webview",
      -        "headless"
      -      ],
      -      "type": "string"
      -    },
      -    "items": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "line_price": {
      -            "type": "number"
      -          },
      -          "name": {
      -            "type": "string"
      -          },
      -          "quantity": {
      -            "type": "number"
      -          },
      -          "unit_price": {
      -            "type": "number"
      -          }
      -        },
      -        "required": [
      -          "name",
      -          "quantity",
      -          "unit_price",
      -          "line_price"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "session_state": {
      -      "enum": [
      -        "new",
      -        "resumed"
      -      ],
      -      "type": "string"
      -    },
      -    "status": {
      -      "const": "NOT_READY_FOR_PAYMENT",
      -      "type": "string"
      -    },
      -    "store_name": {
      -      "type": "string"
      -    },
      -    "subtotal_cents": {
      -      "type": "number"
      -    }
      -  },
      -  "required": [
      -    "cart_id",
      -    "store_name",
      -    "items",
      -    "subtotal_cents",
      -    "currency",
      -    "status",
      -    "agent_session_id",
      -    "session_state",
      -    "display_context"
      -  ],
      -  "type": "object"
      -}New value: +null
  17. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: it explains that the idempotency key is required for this write and can be supplied three ways, that agent_token is signature-verified on Shopify (AGENT_TOKEN_INVALID, no cart created) versus structure-checked elsewhere, and that a Skyfire kya token grants no benefit here. It also notes that buyer_intent can halt a mismatched purchase before charging, which is material behavior not captured by readOnly/destructive hints.

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-loads purpose and the cart_id handoff before the credential and KYA material, which is the right ordering for an agent deciding whether to call. The KYA paragraph is the longest and least actionable section, costing some tightness, but no sentence is pure filler.

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

Completeness5/5

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

For a 7-parameter write tool with a nested items array, the description covers the credential bootstrap, idempotency requirement, token failure modes, and downstream consumers. An output schema exists, so the absence of return-value detail is not a gap.

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 already 100%, so the baseline is 3, but the description adds real meaning: it ties agent_key to create_sandbox_key's output, clarifies the header alternative, and explains the downstream reuse of the returned cart_id. It leaves agent_session_id and display_context to the schema, which is acceptable given full coverage.

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?

Opens with a specific verb and resource ('Create a shopping cart in Demo Store') and immediately states the return value ('Returns a cart_id'). It then enumerates exactly which sibling tools consume that value and under which argument name (cart_id vs checkout_session_id), so an agent can place it in the workflow without opening other schemas.

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

Usage Guidelines4/5

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

Gives strong prerequisite guidance: call create_sandbox_key first, pass the result as agent_key or as an Authorization Bearer header, and explicitly says not to ask a human to log in. It also routes the agent to the trusteed://guides/checkout resource. It does not state when to prefer this over the ucp_create_checkout sibling, so it stops short of full when/when-not coverage.

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