SEO GSC Wizard MCP

Long-tail page clustering

get_longtail_clusters

Read-only

Use this when the user asks whether a property's traffic leans on a few pages or on a bloated long tail: segments its pages into Head / Chunky Middle / Long Tail tiers by elbow detection on the cumulative-clicks curve (the app's Long-tail Clustering report). Not for URL folders: use breakdown_by_path. Returns each tier's page count, click/impression share, average CTR (0-100)/position/query-diversity, the knee points, and the top pages per tier. Page clicks/impressions/position (and the totals) are the page figures Search Console's page filter shows, including anonymized-query traffic; query diversity counts only the page's named queries (query x page rows), and coverage.hiddenClicksShare (0-1) is the share of the property's clicks with no query row. Tiers run head to tail, each tier's pages by clicks, highest first. Reads the ClickHouse warehouse when available, else the live Search Console API. truncated: true (with truncationNote) means a cap was hit: the warehouse clusters at most the 100,000 pages with the most clicks, the live API reads at most 100,000 pages and 100,000 query x page rows. 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
`preset`	No	Tuning preset: default \| content \| ecommerce \| small_site \| enterprise.	default
`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".
`sensitivity`	No	Override the preset's knee sensitivity: low \| normal \| high.
`pagesPerCluster`	No	How many top pages to list per tier (default 10). 0 returns tier stats only.
`includeZeroClicks`	No	Include pages with zero clicks (impressions only). Defaults per preset (usually true).

Output Schema

Name	Required	Description
`note`	No
`knees`	No
`range`	No
`preset`	No
`thenBy`	No
`totals`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`siteUrl`	No
`warning`	No
`clusters`	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
`warnings`	No
`sortOrder`	No
`thenOrder`	No
`truncated`	No
`dataSource`	No
`partialDays`	No
`sensitivity`	No
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`settledThrough`	No
`truncationNote`	No
`apiRowCapReached`	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."
+}

Changed23 schema fields changedOct 18, 2026

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

changedOutput schema / properties / clusters / items / properties / urlRange / anyOf

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

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

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

addedOutput schema / properties / methodLimits

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

addedOutput schema / properties / nextStep

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

addedOutput schema / properties / note

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

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"
-      },
-      "rawRows": {
-        "$ref": "#/properties/range/anyOf/0/properties/days"
-      },
-      "urls": {
-        "$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"
+      },
+      "rawRows": {
+        "$ref": "#/properties/range/anyOf/0/properties/days"
+      },
+      "urls": {
+        "$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"
+}

Changed2 schema fields changedOct 10, 2026
- addedOutput schema / properties / truncated
```
Added value: +{
+  "$ref": "#/properties/apiRowCapReached"
+}
```
- addedOutput schema / properties / truncationNote
```
Added value: +{
+  "$ref": "#/properties/siteUrl"
+}
```
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 already establish read-only, non-destructive, open-world behavior, and the description adds substantial operational context: ClickHouse vs live Search Console fallback, truncation caps, settled-date lag, anonymized-query handling, query-diversity scope, and coverage.hiddenClicksShare semantics. It discloses meaningful limitations beyond the annotations.

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 dense and front-loads the use case, scope exclusion, return shape, data-source behavior, and truncation limits. It is longer than typical, but most details are useful for a complex analytics tool; some return-value detail could have been left to the output schema.

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?

Given the complexity, annotations, high schema coverage, and the presence of an output schema, the description is complete enough to invoke correctly. It explains data sources, date defaults, truncation behavior, tier semantics, and the main sibling alternative.

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 already 86%, so the schema carries most parameter meaning. The description reinforces the optional date range and default 28-day window, but it does not add much explanation for preset, sensitivity, pagesPerCluster, or includeZeroClicks beyond what the schema already provides.

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 states a specific analytical operation: segmenting a property's pages into Head / Chunky Middle / Long Tail tiers by elbow detection on the cumulative-clicks curve. It also distinguishes the tool from a sibling by explicitly saying it is not for URL folders and naming breakdown_by_path instead.

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 gives a clear when-to-use condition: the user asks whether traffic leans on a few pages or a bloated long tail. It also gives an explicit when-not-to-use case and the alternative to use for URL-folder analysis.

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?