SEO GSC Wizard MCP

Top search queries

query_top_queries

Read-only

Returns the top search queries for a property over a date range, sorted by clicks. Convenience wrapper around query_search_analytics for the most common request. Served from the GSC Wizard ClickHouse warehouse (longer history, no sampling) when available, otherwise from the live Search Console API; the response dataSource field says which. Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).

Input Schema

TableJSON 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		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

TableJSON Schema

Name	Required	Description
`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.
`title`	No
`blocks`	No	Stacked sub-blocks (kind="sections").
`source`	No
`columns`	No	Column defs (kind="table").
`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.
`dataMaturity`	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.

Schema Changelog

Changes observed during successful MCP inspections.

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.5/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description goes well beyond structured data: it discloses the dual data source (ClickHouse warehouse vs live API), the no-sampling/longer-history tradeoff, that the response `dataSource` field reports which was used, and the ~2-3 day data lag. This is exactly the operational context an agent cannot infer elsewhere.

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?

Four tight sentences, front-loaded with the core purpose before moving to the wrapper relationship, data-source behavior, and date defaults. Every sentence carries information an agent needs.

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?

For a 9-parameter analytics tool with an output schema and rich annotations, the description supplies the missing operational pieces: source selection, sampling behavior, and default date-window logic. Since an output schema exists, it correctly avoids explaining return values beyond the one useful `dataSource` note.

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 description coverage is high (78%), and the description largely restates what the schema already documents about the optional date range and its 28-day default rather than adding new meaning. It does not compensate for the undocumented params (siteUrl, searchType), so the baseline 3 is appropriate.

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+resource (returns top search queries), the sort order (by clicks), and the scope (for a property over a date range). It explicitly frames itself as a wrapper around query_search_analytics, letting an agent separate it from that sibling and from query_top_pages 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 Guidelines4/5

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

Names the underlying alternative (query_search_analytics) and positions this as 'the most common request', which gives clear context for when to reach for it. It lacks an explicit when-not clause (e.g. 'use query_search_analytics for advanced filtering'), so it falls just short of a 5.

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?