SEO GSC Wizard MCP

Merchant Center best sellers

get_gmc_best_sellers

Read-only

Use this when the user asks what sells best in Google Shopping or which popular products they do not stock. Google's best sellers ranking for one country from the Google Merchant Center account linked to a GSC Wizard site: the most popular product clusters ("product_cluster", the default) or brands ("brand") per Google product category, with rank, previous rank, relative demand (VERY_LOW..VERY_HIGH), its direction (SINKER / FLAT / RISER) and, for product clusters, whether any of your offers matches (inventoryStatus). Rows run by reportCategoryId, then rank (1 = top); rankChange > 0 means it climbed. Each product-cluster row carries demandGap: true when Google ranks the cluster but you do not stock it; note that inventory status ignores the report country. Not for competitors or prices: use get_gmc_competitors or get_gmc_pricing_insights. Pick WEEKLY (Monday-dated) or MONTHLY (1st-dated) reports; omit reportDate for the newest report Google has published (reports lag up to two weeks). countryCode is required because the Merchant API answers one country per request; categoryId (Google product taxonomy id) narrows to one category, otherwise every top-level category is returned. reportUnavailable (with no rows) means Google refuses this report for the Merchant Center account (eligibility); the other reports are unaffected. Returns a notConfigured result (not an error) when Merchant Center is not connected or no Merchant Center account is linked to the site in the GSC Wizard app.

Input Schema

Name	Required	Description	Default
`view`	No	"product_cluster" (ranked product clusters with title, category path, GTINs and your inventory status, the default) or "brand" (ranked brands, no inventory data).	product_cluster
`limit`	No	Rows to return, ordered by (country, category, rank) (default 100, max 1000).
`siteUrl`	Yes	The property URL as returned by list_sites (e.g. "sc-domain:example.com").
`categoryId`	No	Optional. Google product taxonomy id as a digits-only string (e.g. "166" for Apparel & Accessories). Omit for every top-level category.
`reportDate`	No	Optional. The report to read as YYYY-MM-DD: a Monday for WEEKLY, the 1st of a month for MONTHLY. Omit for the newest published report (recommended: reports lag up to two weeks). Never pass null or the string "null".
`countryCode`	Yes	Required. Report country as ISO 3166-1 alpha-2 (e.g. "US", "NL"). Case-insensitive.
`granularity`	No	"WEEKLY" (Monday-dated reports, the default) or "MONTHLY" (1st-of-month reports).	WEEKLY

Output Schema

Name	Required	Description
`hint`	No
`rows`	No
`view`	No
`range`	No
`reason`	No
`thenBy`	No
`account`	No
`hasMore`	No
`lagNote`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`siteUrl`	No
`cachedAt`	No
`nextStep`	No
`ordering`	No
`rowCount`	No
`sortedBy`	No
`emptyNote`	No
`sortOrder`	No
`thenOrder`	No
`truncated`	No
`categoryId`	No
`dataSource`	No
`reportDate`	No
`countryCode`	No
`granularity`	No
`reportsSeen`	No
`emptyBecause`	No
`gmcAccountId`	No
`methodLimits`	No
`countryCaveat`	No
`notConfigured`	No
`demandGapCount`	No
`truncationNote`	No
`fetchedRowCount`	No
`truncationReason`	No
`reportUnavailable`	No
`requestedReportDate`	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."
+}

Changed12 schema fields changedOct 18, 2026

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

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 / range / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "days": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "endDate": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "startDate": {
-        "$ref": "#/properties/siteUrl"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "days": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "endDate": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "startDate": {
+        "$ref": "#/properties/siteUrl"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / reportUnavailable / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "message": {
-        "$ref": "#/properties/siteUrl"
-      },
-      "reason": {
-        "$ref": "#/properties/siteUrl"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "message": {
+        "$ref": "#/properties/siteUrl"
+      },
+      "reason": {
+        "$ref": "#/properties/siteUrl"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

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

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

Changed1 schema field changedOct 10, 2026

addedOutput schema / properties / reportUnavailable

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "message": {
+          "$ref": "#/properties/siteUrl"
+        },
+        "reason": {
+          "$ref": "#/properties/siteUrl"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Changed2 schema fields changedOct 10, 2026
- addedOutput schema / properties / cachedAt
```
Added value: +{
+  "$ref": "#/properties/siteUrl"
+}
```
- addedOutput schema / properties / truncationReason
```
Added value: +{
+  "$ref": "#/properties/siteUrl"
+}
```
First observedOct 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already mark this readOnly/non-destructive/open-world, but the description adds context those cannot carry: report lag of up to two weeks, the `reportUnavailable` eligibility failure mode, the non-error `notConfigured` result when Merchant Center isn't linked, and the caveat that inventory status ignores the report country. These are exactly the edge cases an agent needs before reporting results to a user.

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 use case and alternative routing, then the data shape, then the failure modes — a sensible order. The middle is a single very long run-on sentence that stacks rank, demand, direction and inventory semantics together, which is dense though each clause carries information an agent would otherwise have to guess.

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?

Seven parameters, an output schema, and annotations are all accounted for: the description covers row ordering, default view, dating rules, the two failure results, and a semantic gotcha (demandGap/inventoryStatus scope). Nothing needed to call this correctly or interpret the result 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 goes beyond it by giving the rationale behind required fields (countryCode is required because the Merchant API answers one country per request) and by explaining the reportDate dating convention alongside the recommended omit-for-latest behavior. Marginal gain over the already-descriptive schema, hence 4 rather than 5.

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 the specific resource (Google's best sellers ranking per country from Merchant Center) and the exact shape of the data (product clusters or brands, rank, previous rank, relative demand, direction, inventory status). It explicitly separates itself from the two closest siblings in the same family (get_gmc_competitors, get_gmc_pricing_insights), so an agent can route without opening a 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?

Opens with a concrete trigger: 'Use this when the user asks what sells best in Google Shopping or which popular products they do not stock.' It also gives explicit when-not guidance ('Not for competitors or prices') and names the alternative tools to use instead.

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?