@digestseo/mcp-gsc 0.4.30 → 0.4.32

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.32] - 2026-09-24
+
+### Added
+- `urls.inspect` and successful `urls.inspect_many` items now include a conservative, schema-discoverable `index_status_summary` derived from Google's documented index-status verdict and key crawl/indexing fields while preserving the complete raw provider response.
+
+### Changed
+- Successful `sitemaps.submit` and `sitemaps.delete` results now expose explicit Search Console effect boundaries so agents do not mistake submission for completed processing/indexing or Search Console removal for deletion of the hosted sitemap file/deindexing.
+
+## [0.4.31] - 2026-09-24
+
+### Added
+- Gemini CLI can now install this repository as a native extension, bundling the verified local Streamable HTTP MCP connection with the existing `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities` Agent Skills.
+
+### Changed
+- Exact Search Analytics country and device filters now reject malformed provider values before reserving local Search Analytics budget, resolving Google credentials, or calling Search Console; substring and RE2 regex operators remain unrestricted.
+- `sites.list` and `sites.get` now expose explicit `verification_state` and `owner` fields alongside Google's raw `permissionLevel`, so agents can distinguish unverified properties and owner-only Indexing API prerequisites before choosing a property workflow.
+
 ## [0.4.30] - 2026-09-23
 
 ### Changed
@@ -198,6 +215,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.4.2] - 2026-09-21
 
 ### Fixed
+- Search Analytics now rejects malformed exact-match country/device filters during MCP input validation, before local rate-limit, credential, or Google API work, while preserving contains and regex filter semantics.
 - 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.

package/README.md

@@ -75,6 +75,14 @@ copilot plugin install mcp-gsc@digestseo
 
 The marketplace path makes the plugin discoverable and updateable through Copilot's marketplace workflow. Direct repository install also remains supported with `copilot plugin install AKzar1el/mcp-gsc`. The Copilot plugin bundles the same three Agent Skills plus the local loopback MCP configuration. Start the npm launcher before using the plugin's MCP server; the plugin does not start or deploy mcp-gsc for you.
 
+**Gemini CLI**
+
+```bash
+gemini extensions install https://github.com/AKzar1el/mcp-gsc
+```
+
+The Gemini CLI extension bundles the verified local loopback MCP configuration plus the same three Agent Skills: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. Start the npm launcher before using the extension; the extension does not start or deploy mcp-gsc for you.
+
 **Kiro**
 
 [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-gsc&config=%7B%22url%22%3A%22http%3A%2F%2F127.0.0.1%3A8080%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)

package/package.json

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

package/src/google.ts

@@ -314,6 +314,27 @@ export interface DimensionFilter {
   expression: string;
 }
 
+export function assertSearchAnalyticsFilterCompatible(
+  filter: DimensionFilter,
+): void {
+  if (filter.operator !== 'equals' && filter.operator !== 'notEquals') return;
+
+  if (filter.dimension === 'country' && !/^[A-Za-z]{3}$/.test(filter.expression)) {
+    throw new Error(
+      'Search Analytics exact country filters must use a three-letter ISO 3166-1 alpha-3 code.',
+    );
+  }
+
+  if (
+    filter.dimension === 'device' &&
+    !['DESKTOP', 'MOBILE', 'TABLET'].includes(filter.expression.toUpperCase())
+  ) {
+    throw new Error(
+      'Search Analytics exact device filters must use DESKTOP, MOBILE, or TABLET.',
+    );
+  }
+}
+
 export interface DimensionFilterGroup {
   groupType: 'and';
   filters: DimensionFilter[];
@@ -369,6 +390,7 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     if (filter.expression.length > 4096) {
       throw new Error('Search Analytics filter expressions must be at most 4096 characters.');
     }
+    assertSearchAnalyticsFilterCompatible(filter);
   }
 
   if (body.aggregationType === 'byPage' && hasPageGroupingOrFilter) {
@@ -526,6 +548,70 @@ export async function inspectUrl(
   return data.inspectionResult ?? null;
 }
 
+export type UrlInspectionIndexedState = 'indexed' | 'not_indexed' | 'unknown';
+
+export interface UrlInspectionIndexStatusSummary {
+  indexed_state: UrlInspectionIndexedState;
+  verdict?: string;
+  coverage_state?: string;
+  robots_txt_state?: string;
+  indexing_state?: string;
+  last_crawl_time?: string;
+  page_fetch_state?: string;
+  google_canonical?: string;
+  user_canonical?: string;
+  crawled_as?: string;
+}
+
+function asUnknownRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function optionalStringField(
+  record: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const value = record?.[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function summarizeUrlInspectionIndexStatus(
+  inspectionResult: unknown,
+): UrlInspectionIndexStatusSummary {
+  const result = asUnknownRecord(inspectionResult);
+  const indexStatus = asUnknownRecord(result?.indexStatusResult);
+  const verdict = optionalStringField(indexStatus, 'verdict');
+  const coverageState = optionalStringField(indexStatus, 'coverageState');
+  const robotsTxtState = optionalStringField(indexStatus, 'robotsTxtState');
+  const indexingState = optionalStringField(indexStatus, 'indexingState');
+  const lastCrawlTime = optionalStringField(indexStatus, 'lastCrawlTime');
+  const pageFetchState = optionalStringField(indexStatus, 'pageFetchState');
+  const googleCanonical = optionalStringField(indexStatus, 'googleCanonical');
+  const userCanonical = optionalStringField(indexStatus, 'userCanonical');
+  const crawledAs = optionalStringField(indexStatus, 'crawledAs');
+  const indexedState: UrlInspectionIndexedState =
+    verdict === 'PASS'
+      ? 'indexed'
+      : verdict === 'FAIL' || verdict === 'NEUTRAL'
+        ? 'not_indexed'
+        : 'unknown';
+
+  return {
+    indexed_state: indexedState,
+    ...(verdict !== undefined ? { verdict } : {}),
+    ...(coverageState !== undefined ? { coverage_state: coverageState } : {}),
+    ...(robotsTxtState !== undefined ? { robots_txt_state: robotsTxtState } : {}),
+    ...(indexingState !== undefined ? { indexing_state: indexingState } : {}),
+    ...(lastCrawlTime !== undefined ? { last_crawl_time: lastCrawlTime } : {}),
+    ...(pageFetchState !== undefined ? { page_fetch_state: pageFetchState } : {}),
+    ...(googleCanonical !== undefined ? { google_canonical: googleCanonical } : {}),
+    ...(userCanonical !== undefined ? { user_canonical: userCanonical } : {}),
+    ...(crawledAs !== undefined ? { crawled_as: crawledAs } : {}),
+  };
+}
+
 export interface UrlInspectionBatchResult {
   inspectionUrl: string;
   inspectionResult?: unknown;

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   MCP_RECONNECT_INSTRUCTION,
   inspectUrl,
   inspectUrlsBoundedConcurrently,
+  summarizeUrlInspectionIndexStatus,
   URL_INSPECTION_BATCH_CONCURRENCY,
   listSitemaps,
   listSites,
@@ -32,6 +33,7 @@ import {
   requestIndexingRemoval,
   getIndexingNotificationMetadata,
   processPerformanceComparison,
+  assertSearchAnalyticsFilterCompatible,
   type PaginatedSearchAnalyticsResult,
 } from './google';
 import {
@@ -149,35 +151,57 @@ const SEARCH_ROW_OUTPUT_SCHEMA = {
     ),
 };
 
-const SEARCH_ANALYTICS_FILTER_SCHEMA = z.object({
-  dimension: z.enum([
-    'query',
-    'page',
-    'country',
-    'device',
-    'searchAppearance',
-  ]),
-  operator: z
-    .enum([
-      'equals',
-      'notEquals',
-      'contains',
-      'notContains',
-      'includingRegex',
-      'excludingRegex',
-    ])
-    .default('equals'),
-  expression: z.string().max(4096),
-});
+const SEARCH_ANALYTICS_FILTER_SCHEMA = z
+  .object({
+    dimension: z.enum([
+      'query',
+      'page',
+      'country',
+      'device',
+      'searchAppearance',
+    ]),
+    operator: z
+      .enum([
+        'equals',
+        'notEquals',
+        'contains',
+        'notContains',
+        'includingRegex',
+        'excludingRegex',
+      ])
+      .default('equals'),
+    expression: z.string().max(4096),
+  })
+  .superRefine((filter, ctx) => {
+    try {
+      assertSearchAnalyticsFilterCompatible(filter);
+    } catch (error) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['expression'],
+        message: (error as Error).message,
+      });
+    }
+  });
 
 const SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA = z.object({
   groupType: z.literal('and').default('and'),
   filters: z.array(SEARCH_ANALYTICS_FILTER_SCHEMA),
 });
 
+const SITE_VERIFICATION_STATE_SCHEMA = z
+  .enum(['verified', 'unverified', 'unknown'])
+  .describe(
+    "Derived from Google's permissionLevel. siteOwner/siteFullUser/siteRestrictedUser are verified, siteUnverifiedUser is unverified, and any future undocumented permission level is reported as unknown.",
+  );
+
 const SITE_OUTPUT_SCHEMA = {
   siteUrl: z.string(),
   permissionLevel: z.string(),
+  verification_state: SITE_VERIFICATION_STATE_SCHEMA,
+  owner: z.boolean().describe(
+    "True only when Google returns permissionLevel 'siteOwner'. Restricted Indexing API workflows require owner-level Search Console access.",
+  ),
 };
 
 const LISTED_SITE_OUTPUT_SCHEMA = {
@@ -190,6 +214,26 @@ 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.";
 
+function sitePermissionState(permissionLevel: string): {
+  verification_state: 'verified' | 'unverified' | 'unknown';
+  owner: boolean;
+} {
+  if (permissionLevel === 'siteUnverifiedUser') {
+    return { verification_state: 'unverified', owner: false };
+  }
+  if (
+    permissionLevel === 'siteOwner' ||
+    permissionLevel === 'siteFullUser' ||
+    permissionLevel === 'siteRestrictedUser'
+  ) {
+    return {
+      verification_state: 'verified',
+      owner: permissionLevel === 'siteOwner',
+    };
+  }
+  return { verification_state: 'unknown', owner: false };
+}
+
 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.";
 
@@ -276,8 +320,24 @@ const INDEXING_PROVIDER_USAGE_NOTE =
 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 URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA = z.object({
+  indexed_state: z.enum(['indexed', 'not_indexed', 'unknown']).describe(
+    "Conservative state derived only from Google's indexStatusResult.verdict: PASS => indexed, FAIL/NEUTRAL => not_indexed, and missing/unknown/reserved verdicts => unknown.",
+  ),
+  verdict: z.string().optional(),
+  coverage_state: z.string().optional(),
+  robots_txt_state: z.string().optional(),
+  indexing_state: z.string().optional(),
+  last_crawl_time: z.string().optional(),
+  page_fetch_state: z.string().optional(),
+  google_canonical: z.string().optional(),
+  user_canonical: z.string().optional(),
+  crawled_as: z.string().optional(),
+});
+
 const INSPECTION_OUTPUT_SCHEMA = {
   inspection_result: z.unknown(),
+  index_status_summary: URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA,
   note: z.string(),
 };
 
@@ -290,6 +350,7 @@ const INSPECTION_BATCH_OUTPUT_SCHEMA = {
     z.object({
       inspection_url: z.string(),
       inspection_result: z.unknown().optional(),
+      index_status_summary: URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA.optional(),
       error: z.string().optional(),
     }),
   ),
@@ -361,6 +422,22 @@ const SITE_DELETE_OUTPUT_SCHEMA = {
   provider_scope_note: z.string(),
 };
 
+const SITEMAP_SUBMIT_OUTPUT_SCHEMA = {
+  message: z.string(),
+  submitted_to_search_console: z.literal(true),
+  sitemap_processing_completion_proven: z.literal(false),
+  page_indexing_proven: z.literal(false),
+  provider_scope_note: z.string(),
+};
+
+const SITEMAP_DELETE_OUTPUT_SCHEMA = {
+  message: z.string(),
+  removed_from_search_console: z.literal(true),
+  sitemap_file_deleted: z.literal(false),
+  page_deindexing_proven: z.literal(false),
+  provider_scope_note: z.string(),
+};
+
 const SEARCH_ANALYTICS_PAGINATION_OUTPUT_SCHEMA = z.object({
   rows_fetched: z.number().int().nonnegative(),
   pages_fetched: z.number().int().positive(),
@@ -715,12 +792,12 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect',
     description:
-      "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.",
+      "Inspect Google's indexed version of a single URL: a conservative normalized index-status summary plus Google's raw 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 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.`,
+      `Inspect Google's indexed versions of up to 10 URLs with a conservative normalized index-status summary per successful item and 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',
@@ -730,12 +807,12 @@ const TOOL_CATALOG = [
   {
     name: 'sitemaps.submit',
     description:
-      'Submit a new sitemap to your Google Search Console account.',
+      'Submit a sitemap URL to a Search Console property. A successful API response proves the Search Console submission request succeeded; it does not prove sitemap processing completed or that any page was indexed.',
   },
   {
     name: 'sitemaps.delete',
     description:
-      'Remove/delete a submitted sitemap from your Google Search Console account.',
+      'Remove a submitted sitemap from a Search Console property. This removes the Search Console sitemap entry; it does not delete the remotely hosted sitemap file or prove that any page was deindexed.',
   },
   {
     name: 'sitemaps.get',
@@ -914,7 +991,7 @@ class GscMcpRuntime {
       {
         title: 'List Search Console properties',
         description:
-          "List the Google Search Console properties (sites) the connected Google account has access to. Each entry preserves Google's siteUrl and permissionLevel and adds api_identifier_kind plus mcp_site_url_accepted. Google now exposes platform properties for social/video accounts in the Search Console UI, but its current API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms; identifiers outside those documented forms are preserved here but marked unsupported rather than guessed. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or before another tool that requires site_url.",
+          "List the Google Search Console properties (sites) the connected Google account has access to. Each entry preserves Google's siteUrl and permissionLevel, derives verification_state plus owner from Google's documented permission levels, and adds api_identifier_kind plus mcp_site_url_accepted. Treat verification_state='unverified' as not ready for normal property-scoped Search Console workflows; owner=true is required by this server's restricted Indexing API workflows. Google now exposes platform properties for social/video accounts in the Search Console UI, but its current API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms; identifiers outside those documented forms are preserved here but marked unsupported rather than guessed. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or before another tool that requires site_url.",
         inputSchema: {},
         outputSchema: SITES_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -927,6 +1004,7 @@ class GscMcpRuntime {
           const mcpSiteUrlAccepted = apiIdentifierKind !== 'undocumented';
           return {
             ...site,
+            ...sitePermissionState(site.permissionLevel),
             api_identifier_kind: apiIdentifierKind,
             mcp_site_url_accepted: mcpSiteUrlAccepted,
             ...(!mcpSiteUrlAccepted
@@ -943,7 +1021,7 @@ class GscMcpRuntime {
       {
         title: 'Get Search Console property',
         description:
-          "Retrieve one exact Google Search Console property and the connected account's permission level for it. Use this when the user has already named a property and you need to confirm that exact property or its access level without listing every property first.",
+          "Retrieve one exact Google Search Console property and its connected-account access state. The response preserves Google's permissionLevel and derives verification_state plus owner so callers can distinguish an unverified property and recognize owner-only Indexing API prerequisites without listing every property first.",
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
         },
@@ -954,7 +1032,13 @@ class GscMcpRuntime {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const site = await getSite(accessToken, site_url);
-        return toolResponse(JSON.stringify(site, null, 2), { site });
+        const siteWithPermissionState = {
+          ...site,
+          ...sitePermissionState(site.permissionLevel),
+        };
+        return toolResponse(JSON.stringify(siteWithPermissionState, null, 2), {
+          site: siteWithPermissionState,
+        });
       },
     );
 
@@ -962,7 +1046,7 @@ class GscMcpRuntime {
       'urls.inspect',
       {
         title: 'Inspect URL index status',
-        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.`,
+        description: `Inspect the version of a single URL currently known in Google's index. Returns a conservative normalized index-status summary alongside Google's raw 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: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           inspection_url: z
@@ -991,8 +1075,10 @@ class GscMcpRuntime {
           inspection_url,
           language_code,
         );
-        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, inspection_result: result }, null, 2), {
+        const indexStatusSummary = summarizeUrlInspectionIndexStatus(result);
+        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, index_status_summary: indexStatusSummary, inspection_result: result }, null, 2), {
           inspection_result: result,
+          index_status_summary: indexStatusSummary,
           note: URL_INSPECTION_SCOPE_NOTE,
         });
       },
@@ -1002,7 +1088,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 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.`,
+        description: `Inspect the versions of up to 10 URLs currently known in Google's index from one Search Console property. Each successful item includes a conservative normalized index-status summary alongside Google's raw response. 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
@@ -1046,7 +1132,12 @@ class GscMcpRuntime {
         const results = batchResults.map((result) => ({
           inspection_url: result.inspectionUrl,
           ...(result.inspectionResult !== undefined
-            ? { inspection_result: result.inspectionResult }
+            ? {
+                inspection_result: result.inspectionResult,
+                index_status_summary: summarizeUrlInspectionIndexStatus(
+                  result.inspectionResult,
+                ),
+              }
             : {}),
           ...(result.error !== undefined ? { error: result.error } : {}),
         }));
@@ -1556,12 +1647,12 @@ class GscMcpRuntime {
       'sitemaps.submit',
       {
         title: 'Submit sitemap',
-        description: 'Submit a new sitemap to your Google Search Console account.',
+        description: 'Submit a sitemap URL to a Search Console property. A successful API response means the Search Console submission request succeeded; it does not prove sitemap processing completed or that any page was indexed.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file to submit, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITEMAP_SUBMIT_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sitemaps.submit'],
       },
       async ({ site_url, feedpath }) => {
@@ -1570,8 +1661,15 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         await submitSitemap(accessToken, site_url, feedpath);
-        const message = `Successfully submitted sitemap: ${feedpath} for site: ${site_url}`;
-        return toolResponse(message, { message });
+        const message = `Successfully submitted sitemap to Search Console: ${feedpath} for site: ${site_url}`;
+        const payload = {
+          message,
+          submitted_to_search_console: true as const,
+          sitemap_processing_completion_proven: false as const,
+          page_indexing_proven: false as const,
+          provider_scope_note: "Google's Sitemaps.submit method returns an empty body on success. That success confirms the Search Console submission operation, not completed sitemap processing or page indexing.",
+        };
+        return toolResponse(`${message}\n\n${payload.provider_scope_note}`, payload);
       },
     );
 
@@ -1579,12 +1677,12 @@ class GscMcpRuntime {
       'sitemaps.delete',
       {
         title: 'Delete sitemap',
-        description: 'Remove/delete a submitted sitemap from your Google Search Console account.',
+        description: 'Remove a submitted sitemap from a Search Console property. This removes the Search Console sitemap entry; it does not delete the remotely hosted sitemap file or prove that any page was deindexed.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file to delete, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITEMAP_DELETE_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sitemaps.delete'],
       },
       async ({ site_url, feedpath }) => {
@@ -1593,8 +1691,15 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         await deleteSitemap(accessToken, site_url, feedpath);
-        const message = `Successfully deleted sitemap: ${feedpath} for site: ${site_url}`;
-        return toolResponse(message, { message });
+        const message = `Successfully removed sitemap from Search Console: ${feedpath} for site: ${site_url}`;
+        const payload = {
+          message,
+          removed_from_search_console: true as const,
+          sitemap_file_deleted: false as const,
+          page_deindexing_proven: false as const,
+          provider_scope_note: "Google's Sitemaps.delete method removes the submitted sitemap from the Search Console property. It does not delete the remotely hosted sitemap file or prove that any page was deindexed.",
+        };
+        return toolResponse(`${message}\n\n${payload.provider_scope_note}`, payload);
       },
       );
     }