stub

Save variant

save_variant

Create or update an OPTION (size, colour, pack) under an existing product; for the product itself, use save_product. Pass an id to update it; omit id to create a new one. Returns the new variant id on create. To create/update many at once, send an items array — one all-or-nothing transaction with a single ledger recompute; each item with an id updates, each without creates.

Input Schema

Name	Required	Description
`id`	No	Variant id. Present → update that variant; omit → create a new one.
`sku`	No	Stock-keeping unit / product code.
`cost`	No	Cost price per unit.
`name`	No	Display name / description of the variant.
`image`	No	Variant image URL; pass "$delete" to remove the existing image.
`items`	No	Vector of variant objects to create/update in one all-or-nothing batch. Preferred over repeated calls. Each item with an id updates; each without creates.
`notes`	No	Free-text notes.
`price`	No	Selling price per unit, in the record's currency.
`units`	No	Unit of measure label (e.g. "each", "hour", "kg").
`barcode`	No	Barcode value for this variant.
`archived`	No	Archive (true) or unarchive (false) the variant. An archived variant is kept with its history and stays in the product's variants; it is not deleted.
`currency`	No	ISO 4217 currency code (e.g. "ZAR", "USD"). Defaults to the business currency.
`productid`	No	Parent product id this variant belongs to (see list_products).
`description`	No	Variant description.
`salestaxids`	No	Sales tax ids to link to this variant.
`costcurrency`	No	ISO 4217 currency code for the cost price.
`stocklocationid`	No	Default stock location id for this variant; empty inherits the product's. Pass "$delete" to clear it.
`salestaxexclusive`	No	Whether the price excludes sales tax.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 6, 2026

addedInput schema / properties / archived

Added value: +{
+  "description": "Archive (true) or unarchive (false) the variant. An archived variant is kept with its history and stays in the product's variants; it is not deleted.",
+  "type": "boolean"
+}

addedInput schema / properties / items / items / properties / archived

Added value: +{
+  "description": "Archive (true) or unarchive (false) the variant. An archived variant is kept with its history and stays in the product's variants; it is not deleted.",
+  "type": "boolean"
+}

addedInput schema / properties / items / items / properties / stocklocationid

Added value: +{
+  "description": "Default stock location id for this variant; empty inherits the product's. Pass \"$delete\" to clear it.",
+  "type": "string"
+}

addedInput schema / properties / stocklocationid

Added value: +{
+  "description": "Default stock location id for this variant; empty inherits the product's. Pass \"$delete\" to clear it.",
+  "type": "string"
+}

First observedSep 7, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely useful behaviour beyond that — the bulk path is 'one all-or-nothing transaction with a single ledger recompute' (atomicity plus a side effect on the ledger) and create returns the new variant id. It does not state permission requirements or what happens to top-level params when `items` is supplied, so it stops short of fully transparent.

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?

Three sentences, front-loaded with purpose and the sibling exclusion, then the create/update switch, then bulk mode. The bulk sentence is dense but every clause ('all-or-nothing', 'single ledger recompute', 'each with an `id` updates') carries information rather than filler.

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?

With 18 optional params and no output schema, the description covers the two things an agent most needs: the create-vs-update discriminator and the batch alternative, plus a return value on create that the absent output schema would otherwise leave unknown. The one real gap is that it never says whether top-level fields are ignored when `items` is passed, which matters given the duplicated field sets.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter (including `id` create-vs-update and `items` semantics) is already documented in the schema; the description largely restates that. It adds no syntax, format, or defaulting detail beyond what the schema provides, so the baseline 3 applies.

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 or update an OPTION ... under an existing product') and immediately scopes it with examples (size, colour, pack). It also names the sibling it is not ('for the product itself, use save_product'), so an agent can separate it from save_product and delete_variant without opening any 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 explicit routing rules: save_product for the product, save_variant for the option under it; pass `id` to update, omit `id` to create; send an `items` array for bulk rather than repeated calls. Both the alternative tool and the selection condition are spelled out.

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

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