Allows querying Google Search Console data for verified properties, including top queries and pages, daily performance trends for clicks, impressions, CTR, and average position, period comparisons, quick-win opportunities, dropped pages, and URL Inspection status.
Integrates Stripe for subscription billing, enabling Checkout for monthly or yearly plans and webhook handling for subscription status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Rank by Ouroboros show my top Google Search queries from the last 28 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Rank by Ouroboros answers SEO questions from the Google Search Console account you connect. It is for site owners, bloggers, small businesses, and SEO freelancers who want those numbers inside ChatGPT, Claude, Gemini, Grok, Cursor, or any other MCP client that speaks Streamable HTTP and OAuth.
The assistant can list verified properties, read top queries and pages, follow clicks, impressions, CTR, and average position over time, compare two periods, find queries with high impressions and low CTR, see pages that dropped, and check URL Inspection status. Every metric comes from the Search Console API response. Rank does not estimate traffic or fill in days the API left out. CTR stays the fraction Search Console returned (0.02 is 2%).
A 14-day trial starts when you connect Google. After that, Pro is a Stripe subscription. The amount is shown at Stripe Checkout, not in this README or the product.
The MCP address is https://YOUR_HOST/mcp after deploy, or http://127.0.0.1:44721/mcp when you run it locally. Choose OAuth and leave the client id and secret empty. Rank supports dynamic client registration and PKCE.
Cursor, in ~/.cursor/mcp.json:
{
"mcpServers": {
"rank": {
"url": "http://127.0.0.1:44721/mcp"
}
}
}Claude Code:
claude mcp add --transport http rank http://127.0.0.1:44721/mcpUse the same URL for ChatGPT, Claude, Gemini, and Grok. The in-app connect page repeats these steps for the host in APP_BASE_URL.
Related MCP server: Google Search Console MCP Server
list_properties — verified Search Console properties
top_queries — queries for a date range
top_pages — pages for a date range
performance_trends — daily clicks, impressions, CTR, and position
compare_periods — totals for two ranges, plus differences labeled as derived from those totals
quick_wins — queries at or above an impression threshold and at or below a CTR threshold
dropped_pages — pages whose position worsened, whose clicks fell, or that disappeared from the current response
inspect_url — URL Inspection API result
account_status — whether Google is connected and whether the trial or Pro subscription is active
If you omit dates, Rank uses a 28-day window ending three UTC days ago and says so in the result. Pass startDate and endDate (YYYY-MM-DD) to choose the window.
Create an OAuth client of type Web application. Rank reads:
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
Authorized redirect URI, exactly, with no trailing slash on the origin:
${APP_BASE_URL}/google/callbackLocally, with the default APP_BASE_URL, that is:
http://127.0.0.1:44721/google/callbackAdd these scopes on the OAuth consent screen:
openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/webmasters.readonly
webmasters.readonly is the Search Console read-only scope. Rank requests offline access so Google returns a refresh token. The refresh token is encrypted before it is stored. TOKEN_ENCRYPTION_KEY is the key (a long random string). If the key changes, existing tokens cannot be read and the account has to connect Google again.
If the Google console asks for an authorized JavaScript origin, use the origin of APP_BASE_URL (http://127.0.0.1:44721 locally). The redirect URI above is the value that must match.
Trial state, Stripe customer ids, MCP OAuth clients and tokens, and the encrypted Google refresh token share one storage interface. Set STORAGE_BACKEND:
Backend | When | What it uses |
| local experiments and tests | data disappears when the process stops |
| a single long-running server or Docker volume |
|
| Vercel or more than one instance |
|
Postgres uses one table, created on first use if it is missing:
CREATE TABLE IF NOT EXISTS rank_kv (
collection text NOT NULL,
id text NOT NULL,
document jsonb NOT NULL,
PRIMARY KEY (collection, id)
);There is no second schema. Do not point this at a new database service unless you already have Postgres. Memory is not enough for a deployed server: a restart drops the refresh token and the trial.
Set these from the Stripe account Lawrence already uses. Do not create products in this repo. The price ids are not dollar amounts.
STRIPE_SECRET_KEY
STRIPE_PRICE_MONTHLY
STRIPE_PRICE_YEARLY
STRIPE_WEBHOOK_SECRET
Checkout is POST /billing/checkout with { "plan": "monthly" } or { "plan": "yearly" }. The webhook is POST /billing/webhook. GET /health includes billingConfigured: true only when the secret key and both price ids are set.
The local trial is 14 days from the first Google connection. Checkout sends Stripe the whole days still left in that trial, when any remain, so the first charge waits until the trial is over.
npm install
cp .env.example .env
# fill Google, encryption, and Stripe values in .env
npm run devThe server listens on PORT (default 44721).
npm test
npm run typecheck
npm startnpm start runs the compiled server. Docker builds the same command (node dist/src/server.js) and expects logo.jpg at the image root.
Vercel: set the environment variables above, set APP_BASE_URL to the production origin, and set STORAGE_BACKEND=postgres with DATABASE_URL. vercel.json rewrites every path to the Node server. After the host is final, point server.json remotes[0].url at https://YOUR_HOST/mcp if it is not https://rank-mcp.vercel.app/mcp.
The registry name is io.github.LAHutchins91/rank-mcp. The icon is https://raw.githubusercontent.com/LAHutchins91/rank-mcp/main/logo.jpg.
Variable | Required for |
| public origin; determines the Google redirect URI |
| listen port, default |
| Google sign-in and Search Console |
| Google token exchange |
| encrypting refresh tokens and signing the browser session |
|
|
| file backend path |
| postgres backend |
| Checkout and the billing portal |
| monthly Checkout price id |
| yearly Checkout price id |
| Stripe webhook signatures |
RANK_TEST_HOOKS=1 lets tests complete MCP login without Google. The process refuses to start when that is set and NODE_ENV=production.
MIT. Copyright (c) 2026 Lawrence Hutchins.
Whether Google Search Console is connected, when the 14-day trial ends, and whether Pro access is active. Does not query Search Console and does not include a price.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real scope information beyond that: it clarifies the tool performs no Search Console query (a meaningful nuance given openWorldHint=true) and that no pricing data is returned, heading off a plausible misconception about a billing/status tool.
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 tight sentences, zero waste, with the substantive content (what it reports) front-loaded and the disambiguating caveats trailing. The 'no price' note is short and earns its place by preventing a wrong expectation.
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 an output schema present, return values need no prose, and with zero parameters and full annotation coverage there is little else to document. The description covers what the tool reports and what it does not touch, which is sufficient for an agent to call 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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's field enumeration (connected / trial end / Pro access) usefully frames the response shape even though no inputs exist.
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 verb+resource (account status) and enumerates exactly what it returns: connection state, trial end date, Pro access. The sentence 'Does not query Search Console' cleanly separates it from all eight siblings, which are Search Console data-query tools, so an agent can pick it without opening a 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 exclusion ('does not query Search Console') implicitly tells the agent when NOT to use this tool, but there is no positive when-to-use guidance, no mention of prerequisites, and no named alternative. Usage is inferable from purpose but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two date ranges using the Search Console totals for a property (no dimension grouping). Reports both API metric objects. Differences are labeled as derived from those returned numbers. Omit compare dates to use the previous window of the same length.
| Name | Required | Description | Default |
|---|---|---|---|
| device | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No | ||
| compareEndDate | No | ||
| compareStartDate | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: it reports both API metric objects, states that differences are derived from the returned numbers, and documents the default comparison window when compare dates are omitted. This is meaningful disclosure for a read tool.
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 short sentences, front-loaded with the core purpose and scope before the default-behavior detail. Slightly dense but no filler; 'Reports both API metric objects' borders on redundant given the output schema but still adds a useful hint about the shape of the comparison.
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 an output schema and full annotations present, the description needn't explain returns or safety, and it covers the comparison default well. But for an 8-parameter tool with 0% schema description coverage, the filter parameters (device, country, searchType) are left completely undocumented, which is a real completeness gap.
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 0% across 8 parameters, so the description must carry the burden, and it largely does not. It alludes to compareStartDate/compareEndDate via the default-window sentence and implies siteUrl via 'for a property', but device, country, searchType, startDate, and endDate are never explained in either place.
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 verb and resource ('Compare two date ranges using the Search Console totals for a property') and adds the scope qualifier '(no dimension grouping)', which implicitly distinguishes it from dimension-grouping siblings like top_queries and top_pages. It does not name a sibling explicitly, but the differentiator is clear.
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 final sentence 'Omit compare dates to use the previous window of the same length' gives a useful default-behavior cue for when compare params can be skipped. However, there is no explicit guidance on when to choose this tool over performance_trends or other comparison-capable siblings, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pages whose Search Console position got worse, whose clicks fell, or that disappeared from the current response. Does not invent zeros for pages the current response omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| device | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No | ||
| compareEndDate | No | ||
| compareStartDate | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description nevertheless adds a genuine behavioral disclosure: it will not fabricate zeros for pages absent from the current response, which tells the agent how missing data is handled. It stops short of explaining the comparison mechanics or pagination/limit behavior.
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, front-loaded with the defining condition, and the second sentence earns its place by clarifying an edge case. No filler or restatement of the name.
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 9 parameters at zero schema coverage and no explanation of how 'worse' or 'fell' is computed, the agent cannot confidently supply the required comparison dates. The existing output schema covers return values, but the input-side gap is large for a derived analytics tool.
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 0% across 9 parameters, so the description carries the full burden. It explains none of them: no mention of startDate/compareStartDate/compareEndDate, device, country, searchType, or limit. Only a faint implication of comparison exists.
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 defines the resource (pages) by a precise three-part condition: worse position, falling clicks, or disappearance from the current response. This distinguishes it from siblings like top_pages and quick_wins, though it never names an alternative explicitly.
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?
There is no when-to-use or when-not-to-use guidance, and no mention of how it relates to compare_periods or top_pages. The agent must infer that a comparison window is needed to produce 'worse' or 'fell'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
URL Inspection status for one URL on a property you can access. Returns the Search Console inspection response, including verdict, coverage, and last crawl fields when the API sent them.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | ||
| languageCode | No | ||
| inspectionUrl | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds that results are conditional ('when the API sent them'), which is useful behavioral context, but it doesn't address auth needs, rate limits, or error behavior.
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 efficient sentences, front-loaded with the purpose and followed by the return value. No filler, though it could be slightly more actionable.
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 an output schema present, the description needn't document return fields, and annotations cover safety. However, the total absence of parameter explanation and usage guidance leaves gaps for an agent deciding how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all three parameters (siteUrl, inspectionUrl, languageCode) are undocumented. The description adds no meaning beyond field names; it doesn't explain what siteUrl and inspectionUrl should contain or how languageCode affects the response.
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 verb (Inspect) and resource (URL), and describes the return (Search Console inspection response with verdict, coverage, last crawl). It does not explicitly differentiate itself from siblings, but its scope is clear enough to distinguish it from list_properties and top_queries.
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?
No when-to-use guidance, no exclusions, and no mention of alternatives. The description implies this is for checking a single URL but does not state when to choose it over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Search Console properties on the connected Google account. Returns siteUrl and permissionLevel exactly as the sites.list API returned them.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'connected Google account' auth scope and a fidelity note that fields are returned 'exactly as the sites.list API returned them,' which is modest added value but not deep behavioral context (no pagination, no empty-account behavior).
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 filler, and the core action is front-loaded before the return-value note. 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 zero parameters, rich annotations, and an output schema present, the description does not need to explain return values, and it does not overreach. The only gap is the missing framing of this as the discovery step that supplies siteUrl inputs to sibling tools.
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 takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies a no-argument call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (List) and resource (Search Console properties on the connected Google account), which is unambiguous. It does not explicitly contrast with siblings, but none of the listed siblings (top_queries, inspect_url, account_status, etc.) also enumerate properties, so the distinction is reasonably clear from the resource alone.
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?
Usage is only implied: an agent can infer this is the discovery step for finding which siteUrl values to pass to the other Search Console tools, but the description never states that. There is no explicit when-to-use, when-not-to-use, or alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily clicks, impressions, ctr, and position for a property. Each row is a date Search Console returned. Missing dates are not filled in, and ctr is the API fraction.
| Name | Required | Description | Default |
|---|---|---|---|
| device | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond them: rows are only dates the API returned, missing dates are not backfilled, and ctr is an unfractioned API value rather than a percentage. It omits row limits/pagination, which is the remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each carrying distinct information (what the rows are, gap semantics, unit semantics), with the core output description front-loaded. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not needed, and the gap/unit notes are useful. However, with 6 parameters at 0% schema coverage the description leaves the agent guessing about the date range and filter parameters, which is a material omission for a trends tool.
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 0% across 6 parameters, so the description carries the full burden, yet it documents none of them. Only 'for a property' loosely gestures at siteUrl and 'daily' implies a date range; startDate, endDate, device, country and searchType are never mentioned, and the description does not clarify whether the date range is required.
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 the resource (daily Search Console metrics for a property) and the granularity (one row per date), which is a clear verb-less but specific purpose. It does not distinguish itself from close siblings like compare_periods or top_queries, leaving the agent to infer the boundary.
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?
There is no explicit when-to-use guidance and no named alternative, even though compare_periods and top_queries are plausible overlaps. Usage must be inferred entirely from the phrase 'Daily ... for a property'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queries with high impressions and low ctr in Search Console. Defaults are at least 100 impressions and ctr at or below 0.02 (the API fraction, so 0.02 is 2%). Does not estimate missed clicks.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| device | No | ||
| maxCtr | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No | ||
| minImpressions | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral value on top: it discloses the default thresholds and clarifies the ctr fraction semantics. The note that it does not estimate missed clicks usefully bounds the result semantics, though it doesn't discuss ordering or how many rows appear absent an explicit limit.
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 short sentences, zero filler, and the defining filter is front-loaded ahead of the tuning defaults. Every sentence earns its place, including the scope-limiting final clause.
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?
An output schema exists, so return values need no explanation, and the description correctly focuses on the filters that define the query. The main remaining gap is the default date window and defaults for device/country/searchType, which an agent would need to know before calling.
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 0% across 9 parameters, so the description must compensate. It does so well for the two trickiest thresholds (minImpressions default 100, maxCtr default 0.02 and its fraction interpretation) but says nothing about limit, device, country, date range, searchType, or siteUrl. Partial compensation, so a 3 rather than higher.
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 resource (Search Console queries) and the precise filter that defines the set: high impressions, low ctr. An agent understands the shape of the output without opening the schema. It doesn't explicitly name a sibling (e.g. top_queries) to contrast against, so it stops short of 5.
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 supplies the operative defaults (>=100 impressions, ctr <=0.02), which tells the agent how to invoke it, but gives no when-to-use vs alternatives such as top_queries or top_pages, and no exclusion guidance. Usage context is implied by the topic rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top pages for one property and date range. Metrics are copied from Search Console rows. ctr is the API fraction from 0 to 1. Omit dates to use the default 28-day window.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| device | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/non-destructive, so safety is covered. The description adds real value beyond them: data provenance ('Metrics are copied from Search Console rows') and a unit clarification ('ctr is the API fraction from 0 to 1') that prevents a common misinterpretation of the metric.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the resource and scope, followed by metric semantics and the default-window rule. No filler, though the 'copied from Search Console rows' clause is somewhat incidental.
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?
Output schema exists, so return values needn't be explained, and annotations cover the safety profile. Still, for a 7-parameter tool with 0% schema coverage, most filter parameters (device, country, searchType, limit) remain unexplained, leaving a real gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 7 parameters, so the description carries the full burden. It only addresses the date parameters and ctr; limit, device, country, searchType, and siteUrl are left entirely undocumented in both schema and description.
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 verb+resource: 'Top pages for one property and date range.' The resource (pages) is clear enough to distinguish it from the sibling top_queries, though the description never names that alternative explicitly.
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 line 'Omit dates to use the default 28-day window' gives a concrete usage rule for the date parameters, which is helpful. However there is no when-to-use-this-vs-siblings guidance (e.g. vs top_queries, performance_trends, or quick_wins), so the agent must infer selection from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top search queries for one property and date range. clicks, impressions, ctr, and position are copied from Search Console. ctr is a fraction from 0 to 1, not a percent. Omit dates to use the default 28-day window.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| device | No | ||
| country | No | ||
| endDate | No | ||
| siteUrl | Yes | ||
| startDate | No | ||
| searchType | No |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: metrics are copied verbatim from Search Console, ctr is a 0-1 fraction rather than a percent, and omitting dates triggers a 28-day default window.
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 short sentences, front-loaded with the purpose, then the metric semantics, then the default-window rule. No filler and every sentence carries information.
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?
An output schema exists, so return structure needn't be explained. However, with 7 parameters and zero schema descriptions, several filter parameters (device, country, searchType, limit) are left undocumented by both the schema and the description, leaving gaps for an agent building a call.
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 0% across 7 parameters, so the description carries the burden and only partially compensates. It clarifies date defaults and the ctr unit, but says nothing about siteUrl format, limit bounds, device, country, or searchType values.
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 verb+resource: 'Top search queries for one property and date range,' which is clearly distinct from the sibling top_pages. It does not explicitly name or contrast with siblings, but the resource is unambiguous.
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 one conditional behavior ('Omit dates to use the default 28-day window'), which is useful, but offers no guidance on when to choose this tool over top_pages, compare_periods, or quick_wins. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0account_statuscompare_periodsdropped_pagesinspect_urllist_propertiesperformance_trendsquick_winstop_pagestop_queriesScored across 9 tools
Each tool targets a distinct analysis or resource: listing properties, top queries/pages, URL inspection, trends, period comparison, quick wins, dropped pages, and account status. The purposes are clearly differentiated with no overlap, so an agent can easily select the right tool.
All tool names follow a consistent snake_case pattern, using noun compounds or adjective_noun structures (e.g., top_queries, inspect_url, performance_trends). The naming is predictable and readable throughout.
With 9 tools, the set is well-scoped for a Google Search Console analysis server, covering core reporting and inspection tasks without redundancy. Each tool earns its place and the count is within the ideal 3-15 range.
The tools provide strong coverage for common GSC analysis: listing properties, top queries/pages, trends, comparisons, quick wins, dropped pages, and account status. Minor gaps exist, such as the ability to filter or segment queries/pages by device or country, but the core lifecycle is well addressed.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Google Search Console in your AI: overview, opportunities, index gaps, page checks, long history.
Turn Search Console data into SEO actions, content, publishing, indexing, and AI insights.
SEO data your AI can cite: Search Console, GA4, keywords, backlinks, SERPs and AI visibility.
