Allows reading actual Google Search Console performance data for a site, including top queries, clicks, impressions, CTR, average position, and comparisons between two periods.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SEO MCP Server Audit my site and show me the worst issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Crawl a site, audit its on-page factors, read your actual Google Search Console performance, measure Core Web Vitals and compare against a competitor — from inside Claude, Cursor or any MCP client.
⚡ No site, no credentials, no setup → try it in 30 seconds.
Related MCP server: gsc-mcp
Demo mode serves a small fabricated site and a fabricated Search Console history, so you can see exactly what every tool returns before pointing it at anything real. No credentials, no network access.
{
"mcpServers": {
"seo": {
"command": "npx",
"args": ["-y", "@soyrageagency/seo-mcp"],
"env": { "SEO_MCP_DEMO": "true" }
}
}
}Restart your client and ask: “Audit my site.”
The fake site is deliberately imperfect — a 404 linked from an article, a page
missing its H1, a title 83 characters long, images with no alt text, a page
that quietly says noindex. A demo where everything is fine would teach you
nothing about what the tool actually finds.
Nothing to clone or build. Add this to your MCP client's config
(%APPDATA%\Claude\claude_desktop_config.json on Windows,
~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"seo": {
"command": "npx",
"args": ["-y", "@soyrageagency/seo-mcp"],
"env": {
"SEO_MCP_SITE": "https://yoursite.com",
// Optional, but this is where the real data is — see below
"GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
"GSC_SITE_URL": "https://yoursite.com/",
// Optional: a free key, avoids PageSpeed rate limits
"PAGESPEED_API_KEY": "AIza…"
}
}
}
}npx fetches the package on first run and keeps it current. A ready-to-edit
copy lives in
examples/claude_desktop_config.json.
Everything works with no credentials at all — you get the crawler and the on-page auditor, just not the real search data.
Most SEO tooling hands you a dashboard and leaves you to interpret it. This hands an LLM the underlying data, so you can ask a question in your own words and get an answer about your site.
Every screenshot below is the real, unedited output of the tool named in its
title bar, generated by npm run shots against the demo
site. If the tool's output changes, the screenshots are regenerated, not
retouched.
crawl_site finds what only a crawl can see: broken URLs and the page that
links to them, duplicate titles, missing basics as a proportion, and pages
buried too deep to be crawled often. link_graph, find_orphan_pages and
find_duplicate_content go further into the same crawl.
audit_page reports every on-page signal for a single URL, with findings
ranked by impact instead of listed flat.
search_console_queries returns what Google actually recorded — not an
estimate from a third-party index.
search_console_compare answers the question people actually ask: is this
going up or down, and because of what?
pagespeed keeps field data — what real Chrome users experienced, the part
tied to ranking — separate from the lab simulation. Conflating the two is the
standard mistake.
compare_competitor puts the two pages side by side and then says what they do
that you do not.
generate_meta gathers the evidence — current tags, structure, and the
queries that already bring you impressions — and hands it over with the
limits stated. It does not fill in a template, because a templated
Buy X | Brand is worse than what the model writes from the page's real
content.
The MCP server is for asking questions. The extension is for landing on a page and immediately knowing what you are looking at — no client, no credentials, no config. Install it, click the button, done.
It scores three things separately, because they fail independently: a page can rank beautifully and convert nothing.
A search-result preview showing what Google will actually display, measured
in pixels rather than characters — Google truncates by rendered width, so a
title of capitals is cut far sooner than one of narrow letters. Plus findings
ranked by severity, the full heading outline, images without alt, anchor-text
problems, structured data, lang and hreflang.
The contact details, extracted. Emails, phone numbers, WhatsApp, postal
address, tax id and social profiles — from mailto:/tel: links, JSON-LD and
a deliberately strict text scan. On a prospect's site, this is the lead.
Then the conversion audit: are there calls to action, and are any visible without scrolling? Is there a contact form? Any trust signals — testimonials, reviews, guarantees, case studies? Is a live chat available? And is anything being measured at all?
What a competitor is running tells you more about their strategy than their copy does. CMS, framework, and every analytics and ad pixel on the page. A Meta pixel means they are buying traffic. A session-recording tool means somebody is watching behaviour. No pixels at all means nobody is measuring anything — which is a finding in itself.
The extension is not a smaller copy of the server. It runs in a real browser:
The rendered page. If a site builds its content with JavaScript, an HTTP fetch gets an empty shell. The extension reads the DOM you are looking at. Comparing the two is often the finding.
Real Core Web Vitals for that load — the Largest Contentful Paint, TTFB and bytes transferred your browser measured, not a simulation. Plus images served at more than twice their displayed size, which costs bandwidth on every single visit and is invisible unless you look for it.
Copy puts the whole report on your clipboard as text — contact details, stack, measurements and every finding — ready for a doc, a ticket, or straight into Claude.
Not on the Chrome Web Store yet, so load it unpacked — about thirty seconds:
Download or clone this repo.
Open chrome://extensions.
Turn on Developer mode, top right.
Load unpacked → select the extension folder.
Pin it, then click it on any page.
Worth being precise, because this is where comparable tools overpromise:
✅ Audit any page — yours, a client's, a competitor's | It reads what your browser already loaded. |
✅ See JavaScript-rendered content | It reads the live DOM. |
✅ Pull contact details for prospecting | From links, schema and a strict text scan. Only what the page publishes. |
❌ Show heatmaps of your visitors | An extension only runs for whoever installed it. Your visitors will not install yours. Visitor analytics needs a snippet on the site — that is why Hotjar and Clarity work the way they do, and it is on the roadmap. |
It requests activeTab, not host permissions: it can read a page only
after you click the button, and only that tab. No content script runs on pages
you have not asked about, nothing is sent anywhere, and there is no account or
analytics. The report exists in the popup until you close it.
Real questions, and what the assistant does with them.
Calls crawl_site. Comes back with the 404 and the article that links to
it — which is the part that turns a finding into a fix, because you now know
where to edit. Also surfaces the page quietly serving noindex, which is the
single most expensive thing to have wrong and the least visible.
Calls search_console_queries with dimension: "page". High impressions with
a low CTR means Google shows you and people choose someone else — usually a
snippet problem rather than a ranking problem, and one of the cheapest things
to fix. Follow it with generate_meta on the worst offender.
The why-did-traffic-drop prompt. It compares the window against the one before it, then breaks the loss down by page, query, device and country, because a drop concentrated in one page and a drop spread evenly have completely different causes.
The prompt explicitly tells the assistant not to reach for "a Google update" unless the pattern actually fits one — broad, sudden, sitewide. It is the explanation that requires no evidence, which is exactly why it gets used when there is none.
The beat-competitor prompt: compare_competitor for the on-page
differences, audit_page on each for the detail, search_console_queries
filtered to your URL for what you are already close on.
It is also told to say when the gap looks off-page. Sending you off to rewrite headings when the real difference is 400 referring domains wastes your week, and this server cannot see links pointing at you.
list_sitemap for what the site says it publishes, crawl_site for what it
actually links to. The gap between the two is where stale URLs, orphan pages
and forgotten sections live.
The audit-site prompt against a site you do not own. It obeys robots.txt, identifies itself honestly and paces itself, so you get the picture without being rude to their server. Everything is read-only.
This is the step worth doing. Without it, everything about search intent is inference; with it, the assistant is working from what Google actually recorded.
A service account is the easier path — no browser flow, no token to refresh.
In Google Cloud Console, create a project and enable the Google Search Console API.
Create a service account and download its JSON key.
Open the JSON and copy the client_email — it looks like
something@project.iam.gserviceaccount.com.
In Search Console → your property → Settings → Users and permissions → Add user, paste that email and give it Full or Restricted access.
Point the server at the key:
"env": {
"GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/key.json",
"GSC_SITE_URL": "https://yoursite.com/"
}Then ask: “What did we rank for last month, and what moved?”
"env": {
"GSC_CLIENT_ID": "…apps.googleusercontent.com",
"GSC_CLIENT_SECRET": "…",
"GSC_REFRESH_TOKEN": "…",
"GSC_SITE_URL": "https://yoursite.com/"
}If Search Console is not configured, its tools do not register at all — and the server says why in its startup log. A tool that can only fail is worse than one that is not there.
Tool | What it does |
| Crawl and report site-wide problems: broken URLs with their referrers, duplicate titles and descriptions, missing basics, crawl depth, then the worst individual findings. |
| The URLs a site declares, following the sitemap index. Often revealing on its own — what a site publishes is frequently not what it links to. |
| Every on-page signal for one URL, ranked by impact. |
| Your page and a competitor's, field by field, ending in what they do that you do not. |
| Real performance by query, page, country, device or date. Filterable to a single URL. |
| A window against the one before it: what gained, what lost ground, what dropped out entirely. |
| Which properties your credentials can read, and at what permission level. |
| Core Web Vitals, field data separated from the lab simulation. |
| Assembles the evidence for a new title and description — current tags, structure, and the queries that already work. |
| PageRank over the internal links: where authority accumulates, which important pages are starved of it, which minor pages hoard it. |
| Indexable pages nothing links to — reachable only from the sitemap, crawled rarely, invisible page by page. |
| Pages saying the same thing in different words, by exact phrase overlap with site boilerplate excluded. |
| Schema checked against what Google requires for the rich result each type is for, not merely listed. |
| Reciprocity, self-reference and valid codes across the crawl — where hreflang actually breaks. |
| Outbound links that no longer resolve, with the pages that link to them. |
| The result as Google will render it, measured in pixels.Try a different title without editing the page. |
| Version, configuration and which capabilities loaded. Start here when a tool is missing. |
Tools answer a question you already knew how to ask. SEO is a field where most people do not know which question to ask — so this server also ships MCP prompts, which your client lists for you.
Prompt | What it does |
audit-site | Full sweep, ending in the three things to fix first with what each is plausibly worth. Narrow it with |
why-did-traffic-drop | Works out what actually changed from real Search Console data. |
improve-page | One URL end to end: what it has, what it already ranks for, how fast it is, then a specific edit list. |
beat-competitor | Why their page outranks yours — and honest about what is not visible from here. |
Each prompt names the tools to call, the order, and what a good answer looks like: verdict first, findings ranked, no padding, and ground every claim in tool output. An SEO audit full of confidently invented numbers is worse than no audit, so the instruction is explicit rather than hoped for.
Two resources are exposed as attachable context:
seo://server/capabilities — what is loaded and how it is configured.
seo://reference/checklist — every check and the threshold behind it, so the
numbers in an audit can be questioned rather than taken on faith.
By default an MCP server talks over stdio: your client starts it as a child process on your machine. Set one variable and it serves Streamable HTTP instead, so one instance can serve a whole team:
SEO_MCP_HTTP=true \
SEO_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
SEO_MCP_SITE=https://yoursite.com \
npx -y @soyrageagency/seo-mcp{
"mcpServers": {
"seo": {
"type": "http",
"url": "http://10.0.0.5:8621/mcp",
"headers": { "Authorization": "Bearer <the token you generated>" }
}
}
}It binds loopback by default and warns loudly if you start it without a token.
Anyone who can reach the port can crawl anything the server can reach and read
your Search Console data, so keep it behind your VPN. GET /health needs no
token, for container healthchecks.
docker run --rm -i \
-e SEO_MCP_SITE=https://yoursite.com \
-v /path/to/key.json:/keys/gsc.json:ro \
-e GSC_SERVICE_ACCOUNT_FILE=/keys/gsc.json \
ghcr.io/soyrageagency/seo-mcpKeep -i and do not allocate a TTY: stdout is the JSON-RPC stream. To serve it
over the network instead, add -p 8621:8621 -e SEO_MCP_HTTP=true -e SEO_MCP_HTTP_HOST=0.0.0.0 -e SEO_MCP_HTTP_TOKEN=….
Everything is settable by environment variable, by seo-mcp.config.json, or by
a local .env — in that order of precedence.
Variable | Default | What it does |
| — | Default site, so tools do not need the URL every time. |
|
| Fabricated site and search data. No network access at all. |
|
| Hard cap on pages per crawl. |
|
| How many links deep to follow. |
|
| Parallel requests. |
|
| Pause between requests to the same host. |
|
| Per-request timeout. |
|
| Obey robots.txt. Only turn this off for a site you control. |
|
| How the crawler identifies itself. |
|
| Search Console property. Mind the trailing slash, or use |
| — | Path to a service-account JSON key. |
| — | The key inline, for clients that only pass env vars. |
| — | The OAuth alternative. |
| — | Free key. Without it PageSpeed is rate-limited. |
|
| Serve over HTTP instead of stdio. |
|
| HTTP transport settings. |
| (all) | Allowlist: |
| — | Blocklist. Always wins over the allowlist. |
|
|
|
Every crawl hits somebody's server, often one you do not own — a competitor, a client's staging box. So the crawler is deliberately conservative:
It identifies itself honestly. The default User-Agent names the tool and links to this repo, so a site owner can see who hit them and block it.
It obeys robots.txt, including wildcards, $ anchors, longest-match
precedence and per-agent groups. There is an override, and it warns you every
time you use it.
It honours Crawl-delay, and paces itself per host regardless.
It is bounded by page count and depth, and gives up rather than hanging.
It follows redirects by hand, up to five hops, because the chain itself is a finding worth reporting.
Saying this plainly is more useful than another feature list:
It will not change your site. No edits, no submissions, no settings.
It will not invent numbers. The server's instructions tell the assistant to ground every claim in tool output and to say when it is inferring.
It will not tell you a page is "optimised". It reports conventions and thresholds. Relevance and links matter more than any of them, and a page can pass every check here and rank nowhere.
It has no backlink data. Nothing here sees links pointing to you.
No telemetry. Nothing leaves your machine except the requests you asked for: the sites you crawl, and Google's APIs when you configure them.
It does not register without credentials. Run about — it reports whether
Search Console is connected and lists which capabilities loaded. The server
also logs the reason on startup.
Run list_search_console_sites to see exactly which properties your
credentials can read. The usual cause is a mismatch in how the property is
verified: https://example.com/ (with the trailing slash),
https://www.example.com/ and sc-domain:example.com are three different
properties to Google.
For a service account, also check you added its client_email as a user on the
property itself — enabling the API is not enough.
Set PAGESPEED_API_KEY. The key is free and takes a minute to create; without
one the quota is tiny.
Two common causes. Either robots.txt is blocking the crawler — the report lists those URLs under NOT CRAWLED with the reason — or the site renders its content with JavaScript, and a plain HTTP fetch sees an empty shell. Rendered crawling is on the roadmap.
SEO_MCP_DEMO is still true. Remove it, or set it to false.
git clone https://github.com/soyrageagency/seo-mcp-server.git
cd seo-mcp-server
npm install
npm run build
npm test # 25 unit tests: robots.txt parsing, extraction, audit rules
npm run smoke # 42 checks end to end: boots the real server and drives it
npm run inspect # the MCP Inspector, against your local build
npm run shots # regenerate the README screenshots from real output
npm run gif # regenerate the demo GIF
npm run banner # regenerate the sponsor banner and social card
npm run icons # regenerate the extension icons
npm run extension:shots # load the extension in a real Chrome and screenshot it
npm run extension:gif # the extension demo GIFnpm run dev watches and rebuilds. TypeScript strict, with
noUnusedLocals, noUnusedParameters, noImplicitReturns and
noFallthroughCasesInSwitch. CI runs the whole suite on Linux and Windows.
The full roadmap — shipped, next, and what is deliberately not planned — lives in ROADMAP.md.
The short version: self-hosted visitor analytics with click and scroll heatmaps (a cookieless snippet, since an extension can only ever see its own installer), JavaScript-rendered crawling, and audits that remember so the question becomes "what changed since last week". Backlink data and keyword-volume estimates are not planned, because doing either honestly needs an index this project will never have.
Designed, built and maintained by SoyRage Agency — https://soyrage.es/
Part of a family of self-hosting tools you can talk to: Proxmox MCP · Docker MCP · RageVault
Released under the MIT License — use it, modify it, self-host it, ship it commercially.
If you build something on top of it, a link back to soyrage.es is appreciated but never required.
© 2026 SoyRage Agency — https://soyrage.es/ · Made with care in Valencia, Spain.
Version, credits and the current configuration — which capabilities are loaded, whether Search Console is connected, and whether demo mode is on. Useful when a tool is missing and you want to know why.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It implies a read-only informational call by listing version, credits, and configuration, but it never explicitly states that it has no side effects or does not modify state. For a simple about tool this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first lists the informational contents, the second gives the practical diagnostic use case. No filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, low-complexity tool without an output schema, the description is sufficiently complete. It names the expected content areas and the scenario in which the tool is valuable. It could optionally note the exact return format, but that is not necessary for an about-style endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter usage. The baseline for no-parameter tools is 4, and the description satisfies it by explaining what information the call returns rather than mentioning irrelevant inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (server info) and the specific content delivered: version, credits, current configuration, loaded capabilities, Search Console connection, and demo mode. It lacks an explicit verb like 'returns' or 'provides', but it is easy to distinguish from the sibling SEO-action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case: 'Useful when a tool is missing and you want to know why.' This tells the agent when to invoke this tool. It does not discuss exclusions or alternatives, but no alternatives are really relevant for a server introspection tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one URL and report every on-page SEO signal — title, description, headings, canonical, indexability, structured data, images, links, language and page weight — with findings ranked by impact rather than listed flat. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to audit. A path works if SEO_MCP_SITE is set. | |
| showOutline | No | Include the full heading outline. Useful for structure problems. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explicitly states 'Read-only' and reveals that findings are 'ranked by impact rather than listed flat,' giving useful behavioral detail beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence efficiently front-loads the core action, lists valuable signals, and adds a behavioral qualifier without waste. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the returned signals, the output ordering, and the read-only nature. It is solid for a moderate-complexity tool, though it does not address failure behavior or output formatting since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented in the schema. The description only reiterates that a URL is fetched and does not add new meaning about showOutline or URL handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Fetch one URL') and resource ('one page'), then enumerates the exact SEO signals covered. This clearly distinguishes it from siblings like crawl_site (site-wide) and pagespeed (performance-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear use context — auditing a single page/URL. It does not explicitly name alternatives such as crawl_site for whole-site auditing, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl the site and validate its hreflang across pages: reciprocity, self-reference, valid language and region codes, duplicate or multiple x-default. Faults here are invisible page by page — every page looks correct and the cluster is still ignored, because a declaration Google cannot verify from both ends is dropped entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| maxPages | No | Cap on pages crawled. Default 200. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It states the tool crawls and validates rather than modifies data, and adds an important domain behavior: declarations Google cannot verify from both ends are dropped entirely. It stops short of describing output or crawl side effects, but for a read-only validation tool this is solid coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no filler. The first front-loads the action and resource, the second provides a concise, valuable explanation of why this validation matters. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with fully documented parameters and no output schema, the description covers what the tool does, what it validates, and why it is important. The only notable omission is a description of the return format, but no output schema exists and the validation focus makes the expected result inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the two parameters (site and maxPages) are already fully documented in the input schema. The description does not add parameter-level detail, which is acceptable but not value-adding, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb, resource, and scope: 'Crawl the site and validate its hreflang across pages.' It enumerates the exact checks performed (reciprocity, self-reference, language/region codes, duplicate x-default), which makes it unmistakable and clearly distinct from general crawl or validation siblings like crawl_site and validate_structured_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context for when this tool is needed: hreflang faults are invisible page-by-page and affect the whole cluster, so this is the tool for cross-page cluster validation. It does not explicitly name alternatives or say when not to use it, but the reasoning is clear enough for an agent to route to it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit your page and a competitor's side by side, and report only where they differ. Use it to answer 'what are they doing that we are not' for a query you both target. Read-only, and it fetches both pages.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Your page. | |
| competitor | Yes | The competing page to measure against. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden and it does so directly: 'Read-only, and it fetches both pages' discloses the safety profile and the external network action. It does not go into output format or failure behavior, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the action and output rule come first, the use case second, and the behavioral note last. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is nearly complete: inputs are fully covered by the schema, the purpose is clear, and the read-only/fetch behavior is stated. It only lacks a more precise description of what 'differences' means in the report.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'url' and 'competitor' are already documented as 'Your page' and 'The competing page to measure against'. The description reinforces the side-by-side relationship but adds no per-parameter detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Audit your page and a competitor's side by side') and a precise output contract ('report only where they differ'). The comparison framing distinguishes it clearly from sibling tools like audit_page or crawl_site, which audit a single site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use case: answer 'what are they doing that we are not' for a query both pages target. It does not name exclusions or alternative tools, so it falls just short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl a site and report the problems only visible across pages: broken URLs and what links to them, duplicate titles and descriptions, missing basics counted as a proportion, and pages buried too deep to be crawled often. Seeds from the sitemap when there is one. Read-only, obeys robots.txt and paces itself.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| maxDepth | No | How many links deep to follow. Default 3. | |
| maxPages | No | Hard cap on pages fetched. Default 200 (SEO_MCP_MAX_PAGES). | |
| listPages | No | Include the full page-by-page table. Default false — it is long. | |
| useSitemap | No | Seed the crawl from the sitemap. Default true, and a much better sample. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explicitly stating 'Read-only, obeys robots.txt and paces itself,' which tells the agent about safety, rate-limiting, and site-respect behavior. The sitemap-seeding note adds useful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first defines output scope and contents, the second notes sitemap seeding, and the third covers safety and pacing. Dense but readable, with no fluff or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters, complete schema coverage, no output schema, and no annotations, the description provides the essential behavioral profile (cross-page problems, sitemap seeding, safety) and is sufficient for an agent to invoke correctly. It does not describe result format, but there is no output schema to leverage and the listed report categories imply the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description adds only a small reinforcement of the useSitemap behavior ('Seeds from the sitemap when there is one') but otherwise leaves parameter-level meaning to the already-complete schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('crawl a site') and then enumerates the specific cross-page problems it reports: broken URLs with referrers, duplicate titles and descriptions, missing basics as proportions, and deep-buried pages. This clearly distinguishes it from siblings like find_broken_links and find_duplicate_content, which target single issue classes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that the tool is for site-wide, cross-page problems and mentions read-only behavior, robots.txt compliance, and sitemap seeding. This gives an agent clear context for when a full crawl is appropriate, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl the site, collect its external links and check each one still resolves. Outbound rot is invisible until someone clicks — sites move, shut down and reorganise, and nothing tells you. Checks each target once, paced, and reports the pages that link to it.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| maxLinks | No | Cap on external links checked. Default 100. | |
| maxPages | No | Cap on pages crawled. Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavioral details: 'Checks each target once, paced, and reports the pages that link to it,' indicating deduplication, rate limiting, and a grouped report. It stops short of defining what 'resolves' means (status codes, redirects) or clarifying network side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two functional sentences carry the core action and behavior, with one short motivational sentence for context. Every sentence earns its place; the main functionality is front-loaded and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with no annotations and no output schema, the description is fairly complete: it explains the crawl-and-check process, dedup/pacing behavior, and the report shape ('reports the pages that link to it'). It leaves minor gaps around result structure and the specific definition of a broken link, but the agent has enough to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage (site start URL defaults to SEO_MCP_SITE, maxLinks and maxPages caps). The description adds no parameter-specific detail, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource chain: 'Crawl the site, collect its external links and check each one still resolves.' It clearly identifies the tool's scope as outbound/external links and distinguishes it from sibling tools like find_orphan_pages and link_graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the tool is relevant: 'Outbound rot is invisible until someone clicks — sites move, shut down and reorganise, and nothing tells you.' This implies use when you suspect or want to verify external link health, though it doesn't explicitly name alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find pages that say substantially the same thing in different words — a template filled in forty times, product variants with one word changed. Identical titles are easy to spot; this catches the expensive kind, where two pages compete for one query and neither wins.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| maxPages | No | Cap on pages crawled. Default 200. | |
| threshold | No | Share of three-word phrases in common, 0.3–1. Default 0.6; unrelated pages score near zero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the transparency burden. It usefully explains the detection concept and the kind of duplication targeted, but it does not disclose operational behavior such as crawling scope, rate limits, read-only guarantees, or what happens after the crawl.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The core function is front-loaded, followed by vivid examples and a compelling reason for the tool's existence. Nothing is repeated from the schema, and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description provides a strong conceptual foundation and enough context to infer its role among siblings. It could be more complete by stating what the result looks like (e.g., grouped pages or similarity scores), but the core invocation context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description gives conceptual context that helps interpret 'threshold' and 'near-duplicate,' but it does not map to specific parameters or add syntax/format details beyond the schema. It earns the baseline but not more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Find pages') and clearly scopes the behavior to near-duplicate content that expresses the same idea in different words. Concrete examples ('template filled forty times, product variants with one word changed') and the contrast with 'identical titles' make the tool's purpose unmistakable and distinct from simple duplicate detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear context for use: detecting pages that 'compete for one query and neither wins,' and it explicitly contrasts this with easy-to-spot identical titles. It does not name sibling tools or state when not to use it, but the use case is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find indexable pages that nothing on the site links to. They are usually reachable only from the sitemap, which means they get crawled rarely and rank poorly regardless of how good they are. One of the highest-value findings a crawl produces, and invisible page by page.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| maxPages | No | Cap on pages crawled. Default 200. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the core behavior and consequence of orphan pages, but it does not disclose operational details such as whether the tool performs a new crawl, cost/latency implications, or what the returned data looks like. This is acceptable but not exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core definition and then adds meaningful context about why orphan pages matter. It is slightly wordy with the subjective 'highest-value findings' claim, but every sentence contributes useful context and it remains compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should carry more of the operational context. It explains the concept well, but it does not mention what the return value looks like, whether a crawl is triggered, or any cost/latency caveats. This is a moderate gap for an agent deciding whether and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning about site or maxPages beyond what the schema already documents, which is fine since the schema fully covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Find indexable pages that nothing on the site links to.' This clearly defines what an orphan page is and differentiates the tool from sibling tools like find_broken_links or link_graph without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is valuable: orphan pages are usually reachable only from the sitemap, get crawled rarely, and rank poorly. It implies the use case but does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Collect everything needed to write a strong title tag and meta description for a page: what it currently has, its headings, its opening prose, and — when Search Console is configured — the queries people already use to find it. Returns the evidence and the length limits; you write the copy from the page's actual content.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to write for. A path works if SEO_MCP_SITE is set. | |
| keyword | No | A term to prioritise, if you already know what this page should target. | |
| variants | No | How many alternatives to ask for. Default 3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It explains what the tool collects, mentions the conditional Search Console data, and states the actual output—evidence and length limits—rather than a finished draft. This gives the agent a clear picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs in the tool's inputs, conditional behavior, and output type without unnecessary filler. It is front-loaded with the core purpose and remains readable, though it could be split into two sentences for slightly better clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for a read-oriented tool: it specifies what data is gathered, the Search Console condition, what the return value contains, and the division of labor between the tool and the user. It does not detail the exact structure of the returned evidence, but this is not critical given the absence of an output schema and the focused scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, including url, keyword, and variants. The description adds context about the page content elements used, but it does not materially enhance the schema's parameter explanations, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: it 'collects everything needed to write a strong title tag and meta description,' including current tags, headings, opening prose, and Search Console queries. This distinguishes it from sibling tools like audit_page or serp_preview, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used when gathering evidence for drafting title tags and meta descriptions, and explicitly notes that the user writes the copy, not the tool. However, it does not name any alternative tools or provide explicit when-to-use versus when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl the site and analyse its internal links: which pages hold the most internal authority, which important pages are starved of it, and which minor pages are hoarding it. Answers 'is my linking pointing at the pages that matter', which no single-page audit can.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Start URL. Defaults to SEO_MCP_SITE. | |
| limit | No | Rows per section. Default 15. | |
| maxDepth | No | How deep to follow links. Default 3. | |
| maxPages | No | Cap on pages crawled. Default 200. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It does state that the tool crawls the site and analyzes internal links, which implies read-only analysis, but it does not disclose potential resource usage, crawl behavior limits beyond schema parameters, or any side effects. The description adds some behavioral detail but leaves operational transparency incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core action, and uses every clause to convey either the tool's function or its value proposition. There is no redundant filler, and the single-page audit contrast earns its place by clarifying scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description does a solid job of explaining what analysis is performed and what kind of conclusions it supports. The main gaps are the lack of explicit output format/return shape and absence of operational caveats such as crawl limits or timeout behavior, but the schema and the high-level output categories provide enough for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions for site, limit, maxDepth, and maxPages, so the baseline is 3. The tool description does not add extra meaning to individual parameters, but it also does not need to because the schema is already descriptive. No meaningful parameter semantics are added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource—'Crawl the site and analyse its internal links'—and goes further by naming the concrete analytical outputs: pages with most internal authority, important pages starved of it, and minor pages hoarding it. This clearly separates it from single-page audit tools and other link-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case: answering 'is my linking pointing at the pages that matter.' It also explicitly contrasts itself with a single-page audit, which helps an agent avoid choosing audit_page. However, it does not mention other relevant alternatives like find_broken_links or find_orphan_pages, so it is not fully explicit about when not to use those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the URLs a site declares in its sitemap, following the sitemap index when there is one. Useful on its own to see what the site thinks it publishes, which is often not what it actually links to.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Site URL. Defaults to SEO_MCP_SITE. | |
| limit | No | Maximum URLs to return. Default 200. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses a nontrivial behavior: following the sitemap index when present, and clarifies the source is the declared sitemap rather than actual links. It does not mention network-fetch behavior or error handling, but for a straightforward read-only listing tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, purposeful sentences. The first states the core action and index-following behavior; the second adds practical context. There is no redundant or filler language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description plus schema provides enough for an agent to call it correctly: what it lists, how it handles indexes, and why it is useful. A brief statement of return format would have been nice, but it is not necessary to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for both parameters, including defaults and constraints, so the description does not need to add much. It adds no parameter-specific meaning beyond what the schema already provides, which justifies the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('URLs a site declares in its sitemap'), and adds a precise behavioral detail about following sitemap indexes. It also implicitly distinguishes itself from crawl-oriented siblings by noting the sitemap often differs from what the site actually links to.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: to see what the site thinks it publishes. It also implies this is not the tool for discovering actual linked URLs, but it does not explicitly name alternatives such as crawl_site or link_graph, so the guidance stops short of a full when-to-use/when-not-to-use statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run PageSpeed Insights on a URL and report Core Web Vitals. Separates lab data (a Lighthouse simulation) from field data (what real Chrome users experienced), because only the second is what Google ranks on. Slow: Lighthouse runs server-side and takes up to a minute.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to measure. A path works if SEO_MCP_SITE is set. | |
| strategy | No | Default mobile, which is what indexing uses. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does this well by disclosing that the tool is slow ('takes up to a minute') and explaining the conceptual difference between lab and field data. It does not mention error cases or rate limits, but for this simple measurement tool the disclosed latency and data-source distinction are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, each earning its place: the first states the core action, the second explains the key data distinction, and the third sets latency expectations. It is front-loaded with the primary purpose and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, this description gives an agent enough to select and invoke it: what it measures, the input URL requirement, the default mobile strategy from the schema, and the latency caveat. It could be more explicit about the exact metrics returned, but 'report Core Web Vitals' is a reasonable summary for this simple case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter description coverage, including the 'url' and 'strategy' defaults, so the baseline is 3. The description adds no additional parameter-level meaning; it only reinforces the lab/field distinction conceptually rather than explaining how 'strategy' or 'url' behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run PageSpeed Insights on a URL and report Core Web Vitals') and names the specific resource being measured. It is more specific than a generic audit tool because it focuses on Core Web Vitals, but it does not explicitly contrast itself with the sibling 'audit_page' tool or name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context: field data is what Google ranks on, so a user wanting ranking-relevant CWV should prefer that. However, it never explicitly says when to use this tool instead of siblings like 'audit_page', 'crawl_site', or 'compare_competitor', so usage guidance is only implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a page's title and description the way a Google result will show them, measured in pixels rather than characters. Google truncates by rendered width, so a title of capitals is cut far sooner than one of narrow letters — the character count everyone quotes misleads on exactly the titles worth checking.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to preview. A path works if SEO_MCP_SITE is set. | |
| title | No | Try a different title without editing the page. | |
| description | No | Try a different meta description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses a key behavior—truncation is pixel-based rather than character-based—and explains why that matters. However, it does not clarify what the tool returns (e.g., an image, HTML, or text), nor whether it fetches the page or only uses the provided title/description, leaving important gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the core purpose and measurement unit; the second provides a non-obvious reason why this tool matters. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for selecting the tool, but because there is no output schema, the description should ideally explain the return format or visual result. It also omits whether the tool accesses a live URL or works solely with provided inputs, which an agent would need for correct invocation. The strong schema helps, but the missing output and behavior details keep this from being complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds no parameter-specific details beyond the general pixel-measurement context, which applies to title and description rendering but does not explain syntax, formats, or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Render') and specifies the exact resource ('a page's title and description') in the context of Google search results. It clearly distinguishes this preview tool from sibling tools like generate_meta or audit_page by emphasizing visual, pixel-based rendering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for use: checking how Google will actually truncate a title or description, because character counts are misleading. It does not explicitly name alternatives or state exclusions, but the scenario is concrete enough for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a page's JSON-LD against what Google actually requires for the rich result each type is for. Having schema and being eligible for a rich result are different things: a Product with no offer, a Recipe with no ingredients or a rating above its own scale are all valid JSON that earns nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to check. A path works if SEO_MCP_SITE is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that the tool evaluates eligibility, not just schema validity, and gives concrete examples of failures. It does not mention output format or edge cases like missing JSON-LD, but the core behavioral trait is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The main action is front-loaded, and the clarifying distinction with concrete examples earns its place by preventing a common misconception about the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only validation tool, the description covers the essential question: what is checked, and what the interpretation should be. It does not describe the return format, but the absence of an output schema lowers the burden, and the tool's purpose is clear enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single 'url' parameter is already documented in the input schema. The tool description adds no additional meaning about the parameter beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Check') and a specific resource (a page's JSON-LD against Google's rich-result requirements). It also clarifies the tool's core distinction between valid JSON and rich-result eligibility, which separates it from generic schema validity checkers. Even without naming a sibling, the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when this tool matters: whenever the concern is whether schema earns a Google rich result, not merely whether it is valid JSON. It does not explicitly name an alternative or state when not to use it, but the examples imply the decision point well enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0aboutaudit_pagecheck_hreflangcompare_competitorcrawl_sitefind_broken_linksfind_duplicate_contentfind_orphan_pagesgenerate_metalink_graphlist_sitemappagespeedserp_previewvalidate_structured_dataScored across 14 tools
Each tool targets a clearly distinct concern—site-wide crawl issues, individual page audits, external link checking, internal link analysis, orphans, duplicates, structured data, and hreflang. Even related tools like crawl_site and find_duplicate_content are differentiated by whether they catch exact duplicates or semantic similarity.
Most tools follow a clear verb_noun snake_case pattern such as crawl_site, find_broken_links, and validate_structured_data. A few exceptions like about, pagespeed, serp_preview, and link_graph break the pattern, but the naming remains readable and predictable overall.
14 tools is well within the ideal range for a specialized SEO server. Each tool addresses a discrete diagnostic need, and the count feels comprehensive without being bloated or redundant.
The toolset covers the major technical SEO workflows: crawling, page audits, performance, metadata, internal links, orphans, duplicates, structured data, hreflang, sitemaps, and competitor comparison. There are no obvious dead ends or missing life-cycle operations for an analysis-focused SEO server.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
Run SEO + AI-visibility (GEO) audits from Claude, Cursor & other AI clients.
Open-source AI SEO over MCP: audits, ranks, keywords, backlinks + AI visibility (GEO).
Ask your AI assistant about your own website's SEO and get answers from your real data, not generic advice. One connector, all your channels: Google Search Console (rankings, clicks, indexing), Google Analytics (traffic and sources), Google Ads (campaigns and search terms), Google Business Profile (local visibility and reviews), Google Trends, keyword research, backlinks and link prospects, competitor rankings, site crawls, and AI visibility (does ChatGPT mention your site?). Ask things like: which keywords am I one push away from page 1 for? Why did traffic drop last month? Which competitor is outranking me, and where? Are my ads and SEO fighting over the same keywords? Then let it act. On a paid plan, your assistant can prepare SEO fixes, content campaigns, and article drafts. Nothing touches your site until you approve it in SEOmatic, and every change shows before-and-after results. Connect via OAuth: log in, pick your site, done. No API key needed.
