Skip to main content
Glama

Plan a sync

plan_sync
Read-only

Build a dry-run plan that makes a target Shopify store match a source store or snapshot, showing creates, updates, conflicts, and warnings without writing anything before apply_plan.

Instructions

Build a dry-run plan that would make the target store match the source (a store or a "dir:" snapshot folder) for the selected resources. Reads both sides and writes nothing. Returns { plan_id, expiresAt, totals (create, update, conflict), byResource, ops, warnings, filesToUpload, onlyInTarget, targetWritable, targetProtected }; each op has a seq number, key, action, reason, missing references and field changes (the first 200 ops are listed). Conflicts are items that can't be written, with the reason; items only in the target are listed and never deleted. Show the plan to the person, then pass plan_id to apply_plan; it expires after one hour, and get_plan shows it again. To only look at differences, use diff_stores instead.

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": {
      "source": "<source>",
      "target": "<target>"
    },
    "name": "plan_sync"
  }
}

Input Schema

NameRequiredDescriptionDefault
pricesNoproducts: include variant prices and compare-at prices in what is read, compared and planned. Off by default, since prices usually differ per store.
sourceYesStore alias, or "dir:<path>" for a snapshot folder made with export_snapshot.
targetYesStore alias the plan would write to (see list_stores; snapshot folders can't be a target).
excludeNoDrop keys matching any of these globs.
includeNoOnly keys matching one of these globs, e.g. ["PRODUCT.custom.*", "faq/*", "fr:*"].
localesNoLimit translations to these locales, e.g. ["fr", "de"]. Default: every non-primary locale.
as_draftsNoLeave the published state out of what is compared and copied: in a plan, new pages are created hidden and new metaobject entries as drafts, and existing ones keep their state. Products are always created as drafts.
inventoryNoproducts: include stock (the available quantity per location, matched to the target's location with the same name) in what is read, compared and planned. Off by default. Needs read_inventory and read_locations, plus write_inventory to apply: run connect again if the sign-in is older.
resourcesNoResource types to include. Default: metafield_definitions, metaobject_definitions, collections, pages, shop_policies, metaobjects, menus, redirects. products, metafields and translations are opt-in.
namespacesNoLimit metafield values (metafields) to these namespaces.
owner_typesNoMetafield owner types. For metafield_definitions, default: PRODUCT, PRODUCTVARIANT, COLLECTION, CUSTOMER, ORDER, DRAFTORDER, COMPANY, COMPANY_LOCATION, LOCATION, MARKET, PAGE, BLOG, ARTICLE, SHOP. For metafield values (metafields): PRODUCT, COLLECTION, PRODUCTVARIANT, SHOP (all by default).
include_reservedNometafield_definitions: also compare Shopify-reserved ones (namespace "shopify", the category metafields that drive storefront filters). Compared only: a plan reports them as conflicts and never writes them.
metaobject_typesNoLimit metaobjects to these types. Default: all non-reserved types.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.11.6
    • changedInput schema / properties / as_drafts / description
      Previous value: -"Leave the published state alone: new pages are created hidden and new metaobject entries as drafts, existing ones keep their state. Products are always created as drafts."New value: +"Leave the published state out of what is compared and copied: in a plan, new pages are created hidden and new metaobject entries as drafts, and existing ones keep their state. Products are always created as drafts."
    • changedInput schema / properties / inventory / description
      Previous value: -"products: also copy stock, the available quantity per location, into the target's location with the same name. Off by default. Needs read_inventory and read_locations (and write_inventory to write): run connect again if the sign-in is older."New value: +"products: include stock (the available quantity per location, matched to the target's location with the same name) in what is read, compared and planned. Off by default. Needs read_inventory and read_locations, plus write_inventory to apply: run connect again if the sign-in is older."
    • changedInput schema / properties / prices / description
      Previous value: -"products: also copy variant prices and compare-at prices. Off by default, since prices usually differ per store."New value: +"products: include variant prices and compare-at prices in what is read, compared and planned. Off by default, since prices usually differ per store."
    • changedInput schema / properties / target / description
      Previous value: -"Store alias to write to"New value: +"Store alias the plan would write to (see list_stores; snapshot folders can't be a target)."
  2. Changed11 schema fields changedv0.11.4
    • addedInput schema / properties / as_drafts
      Added value: +{
      +  "description": "Leave the published state alone: new pages are created hidden and new metaobject entries as drafts, existing ones keep their state. Products are always created as drafts.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / include / description
      Previous value: -"Only keys matching one of these globs, e.g. [\"PRODUCT.custom.*\", \"faq/*\", \"main-menu\"]."New value: +"Only keys matching one of these globs, e.g. [\"PRODUCT.custom.*\", \"faq/*\", \"fr:*\"]."
    • addedInput schema / properties / include_reserved
      Added value: +{
      +  "description": "metafield_definitions: also compare Shopify-reserved ones (namespace \"shopify\", the category metafields that drive storefront filters). Compared only: a plan reports them as conflicts and never writes them.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / inventory
      Added value: +{
      +  "description": "products: also copy stock, the available quantity per location, into the target's location with the same name. Off by default. Needs read_inventory and read_locations (and write_inventory to write): run connect again if the sign-in is older.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / locales
      Added value: +{
      +  "description": "Limit translations to these locales, e.g. [\"fr\", \"de\"]. Default: every non-primary locale.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / namespaces
      Added value: +{
      +  "description": "Limit metafield values (metafields) to these namespaces.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / owner_types / description
      Previous value: -"Metafield owner types for metafield_definitions. Default: PRODUCT, PRODUCTVARIANT, COLLECTION, CUSTOMER, ORDER, DRAFTORDER, COMPANY, COMPANY_LOCATION, LOCATION, MARKET, PAGE, BLOG, ARTICLE, SHOP."New value: +"Metafield owner types. For metafield_definitions, default: PRODUCT, PRODUCTVARIANT, COLLECTION, CUSTOMER, ORDER, DRAFTORDER, COMPANY, COMPANY_LOCATION, LOCATION, MARKET, PAGE, BLOG, ARTICLE, SHOP. For metafield values (metafields): PRODUCT, COLLECTION, PRODUCTVARIANT, SHOP (all by default)."
    • addedInput schema / properties / prices
      Added value: +{
      +  "description": "products: also copy variant prices and compare-at prices. Off by default, since prices usually differ per store.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / resources / description
      Previous value: -"Resource types to include. Default: all (metafield_definitions, metaobject_definitions, pages, metaobjects, menus, redirects)."New value: +"Resource types to include. Default: metafield_definitions, metaobject_definitions, collections, pages, shop_policies, metaobjects, menus, redirects. products, metafields and translations are opt-in."
    • changedInput schema / properties / resources / items / enum
      Previous value: -[
      -  "metafield_definitions",
      -  "metaobject_definitions",
      -  "pages",
      -  "metaobjects",
      -  "menus",
      -  "redirects"
      -]New value: +[
      +  "metafield_definitions",
      +  "metaobject_definitions",
      +  "products",
      +  "collections",
      +  "pages",
      +  "shop_policies",
      +  "metaobjects",
      +  "menus",
      +  "redirects",
      +  "metafields",
      +  "translations",
      +  "discounts"
      +]
    • changedInput schema / properties / source / description
      Previous value: -"Store alias to copy from"New value: +"Store alias, or \"dir:<path>\" for a snapshot folder made with export_snapshot."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations say readOnlyHint=true and openWorldHint=true, and the description reinforces rather than contradicts this ('Reads both sides and writes nothing'). Beyond the annotations it discloses the expiry window, the 200-op listing cap, that conflicts are reported but never written, and that target-only items are never deleted.

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 purpose, then the return shape, then the workflow and alternative. The long field enumeration is dense but justified because no output schema exists; a slightly more segmented structure would be easier to scan.

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?

With 13 parameters, no output schema, and no nested objects, the description compensates by documenting the exact return payload, the op structure, the 200-item cap, and the apply handoff. Nothing an agent needs in order to call it and act on the result is missing.

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 the schema already explains source, target, resources defaults, and the prices/inventory opt-ins. The description adds only a mild gloss on source being a store or snapshot folder and on what 'resources' means, which the schema already covers, so 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 and resource ('Build a dry-run plan that would make the target store match the source') plus the scope of 'selected resources', which is enough to separate it from diff_stores and apply_plan 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 sequencing ('Show the plan to the person, then pass plan_id to apply_plan'), a lifecycle constraint (expires after one hour, get_plan re-shows it), and a named alternative with its selecting condition ('To only look at differences, use diff_stores instead').

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