@digestseo/mcp-gsc 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-09-21
+
+### Changed
+- The documented and npm-declared Node.js minimum is now 22+, matching the bundled Wrangler 4 runtime requirement instead of advertising unsupported Node.js 20 installs.
+
+### Fixed
+- URL Inspection guidance now states that Google reports the version currently in its index rather than running a live URL test, and no longer presents the deprecated mobile-usability field as a current primary signal.
+
+## [0.4.2] - 2026-09-21
+
+### Fixed
+- Cannibalization totals and impression shares now expose their query/page-row aggregation scope explicitly so clients do not mistake summed page impressions for a true query-level Search Console total.
+- Discover Search Analytics calls now reject unsupported query grouping/filtering before reaching Google, and query-centric/comparison tools no longer advertise Discover where their contracts depend on query or average-position data that Discover does not provide.
+- Quick-win guidance now treats Search Console position as an aggregate average-position metric rather than a literal current rank, and metadata no longer implies CTR is an eligibility filter when the implementation does not filter on CTR.
+
 ## [0.4.1] - 2026-09-21
 
 ### Changed

package/README.md

@@ -75,10 +75,10 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`sites.get`** | Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
 | **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. |
 | **`insights.page_queries`** / **`insights.query_pages`** | Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it, with `row_limit` / `start_row` pagination. |
-| **`urls.inspect`** | Read | Google's URL Inspection report for a single page. |
-| **`urls.inspect_many`** | Read | Inspect up to 10 URLs sequentially in one call. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget. |
+| **`urls.inspect`** | Read | Google's URL Inspection report for the version of one page currently known in Google's index. It is not a live URL test; mobile-usability output is deprecated. |
+| **`urls.inspect_many`** | Read | Inspect Google's indexed versions of up to 10 URLs sequentially in one call. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget; this does not run live URL tests. |
 | **`sitemaps.list`** / **`sitemaps.get`** | Read | List submitted sitemaps or retrieve one sitemap's details. |
-| **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface striking-distance opportunities, query/page overlap, and evidence-ranked click declines. Content-decay results distinguish likely decay from weak evidence and improving visibility with click volatility. |
+| **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick-win candidates are observed query/page rows selected by aggregate Search Console average position, not proof of a stable current rank, and CTR is context rather than an eligibility filter. Cannibalization candidate totals/shares are scoped to observed query/page rows rather than true query-level property totals; content-decay results distinguish likely decay from weak evidence and improving visibility with click volatility. |
 | **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
 | **`reports.weekly_digest`** | Read | Generate a plain-language seven-day performance report with movers, top pages, and one recommended action. |
 | **`sites.add`** / **`sites.delete`** | Write | Add or remove a Search Console property. |
@@ -97,8 +97,8 @@ Once connected, ask your assistant things like:
 
 - *"What are my top 20 queries by clicks in the last 28 days?"*
 - *"Compare impressions for example.com this month vs last month — which pages dropped?"*
-- *"Is `https://example.com/pricing` indexed? When was it last crawled?"*
-- *"Which queries does my blog rank position 5–15 for? Those are my quick wins."*
+- *"What does Google's indexed version of `https://example.com/pricing` show for index status and last crawl?"*
+- *"Which high-impression query/page rows have an average position between 5 and 15? Show me those optimization opportunities."*
 - *"Give me a weekly digest for `sc-domain:example.com` ending today."*
 - *"Do any of my sitemaps have errors or warnings?"*
 - *"Split my clicks into brand vs non-brand using a regex on the query."*

package/SETUP.md

@@ -10,7 +10,7 @@ By the end you'll have a Worker at `https://<your-worker>.workers.dev/mcp` that
 
 - A [Cloudflare account](https://dash.cloudflare.com/sign-up) (the free Workers plan is enough to start).
 - A [Google account](https://accounts.google.com/) with access to the Search Console properties you want to query.
-- Node.js 20+ and npm.
+- Node.js 22+ and npm. The bundled Wrangler 4 runtime requires Node 22 or newer.
 - The Wrangler CLI — installed for you by `npm install`; invoke it with `npx wrangler …`.
 
 Clone and install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -87,6 +87,6 @@
     "vitest": "^4.1.11"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   }
 }

package/src/google.ts

@@ -247,6 +247,8 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
   const filters = body.dimensionFilterGroups?.flatMap((group) => group.filters) ?? [];
   const hasPageGroupingOrFilter =
     body.dimensions.includes('page') || filters.some((filter) => filter.dimension === 'page');
+  const hasQueryGroupingOrFilter =
+    body.dimensions.includes('query') || filters.some((filter) => filter.dimension === 'query');
 
   for (const filter of filters) {
     if (filter.expression.length > 4096) {
@@ -267,6 +269,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
+  if (body.type === 'discover' && hasQueryGroupingOrFilter) {
+    throw new Error(
+      'Google Discover does not support the query dimension or query filters in Search Analytics.',
+    );
+  }
+
   if (body.aggregationType === 'byNewsShowcasePanel') {
     if (body.type !== 'discover' && body.type !== 'googleNews') {
       throw new Error(
@@ -720,6 +728,7 @@ export interface CannibalizationResult {
   query: string;
   total_clicks: number;
   total_impressions: number;
+  aggregation_scope: 'observed_query_page_rows';
   pages: CannibalizationPage[];
 }
 
@@ -763,6 +772,7 @@ export function processCannibalization(
         query,
         total_clicks: totalClicks,
         total_impressions: totalImpressions,
+        aggregation_scope: 'observed_query_page_rows',
         pages: competingPages.sort(
           (a, b) => b.impressions - a.impressions || a.page.localeCompare(b.page),
         ),

package/src/index.ts

@@ -172,14 +172,19 @@ const SITE_DETAIL_OUTPUT_SCHEMA = {
   site: z.object(SITE_OUTPUT_SCHEMA),
 };
 
+const URL_INSPECTION_SCOPE_NOTE =
+  "Google's URL Inspection API reports the version currently known in Google's index; it does not run a live URL test or prove current live-page indexability. The mobileUsabilityResult field is deprecated and may be absent.";
+
 const INSPECTION_OUTPUT_SCHEMA = {
   inspection_result: z.unknown(),
+  note: z.string(),
 };
 
 const INSPECTION_BATCH_OUTPUT_SCHEMA = {
   requested_count: z.number().int().positive(),
   succeeded_count: z.number().int().nonnegative(),
   failed_count: z.number().int().nonnegative(),
+  note: z.string(),
   results: z.array(
     z.object({
       inspection_url: z.string(),
@@ -258,6 +263,7 @@ const RESULT_START_ROW_SCHEMA = z
   .describe('Zero-based offset into the deterministically ranked result list.');
 
 const QUICK_WIN_OUTPUT_SCHEMA = {
+  note: z.string(),
   quick_wins: z.array(
     z.object({
       query: z.string(),
@@ -297,15 +303,24 @@ const CANNIBALIZATION_OUTPUT_SCHEMA = {
   candidates: z.array(
     z.object({
       query: z.string(),
-      total_clicks: z.number(),
-      total_impressions: z.number(),
+      total_clicks: z.number().describe(
+        'Sum of clicks across the observed query/page Search Analytics rows for this query. This is not a separately queried query-level aggregate.',
+      ),
+      total_impressions: z.number().describe(
+        'Sum of impressions across the observed query/page Search Analytics rows for this query. This can exceed the query-level property aggregate when multiple pages appear for the same search, and it can be incomplete when source pagination is truncated.',
+      ),
+      aggregation_scope: z.literal('observed_query_page_rows').describe(
+        'Makes explicit that total_clicks, total_impressions, and impression_share are calculated from observed query/page rows rather than true query-level Search Console totals.',
+      ),
       page_count: z.number().int().nonnegative(),
       pages_truncated: z.boolean(),
       pages: z.array(
         z.object({
           page: z.string(),
           ...METRIC_OUTPUT_SCHEMA,
-          impression_share: z.number(),
+          impression_share: z.number().describe(
+            'Percentage of the observed query/page impression sum represented by this page; not a share of unique searches or the true query-level property aggregate.',
+          ),
         }),
       ),
     }),
@@ -513,12 +528,12 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect',
     description:
-      "Inspect a single URL's index status in Google: indexed state, last crawl, mobile usability, and rich-results eligibility. Use urls.inspect_many for 2-10 URLs.",
+      "Inspect Google's indexed version of a single URL: index status, last crawl, page-fetch/indexing state, canonicals, and rich-results/AMP analysis where available. This is not a live URL test; mobile usability is a deprecated response field. Use urls.inspect_many for 2-10 URLs.",
   },
   {
     name: 'urls.inspect_many',
     description:
-      'Inspect up to 10 URLs sequentially in one MCP call while charging the same URL Inspection safety budget per URL.',
+      "Inspect Google's indexed versions of up to 10 URLs sequentially in one MCP call while charging the same URL Inspection safety budget per URL. This does not run live URL tests.",
   },
   {
     name: 'sitemaps.list',
@@ -543,12 +558,12 @@ const TOOL_CATALOG = [
   {
     name: 'insights.quick_wins',
     description:
-      'Find search queries with at least the requested impressions that rank in a configurable striking-distance position range (8-20 by default). Returns clicks, impressions, CTR, and average position; CTR is context, not an eligibility filter.',
+      'Find observed query/page Search Analytics rows with at least the requested impressions whose average position falls in a configurable opportunity range (8-20 by default). Average position is an aggregate metric, not a literal current rank; CTR is context, not an eligibility filter.',
   },
   {
     name: 'insights.cannibalization',
     description:
-      'Analyze search analytics to detect instances of keyword cannibalization, where multiple pages on your site compete for the same query.',
+      'Analyze query/page Search Analytics for queries surfaced by multiple pages. Candidate totals and impression shares are explicitly scoped to observed query/page rows, not true query-level property totals.',
   },
   {
     name: 'insights.content_decay',
@@ -709,7 +724,7 @@ class GscMcpRuntime {
       'urls.inspect',
       {
         title: 'Inspect URL index status',
-        description: `Inspect a single URL's index status in Google. Returns: whether the URL is indexed, last crawl date, indexing state, mobile usability, rich-results eligibility, and any AMP results. Use this when the user asks 'is X indexed?', 'why isn't X showing in Google?', or wants a deep look at one specific page. For a bounded group of 2-10 URLs, prefer urls.inspect_many; Google still processes one URL Inspection request per URL and applies the same quota semantics.`,
+        description: `Inspect the version of a single URL currently known in Google's index. Returns Google's index-status analysis, last crawl, page-fetch/indexing state, canonicals, and rich-results/AMP analysis where available. This API does not test the live URL or prove current live-page indexability, and its mobile-usability result is deprecated. Use this when the user asks 'is X indexed?' or wants Google's indexed-state evidence for one page. For a bounded group of 2-10 URLs, prefer urls.inspect_many; Google still processes one URL Inspection request per URL and applies the same quota semantics.`,
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           inspection_url: z
@@ -738,8 +753,9 @@ class GscMcpRuntime {
           inspection_url,
           language_code,
         );
-        return toolResponse(JSON.stringify(result, null, 2), {
+        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, inspection_result: result }, null, 2), {
           inspection_result: result,
+          note: URL_INSPECTION_SCOPE_NOTE,
         });
       },
     );
@@ -748,7 +764,7 @@ class GscMcpRuntime {
       'urls.inspect_many',
       {
         title: 'Inspect multiple URLs',
-        description: `Inspect up to 10 URLs from one Search Console property in a single MCP call. Google still processes one URL Inspection request per URL, so every requested URL consumes one quota unit and one unit of this server's shared URL-inspection safety budget. Requests are sent sequentially to avoid unnecessary bursts. Use this for a small group of important, recently changed, or debugging-target URLs; do not use it to crawl an entire site.`,
+        description: `Inspect the versions of up to 10 URLs currently known in Google's index from one Search Console property. This API does not run live URL tests. Google still processes one URL Inspection request per URL, so every requested URL consumes one quota unit and one unit of this server's shared URL-inspection safety budget. Requests are sent sequentially to avoid unnecessary bursts. Use this for a small group of important or debugging-target URLs; do not use it to crawl an entire site.`,
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           inspection_urls: z
@@ -799,6 +815,7 @@ class GscMcpRuntime {
           requested_count: inspection_urls.length,
           succeeded_count: succeededCount,
           failed_count: results.length - succeededCount,
+          note: URL_INSPECTION_SCOPE_NOTE,
           results,
         };
         return toolResponse(JSON.stringify(payload, null, 2), payload);
@@ -871,6 +888,10 @@ class GscMcpRuntime {
           '- CTR in the response is a 0–1 fraction. Multiply by 100 for percent.',
           '- Use search_type to query image/video/news/discover indexes',
           '  separately from web.',
+          '- Google Discover does not support query grouping/filtering or',
+          '  average position. For Discover, use page/country/device/date/',
+          '  searchAppearance dimensions and interpret clicks, impressions,',
+          '  and CTR; query dimensions/filters are rejected before the API call.',
           '- News Showcase panel reporting: set aggregation_type to',
           '  "byNewsShowcasePanel", use search_type "discover" or',
           '  "googleNews", and include a searchAppearance equals',
@@ -906,7 +927,7 @@ class GscMcpRuntime {
             )
             .default(['query'])
             .describe(
-              'Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals.',
+              'Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. Google Discover does not support the query dimension.',
             ),
           row_limit: z
             .number()
@@ -934,7 +955,7 @@ class GscMcpRuntime {
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web.'),
+            .describe('Which search index to query. Defaults to web. Google Discover does not support query grouping/filtering or average position.'),
           aggregation_type: z
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
@@ -969,7 +990,7 @@ class GscMcpRuntime {
             )
             .optional()
             .describe(
-              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes.",
+              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes. Query filters are not supported when search_type is discover.",
             ),
         },
         outputSchema: SEARCH_ANALYTICS_OUTPUT_SCHEMA,
@@ -1041,16 +1062,16 @@ class GscMcpRuntime {
       'insights.page_queries',
       {
         title: 'Find queries for a page',
-        description: 'For one exact page URL, return the Search Console queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries.',
+        description: 'For one exact page URL, return the Search Console queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries. Google Discover is intentionally unavailable because Discover does not expose query data.',
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           page_url: z.string().url().describe('Exact fully-qualified page URL to filter on, e.g. https://example.com/guides/seo/. Search Console exact page filters are case-sensitive.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web.'),
+            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool groups by query.'),
           row_limit: z
             .number()
             .int()
@@ -1119,16 +1140,16 @@ class GscMcpRuntime {
       'insights.query_pages',
       {
         title: 'Find pages for a query',
-        description: 'For one exact search query, return the site pages that received impressions for it over a date range. This wraps an exact query dimension filter so agents do not need to construct analytics.query filter groups manually. Exact query matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results and verify which URL Google is surfacing before diagnosing cannibalization or content targeting.',
+        description: 'For one exact search query, return the site pages that received impressions for it over a date range. This wraps an exact query dimension filter so agents do not need to construct analytics.query filter groups manually. Exact query matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results and verify which URL Google is surfacing before diagnosing cannibalization or content targeting. Google Discover is intentionally unavailable because Discover does not expose query data.',
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           query: z.string().min(1).describe('Exact Search Console query text to filter on. Exact query filters are case-sensitive.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web.'),
+            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool filters by query.'),
           row_limit: z
             .number()
             .int()
@@ -1309,7 +1330,7 @@ class GscMcpRuntime {
       'insights.quick_wins',
       {
         title: 'Identify SEO Quick Wins',
-        description: 'Find search queries with at least the requested impressions that rank in a configurable striking-distance position range (8-20 by default). Returns clicks, impressions, CTR, and average position; CTR is context, not an eligibility filter. Results are ranked deterministically by impressions, then bounded with limit/start_row and explicit result_page metadata. Source pagination separately flags the local 100,000-row safety ceiling.',
+        description: 'Find observed query/page Search Analytics rows with at least the requested impressions whose average position falls in a configurable opportunity range (8-20 by default). Average position is an aggregate Search Console metric, not a literal current rank; CTR is returned for context and is not an eligibility filter. Results are ordered deterministically by impressions, then bounded with limit/start_row and explicit result_page metadata. Source pagination separately flags the local 100,000-row safety ceiling.',
         inputSchema: createQuickWinsInputSchema(SITE_URL_DESCRIPTION),
         outputSchema: z.object(QUICK_WIN_OUTPUT_SCHEMA),
         annotations: READ_ONLY_ANNOTATIONS,
@@ -1329,6 +1350,7 @@ class GscMcpRuntime {
         const quickWins = processQuickWins(source.rows, min_impressions, min_position, max_position);
         const bounded = windowKnownResults(quickWins, start_row, limit);
         const payload = {
+          note: 'Candidates are observed query/page rows selected by Search Console average position, not proof of a stable or current rank. CTR is reported for context and does not affect eligibility.',
           quick_wins: bounded.items,
           pagination: paginationMetadata(source),
           result_page: bounded.resultPage,
@@ -1341,7 +1363,7 @@ class GscMcpRuntime {
       'insights.cannibalization',
       {
         title: 'Detect Keyword Cannibalization',
-        description: 'Analyze query/page Search Analytics to find queries split across multiple pages. Candidates are ranked deterministically by total impressions, each candidate bounds its page list, and limit/start_row plus result_page provide safe pagination. Multiple ranking URLs can also reflect legitimate locale or intent differences, so treat candidates as evidence to investigate rather than proof of harmful cannibalization.',
+        description: 'Analyze query/page Search Analytics to find queries split across multiple pages. Candidates are ranked deterministically by the observed query/page impression sum, each candidate bounds its page list, and limit/start_row plus result_page provide safe pagination. total_clicks, total_impressions, and impression_share are calculated from observed query/page rows and are not true query-level property aggregates; multiple pages can make that row sum exceed the query-level Search Console total. Multiple ranking URLs can also reflect legitimate locale or intent differences, so treat candidates as evidence to investigate rather than proof of harmful cannibalization.',
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
@@ -1571,7 +1593,7 @@ class GscMcpRuntime {
       'analytics.compare',
       {
         title: 'Compare Performance Between Periods',
-        description: 'Compare Search Console performance metrics (clicks, impressions, CTR, average position) between two distinct date ranges (Period A vs Period B) for a selected dimension (query, page, country, device). Apply the same search type and optional dimension filters to both periods. Results are ranked by largest absolute click change, then impression change, and safely paged with limit/start_row. Percentage change is null when the baseline is zero and the comparison value differs.',
+        description: 'Compare Search Console performance metrics (clicks, impressions, CTR, average position) between two distinct date ranges (Period A vs Period B) for a selected dimension (query, page, country, device). Apply the same search type and optional dimension filters to both periods. Results are ranked by largest absolute click change, then impression change, and safely paged with limit/start_row. Percentage change is null when the baseline is zero and the comparison value differs. Discover is intentionally unavailable because this comparison contract includes average position, which the Discover report does not support.',
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           start_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date of Period A (recent, YYYY-MM-DD)'),
@@ -1580,9 +1602,9 @@ class GscMcpRuntime {
           end_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date of Period B (previous, YYYY-MM-DD)'),
           dimension: z.enum(['query', 'page', 'country', 'device']).default('query').describe('The dimension to compare performance for. Defaults to query.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news', 'googleNews'])
             .default('web')
-            .describe('Which Search Console search index to compare. The same search type is used for both periods.'),
+            .describe('Which Search Console search index to compare. The same search type is used for both periods. Discover is excluded because this tool returns average-position comparisons.'),
           dimension_filter_groups: z
             .array(
               z.object({

package/src/quick-wins-schema.ts

@@ -11,9 +11,9 @@ const POSITION_RANGE_ERROR = {
 };
 
 const QUICK_WINS_THRESHOLDS_SHAPE = {
-  min_impressions: z.number().int().min(0).default(100).describe('Minimum impressions required to consider a query. Must be at least 0. Default is 100.'),
-  min_position: z.number().positive().default(8).describe('Minimum average position to target (inclusive). Must be greater than 0. Default is 8.'),
-  max_position: z.number().positive().default(20).describe('Maximum average position to target (inclusive). Must be greater than 0. Default is 20.'),
+  min_impressions: z.number().int().min(0).default(100).describe('Minimum impressions required to consider an observed query/page row. Must be at least 0. Default is 100.'),
+  min_position: z.number().positive().default(8).describe('Minimum Search Console average position for the opportunity range (inclusive). This is an aggregate metric, not a literal current rank. Must be greater than 0. Default is 8.'),
+  max_position: z.number().positive().default(20).describe('Maximum Search Console average position for the opportunity range (inclusive). This is an aggregate metric, not a literal current rank. Must be greater than 0. Default is 20.'),
 };
 
 export function createQuickWinsInputSchema(siteUrlDescription: string) {
@@ -29,13 +29,13 @@ export function createQuickWinsInputSchema(siteUrlDescription: string) {
         .min(1)
         .max(MAX_ANALYSIS_RESULT_LIMIT)
         .default(DEFAULT_ANALYSIS_RESULT_LIMIT)
-        .describe('Maximum ranked quick-win results to return in this response.'),
+        .describe('Maximum ordered quick-win results to return in this response.'),
       start_row: z
         .number()
         .int()
         .min(0)
         .default(0)
-        .describe('Zero-based offset into the ranked quick-win result list.'),
+        .describe('Zero-based offset into the ordered quick-win result list.'),
     })
     .refine(
       ({ min_position, max_position }) => min_position <= max_position,