docs(gsc): state what Search Console's API cannot tell you - #27
Merged
Conversation
URL Inspection is URL-by-URL, but nothing said so, and the absence read as completeness: inspect ten URLs, get ten clean verdicts, conclude the property is fine. Four Search Console reports have no API at all — Page Indexing, Crawl Stats, manual actions and security issues — so no tool built on the API can cover them, and OpenSEO should say that rather than let silence imply coverage. Adds a docs section naming the four gaps and the sampling limit, and extends the inspect_urls tool description with the same caveat so an agent reading the tool list sees it too — that is where the wrong inference actually gets made. No behaviour change. Reported by Hermes: the product implied URL Inspection was the whole indexation picture. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
URL Inspection is URL-by-URL, but nothing said so. The absence read as completeness: inspect ten URLs, get ten clean verdicts, conclude the property is fine.
Four Search Console reports have no API at all:
No tool built on the API can cover them. OpenSEO should say so rather than let silence imply coverage.
Changes
web/content/docs/mcp.md— a new section naming the four gaps and the sampling limit: "inspecting a handful of URLs that all come back clean is not evidence the property is healthy — you have sampled, not surveyed."inspect_urlstool description — the same caveat, because that is where the wrong inference actually gets made. An agent choosing tools reads the description, not the docs site.No behaviour change.
Note
web/content/docs/mcp.mdis byte-identical toupstream/main, so this section would apply cleanly upstream too.search-console-tools.tshas diverged (fork-only rich-result issue flattening), though the description string itself is shared. Worth upstreaming later — not bundled here, since every-app#173 is still awaiting review.Reported by Hermes: the product implied URL Inspection was the whole indexation picture.