Trusteed Agentic Commerce

select_shipping_option

Idempotent

Select a shipping method for the cart. Must call get_shipping_rates first and provide idempotency_key. Reuse the same key for retries of the same cart and option; use a new key if either changes.

PREFER THE CART CARD: if there is an interactive card for this cart, let the buyer pick shipping there instead of calling this tool yourself — it keeps the flow in one card instead of opening a new one per step. 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
`cart_id`	Yes	Cart session ID
`agent_key`	No	Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
`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.
`shipping_handle`	Yes	Shipping method handle from get_shipping_rates

Output Schema

Name	Required	Description	Default
`cart_id`	Yes
`currency`	Yes
`total_cents`	Yes
`selected_title`	Yes
`shipping_cents`	Yes
`subtotal_cents`	Yes
`selected_handle`	Yes
`shipping_source`	Yes
`shipping_authoritative`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 15, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. 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 / required

Previous value: -[
-  "cart_id",
-  "shipping_handle",
-  "idempotency_key"
-]New value: +[
+  "cart_id",
+  "shipping_handle"
+]

Changed2 schema fields changedOct 15, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Required. Reuse this key only when retrying the same cart and shipping option; use a new key if either changes."New value: +"REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation."

removedInput schema / properties / idempotency_key / minLength
```
Removed value: -1
```

Changed2 schema fields changedSep 24, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Required. Reuse this key only when retrying the same cart and shipping option; use a new key if either changes.",
+  "maxLength": 128,
+  "minLength": 1,
+  "pattern": "^[A-Za-z0-9._:/-]{1,128}$",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "cart_id",
-  "shipping_handle"
-]New value: +[
+  "cart_id",
+  "shipping_handle",
+  "idempotency_key"
+]

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

Changed1 schema field changedSep 21, 2026

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

Changed2 schema fields changedSep 20, 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`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."
+}

Changed2 schema fields changedSep 17, 2026
- changedInput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

Changed3 schema fields changedSep 10, 2026

addedOutput schema / properties / shipping_authoritative
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / shipping_source

Added value: +{
+  "enum": [
+    "platform",
+    "merchant_policy",
+    "estimated"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "cart_id",
-  "selected_handle",
-  "selected_title",
-  "shipping_cents",
-  "subtotal_cents",
-  "total_cents",
-  "currency"
-]New value: +[
+  "cart_id",
+  "selected_handle",
+  "selected_title",
+  "shipping_cents",
+  "subtotal_cents",
+  "total_cents",
+  "currency",
+  "shipping_source",
+  "shipping_authoritative"
+]

Changed1 schema field changedSep 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "cart_id": {
+      "type": "string"
+    },
+    "currency": {
+      "type": "string"
+    },
+    "selected_handle": {
+      "type": "string"
+    },
+    "selected_title": {
+      "type": "string"
+    },
+    "shipping_cents": {
+      "type": "number"
+    },
+    "subtotal_cents": {
+      "type": "number"
+    },
+    "total_cents": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "cart_id",
+    "selected_handle",
+    "selected_title",
+    "shipping_cents",
+    "subtotal_cents",
+    "total_cents",
+    "currency"
+  ],
+  "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: +{
+  "cart_id": {
+    "description": "Cart session ID",
+    "type": "string"
+  },
+  "shipping_handle": {
+    "description": "Shipping method handle from get_shipping_rates",
+    "type": "string"
+  }
+}

addedInput schema / required

Added value: +[
+  "cart_id",
+  "shipping_handle"
+]

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: -{
-  "cart_id": {
-    "description": "Cart session ID",
-    "type": "string"
-  },
-  "shipping_handle": {
-    "description": "Shipping method handle from get_shipping_rates",
-    "type": "string"
-  }
-}

removedInput schema / required

Removed value: -[
-  "cart_id",
-  "shipping_handle"
-]

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "cart_id": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "selected_handle": {
-      "type": "string"
-    },
-    "selected_title": {
-      "type": "string"
-    },
-    "shipping_cents": {
-      "type": "number"
-    },
-    "subtotal_cents": {
-      "type": "number"
-    },
-    "total_cents": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "cart_id",
-    "selected_handle",
-    "selected_title",
-    "shipping_cents",
-    "subtotal_cents",
-    "total_cents",
-    "currency"
-  ],
-  "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 mark this as a non-read-only, idempotent, non-destructive local write, and the description adds substantially more: the idempotency-key lifecycle (reuse for same cart+option, new key when either changes), the sandbox credential requirement, and that no human login exists. This is exactly the context an agent needs before a credentialed write.

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?

Action, precondition, and idempotency rule are front-loaded, then the card preference, then credentials. The credential paragraph runs long and partially duplicates the agent_key schema description, but every block carries actionable information.

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?

Preconditions, idempotency semantics, credential acquisition, and the preferred interactive alternative are all covered, and an output schema exists so return values need no explanation. Nothing required to invoke this write 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 a nuance the schema lacks: the key must be reused for retries of the same cart AND option, and changed if either changes. The agent_key fallback path is also reiterated. This is meaningful added semantics beyond the 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 and resource ('Select a shipping method for the cart') and immediately distinguishes itself from the sibling get_shipping_rates by making it a prerequisite rather than an alternative. An agent knows exactly what this tool does versus the rate-lookup tool.

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?

Explicitly states the precondition (call get_shipping_rates first), gives idempotency-key reuse policy, and routes the agent away from the tool entirely when an interactive cart card exists. The credential path and the 'no human login' constraint are also spelled out, leaving little to inference.

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

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?