Skip to main content
Glama

Compare theme settings

diff_themes
Read-only

Compare Shopify theme configuration between two stores, including JSON templates, section groups, and settings_data.json, to identify changed files and differing settings for review.

Instructions

Compare theme configuration between two stores: JSON templates, section groups and settings_data.json (default files: templates/.json, sections/.json, config/settings_data.json). Use it for theme settings; use diff_stores for store data such as metafields, metaobjects and pages. Compares the published themes unless source_theme or target_theme give theme ids. Returns file counts (onlyInSource, changed, onlyInTarget, identical), the files on one side only, and for each changed file the settings that differ with both values (first 100 per file); format="markdown" gives a report. Use ignore_settings to quiet settings that differ on purpose. Never writes to a theme; both stores need the read_themes scope.

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_themes"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesNoTheme file patterns, e.g. ["templates/product*.json"]
formatNo"markdown" returns a report to paste into a ticket or an email.
sourceYesStore alias to compare from (snapshot folders hold no themes).
targetYesStore alias to compare with.
excludeNoTheme file patterns to leave out, e.g. ["templates/gift_card.json"].
source_themeNo"main" (default) or a theme id
target_themeNo"main" (default) or a theme id
ignore_settingsNoSettings to leave out, as globs on their path, optionally limited to files: ["current.sections.header.*", "config/settings_data.json:current.color_*"]. Use it to quiet settings that differ on purpose between stores.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.11.6
    • addedInput schema / properties / exclude / description
      Added value: +"Theme file patterns to leave out, e.g. [\"templates/gift_card.json\"]."
    • changedInput schema / properties / source / description
      Previous value: -"Store alias"New value: +"Store alias to compare from (snapshot folders hold no themes)."
    • changedInput schema / properties / target / description
      Previous value: -"Store alias"New value: +"Store alias to compare with."
  2. Addedv0.11.4

TDQS

A4.6/5.0
Behavior4/5

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

Adds real behavior beyond the annotations: it declares a no-write guarantee ("Never writes to a theme"), the required read_themes scope on both stores, the truncation cap (first 100 differing settings per file), and the exact shape of the result (file counts plus one-sided files plus per-file setting diffs). The only gap is that it does not mention pagination or how to retrieve beyond the 100-per-file cutoff.

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?

Purpose is front-loaded in the first clause, alternatives second, output contract third, safety last — a sensible ordering. It is dense but nearly every clause carries information; the parenthetical default-file list is the only mildly heavy element and it earns its place by defining the default behavior.

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 8-parameter, no-output-schema tool, the description compensates fully: it defines defaults, the return shape, the truncation limit, the safety profile, and the auth scope. An agent could invoke this correctly without inspecting the schema.

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, but the description adds meaning the schema lacks: the default file set when `files` is omitted, that source_theme/target_theme default to published ("main") themes, and the practical effect of format="markdown" and ignore_settings. That is genuine semantic value over the schema rather than a restatement of it.

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?

Opens with a specific verb and resource ("Compare theme configuration between two stores") and immediately enumerates the scope: JSON templates, section groups, settings_data.json, with concrete default paths. It also names the sibling it is not (diff_stores), so an agent can distinguish the two without reading 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?

Explicitly routes: "Use it for theme settings; use diff_stores for store data such as metafields, metaobjects and pages." It also states the default comparison target (published themes) versus the theme-id path via source_theme/target_theme, and gives the when-to-use for ignore_settings (settings that differ on purpose). Both the selection rule and the escape hatch are covered.

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