SEO GSC Wizard MCP

Find page poaching opportunities

find_page_poaching_opportunities

Read-only

Use this when the user asks which queries could gain the most clicks by moving up. Finds queries ranking just outside the top positions (between minPosition and maxPosition) and estimates the click upside of pushing them to a target position. Not for an impression-weighted score across positions 3-30: use score_opportunities. The upside uses the property's OWN CTR at the target position (measured over every query in the window on the warehouse), not an industry benchmark. Only queries Google lists are scanned: on most properties a large share of clicks has no query row (analyze_sampling_impact measures it). When the property has no queries at the target position, or fewer than 100 impressions there, it falls back to the industry benchmark named by fallbackBenchmark: awr (Advanced Web Ranking 2026, default), awr2026 (AWR 2026 CTR study, organic), awrAio (same study, SERPs with an AI Overview), firstPageSage (First Page Sage 2026), sistrix (Sistrix 2024), or backlinko (Backlinko 2019). The response reports targetCtr (the expected CTR used; it and each row's ctr are 0-100 percentages), ctrSource ("own" or the benchmark key) and ctrSourceNote (why). Sorted by potentialClicks, largest first. Scans up to 25,000 queries: on the warehouse the ones with the most impressions; on the live API its click order. truncated: true means the scan hit that cap (scanNote says what that left out). minImpressions defaults to 10 (it also floors the own CTR curve); when it is left out and no query passes, the tool retries once at 1 on its own and says so in minImpressionsAutoRelaxed (minImpressions is always the floor applied). Served from the GSC Wizard ClickHouse warehouse when available, otherwise the live Search Console API (see dataSource). 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
`limit`	No
`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
`maxPosition`	No
`minPosition`	No
`minImpressions`	No	Minimum impressions per query (default 10). When left out and nothing passes it, the tool retries once at 1 and reports `minImpressionsAutoRelaxed`; a value you pass, including 10, is always applied as given.
`targetPosition`	No
`fallbackBenchmark`	No		awr

Output Schema

Name	Required	Description
`note`	No
`range`	No
`params`	No
`thenBy`	No
`listKey`	No	Name of the top-level field that holds the rows sortedBy describes.
`siteUrl`	No
`warning`	No
`nextStep`	No
`ordering`	No
`scanNote`	No
`sortedBy`	No
`ctrSource`	No
`scanLimit`	No
`sortOrder`	No
`targetCtr`	No
`thenOrder`	No
`truncated`	No
`dataSource`	No
`partialDays`	No
`dataMaturity`	No
`emptyBecause`	No
`methodLimits`	No
`ctrSourceNote`	No
`opportunities`	No
`minImpressions`	No
`settledThrough`	No
`warehouseLatestDate`	No
`minImpressionsAutoRelaxed`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 28, 2026

removedInput schema / properties / minImpressions / default
```
Removed value: -10
```

addedInput schema / properties / minImpressions / description

Added value: +"Minimum impressions per query (default 10). When left out and nothing passes it, the tool retries once at 1 and reports `minImpressionsAutoRelaxed`; a value you pass, including 10, is always applied as given."

addedOutput schema / properties / listKey

Added value: +{
+  "$ref": "#/properties/siteUrl",
+  "description": "Name of the top-level field that holds the rows sortedBy describes."
+}

addedOutput schema / properties / minImpressions

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

addedOutput schema / properties / minImpressionsAutoRelaxed

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "from": {
+          "$ref": "#/properties/range/anyOf/0/properties/days"
+        },
+        "to": {
+          "$ref": "#/properties/range/anyOf/0/properties/days"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

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

Changed14 schema fields changedOct 18, 2026

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

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

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

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

Changed5 schema fields changedOct 10, 2026

addedOutput schema / properties / ctrSourceNote

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

addedOutput schema / properties / scanLimit

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

addedOutput schema / properties / scanNote

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

addedOutput schema / properties / truncated

Added value: +{
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

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?

With readOnlyHint/destructiveHint already covering safety, the description still discloses the non-obvious mechanics: own-CTR-at-target-position calculation, the full fallback benchmark ladder and its trigger conditions, the 25,000-query scan cap with truncation semantics, the auto-relax retry behavior for minImpressions, warehouse-vs-live-API sourcing, and the ~2-3 day data lag. Nothing here contradicts 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 purpose is front-loaded in sentence one, and nearly every sentence adds decision-relevant detail (fallback conditions, scan cap, auto-relax) rather than restating the name. It is a single ~350-word block, though, and would be easier to scan if the fallback/scan/date-range material were broken out.

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 10 parameters, a low schema coverage, and an output schema, the description supplies everything an agent needs to invoke correctly: range semantics, defaults, fallback selection, truncation risk, and date-lag handling. Return-value explanations (targetCtr, ctrSource, scanNote) partly duplicate the output schema but don't leave gaps.

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 description coverage is only 40%, so the description has to carry weight — and it does: it explains minImpressions' default, auto-relax retry, and floor role, expands each fallbackBenchmark enum value, and gives meaning to minPosition/maxPosition/targetPosition. It never mentions `limit`, leaving one parameter undocumented in both places.

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 — finds queries ranking just outside the top (between minPosition and maxPosition) and estimates click upside of moving them to a target position. The opening sentence is framed as a user question, and the explicit contrast with score_opportunities makes it distinguishable from siblings without opening either schema.

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?

Gives an explicit trigger ("Use this when the user asks which queries could gain the most clicks by moving up") and an explicit exclusion with the alternative named ("Not for an impression-weighted score across positions 3-30: use score_opportunities"). The when and the when-not are both stated.

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?