google-search-console-mcp
Google Search Console MCP
Google Search Console API용 MCP 서버 — 검색 실적 데이터, URL 색인 상태, 사이트맵 관리 및 속성 목록.
하나의 코드베이스에서 세 가지 방식으로 실행됩니다: stdio(로컬, npx 사용), Streamable HTTP(자체 호스팅), Cloudflare Workers(URL에서 호스팅). MCP 2026-07-28을 구현하며 2025-11-25, 2025-06-18, 2025-03-26으로 자동 폴백하므로 프로토콜 변경 양쪽의 클라이언트에서 모두 작동합니다.
런타임 의존성 제로.
빠른 시작
npx google-search-console-mcp authGoogle OAuth 클라이언트 생성 과정을 안내하고, 동의 흐름을 실행하며, 라이브 API에 대해 자격 증명을 검증하고, MCP 클라이언트에 붙여넣을 수 있는 구성 블록을 출력합니다. 3분이면 되고, 대부분은 Google Cloud UI를 기다리는 시간입니다.
그런 다음 출력된 JSON을 클라이언트 구성에 넣고 다시 시작하세요.
Related MCP server: searchconsole-mcp
도구
Search Console API v1의 모든 메서드와 두 가지 복합 도구입니다.
도구 | 기능 | API 메서드 |
| 접근 가능한 모든 속성과 권한 수준 |
|
| 하나의 속성과 그에 대한 권한 |
|
| 클릭, 노출, CTR, 위치 — 그룹화, 필터링, 페이지네이션 |
|
| 두 기간의 행별 및 전체 증감 | 복합 |
| 제출된 사이트맵 또는 사이트맵 인덱스의 하위 항목 |
|
| 하나의 사이트맵 상태와 제출/색인 수 |
|
| 사이트맵 제출 또는 재제출 |
|
| 사이트맵 제출 취소 |
|
| 하나의 URL에 대한 전체 색인 상태 |
|
| 최대 25개 URL을 동시에, 적용 상태 요약 포함 | composite |
사이트 인증과 sites.add/sites.delete는 의도적으로 노출하지 않습니다. 속성 추가 및 인증은 브라우저 흐름으로, 에이전트 도구에 들어맞지 않습니다.
서버는 또한 에이전트가 필요할 때 읽을 수 있는 프롬프트(performance_review, indexing_audit, query_opportunities, sitemap_health)와 리소스(gsc://guide/search-analytics, gsc://guide/url-inspection, gsc://guide/sitemaps)를 제공합니다.
인증
1단계 — Google OAuth 클라이언트 만들기
이 작업은 한 번만 하면 됩니다. 서버가 대신 해줄 수 없습니다. Google은 콘솔에서 사람이 필요하기 때문입니다.
Google Cloud Console을 열고 프로젝트를 선택하거나 만듭니다.
해당 프로젝트에서 Search Console API를 사용 설정합니다.
OAuth 동의 화면을 구성합니다. 개인용으로는 외부로 해도 됩니다. 테스트 사용자에 자신의 Google 계정을 추가하세요.
사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID로 이동합니다. 애플리케이션 유형은 데스크톱 앱을 선택합니다.
클라이언트 ID와 클라이언트 비밀번호를 복사합니다.
테스트 vs 게시. 동의 화면이 테스트 상태인 동안 Google은 7일 후에 새로고침 토큰을 만료시키므로 매주
auth를 다시 실행해야 합니다. 앱을 게시하면(동의 화면 → 앱 게시) 토큰이 지속됩니다. 단일 사용자 내부 도구의 경우webmasters범위만 유지하면 게시는 안전하며 Google의 검증 검토가 필요하지 않습니다.
2단계 — 설정 흐름 실행
npx google-search-console-mcp auth127.0.0.1에서 제공되는 작은 설정 페이지가 열립니다. 클라이언트 ID와 비밀번호를 붙여넣고 전체 또는 읽기 전용 액세스를 선택하면 동의 흐름을 실행하고, 코드(PKCE)를 새로고침 토큰으로 교환하며, list_sites를 호출하여 자격 증명이 작동하는지 확인합니다. 자격 증명이 도달할 수 있는 정확한 속성을 보여줍니다.
마지막 페이지에는 자격 증명 블롭과 Claude Desktop, Claude Code, 원격 배포용으로 붙여넣을 수 있는 구성이 각각 복사 버튼과 함께 표시됩니다. 동일한 값은 대체 수단으로 터미널에도 출력됩니다.
헤드리스 머신이나 SSH를 통한 경우 프롬프트 기반 버전인 auth --terminal을 대신 사용하세요.
자격 증명 블롭을 받게 됩니다. 클라이언트 ID, 클라이언트 비밀번호, 새로고침 토큰이 포함된 base64url 인코딩 JSON입니다:
eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…블롭을 비밀번호처럼 취급하세요. 이 블롭을 가진 사람은 myaccount.google.com/permissions에서 해지할 때까지 Search Console에 접근할 수 있습니다.
단일 불투명 문자열로 존재하므로 하나의 값에 서버가 필요한 모든 것이 담깁니다. 디스크의 자격 증명 파일 없이 환경 변수나 Authorization 헤더에 바로 넣을 수 있습니다.
OAuth 흐름의 대안
서비스 계정. CI 및 팀 소유 속성에 유용합니다. Google Cloud에서 계정을 만든 다음, Search Console의 속성(설정 → 사용자 및 권한)에서 client_email을 사용자로 추가하세요. 다운로드한 키 파일을 직접 인코딩하세요:
base64 -i service-account.json | tr -d '\n'서버는 raw 서비스 계정 키를 블롭으로 허용합니다. 래퍼가 필요 없습니다.
기존 액세스 토큰. {"type":"access_token","access_token":"ya29..."}로 설정합니다. 새로고침이 불가능하므로 단기 스크립트에만 적합합니다.
범위
범위 | 부여 권한 |
| 사이트맵 제출/삭제를 제외한 모든 것 |
| 전체 액세스 (기본값) |
auth 중에 읽기 전용을 선택하면 더 좁은 범위를 요청합니다. 서버의 --read-only는 별도의 이중 안전 장치로, 변경 도구가 API에 도달하기 전에 거부합니다.
실행
로컬 (stdio)
auth가 출력한 구성:
{
"mcpServers": {
"google-search-console": {
"command": "npx",
"args": ["-y", "google-search-console-mcp"],
"env": { "GSC_CREDENTIALS": "<your blob>" }
}
}
}구성 파일 위치:
클라이언트 | 경로 |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Claude Code |
|
Cursor |
|
VS Code |
|
매번 npx를 거치지 않으려면 제대로 설치하세요:
npm install -g google-search-console-mcp자체 호스팅 HTTP
GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787POST http://127.0.0.1:8787/mcp를 제공합니다. 기본적으로 루프백에 바인딩됩니다. 노출하려면 의도적으로 --host 0.0.0.0을 전달하고, 노출한다면 TLS를 앞에 두세요.
브라우저 기반 클라이언트는 이름을 지정하지 않으면 거부됩니다. 자체 자격 증명을 보유한 서버는 방문하는 모든 페이지에서 구동될 수 있기 때문입니다. 일반 MCP 클라이언트는 Origin을 보내지 않으므로 영향을 받지 않습니다. 브라우저 클라이언트는 origin을 나열해야 합니다:
npx google-search-console-mcp http --allowed-origins http://localhost:6274 # MCP Inspector거부된 origin은 브라우저가 읽을 수 없는 403을 받습니다(설계상 거부 시 CORS 헤더가 없음), 따라서 일반적인 CORS 오류로 표시됩니다. 브라우저 클라이언트가 연결되지 않으면 서버의 Origins: 시작 줄을 확인하세요. --allowed-origins '*'는 검사를 비활성화합니다.
Cloudflare Workers
git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy엔드포인트는 https://google-search-console-mcp.<subdomain>.workers.dev/mcp입니다.
기본적으로 Worker는 비밀을 저장하지 않습니다. 각 클라이언트는 자체 자격 증명 블롭을 bearer 토큰으로 보내므로 공유 배포는 누구의 Google 자격 증명도 보유하지 않으며, 같은 URL의 다른 사용자는 자신의 속성만 볼 수 있습니다.
대신 프라이빗 단일 테넌트 배포를 원한다면:
npx wrangler secret put GSC_CREDENTIALS # your blob
npx wrangler secret put MCP_SHARED_SECRET # token clients must present클라이언트는 블롭 대신 공유 비밀을 보냅니다.
wrangler.jsonc의 선택적 vars:
변수 | 효과 |
| 서비스할 경로. 기본값 |
|
|
| 쉼표로 구분된 브라우저 origin. 미설정 = 비브라우저 클라이언트만; |
|
|
원격 서버에 클라이언트 연결
{
"mcpServers": {
"google-search-console": {
"type": "http",
"url": "https://your-worker.workers.dev/mcp",
"headers": { "Authorization": "Bearer <your blob>" }
}
}
}Claude 웹 또는 데스크톱 UI에서 설정 → 커넥터 → 사용자 지정 커넥터 추가 아래에 추가하세요.
자신의 배포에 맞게 채워서 출력하세요:
npx google-search-console-mcp config --url https://your-worker.workers.dev/mcpCLI
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 APIdoctor는 문제가 있을 때 가장 먼저 사용하는 도구입니다. "자격 증명이 잘못됨"과 "클라이언트가 서버를 시작할 수 없음"을 구분해 줍니다.
옵션: --credentials <blob>, --site <siteUrl>, --read-only, --port, --host, --endpoint, --secret, --allowed-origins, --url, --terminal, --no-browser.
--allowed-origins는 쉼표로 구분된 목록을 받습니다. 미설정이면 비브라우저 클라이언트만 허용합니다. 항목은 대소문자를 구분하지 않고 일치되며 끝의 슬래시는 무시됩니다.
--site는 기본 속성을 설정하여 도구가 siteUrl을 생략할 수 있게 합니다. 배포가 하나의 사이트만 다루는 경우에 편리합니다.
프로토콜 지원
2026-07-28 개정판은 Streamable HTTP를 크게 변경했습니다: initialize 핸드셰이크 없음, 세션 없음, Mcp-Session-Id 없음, GET 스트림 없음, params._meta의 요청별 메타데이터가 HTTP 헤더로 미러링됩니다. 공식 TypeScript SDK는 아직 이를 구현하지 않으므로 여기의 프로토콜 계층은 손으로 작성되었으며 이중 시대를 지원합니다.
클라이언트가 지원하는 버전 | 서버 동작 |
| 무상태. |
| 표준 |
시대는 요청별로 감지됩니다. 최신 _meta를 담은 요청은 최신으로 처리되고, initialize는 레거시를 선택합니다. 엔드포인트의 GET 및 DELETE는 개정판이 규정한 대로 405를 반환합니다.
헤더 검증은 기본적으로 사양에 따라 엄격합니다. 클라이언트가 헤더를 미러링하지 않고 최신 _meta를 보내는 경우 다운그레이드 대신 MCP_STRICT_HEADERS=0(또는 --loose-headers)을 설정하세요.
인증에 관하여: 스펙의 OAuth 2.1 흐름은 서버가 자체 인증 서버를 둔 리소스 서버라고 가정합니다. 그러나 이 서버는 베어러 토큰을 사용하여 Google 자격 증명을 직접 전달합니다 — 스펙은 사용자 정의 전략을 허용하며, 이는 호스팅 배포가 비밀을 보관하지 않고 사용자 데이터베이스가 필요 없음을 의미합니다. 그 대가로 자동 OAuth 검색을 기대하는 클라이언트는 위에 표시된 대로 헤더를 수동으로 구성해야 합니다.
데이터 다루기
Search Console 데이터의 네 가지 속성 때문에 대부분의 잘못된 결론이 나옵니다. 도구 설명과 번들된 스킬이 이를 자세히 다루며, 간단히 요약하면:
데이터는 약 3일 지연됩니다.
lastDays를 사용하면 도구가 안전한 기간을 선택합니다. 오늘로 끝나는 범위는 가짜 하락을 보여줍니다.쿼리 데이터는 개인정보 보호 필터링됩니다.
query로 그룹화하면 드문 쿼리가 조용히 누락되므로 쿼리 수준 클릭 수는 속성 합계와 일치하지 않습니다. 그 차이는 손실된 트래픽이 아닙니다.위치는 반전됩니다. 위치 3이 위치 8보다 낫습니다. 음수 변화는 개선입니다.
compare_search_analytics는 명시적인improved플래그를 반환합니다.평균은 상쇄됩니다. 평평한 헤드라인 수치는 큰 상쇄 움직임을 일상적으로 숨깁니다. 아무것도 변하지 않았다고 결론 내리기 전에 페이지 또는 쿼리별로 그룹화하세요.
할당량
검색 분석: 속성당 분당 약 1,200개 쿼리.
URL 검사: 속성당 하루 약 2,000개 — 제약 조건입니다. 의도적으로 샘플링하세요.
API로 사용할 수 없는 것
집계 색인 적용 범위 보고서, 실시간 URL 테스트, 색인 요청, Core Web Vitals, 수동 조치, 보안 문제, 링크 보고서 및 제거는 API에 해당하는 기능이 없으므로 여기에 없습니다. URL별 inspect_url이 적용 범위 질문에 대한 가장 가까운 대안입니다.
에이전트 스킬
skills/google-search-console/은 에이전트가 이러한 도구를 잘 사용하도록 가르치는 즉시 설치 가능한 스킬입니다 — 위의 함정들, 트래픽 변화를 위한 진단 사다리, 기회 발견 휴리스틱, 그리고 적용 범위 상태 조회 테이블이 포함됩니다.
cp -r skills/google-search-console ~/.claude/skills/동일한 참고 자료는 런타임에 서버의 gsc://guide/* 리소스를 통해 제공되므로 스킬이 설치되지 않은 에이전트도 읽을 수 있습니다.
개발
npm install
npm run build # compile to dist/
npm run typecheck
npm test
npm run cf:dev # Worker locally via wranglerHTTP 전송에 대한 빠른 수동 확인:
GSC_CREDENTIALS=<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'문제 해결
증상 | 원인 및 해결 방법 |
| 새로 고침 토큰이 취소되었거나 동의 화면이 테스트 모드(7일 만료)입니다. |
한 속성에 대한 |
|
API가 비활성화되었다는 | 자격 증명을 발급한 Google Cloud 프로젝트에서 Search Console API를 활성화하세요. |
빈 | 속성이 없는 Google 계정으로 인증에 성공했습니다. 동의 화면에서 잘못된 계정을 선택했을 가능성이 높습니다. |
최근 며칠 동안 트래픽이 절벽에서 떨어진 것처럼 보임 | 데이터가 아직 확정되지 않았습니다. |
Claude Desktop에서 서버가 시작되지 않음 | 터미널에서 |
| 클라이언트가 헤더를 미러링하지 않고 최신 |
보안
자격 증명 블롭은 Google 액세스 권한입니다. 커밋하지 말고 공유 문서에 붙여넣지 마세요. myaccount.google.com/permissions에서 취소하세요.
HTTP 모드는 기본적으로
127.0.0.1에 바인딩되고 DNS 리바인딩을 차단하기 위해ALLOWED_ORIGINS에 대해Origin을 검증합니다. 설정하지 않으면 브라우저 출처가 허용되지 않습니다 — 명시적으로 나열하거나*를 사용하여 검사를 거부하세요./health와/는 예외이며 자격 증명이 필요한 기능을 노출하지 않습니다.공유 비밀 비교는 길이 검사와 상수 시간 비교를 사용합니다.
기본 Worker 배포는 자격 증명을 전혀 저장하지 않습니다.
--read-only/GSC_READ_ONLY=1은 부여된 OAuth 범위와 독립적으로 사이트맵 변경을 차단합니다.
라이선스
MIT
Available Tools
11 toolscheck_setupCheck server setup and credentialsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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 periodsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | How many of the biggest movers to return. Defaults to 50. | |
| endDate | No | Inclusive end date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set. | |
| siteUrl | No | Search 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. | |
| lastDays | No | Shorthand 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. | |
| rowLimit | No | Rows to fetch per period. Defaults to 1000. | |
| startDate | No | Inclusive start date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set. | |
| comparison | No | Which period to compare against. Defaults to "previousPeriod". | |
| dimensions | No | Dimensions to group and match on. Omit to compare property-level totals only. Avoid "date" here: it makes every row unique and the comparison meaningless. | |
| compareEndDate | No | End of the comparison period. Required when comparison is "custom". | |
| compareStartDate | No | Start of the comparison period. Required when comparison is "custom". | |
| dimensionFilterGroups | No | Filter groups. Filters inside a group are ANDed together; supplying multiple groups is currently equivalent to one combined AND group in the API. |
TDQS
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.
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.
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.
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.
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.
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 sitemapADestructiveIdempotent
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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| feedpath | Yes | Full URL of the sitemap to remove, e.g. "https://example.com/sitemap.xml". |
TDQS
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.
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.
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.
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.
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.
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 propertyARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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
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.
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.
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.
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.
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.
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 sitemapARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| feedpath | Yes | Full URL of the sitemap, e.g. "https://example.com/sitemap.xml". Must match a path returned by `list_sitemaps`. |
TDQS
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.
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.
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.
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.
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.
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 indexARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| languageCode | No | BCP-47 code for human-readable messages. Defaults to "en-US". | |
| inspectionUrl | Yes | Fully-qualified URL to inspect. Must be under the property, e.g. "https://example.com/pricing". |
TDQS
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.
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.
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.
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.
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.
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 URLsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| languageCode | No | BCP-47 code. Defaults to "en-US". | |
| inspectionUrls | Yes | Fully-qualified URLs to inspect. All must belong to the property. |
TDQS
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.
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.
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.
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.
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.
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 sitemapsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| sitemapIndex | No | Full URL of a sitemap index file. When set, returns the sitemaps listed inside that index rather than the property own submissions. |
TDQS
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.
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.
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.
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.
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.
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 propertiesARead-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).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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 dataARead-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
lastDaysto get a safe window automatically.Grouping by
querytriggers 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
pageandqueryis capped harder than either alone, so expect fewer rows than you might predict.rowLimitmaxes at 25000 per call; page withstartRowfor more.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Search surface. Defaults to "web". "discover" and "googleNews" support only a limited set of dimensions and have no query dimension at all. | |
| endDate | No | Inclusive end date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set. | |
| siteUrl | No | Search 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. | |
| lastDays | No | Shorthand 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. | |
| rowLimit | No | Rows to return, 1-25000. Defaults to 1000. | |
| startRow | No | Zero-based offset for pagination. Defaults to 0. | |
| dataState | No | "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. | |
| startDate | No | Inclusive start date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set. | |
| dimensions | No | Group 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. | |
| aggregationType | No | How to aggregate. Leave as "auto" unless you specifically need byPage or byProperty; changing it changes what a click counts as. | |
| dimensionFilterGroups | No | Filter groups. Filters inside a group are ANDed together; supplying multiple groups is currently equivalent to one combined AND group in the API. |
TDQS
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.
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.
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.
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.
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.
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 sitemapAIdempotent
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.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Search 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. | |
| feedpath | Yes | Full URL of the sitemap to submit, e.g. "https://example.com/sitemap.xml". |
TDQS
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.
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.
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.
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.
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.
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.
11 tool updates
v1.0.0- First observed
check_setup - First observed
compare_search_analytics - First observed
delete_sitemap - First observed
get_site - First observed
get_sitemap - First observed
inspect_url - First observed
inspect_urls - First observed
list_sitemaps - First observed
list_sites - First observed
query_search_analytics - First observed
submit_sitemap
TDQS
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Read-only Google Search Console MCP server for AI assistants.
Google Search Console, GA4 and PageSpeed MCP server for Claude, ChatGPT and Cursor. Free, hosted.
Hosted, read-only Google Search Console MCP: performance, comparisons, URL inspection, sitemaps.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for Google Search Console, enabling querying search analytics, URL inspection, sitemap management, and more via natural language.31,535 npm3MIT
- AlicenseAqualityDmaintenanceA lightweight, fast MCP server for Google Search Console. Query search analytics, manage sitemaps, and inspect URLs directly from your AI assistant.7Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for Google Search Console, enabling querying search performance, listing properties, and inspecting URL indexing status from MCP-compatible clients.418 npm1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceSelf-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