shopify-mcp

list_metafields

List metafields from a Shopify resource to inspect custom data. Filter by namespace to scope results. Use before setting metafields or to audit existing values.

Instructions

List metafields attached to a single Shopify resource. Returns each metafield's namespace.key, type, current value, and optional description. Pass a namespace to scope the read to one app/integration's metafields (recommended when the resource has many). Empty result is normal for resources without metafields. Use this to inspect existing custom data before calling set_metafield, or to audit which apps have written what to a record.

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": {
      "ownerId": "<ownerId>"
    },
    "name": "list_metafields"
  }
}

Input Schema

Name	Required	Description
`ownerId`	Yes	GID of the resource to read metafields from.
`namespace`	No	Filter to a single namespace. Omit to return all.
`first`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Apr 25, 2026

TDQS

A4.2/5.0

Behavior4/5

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

No annotations provided, so the description carries the full burden. It correctly identifies this as a read operation, describes the output fields, and normalizes empty results. It does not mention pagination beyond the 'first' parameter which is already in schema, but overall behavior is well-conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first states purpose, second explains return content, third gives usage guidance. Front-loaded with key information, no fluff, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with 3 parameters and no output schema, the description covers purpose, return structure, usage context, and a common scenario (empty results). It could mention pagination behavior (cursor-based) but overall is fairly complete.

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?

The description adds context for the 'namespace' parameter (scope to one app/integration, recommended for many metafields). However, it does not mention the 'first' parameter (pagination) though schema has 67% coverage. The description provides some added value beyond schema but not fully compensates for the missing parameter description.

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 clearly states the tool lists metafields for a single Shopify resource, specifies what is returned (namespace.key, type, value, description), and distinguishes from siblings like set_metafield and delete_metafield. It is specific with verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: use before set_metafield or for auditing, and recommends passing namespace when resource has many metafields. However, it does not explicitly state when not to use it or name alternative tools beyond set_metafield.

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

Deploy Server