SEO GSC Wizard MCP

Merchant listings performance

get_merchant_listings_performance

Read-only

Use this when the user asks how visible their product results are in Google web Search, and which product pages carry them. Search Console performance for one search appearance, defaulting to MERCHANT_LISTINGS: the appearance inventory of the property, a daily clicks / impressions / CTR / position timeline in date order, and the top pages (product URLs) behind it; appearances and pages are sorted by clicks, highest first, and CTR is a 0-100 percentage. Search Console merchant listings counts enriched product results in web Search only, so it does not reconcile to one figure with Merchant Center free listings. Not for the Shopping tab, Images, Lens, YouTube or Maps: use get_organic_shopping_performance. Always served from the live Search Console API: search appearance is never stored in the GSC Wizard warehouse, and it can be filtered on but never grouped with another dimension. hasAppearance is false when the property has no rows for the requested appearance, and emptyBecause is set whenever it has no impressions, which is normal for non-ecommerce sites. The window may span at most 16 months (Search Console retention); a longer one is rejected with bad_request. Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).

Input Schema

Name	Required	Description	Default
`limit`	No	Top pages to return, ordered by clicks (default 25, max 1000).
`endDate`	No	Optional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null".
`siteUrl`	Yes	The property URL as returned by list_sites (e.g. "sc-domain:example.com").
`startDate`	No	Optional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null".
`appearance`	No	Search appearance code to report on. Defaults to MERCHANT_LISTINGS; other common values are PRODUCT_SNIPPETS and ORGANIC_SHOPPING. Read `appearances` in the response to see which codes this property actually has.	MERCHANT_LISTINGS
`includeAppearances`	No	Include the unfiltered per-appearance breakdown, which is the only way to learn which appearance codes the property has and how big each one is.

Output Schema

Name	Required	Description
`note`	No
`pages`	No
`thenBy`	No
`totals`	No
`endDate`	No
`hasMore`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`siteUrl`	No
`warning`	No
`nextStep`	No
`ordering`	No
`rowCount`	No
`sortedBy`	No
`timeline`	No
`emptyNote`	No
`sortOrder`	No
`startDate`	No
`thenOrder`	No
`appearance`	No
`dataSource`	No
`searchType`	No
`appearances`	No
`partialDays`	No
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`hasAppearance`	No
`settledThrough`	No
`warehouseLatestDate`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 28, 2026

addedOutput schema / properties / listKey

Added value: +{
+  "$ref": "#/properties/siteUrl",
+  "description": "Name of the top-level field that holds the rows sortedBy describes."
+}

Changed16 schema fields changedOct 18, 2026

changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

changedOutput schema / properties / appearances / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "appearance": {
-          "$ref": "#/properties/siteUrl"
-        },
-        "clicks": {
-          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-        },
-        "ctr": {
-          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-        },
-        "impressions": {
-          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-        },
-        "position": {
-          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": true,
+      "properties": {
+        "appearance": {
+          "$ref": "#/properties/siteUrl"
+        },
+        "clicks": {
+          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+        },
+        "ctr": {
+          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+        },
+        "impressions": {
+          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+        },
+        "position": {
+          "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / dataMaturity / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "dateBasis": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "firstIncompleteDate": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "note": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "probe": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "dataState": {
-                "$ref": "#/properties/siteUrl"
-              },
-              "endDate": {
-                "$ref": "#/properties/siteUrl"
-              },
-              "searchType": {
-                "$ref": "#/properties/siteUrl"
-              },
-              "startDate": {
-                "$ref": "#/properties/siteUrl"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "settledThrough": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "source": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "warehouseCutoff": {
-        "$ref": "#/properties/siteUrl"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "dateBasis": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "firstIncompleteDate": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "note": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "probe": {
+        "anyOf": [
+          {
+            "additionalProperties": true,
+            "properties": {
+              "dataState": {
+                "$ref": "#/properties/siteUrl"
+              },
+              "endDate": {
+                "$ref": "#/properties/siteUrl"
+              },
+              "searchType": {
+                "$ref": "#/properties/siteUrl"
+              },
+              "startDate": {
+                "$ref": "#/properties/siteUrl"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "settledThrough": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "source": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "warehouseCutoff": {
+        "$ref": "#/properties/siteUrl"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / emptyBecause

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / methodLimits

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / nextStep

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / ordering

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "additionalProperties": true,
+        "properties": {
+          "sortOrder": {
+            "$ref": "#/properties/siteUrl"
+          },
+          "sortedBy": {
+            "$ref": "#/properties/siteUrl"
+          },
+          "thenBy": {
+            "$ref": "#/properties/siteUrl"
+          },
+          "thenOrder": {
+            "$ref": "#/properties/siteUrl"
+          }
+        },
+        "type": "object"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / pages / items / additionalProperties
```
Previous value: -falseNew value: +true
```

addedOutput schema / properties / partialDays

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / sortOrder

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / sortedBy

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / thenBy

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

addedOutput schema / properties / thenOrder

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

changedOutput schema / properties / timeline / items / additionalProperties
```
Previous value: -falseNew value: +true
```

changedOutput schema / properties / totals / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "clicks": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "ctr": {
-        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-      },
-      "impressions": {
-        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-      },
-      "position": {
-        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "clicks": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "ctr": {
+        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+      },
+      "impressions": {
+        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+      },
+      "position": {
+        "$ref": "#/properties/totals/anyOf/0/properties/clicks"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / warning

Added value: +{
+  "$ref": "#/properties/siteUrl"
+}

Changed1 schema field changedOct 10, 2026
- addedOutput schema / properties / warehouseLatestDate
```
Added value: +{
+  "$ref": "#/properties/siteUrl"
+}
```
First observedOct 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnlyHint true, destructiveHint false), and the description layers on genuinely non-obvious behavior: always served live from the API and never from the warehouse, filterable but never groupable by another dimension, hasAppearance=false semantics, emptyBecause population rules, a hard 16-month retention cap that returns bad_request, and a ~2-3 day data lag. The reconciliation caveat versus Merchant Center free listings is exactly the kind of cross-tool behavioral warning annotations cannot express.

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?

Despite its length, it is front-loaded with the usage trigger and the sibling exclusion before any detail, and each subsequent clause carries a distinct fact (warehouse exclusion, grouping restriction, empty-state fields, retention cap, date default). No sentence is redundant with the schema or annotations, though a light bullet structure would improve scanability.

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 an output schema present, return values need not be explained, yet the description still clarifies the two empty-state fields an agent must interpret (hasAppearance, emptyBecause). Combined with the retention limit, date defaults, and live-API constraint, nothing an agent needs to call this correctly or interpret an empty response 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, but the description adds meaning beyond the schema: the appearance defaults to MERCHANT_LISTINGS, appearances and pages are sorted by clicks highest-first, CTR is expressed as a 0-100 percentage, and omitting both dates yields the last 28 settled days. The `appearances` response field pointer also tells the agent how to discover valid codes despite the absence of an enum.

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 names a specific verb and resource ('Search Console performance for one search appearance') plus the exact default (MERCHANT_LISTINGS) and the three artifacts returned: appearance inventory, daily clicks/impressions/CTR/position timeline, and top product URLs. It explicitly distinguishes itself from get_organic_shopping_performance by listing the surfaces that tool covers (Shopping tab, Images, Lens, YouTube, Maps), so an agent can separate the two siblings without opening 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?

States the triggering user intent ('how visible their product results are in Google web Search, and which product pages carry them') and names the alternative with its condition ('Not for the Shopping tab, Images, Lens, YouTube or Maps: use get_organic_shopping_performance'). It also gives a caveat about non-ecommerce sites producing empty results, which pre-empts a wrong-tool conclusion.

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

All SEO GSC Wizard MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?