SEO GSC Wizard MCP

Query shape analysis (AI Mode fingerprints)

analyze_query_shapes

Read-only

Use this when the user asks whether AI Overviews / AI Mode fan-out shows in a property's queries: classifies them by SHAPE (the app's Query Analysis report). Not for change over time: use get_query_shape_trend. Buckets: reply artefacts ("yes", "show me"), pivot follow-ups ("what about gemini"), conversational questions, LLM tracker probes, agent harnesses, pasted strings, long uncategorised, and conventional keywords. Returns per-bucket query/click/impression counts and shares (0-100), zero-click counts, average position, and top example queries (ctr 0-100), plus an aiShaped roll-up of the conversational buckets. Shares are of visible queries only: coverage.hiddenClicksShare (0-1) is the share of the property's clicks with no query row. Buckets run in bucketOrder (conventional last), examples by impressions, highest first. Heuristic pattern matching in 27 languages: it judges how a query LOOKS, not what the searcher meant, so treat single rows as evidence rather than proof. Reads the ClickHouse warehouse when available, else the live Search Console API. 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
`buckets`	No	Optional. Only return these buckets, e.g. ["reply_artefact","pivot_follow_up","conversational_question"] for the AI-conversation shapes. Omit for all buckets.
`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
`examplesPerBucket`	No	How many top example queries (by impressions) to return per bucket. 0 returns counts only.

Output Schema

Name	Required	Description
`note`	No
`range`	No
`thenBy`	No
`totals`	No
`buckets`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`siteUrl`	No
`warning`	No
`aiShaped`	No
`coverage`	No	How much of the property total the rows cover, totals inline. Quote totals from here; do not sum rows.
`nextStep`	No
`ordering`	No
`sortedBy`	No
`languages`	No
`sortOrder`	No
`thenOrder`	No
`truncated`	No
`dataSource`	No
`searchType`	No
`partialDays`	No
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`settledThrough`	No
`candidateFiltered`	No
`candidatesScanned`	No
`coverageUnavailable`	No	Why coverage is null, when it is.
`questionFormQueries`	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."
+}

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

Changed22 schema fields changedOct 18, 2026

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

changedOutput schema / properties / aiShaped / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "clicks": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "impressions": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "queries": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "shareOfImpressionsPct": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "shareOfQueriesPct": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "zeroClickQueries": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "clicks": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "impressions": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "queries": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "shareOfImpressionsPct": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "shareOfQueriesPct": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "zeroClickQueries": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

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

addedOutput schema / properties / buckets / items / properties / bucketOrder

Added value: +{
+  "$ref": "#/properties/range/anyOf/0/properties/days"
+}

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

addedOutput schema / properties / coverage

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "clicksCovered": {
+          "$ref": "#/properties/range/anyOf/0/properties/days",
+          "description": "0-1 share of the totals named by sharesOf that this page's rows carry."
+        },
+        "filteredTotals": {
+          "$ref": "#/properties/coverage/anyOf/0/properties/siteTotals",
+          "description": "The same totals with the filters applied (scope \"filtered\")."
+        },
+        "hiddenClicksShare": {
+          "$ref": "#/properties/range/anyOf/0/properties/days",
+          "description": "0-1 share of those totals that no row of this dimension carries (anonymised queries on query rows, near zero on page, country and device rows); null when unknown."
+        },
+        "hiddenImpressionsShare": {
+          "$ref": "#/properties/range/anyOf/0/properties/days"
+        },
+        "impressionsCovered": {
+          "$ref": "#/properties/range/anyOf/0/properties/days"
+        },
+        "note": {
+          "$ref": "#/properties/siteUrl",
+          "description": "Why some fields are null, when they are."
+        },
+        "rowsReturned": {
+          "$ref": "#/properties/range/anyOf/0/properties/days",
+          "description": "Rows on this page."
+        },
+        "rowsTotal": {
+          "$ref": "#/properties/range/anyOf/0/properties/days",
+          "description": "Rows across every page; null when unknown."
+        },
+        "scope": {
+          "$ref": "#/properties/siteUrl",
+          "description": "\"property\", or \"filtered\" when the rows were read with filters."
+        },
+        "sharesOf": {
+          "$ref": "#/properties/siteUrl",
+          "description": "\"siteTotals\", or \"filteredTotals\" when scope is \"filtered\"."
+        },
+        "siteTotals": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "properties": {
+                "avgPositionWeighted": {
+                  "$ref": "#/properties/range/anyOf/0/properties/days",
+                  "description": "Impression-weighted average position."
+                },
+                "clicks": {
+                  "$ref": "#/properties/range/anyOf/0/properties/days"
+                },
+                "ctrPercent": {
+                  "$ref": "#/properties/range/anyOf/0/properties/days",
+                  "description": "A 0-100 percentage."
+                },
+                "impressions": {
+                  "$ref": "#/properties/range/anyOf/0/properties/days"
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The property's totals for this window and search type, with no dimension and no filter."
+        },
+        "totalsFrom": {
+          "$ref": "#/properties/siteUrl",
+          "description": "\"get_site_summary\" (the read and arithmetic that tool uses) or \"property_totals\" (the same, for a search type other than web)."
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How much of the property total the rows cover, totals inline. Quote totals from here; do not sum rows."
+}

addedOutput schema / properties / coverageUnavailable

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

addedOutput schema / properties / dataMaturity

Added value: +{
+  "anyOf": [
+    {
+      "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"
+    }
+  ]
+}

addedOutput schema / properties / partialDays

Added value: +{
+  "$ref": "#/properties/buckets/items/properties/examples/items/properties/signals"
+}

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

addedOutput schema / properties / settledThrough

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

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

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "clicks": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "impressions": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "queries": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "clicks": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "impressions": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "queries": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / warehouseLatestDate

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

addedOutput schema / properties / warning

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?

Goes far beyond the readOnly/openWorld annotations: discloses the 27-language heuristic pattern matcher and its epistemic limit ("judges how a query LOOKS, not what the searcher meant, so treat single rows as evidence rather than proof"), the ClickHouse-then-live-GSC data path, the ~2-3 day data lag, and the visible-queries-only share caveat with coverage.hiddenClicksShare. Ordering semantics (bucketOrder, examples by impressions) and the aiShaped roll-up are also stated.

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 trigger and the alternative, then the bucket taxonomy, then caveats — a sensible information hierarchy. It is dense and long for a single paragraph, with the return-shape details packed tightly enough to slow scanning, but no sentence is filler.

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?

Covers everything an agent needs to call and interpret this correctly: trigger, sibling routing, bucket vocabulary, date defaults, data source fallback, lag, coverage caveat, and the heuristic's reliability limits. An output schema exists so return values needn't be explained, yet the description still frames the key fields usefully.

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 already 83%, so the baseline is 3; the description still adds real meaning by defining what each bucket name actually contains ("reply artefacts ("yes", "show me"), pivot follow-ups...") rather than leaving the enum opaque. It also reinforces the optional date-range default (omit both → last 28 settled days), though it does not add anything on searchType or examplesPerBucket beyond the schema.

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?

Specific verb+resource: classifies query rows by SHAPE (AI Mode / AI Overview fan-out) against the app's Query Analysis report. It immediately distinguishes itself from the sibling get_query_shape_trend and from query_top_queries-style tools by naming the SHAPE lens explicitly.

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 an explicit trigger ("Use this when the user asks whether AI Overviews / AI Mode fan-out shows in a property's queries") and an explicit exclusion with the correct alternative ("Not for change over time: use get_query_shape_trend"). Nothing about when-to-use is left to inference.

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?