docs(gsc): state what Search Console's API cannot tell you

src/server/mcp/tools/search-console-tools.ts

@@ -376,7 +376,7 @@ export const inspectUrlsTool = {
   config: {
     title: "Inspect URLs in Google Search Console",
     description:
-      "Run Google Search Console's URL Inspection on up to 10 URLs of the connected property: index/coverage state, last crawl time, Google-selected vs declared canonical, and rich-results verdicts with Google's own per-item issue messages. Use it to answer 'is this page indexed? why not?' and 'what does Google think is wrong with my structured data?'. Reflects Google's last crawl, not the page as it is right now — for unpublished or uncrawled markup use validate_structured_data. Per-URL failures are reported inline. Read-only; uses no credits.",
+      "Run Google Search Console's URL Inspection on up to 10 URLs of the connected property: index/coverage state, last crawl time, Google-selected vs declared canonical, and rich-results verdicts with Google's own per-item issue messages. Use it to answer 'is this page indexed? why not?' and 'what does Google think is wrong with my structured data?'. Reflects Google's last crawl, not the page as it is right now — for unpublished or uncrawled markup use validate_structured_data. This is URL-by-URL and is not a property-wide indexation picture: Search Console's API does not expose the aggregate Page Indexing report, Crawl Stats, manual actions, or security issues, so clean verdicts here are not evidence the property as a whole is healthy — check those four in the Search Console UI. Per-URL failures are reported inline. Read-only; uses no credits.",
     inputSchema: inspectInputSchema,
     outputSchema: {
       ok: z.boolean(),

web/content/docs/mcp.md

@@ -88,6 +88,19 @@ OpenSEO MCP exposes tools for SEO research workflows:
 - Read first-party Google Search Console performance (clicks, impressions, CTR, position).
 - Inspect index status, crawl, and canonical for specific URLs (up to 10 per call).
 
+## What Search Console's API cannot tell you
+
+Search Console's API is narrower than the Search Console interface, and the gap matters most where you are likely to want it least — diagnosing indexation. Four reports have no API at all:
+
+- **Page Indexing** — the aggregate breakdown of which pages are indexed and why the rest are not
+- **Crawl Stats** — request volume, response codes, and crawl budget over time
+- **Manual actions**
+- **Security issues**
+
+OpenSEO reads what Google exposes: Search Analytics performance, and URL Inspection one URL at a time, ten per call. That answers "is this page indexed, and what does Google think of it?" It does not answer "how many of my pages are indexed?", and inspecting a handful of URLs that all come back clean is not evidence the property is healthy — you have sampled, not surveyed.
+
+For those four reports, open Search Console. No tool can proxy them, and any tool claiming to has either guessed or scraped.
+
 ## What to do after setup
 
 Once OpenSEO MCP is connected, [set up OpenSEO Agent Skills](/docs/skills/setup). MCP gives your agent access to OpenSEO data. Skills are separate `SKILL.md` files that tell your agent how to use that data for specific SEO jobs.