Skip to main content
Glama

Order: Edit Supplier

update_order_supplier
Destructive

[Order] [What it does] Changes the supplier product and/or fulfillment Variant used by one order item. It can switch suppliers, select another product or Variant from the same supplier, or change only the fulfillment Variant while keeping the supplier and product unchanged. This edit affects the current order only: it does not change the buyer's original sales-channel SKU/Variant or the product's long-term Mapping. [When to use] Use when the current supplier product or Variant is unavailable, out of stock, mispriced, cannot ship, or when the user explicitly chooses a different fulfillment Variant for this order. [When not to use] To change the permanent product Mapping used by future orders, use apply_product_mapping. To change the buyer-facing sales-channel SKU/Variant, use the sales-channel workflow. The current supplier row must still be unplaced, cancelled, or failed; placed, in-progress, paid, shipped, fulfilled, or otherwise locked rows cannot be edited. [How to use] Read the exact order and item with get_order, including its current supplier row and fulfillment Variant. Resolve and validate the selected supplier product, fulfillment Variant, stock, price, destination support, and freight. Pass exactly one of supplier_product_id and supplier_product_url; supplier_platform_id is required with either input. Before writing, show the old and new supplier, supplier product, fulfillment Variant name and ID, product price, freight, stock, and net cost change; label unavailable comparison values as unavailable rather than guessing. Obtain the user's explicit confirmation and their explicit allow_future_mapping_override choice. true allows a later product-level Mapping update to replace this order's manual fulfillment selection; false keeps the manual selection fixed against later Mapping updates. This choice does not modify the buyer's original SKU/Variant or immediately change product-level Mapping. If the write outcome is unknown, re-read get_order and the Orders page; never automatically retry. [Side effects] Changes the supplier product, fulfillment Variant, and applicable freight used for this order item, which can change fulfillment cost and delivery details. It does not change the buyer's original sales-channel SKU/Variant or immediately modify product-level Mapping. [Confirmation] Required, never skippable: show the complete old-versus-new fulfillment comparison and obtain the Mapping-override choice before calling.

Input Schema

NameRequiredDescriptionDefault
ship_fromNoOptional quote origin; required only when the service ID is ambiguous across origins.
dsers_order_idYesExactly one DSers order ID returned by list_orders.
shipping_currencyNoCurrency used to refresh and validate freight quotes.USD
shipping_method_idNoExact quotes[].service_id from list_supplier_product_shipping_methods_and_cost for the selected product, variant, and current order destination. Required and non-empty for non-Agent suppliers. Optional for Agent/点石; omit or pass empty to skip freight preflight. If supplied, supplier_product_variant_id is still required.
dsers_order_item_idYesExact items[].dsers_order_item_id from get_order.
supplier_product_idNoExact supplier product ID from supplier search/detail. Provide this or supplier_product_url, never both.
supplier_platform_idYesSelected supplier platform ID from supplier search/detail.
supplier_product_urlNoSupplier product URL to use for the replacement. Provide this instead of supplier_product_id, never both; supplier_platform_id remains required.
supplier_order_item_idNoExact current items[].suppliers[].supplier_order_item_id. Omit for an unmapped item or one unambiguous row.
supplier_product_variant_idNoExact fulfillment Variant ID from get_supplier_product supplier_product_variant_list[].supplier_product_variant_id. It may differ from the current order Variant even when supplier_platform_id and supplier_product_id stay unchanged. Required for non-Agent suppliers and whenever shipping_method_id is supplied.
allow_future_mapping_overrideYesRequired explicit user choice. true allows a later product-level Mapping update to replace this order's manually selected supplier product/fulfillment Variant; false keeps this order's manual selection fixed against later Mapping updates. Neither value changes the buyer's original sales-channel SKU/Variant, and this edit does not immediately modify product-level Mapping.

Output Schema

NameRequiredDescriptionDefault
messageYesOutcome and safe next step
toolcall_response_atYesUTC timestamp when the Tool response was returned, formatted as RFC3339.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations declare destructive=true and non-idempotent, but the description adds material context beyond them: the blast radius (freight and fulfillment cost change, but not the buyer's SKU or product-level Mapping), the mandatory old-versus-new comparison and explicit confirmation, and the instruction to re-read get_order rather than retry when the write outcome is unknown. The only minor gap is that it never states the response shape, which is acceptable given an output schema exists.

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 bracketed section labels ([What it does], [When to use], [When not to use], [How to use], [Side effects], [Confirmation]) make it scannable and the critical scope and exclusions are front-loaded. It runs long and repeats the Mapping-override explanation in both the How-to-use and Side-effects sections, which costs it a point.

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 an 11-parameter destructive mutation with a one-of constraint, an enum-conditional on supplier platform, and a required user-choice flag, the description supplies everything needed: prerequisite reads (get_order, get_supplier_product, shipping-method lookup), validation steps before writing, confirmation protocol, and unknown-outcome handling. Return values are covered by the output schema, so their absence from the description is not a gap.

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 coverage is 100%, so the schema already documents all 11 parameters; the description largely restates the one-of rule between `supplier_product_id` and `supplier_product_url` and the requirement that `supplier_platform_id` accompany either. The `allow_future_mapping_override` explanation is the one place it adds real meaning by spelling out the consequence of true versus false for future Mapping updates.

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 names a specific verb and resource — 'Changes the supplier product and/or fulfillment Variant used by one order item' — and immediately bounds the scope: current order only, not the buyer's SKU or the long-term Mapping. An agent can distinguish it from apply_product_mapping and the sales-channel workflow without opening either 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?

It gives explicit when-to-use conditions (unavailable, out of stock, mispriced, cannot ship, or user picks a different Variant) and explicit when-not-to-use routing to `apply_product_mapping` and the sales-channel workflow. It also states the row-state precondition: the supplier row must still be unplaced, cancelled, or failed, with locked/paid/shipped rows excluded.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.