SEO GSC Wizard MCP

Top search queries

query_top_queries

Read-only

Use this when the user asks which search queries bring a property the most clicks. Returns the top queries over a date range: a wrapper around query_search_analytics. Not for totals: use get_site_summary. Rows are sorted by clicks, highest first; ctr is a 0-100 percentage. Query rows cover only the queries Google lists: coverage.hiddenClicksShare (0-1) is the share of clicks with no query row, so quote totals from coverage.siteTotals, or coverage.filteredTotals when coverage.scope is "filtered", not summed rows. Served from the ClickHouse warehouse (longer history) when available, else the live Search Console API (dataSource says which). 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
`brand`	No	Optional. Narrow to queries matching the property's branded keywords ('branded') or to all others ('non_branded'). Needs branded keywords set (update_site brandedKeywords); see get_filter_options.
`limit`	No	Rows to return per call (default 100, max 1000).
`offset`	No	Rows to skip. Use pagination.nextOffset from a previous call to get the next page.
`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
`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".
`searchType`	No	Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), or all (web + image + video + news + discover combined, position impression-weighted, like the app's "All" filter). Discover and googleNews carry no query dimension, so query-level results for them are empty, and no position: it reads null, not 0.	web
`contentGroupId`	No	Optional. Narrow to pages in this content group (id from get_filter_options or list_content_groups). Groups whose rules cannot be applied as a filter are refused; get_filter_options says which.
`topicClusterId`	No	Optional. Narrow to queries in this topic cluster (id from get_filter_options or list_topic_clusters). Clusters whose keywords cannot be applied as a filter are refused.

Output Schema

Name	Required	Description
`hint`	No
`kind`	No	Widget variant: "kpis", "table", or "sections".
`kpis`	No	KPI cards (kind="kpis").
`note`	No	Caveat about the result, when the tool returned one.
`rows`	No	Data rows (kind="table").
`notes`	No	Caveats about the result, when the tool returned several.
`scope`	No	The brand, content group or topic cluster filter these numbers are narrowed to; absent when the call was unscoped and the numbers cover the whole property.
`title`	No
`blocks`	No	Stacked sub-blocks (kind="sections").
`reason`	No
`source`	No
`thenBy`	No	Secondary sort field, when the tool states one.
`account`	No
`columns`	No	Column defs (kind="table").
`warning`	No	A caveat that changes how the numbers read.
`coverage`	No	How much of the property total the returned rows cover, with the property totals inline. Quote totals from here; do not sum the rows.
`nextStep`	No
`ordering`	No	Sort order per list, when the result holds several lists.
`sortedBy`	No	Row field the rows are sorted by.
`timeZone`	No	GA4 property's IANA reporting time zone.
`emptyText`	No
`siteScope`	No	Set when GA4 numbers were narrowed to this site's hostnames because the property is shared with other sites.
`sortOrder`	No	"asc" or "desc".
`thenOrder`	No	The tie-break's direction, present only when it differs from sortOrder.
`partialDays`	No	Requested days after settledThrough; their numbers are still incomplete.
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`notConfigured`	No
`reauthRequired`	No
`settledThrough`	No	Last day the data is complete through.
`comparisonHasData`	No	false when the comparison period has no data at all, so there is no comparison.
`coverageUnavailable`	No	Why coverage is null, when it is.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 25, 2026

changedInput schema / properties / searchType / description

Previous value: -"Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), or all (web + image + video + news + discover combined, position impression-weighted, like the app's \"All\" filter). Discover and googleNews carry no query dimension, so query-level results for them are empty."New value: +"Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), or all (web + image + video + news + discover combined, position impression-weighted, like the app's \"All\" filter). Discover and googleNews carry no query dimension, so query-level results for them are empty, and no position: it reads null, not 0."

Changed2 schema fields changedOct 25, 2026

addedInput schema / properties / searchType / description

Added value: +"Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), or all (web + image + video + news + discover combined, position impression-weighted, like the app's \"All\" filter). Discover and googleNews carry no query dimension, so query-level results for them are empty."

changedInput schema / properties / searchType / enum

Previous value: -[
-  "web",
-  "image",
-  "video",
-  "news"
-]New value: +[
+  "web",
+  "image",
+  "video",
+  "news",
+  "discover",
+  "googleNews",
+  "all"
+]

Changed21 schema fields changedOct 18, 2026

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

addedOutput schema / properties / account

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

addedOutput schema / properties / coverage

Added value: +{
+  "description": "How much of the property total the returned rows cover, with the property totals inline. Quote totals from here; do not sum the rows."
+}

addedOutput schema / properties / coverageUnavailable

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "Why coverage is null, when it is."
+}

changedOutput schema / properties / dataMaturity / anyOf

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

addedOutput schema / properties / emptyBecause

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

addedOutput schema / properties / hint

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

addedOutput schema / properties / methodLimits

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

addedOutput schema / properties / nextStep

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

addedOutput schema / properties / notConfigured

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

addedOutput schema / properties / ordering

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "additionalProperties": true,
+        "properties": {
+          "sortOrder": {
+            "$ref": "#/properties/title"
+          },
+          "sortedBy": {
+            "$ref": "#/properties/title"
+          },
+          "thenBy": {
+            "$ref": "#/properties/title"
+          },
+          "thenOrder": {
+            "$ref": "#/properties/title"
+          }
+        },
+        "type": "object"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Sort order per list, when the result holds several lists."
+}

addedOutput schema / properties / partialDays

Added value: +{
+  "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames",
+  "description": "Requested days after settledThrough; their numbers are still incomplete."
+}

addedOutput schema / properties / reason

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

addedOutput schema / properties / reauthRequired

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

addedOutput schema / properties / scope

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "brand": {
+          "$ref": "#/properties/kind",
+          "description": "\"branded\" or \"non_branded\"."
+        },
+        "brandKeywordsSkipped": {
+          "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames",
+          "description": "Branded keywords that could not be compiled and were left out of the filter."
+        },
+        "contentGroup": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "properties": {
+                "id": {
+                  "$ref": "#/properties/title"
+                },
+                "name": {
+                  "$ref": "#/properties/title"
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "topicCluster": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "properties": {
+                "id": {
+                  "$ref": "#/properties/title"
+                },
+                "name": {
+                  "$ref": "#/properties/title"
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The brand, content group or topic cluster filter these numbers are narrowed to; absent when the call was unscoped and the numbers cover the whole property."
+}

changedOutput schema / properties / siteScope / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "hostnames": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "includesSubdomainsOf": {
-        "$ref": "#/properties/title"
-      },
-      "note": {
-        "$ref": "#/properties/title"
-      },
-      "sharedWithSites": {
-        "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "hostnames": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "includesSubdomainsOf": {
+        "$ref": "#/properties/title"
+      },
+      "note": {
+        "$ref": "#/properties/title"
+      },
+      "sharedWithSites": {
+        "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / sortOrder

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "\"asc\" or \"desc\"."
+}

addedOutput schema / properties / sortedBy

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "Row field the rows are sorted by."
+}

addedOutput schema / properties / thenBy

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "Secondary sort field, when the tool states one."
+}

addedOutput schema / properties / thenOrder

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "The tie-break's direction, present only when it differs from sortOrder."
+}

addedOutput schema / properties / warning

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "A caveat that changes how the numbers read."
+}

Changed4 schema fields changedOct 7, 2026

addedOutput schema / properties / comparisonHasData

Added value: +{
+  "description": "false when the comparison period has no data at all, so there is no comparison.",
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

addedOutput schema / properties / note

Added value: +{
+  "$ref": "#/properties/kind",
+  "description": "Caveat about the result, when the tool returned one."
+}

addedOutput schema / properties / notes

Added value: +{
+  "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames",
+  "description": "Caveats about the result, when the tool returned several."
+}

addedOutput schema / properties / siteScope

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "hostnames": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "includesSubdomainsOf": {
+          "$ref": "#/properties/title"
+        },
+        "note": {
+          "$ref": "#/properties/title"
+        },
+        "sharedWithSites": {
+          "$ref": "#/properties/siteScope/anyOf/0/properties/hostnames"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Set when GA4 numbers were narrowed to this site's hostnames because the property is shared with other sites."
+}

First observedOct 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare read-only/open-world/safe, and the description adds substantial context beyond them: rows are click-sorted, ctr is a 0-100 percentage, results come from ClickHouse when available else the live API (exposed via dataSource), and data lags ~2-3 days. The coverage caveat (`hiddenClicksShare`, `siteTotals` vs `filteredTotals`) warns about a real correctness trap (summing rows understates totals) that no structured field conveys.

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-loads the use case before the mechanics, and nearly every sentence carries operational value. It is dense — the coverage/totals caveat is a long compound sentence — but nothing is pure filler, so it stays readable for its payload.

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?

An output schema exists, yet the description still supplies the semantics an agent needs to interpret results correctly (sort order, ctr units, hidden-clicks share, which totals to quote, which data source served them). For a 9-parameter analytics query tool with cross-source fallback, nothing important is missing.

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?

Schema coverage is 89%, so nearly every parameter is already documented in the schema — including the 28-day default and the ~2-3 day lag, which the description largely restates. The description adds little per-parameter detail beyond the schema, so this is the baseline-3 case where the schema does the heavy lifting.

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 a specific verb and resource ("Returns the top queries over a date range"), names the sort (clicks, highest first) and its underlying implementation (a wrapper around query_search_analytics). It also explicitly disambiguates from get_site_summary for totals, so an agent can distinguish it from siblings without opening schemas.

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 use trigger ("when the user asks which search queries bring a property the most clicks") and gives an explicit exclusion with the correct alternative ("Not for totals: use get_site_summary"). It additionally points at query_search_analytics as the general-purpose sibling, covering both when-to-use and when-not.

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?