Skip to main content
Glama

Diff two stores

diff_stores
Read-only

Compare configuration between two Shopify stores or snapshots by resource type, returning counts, changed keys, and before/after values without writing anything.

Instructions

Compare configuration between a source and a target, resource type by resource type. Returns for each type the counts (onlyInSource, changed, onlyInTarget, identical) and the keys in each section, with before and after values for every changed field (show_values=false keeps only the field paths); limit caps each list while the counts cover everything, and format="markdown" gives a report to share. Either side can be a snapshot folder ("dir:"), e.g. to check whether production drifted from the committed config. The options shared with plan_sync (resources, include, prices, inventory, as_drafts...) only decide what is read and compared, so the diff matches the plan the same options would produce; nothing is written. Use compare_item for a single item, diff_themes for theme settings, and plan_sync to prepare the changes.

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": "diff_stores"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax items listed per section (default 100, markdown 50). The counts always cover everything.
formatNo"markdown" returns a report to paste into a ticket or an email.
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, or "dir:<path>" for a snapshot folder made with export_snapshot.
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).
show_valuesNoInclude before/after values for each changed field (default true).
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. Changed3 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."
  2. Changed14 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"
      +}
    • addedInput schema / properties / format
      Added value: +{
      +  "description": "\"markdown\" returns a report to paste into a ticket or an email.",
      +  "enum": [
      +    "json",
      +    "markdown"
      +  ],
      +  "type": "string"
      +}
    • 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"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Max keys listed per section (default 100)."New value: +"Max items listed per section (default 100, markdown 50). The counts always cover everything."
    • 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."
    • changedInput schema / properties / target / description
      Previous value: -"Store alias to compare against"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
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces this by stating nothing is written and that snapshot directories are accepted as either side. It also discloses output behavior (counts cover everything while limit caps each list, show_values=false keeps only field paths, markdown produces a shareable report), which goes beyond the annotations, though permissions/rate-limit behavior is not covered.

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-loaded with the core action and return shape, then usage routing, with no filler sentences. It is dense in a single block rather than being broken into scannable pieces, which slightly reduces readability for a 16-parameter tool.

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 a 16-parameter read-only comparison tool with no output schema, the description covers return contents, limit-vs-counts behavior, value suppression, source/target snapshot support, and sibling routing. Nothing essential for correct invocation is 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 coverage is 100%, so the baseline is 3; the description earns more by explaining cross-parameter semantics the schema documents only piecemeal — that resources/include/prices/inventory/as_drafts only decide what is read and compared, that the diff mirrors the plan those options would produce, and how limit interacts with counts.

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 concrete verb and scope: compare configuration between a source and a target, resource type by resource type, and further specifies what is returned (counts plus keys per section). It also names the siblings it replaces for narrower jobs (compare_item, diff_themes, plan_sync), so an agent can distinguish it without opening other schemas.

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?

Explicit routing is given: compare_item for a single item, diff_themes for theme settings, plan_sync to prepare changes. It also names a concrete use case (checking whether production drifted from the committed config) and clarifies that the plan_sync-shared options only affect what is read, not what is written.

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