Trusteed Agentic Commerce

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.

Input Schema

Name	Required	Description	Default
`items`	Yes	Items to add to cart
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`agent_token`	No	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.
`display_context`	No	Agent display capability: webview (browser) or headless	headless
`idempotency_key`	No	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.
`agent_session_id`	No	Opaque agent session identifier for cart resume across sessions

Output Schema

Name	Required	Description
`items`	Yes
`status`	Yes
`cart_id`	Yes
`currency`	Yes
`next_step`	Yes
`expires_at`	No	ISO-8601 UTC instant at which this checkout SESSION stops being usable. It is not a stock reservation and not a price guarantee.
`store_name`	Yes
`session_state`	Yes
`subtotal_cents`	Yes
`display_context`	Yes
`agent_session_id`	Yes
`expires_in_seconds`	No	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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 15, 2026

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}$"
```

Changed1 schema field changedOct 14, 2026

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."

Changed2 schema fields changedOct 10, 2026

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"
+}

Changed2 schema fields changedSep 24, 2026

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"
+]

Changed2 schema fields changedSep 24, 2026
- 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"
+}
```
Changed1 schema field changedSep 23, 2026
- addedOutput schema / properties / items / items / properties / image
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedSep 22, 2026

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."
-}

Changed2 schema fields changedSep 22, 2026

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."
+}

Changed1 schema field changedSep 21, 2026

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"
+}

Changed2 schema fields changedSep 17, 2026
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / properties / items / items / additionalProperties
```
Previous value: -falseNew value: +true
```
Changed4 schema fields changedSep 11, 2026
- 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"
+}
```

Changed1 schema field changedSep 8, 2026

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"
+}

Changed4 schema fields changedAug 24, 2026

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"
+]
```

Changed5 schema fields changedJul 10, 2026

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

First observedApr 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), and the description goes well beyond them by disclosing the credential model, the fact that a Skyfire kya token has no effect here, and the distinction between MCP auth and the REST agent API. This is exactly the auth/permission context annotations cannot carry.

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

Conciseness4/5

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

Front-loaded with purpose and downstream routing first, credentials and identity caveats after. The uppercase labels (KYA IDENTITY, CREDENTIAL) aid scanning, though the block is dense enough that it reads more like a runbook than a description.

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?

An output schema exists so return values need no explanation, and for a 6-parameter write tool the description still covers the credential prerequisite, the identity caveat, the downstream tool chain, and a guide pointer. Nothing an agent needs to call this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic glue by documenting how the output value flows into differently-named parameters (cart_id vs checkout_session_id) and by clarifying the agent_key/header relationship. It adds meaning without re-stating the schema's own field descriptions.

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+resource ('Create a shopping cart in Demo Store') and names the concrete artifact produced ('Returns a cart_id'). It also disambiguates from the large checkout sibling cluster by mapping its output to the exact parameter names downstream tools expect, 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 Guidelines5/5

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

Explicit ordering and prerequisites: call create_sandbox_key first, then pass the returned key as agent_key or an Authorization header. It also states when-not (no human login exists for this store) and points to the authoritative checkout guide resource, leaving no routing inference to the agent.

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

All Trusteed Agentic Commerce tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?