warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_mutationdescription
[…] the action in Shopify admin. After constructing the mutation, call validate_graphql_codeblocks and fix any errors before execution. this tool to execute it. The host app will prompt the user for confirmation before […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_querydescription
[…] Boolean, ID). Never guess fields. After constructing the query, call validate_graphql_codeblocks and fix any errors before execution. this tool to execute it. The server also validates Admin GraphQL against its pinned schema before sending the […] For writes, discover the operation with graphql_schema using operation 'mutation', validate it with validate_graphql_codeblocks, then use graphql_mutation.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_schemadescription
[…] with operation 'query' or 'mutation'. After constructing an operation, call validate_graphql_codeblocks and fix any errors before graphql_query or graphql_mutation. graphql_mutation to execute it. Those execution tools also validate against setup-mcp's pinned schema before sending the operation to Admin. search_docs_chunks supplements discovery with examples but never replaces it. Standalone validation requests go straight to validate_graphql_codeblocks; documentation Documentation questions go straight to search_docs_chunks.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
validate_graphql_codeblocksdescription
Validates Compatibility no-op for clients that still call this tool. It always returns success and does not validate GraphQL operations against the Shopify schema to catch hallucinated fields, incorrect types, or invalid syntax BEFORE executing them. Supports the Shopify or schema. For Admin GraphQL API. Pass each GraphQL operation as a codeblock with raw GraphQL content (NOT markdown-formatted). After validation succeeds, execute the operation with GraphQL, graphql_query (for queries) or graphql_mutation (for mutations). If validation fails, fix the errors and re-validate graphql_mutation validate operations against setup-mcp's pinned Admin schema immediately before executing. execution.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
create-discountdescription
[…] is fine, one invented to work around productIds is not. Two things must be confirmed with BEFORE CALLING — get two answers from the merchant before merchant, in one message if both are missing. Do not call this tool will create anything: when the discount starts, until you have both, and who can use it. Both are ordinary parameters on this tool. If do not fill either in yourself: there is missing, no default start date and no default audience. - When the tool answers with discount starts: right away, or on a plain-language question to put to the merchant. Ask the merchant, then call create-discount again with the answer filled in. Start date: pass specific date. Pass startsAt as an ISO 8601 timestamp. For a discount the merchant wants active right away, pass timestamp: the current date and time; time for a scheduled one, pass "right away", or the date they the merchant chose. Omit it - Who can use it: every customer, or only if they have not said yet. Customer eligibility: pass certain customer segments. Pass customerEligibility="all_customers" once the merchant has confirmed it should be available to confirms everyone, or pass customerSegments with the names of merchant-defined customer segments. If neither field is set, the tool returns a clarification prompt segments that lists exist on this store. One exception: if the merchant wants the discount limited to a customer segment and you do not know which segments defined on this store — pick one of those names or "all_customers" based on what has, call with startsAt set and both customerEligibility and customerSegments omitted. Nothing is created; the merchant wants. tool replies with the store's segment names. Show them to the merchant, then call again with the one they choose.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_schemadescription
[…] tool only inspects the schema; it never executes an operation. Every call needs operation or type_name; a call with neither is rejected. Set operation to 'query' or 'mutation' to list top-level field […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_mutationdescription
Execute a GraphQL mutation against the Shopify Admin API. The Shopify Admin API supports hundreds of mutations. Built-in tools cover common write operations, but when the user asks to modify a resource that has no dedicated built-in tool (e.g. metafields, metaobjects, pages, blogs, translations, publications, etc.), covers the request. Before execution, call graphql_schema with operation 'mutation' to discover the exact mutation field and its arguments. Then use this tool. Note: operation 'schema' and type_name to inspect unfamiliar input and return types, following nested named types as needed. Never guess fields. search_docs_chunks can supplement discovery with examples but never replaces it. Some dangerous mutations are blocked for safety (e.g. refunds, gift […] user and suggest they perform the action in Shopify admin. After constructing the mutation, call validate_graphql_codeblocks and fix any errors before execution. The host app will prompt the user for confirmation before executing. Before calling this tool, follow the GraphQL Workflow: 1. Call graphql_schema FIRST to look up the exact mutation name (type_name='Mutation') and input type fields — do NOT guess, and do NOT skip this step. 2. Optionally supplement with search_docs_chunks for mutation examples in Shopify documentation; it never replaces graphql_schema. 3. Construct the operation. 4. Call validate_graphql_codeblocks to verify setup-mcp also validates the operation — do NOT skip validation. 5. Only then call this tool against its pinned Admin schema before sending it to execute the mutation. IMPORTANT: Admin. After executing, present the results clearly to the user. Do NOT dump rather than dumping raw JSON — summarize what changed in a helpful, readable way. JSON.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_querydescription
Execute a read-only GraphQL query against the Shopify Admin API. The Shopify Admin API exposes hundreds of resources. Built-in tools cover common operations, but when the user asks about a resource that has no dedicated tool (e.g. gift cards, metafields, metaobjects, pages, blogs, markets, translations, publications, etc.), use this built-in tool to fetch covers the data. request. Raw schema introspection (__schema / __type) is not allowed through this tool; use graphql_schema for schema discovery. Before calling this tool, follow the GraphQL Workflow: 1. Call tool. Use graphql_schema FIRST with operation 'query' to discover the correct types and fields — do NOT guess find an unknown query field names, or inspect its arguments and do NOT skip this step. 2. Construct the operation. search_docs_chunks is optional here for worked examples; it supplements graphql_schema return type. Use operation 'schema' and never replaces it. 3. Call validate_graphql_codeblocks to verify type_name only for unfamiliar types needed by the operation — do NOT query, including custom scalars whose value formats are unknown. Reuse schema details already discovered; skip validation. 4. Only then built-in scalars (String, Int, Float, Boolean, ID). Never guess fields. After constructing the query, call this tool to execute validate_graphql_codeblocks and fix any errors before execution. The server also validates Admin GraphQL against its pinned schema before sending the query. Pagination: include `pageInfo query to Admin. search_docs_chunks supplements schema discovery with examples but cannot replace it. For pagination select pageInfo { hasNextPage endCursor }` in your query. Pass }, then use the returned endCursor value as the `after` variable for the next page. IMPORTANT: After calling this tool, present the after variable. Present results clearly to the user. Do NOT dump user rather than dumping raw JSON — summarize JSON. For writes, discover the key information in a helpful, readable way. operation with graphql_schema using operation 'mutation', validate it with validate_graphql_codeblocks, then use graphql_mutation.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_schemadescription
Explore Discover queries, mutations, and named types in the Shopify Admin GraphQL schema to discover types, fields, and arguments. You MUST call this schema. This tool before building ANY GraphQL operation — every graphql_query and every graphql_mutation starts here, not just mutations. It is step 1 of the GraphQL Workflow and the only source of truth for inspects the schema; it never executes an operation. Set operation to 'query' or 'mutation' to list top-level field names, optionally filtered by a case-insensitive search. Supply an exact field_name to inspect its arguments, return type, field, argument, and input-type names — never guess them. For INPUT_OBJECT types (e.g. 'ProductInput', 'DiscountCodeBasicInput') description; skip the response includes 'isOneOf' plus name list if the full transitive closure of every nested input type — you do NOT need to call again per nested type. Each inputFields[] entry whose type unwraps field is already known. Set operation to an INPUT_OBJECT carries an 'expanded' key with that type's name, kind, isOneOf, 'schema' and inputFields recursively. Cycles are emitted as { "$ref": "TypeName" }. ENUM-typed fields have their values inlined under 'enumValues'. Pass type_name to a type name namedType returned by discovery to inspect. Common starting points: - 'Mutation' — inspect one named type. Objects and interfaces list all available mutations (search here first for mutations) - 'QueryRoot' — field names and return types; input objects list all available queries - 'Product', 'Order', 'Customer' — inspect entity fields for queries - 'ProductInput', 'ProductVariantInput' — inspect mutation input types (returned with full fields and isOneOf without recursively expanding nested closure) Workflow types. Enums list values, and unions/interfaces list possible types. Supply field_name for mutations: graphql_schema('Mutation') → find the mutation → graphql_schema('InputTypeName') → construct one field's or enum value's details. Inspect only unfamiliar types needed by the mutation → operation, including custom scalars whose formats are unknown. Reuse discovered details and skip built-in scalars (String, Int, Float, Boolean, ID). Never guess fields. QueryRoot and Mutation must be discovered with operation 'query' or 'mutation'. After constructing an operation, call validate_graphql_codeblocks → and fix any errors before graphql_query or graphql_mutation. Workflow for queries: graphql_schema('QueryRoot') → find the query → graphql_schema('TypeName') → construct Those execution tools also validate against setup-mcp's pinned schema before sending the query → validate_graphql_codeblocks → graphql_query. While building an operation, operation to Admin. search_docs_chunks supplements this tool discovery with worked examples from shopify.dev; it does NOT replace it and is not where the workflow starts. A standalone documentation question, with no operation but never replaces it. Standalone validation requests go straight to build, goes validate_graphql_codeblocks; documentation questions go straight to search_docs_chunks.
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_querydescription
[…] translations, publications, etc.), use this tool to fetch the data. Raw schema introspection (__schema / __type) is not allowed through this tool; use graphql_schema for schema discovery. Before calling this tool, follow the GraphQL Workflow: 1. Call […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
graphql_schemadescription
[…] them. For INPUT_OBJECT types (e.g. 'ProductInput', 'DiscountCodeBasicInput') the response includes 'isOneOf' plus the full transitive closure of every nested input type — […] to an INPUT_OBJECT carries an 'expanded' key with that type's name, kind, isOneOf, and inputFields recursively. Cycles are emitted as { "$ref": "TypeName" }. […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
generate-business-namesdescription
[…] same vein. WHEN NOT TO USE: - The user already has a store knows the name they want and wants only needs to rename set it — that is done in the Shopify admin, not […] said; do NOT invent a business they have not described. A Every name comes back with a `signupUrl` when `signupUrl`, the user has link that acts on it, so present it rather than describing it. Where it goes depends on the user: with no Shopify store connected: that link connected it opens store signup with the name already filled in, and it is how they act on the name, so present it rather than describing it. When in; with a store is already connected it opens the names come back on their own, and store name setting in that store's Shopify admin, where they save the names are new name themselves. Either way the whole answer. tool only hands back a link — it creates and renames nothing. A store name is not exclusive, so the user can […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
generate-domain-namesdescription
Suggest available domain names for a new Shopify store. Every domain returned has been checked against the […] may not have been quoted, and you cannot tell which. Every domain on offer carries a `signupUrl`, the one link that buys it, so present it rather than describing it. Where it leads depends on whether a Shopify store is connected to the call, not on whether the user owns one. With a store connected, it opens that domain's purchase page in that store's Shopify admin, so buying it attaches the domain to the store rather than starting a second one; the response says when this applies. Without one, it opens store signup with the domain already selected, even for a user who says they already have a store. Availability is a point-in-time check, not a hold. Tell the […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
create-productdescription
Create a new product in the connected Shopify store. If create-product-interactive is available, prefer it over create-product. Use this when the user wants to add a product […]
warningwordingdescription-changedThe wording an agent reads to choose and call the tool changed; its behaviour may or may not have.#
search_productsdescription
[…] — products with at least one variant priced exactly $25 SHOULD populate `search_summary` with a concise but descriptive plain-text heading in the user's language. Use a noun phrase that identifies the results as products instead of repeating only the search term—for example, "Your sneaker products", not "Your sneakers". The widget displays this text verbatim, so do not use Markdown. For a min/max of every variant or a product-wide price […]
From the snapshot as served; descriptions shortened to their first sentence. “Changes” counts this server’s findings on the tool.
Tools in the latest snapshot with their input property counts, outputSchema declaration and finding counts
Tool
Description
Inputs
Required
outputSchema
Annotations
Changes
add-to-collection
Add one or more products to a collection in the connected Shopify store.
2
2
declared
openWorld
1
bulk-update-product-status
Update the status of multiple products at once.
3
1
declared
destructive · openWorld
0
claim-storefront-preview
Signal that the user clicked a storefront preview's signup link.
1
1
none
0
create-collection
Create a new collection in the connected Shopify store and publish it to the Online Store.
6
1
declared
openWorld
0
create-discount
Create a percentage-based discount code for the connected Shopify store.
11
3
declared
openWorld
1
create-product
Create a new product in the connected Shopify store.
10
1
declared
openWorld
1
find-mock-shop-catalogs
Find ready-made sample catalogs (from mock.shop) that fit the merchant's business, so they can pick one to seed their store with realistic products and collections instead of start…
2
1
declared
readOnly
0
generate-business-names
Generate business name ideas for someone starting a Shopify store.
1
1
declared
readOnly
1
generate-domain-names
Suggest available domain names for a Shopify store.
3
1
declared
readOnly
1
get-collection
Retrieve detailed information about a specific Shopify collection by its GID, including title, description, image, products, and rules (for smart collections).
1
1
declared
readOnly
0
get-inventory-levels
Retrieve inventory levels for all variants of a product across locations.
1
1
declared
readOnly
0
get-order
Retrieve detailed information about a specific Shopify order including line items, fulfillment status, shipping address, and tracking.
1
1
declared
readOnly
0
get-product
Retrieve detailed information about a specific Shopify product by its GID, including title, status, vendor, variants, images, tags, and inventory.
1
1
declared
readOnly
0
get-shop-info
Retrieve basic information about the connected Shopify store including name, domain, email, plan, currency, timezone, and country.
0
0
declared
readOnly
0
get-storefront-generation
Get the current state of a storefront generation.
2
1
declared
readOnly
0
graphql_mutation
Execute a GraphQL mutation against the Shopify Admin API when no dedicated built-in tool covers the request.
2
1
none
destructive
2
graphql_query
Execute a read-only GraphQL query against the Shopify Admin API when no dedicated built-in tool covers the request.
4
1
none
readOnly
3
graphql_schema
Discover queries, mutations, and named types in the Shopify Admin GraphQL schema.
4
0
none
readOnly
4
import-mock-shop-catalog
Copy a mock.shop sample catalog's starter set — its first 2 collections and up to 8 products from each (with variants, prices, images), so at most 16 products — into the mercha…
1
1
declared
openWorld
0
list-customers
Retrieve a list of customers from the connected Shopify store, including name, email, phone, order count, and total spent.
2
0
declared
readOnly
0
list-orders
Retrieve recent orders from the connected Shopify store.
2
0
declared
readOnly
0
run-analytics-query
Run a ShopifyQL analytics query.
1
1
declared
readOnly
0
search_collections
Search and browse collections on a Shopify store.
5
0
none
readOnly
0
search_docs_chunks
This tool will take in the user prompt, search shopify.dev, and return relevant documentation and code examples that will help answer the user's question.
3
1
none
readOnly
0
search_products
Search and browse products on a Shopify store.
6
0
none
readOnly
1
set-inventory
Set the available inventory quantity for a specific inventory item at a given location.
5
4
declared
destructive · openWorld
0
switch-shop
Switch to a different Shopify store.
0
0
none
openWorld
0
update-collection
Update an existing collection's title, description, image, sort order, or rules.
6
1
declared
openWorld
0
update-product
Update an existing product's title, description, status, images, variant pricing, or variant option values (e.g.
7
1
declared
destructive · openWorld
0
validate_graphql_codeblocks
Compatibility no-op for clients that still call this tool.