SEO GSC Wizard MCP

Query shape trend over time

get_query_shape_trend

Read-only

Use this when the user asks "are AI Overviews / AI Mode queries growing on this site?", which no single-period report can show: tracks how much of a property's search traffic comes from AI-shaped queries over time (the trend chart on the app's Query Analysis report). Not for the per-bucket breakdown: use analyze_query_shapes. Returns one row per month (or week), oldest first, with clicks and impressions split into AI-shaped (reply artefacts, pivot follow-ups, conversational questions) versus conventional keywords, plus the AI-shaped share of each metric (0-100). Shares and totals are of visible queries only: coverage.hiddenClicksShare (0-1) is the share of the property's clicks with no query row. Defaults to the last 12 complete months. Served from the GSC Wizard ClickHouse warehouse when available (longer history), otherwise the live Search Console API.

Input Schema

Name	Required	Description	Default
`months`	No	How many complete months to cover, ending with last month (1-16; Search Console keeps ~16 months).
`endDate`	No	Optional. Window end as YYYY-MM-DD. Provide BOTH startDate and endDate to override the default window, or omit both to use the last `months` complete months. Never pass null or "null".
`siteUrl`	Yes
`startDate`	No	Optional. Window start as YYYY-MM-DD. Provide BOTH startDate and endDate to override the default window, or omit both to use the last `months` complete months. Never pass null or "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
`granularity`	No		month

Output Schema

Name	Required	Description
`note`	No
`range`	No
`thenBy`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`periods`	No
`siteUrl`	No
`warning`	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
`shapeNote`	No
`sortOrder`	No
`thenOrder`	No
`truncated`	No
`dataSource`	No
`granularity`	No
`partialDays`	No
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`settledThrough`	No
`truncationNote`	No
`coverageUnavailable`	No	Why coverage is null, when it is.
`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"
+]

Changed16 schema fields changedOct 18, 2026

changedOutput schema / 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."
+}

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

addedOutput schema / properties / partialDays

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

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

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

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

Behavior5/5

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

Beyond the read-only annotations, it discloses that results come from a ClickHouse warehouse when available or the live Search Console API otherwise, that totals are based only on visible queries, and that coverage.hiddenClicksShare reports the missing-query-row share. It also describes the output shape, ordering, and share ranges.

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?

The description is front-loaded with the core use case and the sibling distinction, and most sentences carry useful information. It is a dense single paragraph with nested parentheticals, so readability could be improved, but it is not bloated.

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 trend tool with six parameters and an output schema, the description supplies the key context an agent needs: when to use it, the alternative for per-bucket analysis, default window, output granularity, caveats about visible queries, and data-source differences.

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 67%, and the description adds meaning by stating the default 12 complete months and that output rows are per month or week. It does not explain every parameter, but the schema itself documents months, startDate, endDate, and searchType well, and the description covers the most important defaults and caveats.

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 gives a specific verb and resource: tracking AI-shaped query traffic over time for a property. It explicitly contrasts itself with analyze_query_shapes, so an agent can distinguish it from the per-bucket breakdown sibling.

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?

It states the exact user question this tool answers (growth of AI Overviews / AI Mode queries), notes that no single-period report can show it, and explicitly says not to use it for per-bucket breakdowns, directing the agent to analyze_query_shapes 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?