@digestseo/mcp-gsc 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.12] - 2026-09-22
+
+### Fixed
+- `urls.inspect_many` now runs URL Inspection requests with bounded concurrency of three instead of strictly sequentially, reducing batch latency while preserving per-URL safety-budget accounting, input-order results, per-URL failures, and batch-fatal Google-access revocation.
+- Search Analytics now rejects `searchAppearance` combined with another grouping dimension and documents Google's required two-step appearance discovery/filter workflow instead of sending invalid grouped requests to the provider.
+- Brand/non-brand Search Analytics guidance now distinguishes caller-supplied regex segmentation from Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose.
+
+## [0.4.11] - 2026-09-22
+
+### Fixed
+- Sitemap read tools now explain Google's `lastSubmitted` and `lastDownloaded` timestamp semantics so agents do not mistake Search Console submission/download times for sitemap-file modification, page-crawl, or indexing timestamps.
+- Google News Search Analytics now rejects unsupported query grouping/filtering, marks average position unavailable, and removes Google News from query-centric and average-position comparison helpers while preserving supported page/country/date/device/appearance and News Showcase reporting.
+
 ## [0.4.10] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -75,13 +75,13 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report whether your Google connection is currently authenticated (`connected` / `not_connected`). Takes no arguments — a good first call for discovery. |
 | **`sites.list`** | Read | List the Search Console properties the connected Google account can access (`siteUrl`, `permissionLevel`). |
 | **`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`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. For `search_type: "discover"`, `position_supported` is `false` because Google Discover does not support average position. |
-| **`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. |
+| **`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`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. Search appearance discovery is a two-step workflow: group by `searchAppearance` alone to discover the exact values Google returns for the property, then filter to one returned value in a separate query when grouping by page/query/country/device/date/hour. For `search_type: "discover"` or `"googleNews"`, `position_supported` is `false`; those reports expose clicks, impressions, and CTR but not average position, and query grouping/filtering is unavailable. |
+| **`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. These query-centric helpers support web, image, video, and the Search results News tab; Discover and the Google News report are excluded because they do not expose query data. |
 | **`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. |
+| **`urls.inspect_many`** | Read | Inspect Google's indexed versions of up to 10 URLs with bounded concurrency of 3 in one call while preserving input-order results. 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. `lastSubmitted` is when the sitemap was submitted to Search Console; `lastDownloaded` is when Google last downloaded the sitemap. Neither value is the sitemap file's modification/deploy time or a page crawl/indexing timestamp. |
 | **`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 compare only pages returned in both periods and do not turn one-sided row absence into zero traffic. |
-| **`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. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. `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. |
+| **`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. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. Because its comparison contract includes average position, it excludes Discover and Google News. `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. Query movers compare only rows returned in both weekly Search Analytics result sets; a query missing from one bounded response is not treated as zero because Google does not guarantee every data row. |
 | **`sites.add`** / **`sites.delete`** | Write | Add or remove a Search Console property. |
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |
@@ -105,9 +105,11 @@ Once connected, ask your assistant things like:
 - *"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."*
+- *"Using this brand regex I provide, approximate my clicks as brand vs non-brand."*
 - *"How is my site doing in Google Discover vs regular web search?"*
 
+Query regexes are a manual approximation only. Search Console's native Branded/Non-branded filter uses Google's own AI-assisted classification (including language variants, typos, and associated products/services), and that native classifier is not exposed as a Search Analytics API filter.
+
 ## Connect in your AI client
 
 Once you've deployed the server (see **[SETUP.md](SETUP.md)**), connect it by pasting your Worker's `/mcp` URL into your client:

package/SECURITY.md

@@ -58,7 +58,7 @@ delay and does not disclose another user's usage.
 | Category | Tools | Limit |
 |---|---|---|
 | Search Analytics | `analytics.query`, `insights.quick_wins`, `insights.cannibalization`, `insights.content_decay`, `indexing.list_pages`, `analytics.compare` | 30 per user / 10 minutes |
-| URL inspection | `urls.inspect`, `urls.inspect_many` | 20 inspected URLs per user / 24 hours; batch requests reserve one unit per URL |
+| URL inspection | `urls.inspect`, `urls.inspect_many` | 20 inspected URLs per user / 24 hours; batch requests reserve one unit per URL and run at most 3 inspections concurrently |
 | Search Console writes | `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete` | 10 per user / hour |
 | Indexing publish | `indexing.request` | 2 per user / 24 hours; 200 per deployment / 24 hours |
 | Weekly digest | `reports.weekly_digest` | 6 per user / hour |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {

package/src/google.ts

@@ -309,6 +309,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     throw new Error('Search Analytics dimensions must not contain duplicates.');
   }
 
+  if (body.dimensions.includes('searchAppearance') && body.dimensions.length > 1) {
+    throw new Error(
+      'Search Analytics searchAppearance must be the only grouping dimension. Discover an appearance value with dimensions ["searchAppearance"], then filter by that value in a separate query when grouping by page, query, country, device, date, or hour.',
+    );
+  }
+
   const hasHourDimension = body.dimensions.includes('hour');
   const usesHourlyData = body.dataState === 'hourly_all';
   if (hasHourDimension && !usesHourlyData) {
@@ -343,9 +349,10 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
-  if (body.type === 'discover' && hasQueryGroupingOrFilter) {
+  if ((body.type === 'discover' || body.type === 'googleNews') && hasQueryGroupingOrFilter) {
+    const surfaceName = body.type === 'discover' ? 'Google Discover' : 'Google News';
     throw new Error(
-      'Google Discover does not support the query dimension or query filters in Search Analytics.',
+      `${surfaceName} does not support the query dimension or query filters in Search Analytics.`,
     );
   }
 
@@ -466,7 +473,9 @@ export interface UrlInspectionBatchResult {
   error?: string;
 }
 
-export async function inspectUrlsSequentially(
+export const URL_INSPECTION_BATCH_CONCURRENCY = 3;
+
+export async function inspectUrlsBoundedConcurrently(
   accessToken: string,
   siteUrl: string,
   inspectionUrls: readonly string[],
@@ -474,31 +483,53 @@ export async function inspectUrlsSequentially(
 ): Promise<UrlInspectionBatchResult[]> {
   const results: UrlInspectionBatchResult[] = [];
 
-  for (const inspectionUrl of inspectionUrls) {
-    try {
-      results.push({
-        inspectionUrl,
-        inspectionResult: await inspectUrl(
-          accessToken,
-          siteUrl,
-          inspectionUrl,
-          languageCode,
-        ),
-      });
-    } catch (error) {
-      if (error instanceof Error && error.message === GSC_ACCESS_REVOKED_MESSAGE) {
-        throw error;
-      }
-      results.push({
-        inspectionUrl,
-        error: error instanceof Error ? error.message : 'URL inspection failed.',
-      });
+  for (
+    let offset = 0;
+    offset < inspectionUrls.length;
+    offset += URL_INSPECTION_BATCH_CONCURRENCY
+  ) {
+    const chunk = inspectionUrls.slice(offset, offset + URL_INSPECTION_BATCH_CONCURRENCY);
+    const chunkResults = await Promise.all(
+      chunk.map(async (inspectionUrl): Promise<UrlInspectionBatchResult | Error> => {
+        try {
+          return {
+            inspectionUrl,
+            inspectionResult: await inspectUrl(
+              accessToken,
+              siteUrl,
+              inspectionUrl,
+              languageCode,
+            ),
+          };
+        } catch (error) {
+          if (error instanceof Error && error.message === GSC_ACCESS_REVOKED_MESSAGE) {
+            return error;
+          }
+          return {
+            inspectionUrl,
+            error: error instanceof Error ? error.message : 'URL inspection failed.',
+          };
+        }
+      }),
+    );
+
+    const accessRevoked = chunkResults.find((result): result is Error => result instanceof Error);
+    if (accessRevoked) {
+      throw accessRevoked;
     }
+    results.push(
+      ...chunkResults.filter(
+        (result): result is UrlInspectionBatchResult => !(result instanceof Error),
+      ),
+    );
   }
 
   return results;
 }
 
+// Kept for compatibility with callers that imported the original helper directly.
+export const inspectUrlsSequentially = inspectUrlsBoundedConcurrently;
+
 export interface SitemapEntry {
   path: string;
   lastSubmitted?: string | null;

package/src/index.ts

@@ -12,7 +12,8 @@ import {
   GSC_ACCESS_REVOKED_MESSAGE,
   MCP_RECONNECT_INSTRUCTION,
   inspectUrl,
-  inspectUrlsSequentially,
+  inspectUrlsBoundedConcurrently,
+  URL_INSPECTION_BATCH_CONCURRENCY,
   listSitemaps,
   listSites,
   getSite,
@@ -143,21 +144,38 @@ const LISTED_SITE_OUTPUT_SCHEMA = {
 const PLATFORM_PROPERTY_API_NOTE =
   "Google Search Console now has platform properties for social/video accounts in its UI, but the current Search Console API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms. mcp-gsc preserves any other identifier returned by sites.list but will not pass an undocumented property identifier to API tools until Google publishes that contract.";
 
+const SITEMAP_PROVIDER_NOTE =
+  "Google's lastSubmitted is the time the sitemap was submitted to Search Console; it is not the sitemap file's generation, deployment, or last-modified time. lastDownloaded is the time Google last downloaded the sitemap; it is not a page crawl or indexing timestamp.";
+
 const SITEMAP_OUTPUT_SCHEMA = z
   .object({
     path: z.string(),
-    lastSubmitted: z.string().nullable().optional(),
+    lastSubmitted: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        'Provider-reported time the sitemap was submitted to Search Console; not the sitemap file generation, deployment, or modification time.',
+      ),
     isPending: z.boolean().nullable().optional(),
     isSitemapsIndex: z.boolean().nullable().optional(),
     type: z.string().nullable().optional(),
-    lastDownloaded: z.string().nullable().optional(),
+    lastDownloaded: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        'Provider-reported time Google last downloaded the sitemap; not a page crawl or page indexing timestamp.',
+      ),
     warnings: z.string().nullable().optional(),
     errors: z.string().nullable().optional(),
     contents: z
       .array(
         z.object({
           type: z.string(),
-          submitted: z.string(),
+          submitted: z
+            .string()
+            .describe('Provider-reported submitted URL count for this sitemap content type.'),
         }),
       )
       .nullable()
@@ -210,6 +228,7 @@ const INSPECTION_BATCH_OUTPUT_SCHEMA = {
 
 const SITEMAPS_OUTPUT_SCHEMA = {
   sitemaps: z.array(SITEMAP_OUTPUT_SCHEMA),
+  provider_note: z.string(),
 };
 
 const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
@@ -217,7 +236,7 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
   start_row: z.number().int().nonnegative(),
   rows: z.array(z.object(SEARCH_ROW_OUTPUT_SCHEMA)),
   position_supported: z.boolean().describe(
-    'Whether average position is supported for the selected Search Analytics search type. False for Google Discover.',
+    'Whether average position is supported for the selected Search Analytics search type. False for Google Discover and Google News.',
   ),
   position_note: z.string().optional(),
   provider_exhaustiveness_guaranteed: z.literal(false).describe(
@@ -571,7 +590,7 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect_many',
     description:
-      "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.",
+      `Inspect Google's indexed versions of up to 10 URLs with bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY} in one MCP call while charging the same URL Inspection safety budget per URL. This does not run live URL tests.`,
   },
   {
     name: 'sitemaps.list',
@@ -818,7 +837,7 @@ class GscMcpRuntime {
       'urls.inspect_many',
       {
         title: 'Inspect multiple URLs',
-        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.`,
+        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 use bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY}; results preserve input order, and a Google-access revocation stops later chunks from starting. Use this for a small group of important or debugging-target URLs; do not use it to crawl an entire site.`,
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           inspection_urls: z
@@ -855,7 +874,7 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
 
         const accessToken = await this.getAccessToken(googleId);
-        const batchResults = await inspectUrlsSequentially(
+        const batchResults = await inspectUrlsBoundedConcurrently(
           accessToken,
           site_url,
           inspection_urls,
@@ -888,7 +907,7 @@ class GscMcpRuntime {
       {
         title: 'List submitted sitemaps',
         description:
-          'List sitemaps submitted for a Search Console property. Optionally filter to entries included by one sitemap index. Returns sitemap URLs, last submitted/downloaded dates, submitted URL counts, warning and error counts, and sitemap status. Google\'s deprecated sitemap indexed count is intentionally omitted. Use this when the user asks about sitemap health, submission status, wants to audit which sitemaps are working, or needs the child sitemaps belonging to a specific sitemap index.',
+          'List sitemaps submitted for a Search Console property. Optionally filter to entries included by one sitemap index. Returns sitemap URLs, provider-reported submission/download timestamps, submitted URL counts, warning and error counts, and sitemap status. lastSubmitted is when the sitemap was submitted to Search Console; lastDownloaded is when Google last downloaded the sitemap. Neither timestamp is a sitemap-file modification time or a page crawl/indexing time. Google\'s deprecated sitemap indexed count is intentionally omitted. Use this when the user asks about sitemap health, submission status, wants to audit which sitemaps are working, or needs the child sitemaps belonging to a specific sitemap index.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           sitemap_index: SITEMAP_URL_SCHEMA
@@ -904,7 +923,8 @@ class GscMcpRuntime {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const sitemaps = await listSitemaps(accessToken, site_url, sitemap_index);
-        return toolResponse(JSON.stringify(sitemaps, null, 2), { sitemaps });
+        const payload = { sitemaps, provider_note: SITEMAP_PROVIDER_NOTE };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
       },
     );
 
@@ -952,10 +972,11 @@ 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.',
+          '- Google Discover and Google News do not support query grouping/',
+          '  filtering or average position. For those surfaces, 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',
@@ -965,10 +986,22 @@ class GscMcpRuntime {
           '  data_state to "hourly_all". The hourly date range can span at',
           '  most 10 inclusive days, and hourly data',
           '  is preliminary.',
+          '- SEARCH APPEARANCE uses a two-step workflow. To discover the',
+          '  property-specific appearance values Google currently exposes,',
+          '  call with dimensions: ["searchAppearance"] and no other grouping',
+          '  dimension. Then filter to one exact returned searchAppearance',
+          '  value in a separate query and group by page/query/country/device/',
+          '  date/hour as needed. Do not guess new appearance identifiers;',
+          '  discover the values Google returns for the property first.',
           '- Use dimension_filter_groups to filter by country, device, query',
           '  content, page URL, or search feature. includingRegex and',
-          '  excludingRegex use RE2 syntax. For brand vs non-brand splits,',
-          "  pass a single regex filter on the 'query' dimension.",
+          '  excludingRegex use RE2 syntax. A query regex can provide a manual',
+          '  brand/non-brand approximation when the caller supplies the brand',
+          "  pattern. It is not equivalent to Search Console's native Branded/",
+          '  Non-branded filter: Google describes that classification as',
+          '  AI-assisted (including language variants, typos, and associated',
+          '  products/services), and the Search Analytics API does not expose',
+          '  that native classifier as a filter.',
           "- data_state defaults to 'all' which matches the GSC dashboard.",
           "  Pass 'final' only when the user explicitly asks for stable,",
           '  non-preliminary data.',
@@ -993,7 +1026,7 @@ class GscMcpRuntime {
             )
             .default(['query'])
             .describe(
-              "Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. The 'hour' dimension requires data_state 'hourly_all' and an inclusive date range of at most 10 days. Google Discover does not support the query dimension.",
+              "Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. searchAppearance must be the only grouping dimension; discover an appearance value with ['searchAppearance'], then filter to that value in a separate query when grouping by another dimension. The 'hour' dimension requires data_state 'hourly_all' and an inclusive date range of at most 10 days. Google Discover and Google News do not support the query dimension.",
             ),
           row_limit: z
             .number()
@@ -1021,7 +1054,7 @@ class GscMcpRuntime {
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Google Discover does not support query grouping/filtering or average position.'),
+            .describe('Which search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position.'),
           aggregation_type: z
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
@@ -1056,7 +1089,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. Query filters are not supported when search_type is discover.",
+              "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 or googleNews.",
             ),
         },
         outputSchema: SEARCH_ANALYTICS_OUTPUT_SCHEMA,
@@ -1105,11 +1138,12 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
-          position_supported: search_type !== 'discover',
-          ...(search_type === 'discover'
+          position_supported:
+            search_type !== 'discover' && search_type !== 'googleNews',
+          ...(search_type === 'discover' || search_type === 'googleNews'
             ? {
                 position_note:
-                  "Google Discover does not support average position. Do not interpret rows[].position for search_type='discover'.",
+                  `${search_type === 'discover' ? 'Google Discover' : 'Google News'} does not support average position. Do not interpret rows[].position for search_type='${search_type}'.`,
               }
             : {}),
           provider_exhaustiveness_guaranteed: false,
@@ -1137,16 +1171,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. Google Discover is intentionally unavailable because Discover does not expose query data.',
+        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 and Google News are intentionally unavailable because those reports do not expose query data.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           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', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool groups by query.'),
+            .describe('Which search index to query. Defaults to web. Discover and Google News are not supported because this tool groups by query.'),
           row_limit: z
             .number()
             .int()
@@ -1215,16 +1249,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. Google Discover is intentionally unavailable because Discover does not expose query data.',
+        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 and Google News are intentionally unavailable because those reports do not expose query data.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           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', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool filters by query.'),
+            .describe('Which search index to query. Defaults to web. Discover and Google News are not supported because this tool filters by query.'),
           row_limit: z
             .number()
             .int()
@@ -1385,19 +1419,20 @@ class GscMcpRuntime {
       'sitemaps.get',
       {
         title: 'Get sitemap details',
-        description: 'Get status and details of a single sitemap submitted to Google Search Console.',
+        description: 'Get status and details of a single sitemap submitted to Google Search Console. lastSubmitted is when the sitemap was submitted to Search Console; lastDownloaded is when Google last downloaded the sitemap. Neither timestamp is a sitemap-file modification time or a page crawl/indexing time.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: { sitemap: SITEMAP_OUTPUT_SCHEMA },
+        outputSchema: { sitemap: SITEMAP_OUTPUT_SCHEMA, provider_note: z.string() },
         annotations: READ_ONLY_ANNOTATIONS,
       },
       async ({ site_url, feedpath }) => {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const details = await getSitemap(accessToken, site_url, feedpath);
-        return toolResponse(JSON.stringify(details, null, 2), { sitemap: details });
+        const payload = { sitemap: details, provider_note: SITEMAP_PROVIDER_NOTE };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
       },
     );
 
@@ -1670,7 +1705,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). Only dimension keys returned in both Search Analytics period responses are compared; a key missing from one response is not treated as zero because Google does not guarantee every data row. 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 an explicitly returned baseline row has zero and the comparison value differs. Discover is intentionally unavailable because this comparison contract includes average position, which the Discover report does not support.',
+        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). Only dimension keys returned in both Search Analytics period responses are compared; a key missing from one response is not treated as zero because Google does not guarantee every data row. 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 an explicitly returned baseline row has zero and the comparison value differs. Discover and Google News are intentionally unavailable because this comparison contract includes average position, which those reports do not support.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           start_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date of Period A (recent, YYYY-MM-DD)'),
@@ -1679,9 +1714,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', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news'])
             .default('web')
-            .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.'),
+            .describe('Which Search Console search index to compare. The same search type is used for both periods. Discover and Google News are excluded because this tool returns average-position comparisons.'),
           dimension_filter_groups: z
             .array(
               z.object({
@@ -1710,7 +1745,7 @@ class GscMcpRuntime {
             )
             .optional()
             .describe(
-              "Optional Search Console filters applied identically to both periods. Use query regex filters for brand/non-brand comparisons; countries use ISO 3166-1 alpha-3 codes.",
+              "Optional Search Console filters applied identically to both periods. A caller-supplied query regex can approximate a manual brand/non-brand split, but it is not equivalent to Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose. Countries use ISO 3166-1 alpha-3 codes.",
             ),
           limit: ANALYSIS_RESULT_LIMIT_SCHEMA,
           start_row: RESULT_START_ROW_SCHEMA,