Skip to main content
Glama

MyProduct: Update Variant Mapping

apply_product_mapping
Destructive

[Store Products] [What it does] Changes only the active Basic/Advanced Mapping type, or applies a confirmed partial Mapping update to selected sales-product variants of one DSers-managed product. Omitted sales variants and the other Mapping mode are preserved. [When to use] Use after reading the latest state with get_store_product_mapping, inspecting the selected supplier products and variants, and obtaining explicit user confirmation for the exact changes. [When not to use] This Tool does not search for suppliers, infer relationships from names, or save unconfirmed AI Mapping suggestions. Use the supplier-search or AI-Mapping tools first when the relationship is not already known. [How to use]

  • Top-level mapping=[] changes only the active Mapping type. It preserves every sales variant, Basic and Advanced relationship, country array, Agent relationship, quantity, option, and Mapping Pool entry. Omit advanced_country_codes, basic_option_maps, and cam_id in this mode. If the requested type is already active, no upstream write is sent.

  • When top-level mapping contains variants, include each sales_product_variant_id at most once. For every submitted variant, nested mappings is the complete replacement within mapping_type and, for Advanced, the selected country scope. Omitted variants remain unchanged.

  • Nested mappings=[] deletes all Basic relationships for that submitted variant, including its last relationship. For Advanced it deletes only advanced_country_codes; when that field is omitted, only Global is deleted. [Basic Mapping]

  • mapping_type=Basic accepts concrete supplier products only; Agent mappings are not allowed. is_default=true is the main supplier; false or omitted is the backup supplier. Each sales variant may have at most one main and one backup relationship, and the complete final Basic state may use at most one main supplier product and one backup supplier product across the sales product.

  • Every submitted Basic relationship must contain the complete supplier_product_variant_options combination, including supplier options that are not driven by a sales option and are therefore treated as fixed selections. The Option-ID/value-ID combination must identify exactly one supplier variant and must match supplier_product_variant_id. Option names and value names may differ and are never used to infer the relationship.

  • basic_option_maps is an ID-based partial patch: submitted sales option/value keys add or replace pairs, omitted pairs are initially preserved, and pairs with no final Basic relationship reference are removed. Do not create artificial Option Pairs for fixed supplier options. [Advanced Mapping]

  • mapping_type=Advanced replaces only advanced_country_codes for submitted variants. Omission defaults to Global. Global is a fallback scope, remains distinct from country-specific mappings, and must not be dropped when both are configured. An identical relationship and quantity may carry multiple countries in one country array; different quantities remain separate relationships.

  • For the same sales variant and country, all concrete supplier mappings must use the same supplier platform; multiple supplier variants or products are allowed only when they belong to that platform. Mixing platforms for one sales variant/country is rejected.

  • The Agent platform is identified from the configured Agent platform ID, never a hard-coded ID. For the same sales variant and country, submit exactly one Agent ID with quantity 1. An Agent request must not include concrete supplier product or variant IDs or supplier variant options.

  • Every submitted supplier platform must be installed and enabled for Find Products for the current user. [Write safety] This Tool is not idempotent. It reads the current Mapping, builds one complete upstream state, writes once, and reads it back for verification. Never retry automatically when the write outcome is uncertain. [Side effects] Changes supplier relationships used by future supply and order fulfillment. [Confirmation] Required and never skippable: show the exact product, sales variants, country scopes, deletions, and old-to-new relationships before calling.

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": {
      "dsers_product_id": "<dsers_product_id>",
      "mapping_type": "<mapping_type>",
      "mapping": "<mapping>"
    },
    "name": "apply_product_mapping"
  }
}

Input Schema

NameRequiredDescriptionDefault
cam_idNoOptional order-recommendation CAM ID. Omit for a normal product Mapping update; 0 is treated as unset.
mappingYesRequired. Use top-level [] to change only mapping_type without modifying variants or pools; omit advanced_country_codes, basic_option_maps, and cam_id in that mode. Otherwise include only sales variants to change, once each. Nested mappings completely replaces the selected mode/scope: Basic [] deletes all Basic relationships for that variant, while Advanced [] deletes only advanced_country_codes (default Global). Omitted variants are preserved. Paste JSON example: [{"mappings":[{"supplier_platform_id":"159831080","supplier_product_id":"10050011958743969","supplier_product_variant_id":"10050011958743970"}],"sales_product_variant_id":"45382179012608"}].
mapping_typeYesPage-aligned Mapping mode. Basic is stored internally as MapBas; Advanced is stored as MapNewAdv.
dsers_product_idYesExact DSers product ID from the latest Mapping read. It also selects /dsers-product-bff/mapping/v2/{dsers_product_id}.
basic_option_mapsNoBasic-only option-pair patches grouped by supplier product. Omission preserves current pairs; submitted sales option-value keys add or replace pairs. Add pairs only for sales-driven supplier options. Fixed supplier options remain in supplier_product_variant_options without an Option Pair. Unreferenced pairs are removed after the complete final Mapping is built. Paste JSON example: [{"option_pairs":[{"sales_option_id":"Color","sales_option_value_id":"Silver","supplier_option_id":"Style","supplier_option_value_id":"B"}],"supplier_platform_id":"159831080","supplier_product_id":"10050011958743969"}].
advanced_country_codesNoAdvanced-only country scopes replaced or deleted for submitted variants. Omit to select Global only. Global is a fallback and remains explicit alongside country-specific scopes; do not collapse ["Global","US"] to ["US"]. Paste JSON example: ["Global","US"].

Output Schema

NameRequiredDescriptionDefault
messageYesProduct BFF acknowledgement and verification guidance
update_modeYesUpdate mode: partial or mapping_type_only
mapping_typeYesUpdated public Mapping mode: Basic or Advanced
dsers_product_idYesTarget DSers product ID
updated_variant_idsYesSales variant IDs changed by this patch
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.8/5.0
Behavior5/5

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

Annotations already declare destructive=true, idempotent=false, and readOnly=false, but the description adds substantial context beyond them: it explains the read-build-write-read-back verification flow, warns never to retry automatically when the write outcome is uncertain, describes the side effect on future supply and order fulfillment, and mandates non-skippable confirmation with old-to-new relationships shown. This is exactly the behavioral detail an agent needs for a destructive mutation.

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 bold section headers and bullets, and the critical scoping and confirmation warnings are front-loaded. Some sentences duplicate schema descriptions, particularly in the Basic and Advanced Mapping sections, so it is not maximally concise, but the length is largely justified by the tool's complexity.

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?

Given a six-parameter destructive mutation with an output schema, the description covers the full operational picture: prerequisites, confirmation, preservation and deletion semantics, non-idempotency, side effects, and verification. Nothing an agent needs in order to call it safely appears to be 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 description coverage is 100%, so the baseline is 3, and the description goes further by explaining cross-parameter modes: top-level `mapping=[]` changes only the mapping type, nested `mappings=[]` has different deletion semantics for Basic versus Advanced, and omitted variants are preserved. However, many individual parameter rules are repeated nearly verbatim from the schema (for example the Agent ID rules and option-ID matching requirements), so the added value is real but partially redundant.

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 states a specific verb and resource: it changes the active Basic/Advanced Mapping type or applies a confirmed partial Mapping update to selected sales-product variants of one DSers-managed product. It clearly distinguishes itself from the read-only `get_store_product_mapping` and from supplier-search or AI-Mapping tools, so an agent can select it 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?

It gives explicit when-to-use guidance (after reading state with `get_store_product_mapping`, inspecting supplier products, and obtaining user confirmation) and explicit when-not-to-use guidance (does not search suppliers, infer relationships, or save unconfirmed AI suggestions). It names the alternative tools to use when the relationship is not already known.

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.