mcp-gateway

select_shipping_option

Idempotent

Select a shipping method for the cart. Must call get_shipping_rates first.

SKYFIRE TOKEN (optional): Pass a kya or kya-pay token in the skyfire-pay-id header to boost trust score. No token required — request proceeds normally if omitted. PAYMENT MANDATE: this tool also requires one. Send it as the payment_mandate argument if your client cannot set headers, or as an X-Payment-Mandate header. It must carry mandate_id, max_amount_cents, currency, exp, sub, aud, and its currency must match the cart's currency or the call is denied outright. The cap in max_amount_cents is enforced against the cart total. 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

TableJSON 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.
`payment_mandate`	No	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.
`shipping_handle`	Yes	Shipping method handle from get_shipping_rates

Output Schema

TableJSON 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 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.4/5.0

Behavior4/5

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

The description goes well beyond the annotations by disclosing authentication requirements, the mandatory payment mandate, currency-matching enforcement, the max_amount_cents cap, and the optional skyfire token behavior. It also clarifies that the call is denied outright on currency mismatch. This is strong behavioral context; a slight deduction is warranted because it does not describe the mutation effect on the cart or any idempotency-relevant behavior beyond the annotation.

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?

The description is long but well-structured with clear all-caps sections and front-loaded purpose. Every section carries actionable detail, but it could be tightened; for example, the header-vs-argument alternatives are stated multiple times for both agent_key and payment_mandate. Still, it remains focused and scannable.

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 tool with authentication, a payment mandate, and prerequisite calls, the description is remarkably complete: it covers the prerequisite sequence, credential acquisition, header/argument alternatives, mandatory mandate contents, denial conditions, and the lack of human login. With an output schema present and full input schema coverage, an agent has everything needed to invoke this tool correctly.

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 meaningful meaning to agent_key and payment_mandate by explaining how to obtain the credential via create_sandbox_key, when to use arguments versus headers, and the required mandate fields/currency rule. This exceeds schema-only documentation, though cart_id and shipping_handle receive no additional explanation beyond the schema.

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?

The description opens with a specific verb and resource: 'Select a shipping method for the cart.' It clearly distinguishes the tool from the sibling get_shipping_rates by requiring that tool to be called first, and the shipping_handle parameter is explicitly tied to get_shipping_rates output. This leaves no ambiguity about what the tool does.

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?

The description gives clear workflow guidance: call get_shipping_rates first, then select a shipping option, and for credentials call create_sandbox_key first. It also states that no human login exists. However, it does not explicitly say when not to use this tool, such as 'use complete_checkout instead when finalizing the purchase,' so it falls short of fully explicit alternative routing.

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

All mcp-gateway 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?