SuperCheap

Set cart item

cart_set_item

DestructiveIdempotent

Set the exact cart line quantity and wholesale selection. This overwrites the quantity and wholesale setting for the same itemId/configurationId; it does not add to the quantity. Omitting wholesale uses standard pricing. Appends a new line when that itemId/configurationId is not already in the cart. For a supplier preview, first call catalog_get_product and wait for full product details; use only a configuration and buyer offer actually returned there. Current pricing and availability are re-quoted. Returns the updated cart view. Requires cart:write scope. Use cart_remove_item to remove a line.

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": {
      "countryCode": "<countryCode>",
      "currencyCode": "<currencyCode>",
      "languageCode": "<languageCode>",
      "itemId": "<itemId>",
      "quantity": "<quantity>"
    },
    "name": "cart_set_item"
  }
}

Input Schema

Name	Required	Description
`itemId`	Yes	SuperCheap product ID from full catalog_get_product details. Open supplier previews with catalog_get_product and wait for complete variants and buyer offers before adding.
`source`	No
`channel`	No
`quantity`	Yes	Exact line quantity. Replaces current quantity for this itemId/configurationId (not additive).
`wholesale`	No	Enable wholesale pricing for this line.
`collection`	No	Copy the collection tag from the product card that led to this cart change.
`countryCode`	Yes	ISO 3166-1 alpha-2 market country code. Choose from market_list output.
`currencyCode`	Yes	ISO 4217 alpha-3 market currency code. Choose from market_list output.
`languageCode`	Yes	Lowercase ISO 639-1 language code. Choose from market_list output.
`configurationId`	No	Variant or option selection ID as returned by catalog_get_product. Omit for products without configurations.
`sourceSchemaVersion`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 24, 2026

addedInput schema / properties / channel

Added value: +{
+  "enum": [
+    "category",
+    "home",
+    "image",
+    "pinterest",
+    "search",
+    "similar",
+    "supplier"
+  ],
+  "type": "string"
+}

addedInput schema / properties / collection

Added value: +{
+  "description": "Copy the collection tag from the product card that led to this cart change.",
+  "maxLength": 64,
+  "type": "string"
+}

addedInput schema / properties / source

Added value: +{
+  "maximum": 2147483647,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / sourceSchemaVersion

Added value: +{
+  "const": 1,
+  "type": "number"
+}

Changed1 schema field changedOct 3, 2026

changedInput schema / properties / itemId / description

Previous value: -"Canonical SuperCheap product ID from catalog search or product details."New value: +"SuperCheap product ID from full catalog_get_product details. Open supplier previews with catalog_get_product and wait for complete variants and buyer offers before adding."

Changed7 schema fields changedOct 2, 2026

addedInput schema / properties / configurationId / description

Added value: +"Variant or option selection ID as returned by catalog_get_product. Omit for products without configurations."

addedInput schema / properties / countryCode / description

Added value: +"ISO 3166-1 alpha-2 market country code. Choose from market_list output."

addedInput schema / properties / currencyCode / description

Added value: +"ISO 4217 alpha-3 market currency code. Choose from market_list output."

addedInput schema / properties / itemId / description

Added value: +"Canonical SuperCheap product ID from catalog search or product details."

addedInput schema / properties / languageCode / description

Added value: +"Lowercase ISO 639-1 language code. Choose from market_list output."

addedInput schema / properties / quantity / description

Added value: +"Exact line quantity. Replaces current quantity for this itemId/configurationId (not additive)."

addedInput schema / properties / wholesale / description

Added value: +"Enable wholesale pricing for this line."

First observedOct 2, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Adds substantial context beyond the annotations: cart:write scope requirement, that existing quantity/wholesale for the same itemId/configurationId are overwritten, that pricing is re-quoted at write time, and that the updated cart view is returned. The one gap is whether other line properties (source, channel, collection) are replaced or preserved on an existing line, which matters for a tool flagged destructiveHint=true.

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 the core save/overwrite semantics and keeps the alternative and scope note to the end. Slightly repetitive with the itemId parameter description, which repeats the supplier-preview instruction almost verbatim, but no sentence is wasted.

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?

For an 11-parameter mutation with no output schema, the description covers the return value ('updated cart view'), the auth requirement, and the upstream supplier-preview flow. What remains thin is the behavior of the optional attribution parameters and the failure modes when a configuration is no longer available.

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 73%, and the description adds meaning on top: the default behavior when wholesale is omitted ('uses standard pricing') and the guidance to source configurationId/itemId only from a completed catalog_get_product call. source, channel and sourceSchemaVersion remain undocumented in both places, so it is not a 5.

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 with its exact semantics: 'Set the exact cart line quantity and wholesale selection', immediately disambiguating from the sibling cart_remove_item. The overwrite-vs-add and append-if-absent rules make the operation unambiguous without opening the schema.

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 an explicit prerequisite chain ('first call catalog_get_product and wait for full product details; use only a configuration and buyer offer actually returned there') and names the alternative for the opposite action ('Use cart_remove_item to remove a line'). It also warns that quantities are not additive, which is the main misuse risk.

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

All SuperCheap 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?