Skip to main content
Glama
russjeffery

google-search-console-mcp

by russjeffery

Google Search Console MCP

An MCP server for the Google Search Console API: search performance data, URL index status, sitemap management, and property listing.

One codebase runs three ways — stdio (local, through npx), Streamable HTTP (self-hosted), and Cloudflare Workers (hosted at a URL). It implements MCP 2026-07-28 and falls back automatically to 2025-11-25, 2025-06-18, and 2025-03-26, so it works with clients on either side of the protocol change.

Zero runtime dependencies.


Quick start

You need Google credentials either way, so start there. Open the setup page in a browser:

https://search-console-mcp.russjeffery.com/setup

The page walks you through creating a Google OAuth client, runs the consent flow, verifies the credentials against the live API, and gives you a ready-to-paste config block for your MCP client. Nothing is installed, and the server stores nothing.

To do the same thing locally instead, with the page served from 127.0.0.1:

npx google-search-console-mcp auth

Then choose how to run the server:

  • Locally, by pasting the printed stdio config into your client. See Run the server.

  • Against the hosted endpoint, with no install at all. See Hosted endpoint.


Related MCP server: searchconsole-mcp

Hosted endpoint

A public deployment runs at:

https://search-console-mcp.russjeffery.com/mcp

To get a credential blob for it, open the setup page in a browser.

It runs in bring-your-own-credential mode. You send your own credential blob as the bearer token, the server uses it for that one request, and it stores nothing. Two people pointing the same client at this URL see only their own Search Console properties.

Add it to a client like this, replacing CREDENTIAL_BLOB with the blob the setup page gave you:

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://search-console-mcp.russjeffery.com/mcp",
      "headers": { "Authorization": "Bearer CREDENTIAL_BLOB" }
    }
  }
}

In the Claude web or desktop UI, add the same URL and header under Settings → Connectors → Add custom connector.

The deployment answers on these routes:

Route

Behavior

POST /mcp

The MCP endpoint. Data tools require an Authorization: Bearer header carrying your blob.

GET /setup

The credential setup page. It creates blobs in your browser and stores nothing on the server.

GET /health, GET /

Server name, version, endpoint path, setup URL, and supported protocol versions. No authentication, no credentialed data.

GET /mcp, DELETE /mcp

405, as the 2026-07-28 revision prescribes. There is no GET stream and no session to delete.

A request that arrives with no bearer token isn't refused outright. Discovery — initialize, tools/list, resources/read, and the check_setup tool — answers normally and returns setup instructions in place of the usual guidance, so a client that isn't configured yet still connects and its agent can explain what to do. Only tools/call for a data tool returns 401. A deployment with MCP_SHARED_SECRET set is the exception: it requires the secret on every request, including discovery.

Two things to know before you point production work at it:

  • You are sending your credentials to someone else's host. The blob grants Search Console access to your account until you revoke it. The code that receives it is in this repository, and it stores nothing. If that tradeoff doesn't suit you, run the server yourself. The stdio and self-hosted paths are equivalent in every other respect.

  • It's a personal deployment with no uptime commitment. For anything you depend on, deploy your own copy. See Cloudflare Workers.

The hosted deployment allows no browser origins, so browser-based MCP clients are refused. Ordinary MCP clients send no Origin header and are unaffected. The setup page sits outside that check, because it holds no credentials of its own and exists to be opened in a browser.


Tools

The server exposes every method in the Search Console API v1, plus two composites and a setup check:

Tool

Does

API method

list_sites

All properties you can access, with permission levels

sites.list

get_site

One property and your permission on it

sites.get

query_search_analytics

Clicks, impressions, CTR, and position — grouped, filtered, paged

searchanalytics.query

compare_search_analytics

Two periods with per-row and total deltas

composite

list_sitemaps

Submitted sitemaps, or the children of a sitemap index

sitemaps.list

get_sitemap

One sitemap's status and submitted and indexed counts

sitemaps.get

submit_sitemap

Submit or resubmit a sitemap

sitemaps.submit

delete_sitemap

Unsubmit a sitemap

sitemaps.delete

inspect_url

Full index status for one URL

urlInspection.index.inspect

inspect_urls

Up to 25 URLs concurrently, with a coverage-state summary

composite

check_setup

Whether credentials are present, still valid, and which properties they reach

diagnostic

Site verification and the sites.add and sites.delete methods are deliberately not exposed. Adding and verifying a property is a browser flow that doesn't belong in an agent tool.

The server also serves prompts (performance_review, indexing_audit, query_opportunities, and sitemap_health) and resources (gsc://guide/search-analytics, gsc://guide/url-inspection, and gsc://guide/sitemaps) that agents can read on demand.


Authentication

Create a Google OAuth client

You do this once. The server can't do it for you, because Google requires a human in their console.

  1. Open the Google Cloud Console and select or create a project.

  2. Enable the Search Console API for that project.

  3. Open Google Auth Platform. If the project has no consent screen yet, click Get started and fill in the four panels:

    • App information: any app name, and your own address as the user support email.

    • Audience: External, unless this is a Workspace account and every user of the app is inside it.

    • Contact information: your email address, for Google's notices about the project.

    • Finish: agree to the User Data Policy, then click Create.

  4. Go to Data access, click Add or remove scopes, and add the scope you want: https://www.googleapis.com/auth/webmasters for full access, or https://www.googleapis.com/auth/webmasters.readonly for read-only. Click Update, then Save.

  5. Go to Audience. Under Test users, click Add users and add the Google account that owns the Search Console properties. An External app in testing refuses every account that isn't listed there.

  6. Go to Clients, click Create client, and choose the application type for where you run the setup flow:

    • For a setup page on a server, such as the hosted endpoint, choose Web application. On that client, under Authorized redirect URIs, click Add URI and paste that server's callback address. The setup page shows the exact address to copy, and Google refuses the sign-in unless it matches character for character.

    • For npx google-search-console-mcp auth on your own machine, choose Desktop app. It needs no redirect URI, because Google accepts any loopback port for that client type.

  7. Copy the Client ID and the Client secret.

While the consent screen is in Testing, Google expires refresh tokens after seven days, and you have to run setup again weekly. Publishing the app, under Audience → Publish app, makes them durable.

Google classes both webmasters scopes as sensitive, so a published app that hasn't been through verification shows an unverified app warning ahead of the consent screen, and is capped at 100 users. You can continue past the warning under Advanced. For a client only you sign in to, that's the whole cost; verification matters once you hand the client to other people.

Run the setup flow

The setup page is the same in both places. Paste in the client ID and secret, then choose full or read-only access. The flow runs Google's consent screen and exchanges the code for a refresh token with PKCE. It then calls list_sites to prove the credentials work, showing you the exact properties they can reach.

The final page gives you the credential blob and ready-to-paste config for Claude Desktop, Claude Code, and remote deployments, each with a copy button.

In a browser, with nothing installed

Open /setup on any deployment of this server, including the hosted endpoint:

https://search-console-mcp.russjeffery.com/setup

The page prepares the authorization request in your own browser and keeps the client ID, client secret, and PKCE verifier in sessionStorage until Google redirects back. The server holds no part of a pending flow. Your client secret reaches it once, in the request that trades Google's authorization code for a refresh token, and isn't stored.

From a terminal

npx google-search-console-mcp auth

This serves the same page from 127.0.0.1 and opens it for you, then prints the blob and config to your terminal as well. On a headless machine or over SSH, run auth --terminal for the prompt-driven version instead.

The credential blob

What you get back is a credential blob: base64url-encoded JSON holding your client ID, client secret, and refresh token.

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

Treat the blob as a password. Anyone holding it has your Search Console access until you revoke it at Google Account permissions.

It's a single opaque string so that one value carries everything the server needs. That way it goes straight into an environment variable or an Authorization header, with no credentials file on disk.

Alternatives to the OAuth flow

Service account. This suits CI and team-owned properties. Create a service account in Google Cloud, then add its client_email address as a user on the property in Search Console, under Settings → Users and permissions. Encode the downloaded key file directly:

base64 -i service-account.json | tr -d '\n'

The server accepts a raw service-account key as the blob, with no envelope needed.

Existing access token. Set the blob to {"type":"access_token","access_token":"ya29..."}. No refresh is possible, so this suits only short-lived scripts.

Scopes

The flow requests one of two scopes:

Scope

Grants

https://www.googleapis.com/auth/webmasters.readonly

Everything except sitemap submit and delete

https://www.googleapis.com/auth/webmasters

Full access (default)

Choosing read-only on the setup page requests the narrower scope. The --read-only flag on the server is a separate, independent block that rejects mutating tools before they reach the API.


Run the server

Local (stdio)

Paste the config that auth printed into your client, replacing CREDENTIAL_BLOB with your own blob:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "CREDENTIAL_BLOB" }
    }
  }
}

Config file locations differ by client:

Client

Path

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json

Claude Code

Run claude mcp add google-search-console --env GSC_CREDENTIALS=CREDENTIAL_BLOB -- npx -y google-search-console-mcp

Cursor

~/.cursor/mcp.json

VS Code

.vscode/mcp.json

To skip the npx download on every launch, install the package globally:

npm install -g google-search-console-mcp

Self-hosted HTTP

Start a local Streamable HTTP server with your own credentials:

GSC_CREDENTIALS=CREDENTIAL_BLOB npx google-search-console-mcp http --port 8787

That serves POST http://127.0.0.1:8787/mcp, and the setup page at http://127.0.0.1:8787/setup. Pass --no-setup-ui to leave the page off. It binds to loopback by default. Pass --host 0.0.0.0 only if you mean to expose it, and put TLS in front of it when you do.

Browser-based clients are refused unless you name them, because a server holding its own credentials would otherwise be drivable by any page you visit. Ordinary MCP clients send no Origin header and are unaffected. A browser client needs its origin listed:

npx google-search-console-mcp http --allowed-origins http://localhost:6274

A rejected origin gets a 403 that the browser can't read, because a refusal carries no CORS headers by design. It surfaces as a generic CORS failure, so check the server's Origins: startup line when a browser client can't connect. To turn the check off, pass --allowed-origins '*'.

Cloudflare Workers

Deploy your own copy:

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

Your endpoint is https://google-search-console-mcp.SUBDOMAIN.workers.dev/mcp, where SUBDOMAIN is your workers.dev subdomain. The setup page is at /setup on the same host, so anyone you share the deployment with can mint their own blob without installing anything.

By default the Worker stores no secrets. Each client sends its own credential blob as the bearer token, so a shared deployment never holds anyone's Google credentials. Different users of the same URL see only their own properties.

For a private, single-tenant deployment, set both secrets instead:

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

Clients then send the shared secret rather than a blob.

The Worker reads these optional vars from wrangler.jsonc:

Variable

Effect

MCP_ENDPOINT

Path to serve on. Default /mcp

GSC_READ_ONLY

"1" disables sitemap submit and delete

ALLOWED_ORIGINS

Comma-separated browser origins. Unset means non-browser clients only; * allows any

MCP_STRICT_HEADERS

"0" relaxes 2026-07-28 header-mirroring validation

SETUP_UI

"0" stops serving the setup page

SETUP_PATH

Path for the setup page. Default /setup

Serve it from your own domain

To use a custom hostname, add a named environment to wrangler.jsonc with the hostname as a custom-domain route. The prod environment already there is the one behind the hosted endpoint, so copy its shape and change the pattern:

"env": {
  "prod": {
    "name": "google-search-console-mcp",
    "routes": [
      { "pattern": "mcp.example.com", "custom_domain": true }
    ],
    "vars": { "MCP_ENDPOINT": "/mcp" }
  }
}

Then deploy that environment:

npx wrangler deploy --env prod

Wrangler creates the DNS record and the edge certificate itself. The zone has to already be on the same Cloudflare account. Keeping the route out of the top level means a plain wrangler deploy still works for anyone else who clones this repository. Environments don't inherit vars, so repeat any you need. Secrets are per-environment too, so pass --env prod to wrangler secret put as well.

Connect a client to a remote server

Point the client at your deployment's URL and send the blob as a bearer token:

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer CREDENTIAL_BLOB" }
    }
  }
}

In the Claude web or desktop UI, add it under Settings → Connectors → Add custom connector.

To print that config filled in for your own deployment, run:

npx google-search-console-mcp config --url https://mcp.example.com/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API
  help      Show usage

When something isn't working, run doctor first. It separates "the credentials are wrong" from "the client can't launch the server." doctor exits non-zero on a credential problem, so it also works in a health check.

The stdio command behaves differently: missing or unreadable credentials don't stop it. It starts anyway, lists its tools, and replaces its usual instructions with setup guidance, so the agent connected to it can explain the problem and walk you through the fix. Data tools return an error naming the remedy; check_setup returns the full diagnosis. A line on stderr says NOT CONFIGURED when the server comes up this way.

The commands accept these options: --credentials, --site, --read-only, --port, --host, --endpoint, --secret, --allowed-origins, --loose-headers, --no-setup-ui, --url, --terminal, and --no-browser.

Four of them are worth a note:

  • --allowed-origins takes a comma-separated list, and unset means non-browser clients only. Entries are matched case-insensitively, and a trailing slash is ignored.

  • --site sets a default property so tools can omit siteUrl. That's convenient when a deployment only ever covers one site.

  • --loose-headers relaxes the 2026-07-28 header-mirroring checks, the same as setting MCP_STRICT_HEADERS=0.

  • --no-setup-ui stops the http command serving the setup page at /setup.


Protocol support

The 2026-07-28 revision changed Streamable HTTP substantially: no initialize handshake, no sessions, no Mcp-Session-Id header, no GET stream, and per-request metadata in params._meta mirrored into HTTP headers. The official TypeScript SDK doesn't implement it yet, so the protocol layer here is hand-written and dual-era.

Client speaks

Server behavior

2026-07-28

Stateless. Validates _meta, MCP-Protocol-Version, Mcp-Method, and Mcp-Name. Answers server/discover. Results carry resultType and serverInfo.

2025-11-25 and earlier

Standard initialize handshake. No session ID is issued, because the server is stateless either way.

The era is detected per request. A request carrying modern _meta is served as modern, and an initialize selects legacy. GET and DELETE on the endpoint return 405, as the revision prescribes.

Header validation is strict by default, per the specification. When a client sends modern _meta without mirroring the headers, set MCP_STRICT_HEADERS=0 or pass --loose-headers rather than downgrading the protocol version.

On authorization. The specification's OAuth 2.1 flow assumes the server is a resource server with its own authorization server. This server instead uses the bearer token to carry your Google credentials directly. The specification permits custom strategies, and it means a hosted deployment holds no secrets and needs no user database. The tradeoff is that clients expecting automatic OAuth discovery need the header configured manually, as shown earlier.


Data caveats

Four properties of Search Console data cause most wrong conclusions. The tool descriptions and the bundled skill cover these in depth. In brief:

  1. Data lags about three days. Use lastDays and the tools pick a safe window. A range ending today shows a decline that isn't real.

  2. Query data is privacy-filtered. Grouping by query silently drops rare queries, so query-level clicks never sum to the property total. That gap isn't lost traffic.

  3. Position is inverted. Position 3 beats position 8, so a negative change is an improvement. The compare_search_analytics tool returns an explicit improved flag.

  4. Averages cancel out. Flat headline numbers routinely hide large offsetting movements. Group by page or query before concluding that nothing changed.

Quotas

Google enforces two limits that shape how you query:

  • Search analytics: about 1,200 queries per minute per property.

  • URL inspection: about 2,000 per day per property. This is the tighter of the two, so sample deliberately.

Not available through the API

Google exposes no API for the aggregate Index Coverage report, live URL testing, requesting indexing, Core Web Vitals, manual actions, security issues, links reports, or removals, so none of them are here. Per-URL inspect_url calls are the closest substitute for coverage questions.


Agent skill

The skills/google-search-console/ directory holds a ready-to-install skill that teaches an agent how to use these tools well: the preceding caveats, a diagnostic ladder for traffic changes, opportunity-finding heuristics, and a coverage-state lookup table.

cp -r skills/google-search-console ~/.claude/skills/

The same reference material is available at runtime through the server's gsc://guide/* resources, so agents without the skill installed can still read it.


Development

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally through wrangler

To check the HTTP transport by hand, start the server and send it a tools/list call:

GSC_CREDENTIALS=CREDENTIAL_BLOB npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

Troubleshooting

Symptom

Cause and fix

invalid_grant

The refresh token was revoked, or the consent screen is in Testing mode, which expires tokens after seven days. Re-run auth, and publish the app to stop it recurring.

403 insufficient permission on one property

The siteUrl value doesn't match exactly. Run list_sites and copy the string verbatim. https://example.com/ and sc-domain:example.com are different properties.

403 mentioning the API being disabled

Enable the Search Console API in the Google Cloud project that issued the credentials.

Empty list_sites result

You authenticated successfully as a Google account with no properties. You most likely picked the wrong account at the consent screen.

Traffic appears to drop sharply in the last few days

The data isn't final yet. Use lastDays.

The server connects but every data tool fails

It started without usable credentials. Ask the agent to call check_setup, or run npx google-search-console-mcp doctor in a terminal for the same diagnosis.

The agent says the server isn't configured

check_setup reports which of the three cases it is: credentials missing, unreadable, or rejected by Google. Its howToFix list is the remedy for that case.

-32020 HeaderMismatch

The client sends modern _meta without mirroring the headers. Set MCP_STRICT_HEADERS=0.


Security

  • The credential blob is your Google access. Don't commit it, and don't paste it into shared documents. Revoke it at Google Account permissions.

  • HTTP mode binds to 127.0.0.1 by default and validates Origin against ALLOWED_ORIGINS, which helps prevent DNS rebinding. Unset means no browser origin is allowed, so list them explicitly or use * to opt out of the check. The /health, /, and /setup routes are exempt, because they expose no credentialed capability.

  • The setup page is stateless. A pending authorization lives in the browser's sessionStorage, guarded by a PKCE verifier and a state value the page checks against Google's response, so the server never holds a half-finished flow. Set SETUP_UI=0 to turn the page off entirely.

  • Shared-secret comparison is length-checked and constant-time.

  • The default Worker deployment stores no credentials at all.

  • The --read-only flag and GSC_READ_ONLY=1 block sitemap mutation independently of the granted OAuth scope.

License

MIT

Available Tools

11 tools
check_setupCheck server setup and credentialsA
Read-only

Diagnose this server's configuration: whether credentials are present, whether they still work against Google, and which properties they reach. Call it when another tool fails with an authentication or permission error, when the user is setting the server up, or when the user asks why it is not working. It is the only tool that works before credentials are configured, and it returns remediation steps rather than failing. Do not call it as a warm-up before ordinary requests - list_sites already proves access.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context beyond those: it works before credentials exist and returns remediation steps instead of failing. This gives the agent a clear model of the tool's failure semantics without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the diagnosis scope first and usage conditions following. Each sentence contributes useful guidance, though the final negative instruction could arguably be merged with earlier guidance without much loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter diagnostic tool with no output schema, this description covers the key decision factors: when to call it, when not to, what it checks, why it is unique, and what it returns. There is no missing information an agent would need to invoke or route to this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 meaning. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than inventing parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Diagnose') and resource ('this server's configuration'), then enumerates exactly what it checks: credential presence, validity against Google, and property reach. It clearly differentiates from sibling tools by noting it is the only tool that works before credentials are configured.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit call conditions: after an authentication/permission error, during setup, or when the user asks why it is not working. It also states a concrete negative case—do not use it as a warm-up—and names list_sites as the correct alternative for proving access.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_search_analyticsCompare two periodsA
Read-only

Run the same search-analytics query over two periods and return per-row and total deltas. Use it for "is traffic up or down", "what lost rankings", or "which pages grew" questions.

By default the comparison period is the equal-length window immediately before the current one. Set comparison to "yearOverYear" for the same window 364 days earlier (364 rather than 365 keeps weekdays aligned), or "custom" with explicit compareStartDate and compareEndDate.

Rows are matched on their dimension values and sorted by absolute click change, so the biggest movers in either direction come first. Rows present in only one period are included, with the missing side reported as zero.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNo
limitNoHow many of the biggest movers to return. Defaults to 50.
endDateNoInclusive end date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
siteUrlNoSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
lastDaysNoShorthand for a trailing window, e.g. 28 for "the last 28 days". The window ends 3 days ago because Search Console data is not final before then. Prefer this over startDate/endDate unless you need a specific window.
rowLimitNoRows to fetch per period. Defaults to 1000.
startDateNoInclusive start date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
comparisonNoWhich period to compare against. Defaults to "previousPeriod".
dimensionsNoDimensions to group and match on. Omit to compare property-level totals only. Avoid "date" here: it makes every row unique and the comparison meaningless.
compareEndDateNoEnd of the comparison period. Required when comparison is "custom".
compareStartDateNoStart of the comparison period. Required when comparison is "custom".
dimensionFilterGroupsNoFilter groups. Filters inside a group are ANDed together; supplying multiple groups is currently equivalent to one combined AND group in the API.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing concrete behaviors: the comparison window defaults to an equal-length preceding period, yearOverYear uses 364 days to keep weekdays aligned, rows are matched on dimension values, results are sorted by absolute click change, and rows present in only one period are reported with zeroes. This is exactly the kind of behavioral detail an agent needs to interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient: three paragraphs each serve a distinct purpose — what the tool does, how the comparison period is selected, and how rows are matched and sorted. There is no filler or repetition of annotation information, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only comparison tool with no output schema, the description adequately covers input semantics, period selection, row matching, sorting, and treatment of missing rows. An agent can understand what the tool returns and how to configure it without needing additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 92%, so the schema already documents most parameters well. The description adds meaningful semantics beyond the schema: the meaning of the default comparison period, why yearOverYear uses 364 days, and the caution that using the date dimension makes comparisons meaningless. This improves parameter understanding without repeating the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Compare') and resource ('search-analytics query') and clearly states the return value ('per-row and total deltas'), which differentiates it from the single-period sibling query_search_analytics. The title and description align with the tool name, and the use-case list makes its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use cases ('is traffic up or down', 'what lost rankings', 'which pages grew') and explains the default comparison window and the three comparison modes. It does not explicitly name the alternative single-period tool or state when not to use it, but the context is clear enough that an agent can select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_sitemapRemove a sitemapA
DestructiveIdempotent

Remove a sitemap from a property. This unsubmits the sitemap from Search Console; it does not delete the file from the site and does not remove any indexed URLs. It is destructive only in that the submission history for that sitemap is lost.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
feedpathYesFull URL of the sitemap to remove, e.g. "https://example.com/sitemap.xml".

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable context by specifying that destruction is limited to loss of submission history. It also clarifies open-world effects: the sitemap file remains on the site and indexed URLs are unaffected. This exceeds what the annotations alone provide and does not contradict them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. The first sentence states the core action, while the second and third add critical caveats that prevent misuse. Each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 fully documented schema, safety annotations, and no output schema, the description covers all essential behavioral context: what the tool does, what it does not do, and the precise destructive impact. There is no meaningful gap for an agent to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents both parameters with full 100% coverage, including examples and distinctions for siteUrl. The description adds little parameter-specific meaning beyond restating the general context of a 'property' and a 'sitemap', so it does not compensate meaningfully beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Remove a sitemap from a property') and then clarifies the actual behavior: it unsubmits from Search Console rather than deleting the file or indexed URLs. This distinguishes it clearly from sibling tools like submit_sitemap or list_sitemaps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context by explaining what the tool does and does not do: it unsubmits a sitemap, does not delete the site file, and does not remove indexed URLs. This acts as an implicit usage boundary, though it does not explicitly name alternative sibling tools or provide a direct 'use when...' condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_siteGet one propertyA
Read-only

Fetch a single Search Console property and the permission level the authenticated account holds on it. Useful to confirm access before a longer sequence of calls; list_sites is usually more efficient.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations by explaining the tool returns the authenticated account's permission level and is appropriate for pre-flight access confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The primary action is front-loaded, and the usage guidance and alternative are clearly separated without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one fully documented parameter, read-only annotations, and no output schema, the description provides sufficient context: what is fetched, what information is returned, when to use it, and when to prefer an alternative. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter is fully documented in the input schema. The description adds no additional parameter-level details, so the baseline score of 3 is appropriate; the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch'), names the exact resource ('a single Search Console property'), and states the returned information (permission level). It also distinguishes itself from the sibling list_sites by emphasizing it returns the permission level for one property.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends when to use this tool ('useful to confirm access before a longer sequence of calls') and names the more efficient alternative ('list_sites is usually more efficient'). This gives an agent clear decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sitemapGet one sitemapA
Read-only

Fetch details for a single submitted sitemap: when it was last submitted and downloaded, whether processing is still pending, its type, and how many URLs were submitted versus indexed per content type. Treat the indexed counts as a lower bound - Google has long under-reported them here.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
feedpathYesFull URL of the sitemap, e.g. "https://example.com/sitemap.xml". Must match a path returned by `list_sitemaps`.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description is consistent with readOnlyHint=true, framing the operation as a fetch. It goes beyond annotations by adding the important caveat that indexed counts are under-reported by Google and should be treated as a lower bound. This gives the agent useful reliability context that the annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. The first sentence front-loads the operation and the returned fields, and the second adds a high-value caveat. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values, and it does so by listing the key fields returned and adding the data-reliability caveat. It may not describe error behavior or exact response formatting, but for a simple read-only fetch tool with rich schema descriptions, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are already richly documented in the schema: siteUrl explains URL-prefix vs domain properties, and feedpath gives an example and requires a path from list_sitemaps. The description adds little to parameter understanding beyond referencing 'per content type,' which relates more to the output than the inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch details') and resource ('a single submitted sitemap'), then enumerates exactly what information is returned: submission/download times, processing state, type, and submitted vs indexed URL counts. This clearly distinguishes it from siblings like list_sitemaps (listing), submit_sitemap (creating), and delete_sitemap (removing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'single submitted sitemap' implies this is for retrieving details about one already-submitted sitemap, and the schema requires feedpath to match a path from list_sitemaps. However, the description itself does not explicitly state when to use this tool instead of alternatives or mention any exclusions, leaving the agent to infer routing from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_urlInspect a URL in the indexA
Read-only

Inspect one URL as Google sees it: whether it is indexed, its coverage state, robots.txt status, last crawl time, the canonical Google chose versus the one you declared, which sitemaps reference it, plus AMP, mobile-usability and rich-results verdicts where applicable.

This is the tool for "why is this page not indexed" questions. Read indexStatusResult.coverageState first: it carries the specific reason, such as "Crawled - currently not indexed", "Discovered - currently not indexed", or "Duplicate without user-selected canonical".

Quota is roughly 2000 inspections per property per day, so inspect a considered sample rather than every URL. The URL must belong to the property being inspected. Results describe the indexed version only - this API cannot run the live test that the Search Console UI offers.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
languageCodeNoBCP-47 code for human-readable messages. Defaults to "en-US".
inspectionUrlYesFully-qualified URL to inspect. Must be under the property, e.g. "https://example.com/pricing".

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important operational behavior: the rough quota, that results describe the indexed version only, that it cannot run the live test offered in the UI, and that the inspected URL must belong to the property. It also tells the agent which field to read first when diagnosing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all information-dense and free of filler. The most distinguishing information is front-loaded, followed by the use case, quota caveat, and limitation. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description names the critical return field (indexStatusResult.coverageState), gives example values, lists the categories of results, and covers quota, scoping, and the live-test limitation. This is sufficient context for an agent to invoke the tool correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline applies: the schema already documents siteUrl, inspectionUrl, and languageCode. The description adds one useful constraint ('The URL must belong to the property being inspected') but does not significantly extend parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Inspect one URL as Google sees it,' and enumerates the concrete result areas (coverage state, robots.txt, crawl time, canonicals, sitemaps, AMP, mobile usability, rich results). The phrase 'one URL' distinguishes it from the sibling inspect_urls without needing to open the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit use case: 'This is the tool for "why is this page not indexed" questions,' and adds quota-based sampling guidance. It does not name alternatives or state when not to use it, but the intended context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_urlsInspect several URLsA
Read-only

Inspect up to 25 URLs in one call, run concurrently, returning a compact per-URL summary plus a count of how many URLs fell into each coverage state. Use it to audit a set of pages - for example the top landing pages from query_search_analytics, or URLs listed in a sitemap.

Failures are reported per URL rather than aborting the batch, so one bad URL will not cost you the rest of the results. Each URL consumes one unit of the roughly 2000/day per-property inspection quota.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
languageCodeNoBCP-47 code. Defaults to "en-US".
inspectionUrlsYesFully-qualified URLs to inspect. All must belong to the property.

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond the annotations: concurrent execution, per-URL failure handling rather than whole-batch abortion, and quota consumption of roughly 2000/day per property. This is exactly the kind of operational behavior an agent needs to know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise and front-loaded with the most important facts: batch size, concurrency, output shape, and usage examples. The second paragraph adds valuable failure and quota details without excessive padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core invocation requirements, return shape at a high level, failure behavior, and quota implications. It does not enumerate exact response fields, but for a batch inspection tool with a clear purpose and well-described schema, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces the 25-URL limit and mentions that all URLs must belong to the property, but it does not add meaning beyond the schema's existing field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool inspects up to 25 URLs in one call, runs concurrently, and returns a per-URL summary plus coverage-state counts. It is immediately distinguishable from the singular sibling `inspect_url` by its batch orientation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage context: auditing sets of pages, such as top landing pages from `query_search_analytics` or URLs from a sitemap. It does not explicitly state when to prefer `inspect_url` over this tool, but the batch purpose is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sitemapsList sitemapsA
Read-only

List the sitemaps submitted for a property, with submission and download timestamps, error and warning counts, and per-content-type submitted and indexed counts. Pass sitemapIndex to list the child sitemaps inside a sitemap index file instead of the top-level submissions.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
sitemapIndexNoFull URL of a sitemap index file. When set, returns the sitemaps listed inside that index rather than the property own submissions.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint and openWorldHint annotations already cover the safety and external-state aspects. The description adds meaningful behavioral detail by stating exactly what the tool returns—timestamps, error/warning counts, and per-content-type counts—and how sitemapIndex changes the result set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundant filler, and the primary purpose is front-loaded. The second sentence earns its place by explaining the optional parameter behavior without repeating schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with two parameters and no output schema, the description provides enough information about return contents and the special sitemapIndex behavior. Annotations cover safety, and the schema covers parameter formats, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters, so the schema carries the parameter documentation burden. The description largely restates the sitemapIndex behavior already in the schema, adding only the phrase 'child sitemaps' and 'top-level submissions' as clarifying vocabulary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List the sitemaps submitted for a property,' and further specifies the returned metadata (timestamps, counts, per-content-type values). It also clarifies the sitemapIndex variant, which distinctively separates top-level listing from child-sitemap listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states the main use case and explicitly explains when to pass sitemapIndex to list child sitemaps instead of top-level submissions. It does not name alternative sibling tools like get_sitemap or submit_sitemap, but the context is clear and the parameter guidance is practical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sitesList Search Console propertiesA
Read-only

List every Search Console property the authenticated account can access, with its permission level. Call this first in any session: the exact siteUrl strings it returns are required by every other tool, and permission level tells you what you can do (siteOwner and siteFullUser can read analytics and manage sitemaps; siteRestrictedUser has limited read access; siteUnverifiedUser cannot read data).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context about the output including permission levels and downstream dependency on siteUrl. It does not discuss pagination or potential response size, but openWorldHint partially covers the open-ended nature of the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver a clear purpose statement and high-value usage guidance without redundancy. The critical 'call this first' instruction is front-loaded and the permission details are compactly organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with no output schema, the description fully explains what is returned (properties with permission levels), why it matters (siteUrl needed by other tools), and how to interpret permission levels. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4 and there is no parameter semantics burden on the description. The description adds no parameter detail, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('every Search Console property the authenticated account can access'), and it clarifies that the result includes permission levels. This clearly distinguishes it from sibling tools like get_site, which presumably targets a single property.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs the agent to 'Call this first in any session' and explains that the returned siteUrl strings are required by every other tool. It also maps permission levels to capabilities, giving concrete guidance on what actions are possible for each role.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_search_analyticsQuery search performance dataA
Read-only

Query clicks, impressions, CTR and average position from the Search Console Performance report - the core tool for all traffic and ranking analysis.

Group by one or more dimensions (query, page, country, device, searchAppearance, date, hour). Rows come back sorted by clicks descending, and only rows with data are returned. Omitting dimensions returns a single totals row for the whole property.

Behaviours worth planning around:

  • Data is final only up to about 3 days ago; use lastDays to get a safe window automatically.

  • Grouping by query triggers privacy filtering: rare queries are omitted entirely, so query-level clicks will not sum to the property total. Never present that gap as lost traffic.

  • Combining page and query is capped harder than either alone, so expect fewer rows than you might predict.

  • rowLimit maxes at 25000 per call; page with startRow for more.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoSearch surface. Defaults to "web". "discover" and "googleNews" support only a limited set of dimensions and have no query dimension at all.
endDateNoInclusive end date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
siteUrlNoSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
lastDaysNoShorthand for a trailing window, e.g. 28 for "the last 28 days". The window ends 3 days ago because Search Console data is not final before then. Prefer this over startDate/endDate unless you need a specific window.
rowLimitNoRows to return, 1-25000. Defaults to 1000.
startRowNoZero-based offset for pagination. Defaults to 0.
dataStateNo"final" (default) returns only finalised data. "all" includes fresh, still-changing data for the most recent days. "hourly_all" is required when using the "hour" dimension.
startDateNoInclusive start date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
dimensionsNoGroup results by these dimensions, in order. Omit for property-level totals. "date" gives a time series; "hour" requires dataState "hourly_all" and only covers roughly the last 10 days.
aggregationTypeNoHow to aggregate. Leave as "auto" unless you specifically need byPage or byProperty; changing it changes what a click counts as.
dimensionFilterGroupsNoFilter groups. Filters inside a group are ANDed together; supplying multiple groups is currently equivalent to one combined AND group in the API.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond that: data finality lag, query-level privacy filtering, row limits, the cap on combining page and query, sorted output, and omission of empty rows. No contradiction exists between the description and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then gives grouping and return behavior, then uses a compact bulleted list for the most important planning caveats. Every sentence carries useful information and the structure makes the caveats scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no output schema, the description covers the key behavioral gaps an agent needs before calling it: what is returned, how default totals work, data freshness, privacy filtering, expected row counts, and pagination. The remaining parameter details are already well documented in the input schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: sorting by clicks descending, only returning rows with data, the privacy-filtering effect of grouping by query, the harder cap when combining page and query, and pagination guidance for rowLimit/startRow. It does not cover every parameter, but the schema already does.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: querying clicks, impressions, CTR, and average position from the Search Console Performance report. It also names the available dimensions and distinguishes its role as the core traffic and ranking analysis tool, making its purpose immediately identifiable relative to siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: how to get totals, how to group, how to paginate, and why to use lastDays for a safe data window. It does not explicitly name alternatives like compare_search_analytics or state when not to use this tool, so it stops short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_sitemapSubmit a sitemapA
Idempotent

Submit or resubmit a sitemap for a property. Resubmitting an existing sitemap is a safe way to nudge Google into re-downloading it after content changes. The sitemap must already be reachable at the given URL and must live under the property. Returns no data on success; call get_sitemap afterwards to check processing status.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteUrlYesSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
feedpathYesFull URL of the sitemap to submit, e.g. "https://example.com/sitemap.xml".

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds value beyond annotations by explaining that resubmission is a safe nudge, that the sitemap must already be reachable, and that no data is returned on success. It also directs the caller to get_sitemap for status, which is useful behavioral context not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three focused sentences with no wasted words. The core action is front-loaded, and each sentence contributes essential information: what the tool does, when resubmission is useful, prerequisites, and expected return behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 fully covers what an agent needs: prerequisites, behavior, and follow-up action. It even preempts confusion about the empty response by telling the agent to check get_sitemap afterward.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with strong parameter descriptions containing examples and format guidance. The description adds further meaning by specifying that the sitemap must be reachable and must live under the property, which clarifies feedpath requirements beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (submit or resubmit), the resource (sitemap), and the target context (a property). It clearly differentiates from siblings like get_sitemap, list_sitemaps, and delete_sitemap by naming the operation and its resubmission role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for when to use it, including resubmitting after content changes and the prerequisites that the sitemap must be reachable and under the property. It does not explicitly exclude alternatives like list_sitemaps or get_sitemap, but the guidance is sufficient for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv1.0.0
    • First observedcheck_setup
    • First observedcompare_search_analytics
    • First observeddelete_sitemap
    • First observedget_site
    • First observedget_sitemap
    • First observedinspect_url
    • First observedinspect_urls
    • First observedlist_sitemaps
    • First observedlist_sites
    • First observedquery_search_analytics
    • First observedsubmit_sitemap

TDQS

A4.4/5.0

Scored across 11 tools

Disambiguation5/5

Each tool maps to a distinct resource or action: sites, analytics, sitemaps, URL inspection, and setup. The only close pairs are list/get for sites and sitemaps plus inspect_url/inspect_urls, but plural vs. singular and single vs. batch behavior make them unambiguous.

Naming Consistency5/5

Tool names consistently follow a verb_noun pattern with snake_case throughout: list_sites, get_site, submit_sitemap, inspect_url, check_setup. Plural and singular forms match the tool's behavior, so the naming convention is predictable and coherent.

Tool Count5/5

Eleven tools is well-scoped for the Google Search Console domain. Each tool covers a meaningful capability without bloating the surface, and the count aligns with the major API areas: sites, analytics, sitemaps, URL inspection, and configuration.

Completeness4/5

The set covers the primary Search Console workflows well: property listing, search analytics with comparison, full sitemap lifecycle, and single/batch URL inspection. Minor gaps exist such as adding or deleting properties and deeper permission management, but these are not core to typical agent use and can be worked around.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    MCP server for Google Search Console, enabling querying search analytics, URL inspection, sitemap management, and more via natural language.
    260
    1
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    A lightweight, fast MCP server for Google Search Console. Query search analytics, manage sitemaps, and inspect URLs directly from your AI assistant.
    7
    Apache 2.0
  • A
    license
    A
    quality
    B
    maintenance
    MCP server for Google Search Console, enabling querying search performance, listing properties, and inspecting URL indexing status from MCP-compatible clients.
    4
    14
    1
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Self-hosted MCP server for Google Search Console. Enables natural language queries to list sites, analyze search analytics, inspect URLs, and check sitemaps through AI assistants.
    MIT