Skip to main content
Glama
@mgcrea/mcp-google-search-console

@mgcrea/mcp-google-search-console

by mgcrea

Search Console: Compare Periods

gsc_compare_periods
Read-only

Compare two Google Search Console periods by query, page, country or device to find top gainers and losers, new and lost keys, and period totals in one call instead of diffing queries manually.

Instructions

What changed between two periods, by one dimension: the top gainers and losers present in both, keys that are new or lost, and each period's returned_totals. This is the tool for "what dropped?" or "which pages grew?" — prefer it over two gsc_query_search_analytics calls and diffing them by eye. Defaults: current = the 28 days ending 3 days ago (Pacific), previous = the same-length window just before it. Runs two queries of depth rows each (1,000 by default); by query or page that is the expensive kind of load quota, so do not loop it. returned_totals sum the fetched rows only, not the property: rows past depth are not counted, and by query anonymized queries are missing. When a period fills depth, truncated is set and some new/lost keys may only have crossed the cut.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site": "<site>",
      "dimension": "<dimension>"
    },
    "name": "gsc_compare_periods"
  }
}

Input Schema

NameRequiredDescriptionDefault
siteYesThe Search Console property, e.g. "sc-domain:example.com" (a domain property: every protocol and subdomain) or "https://www.example.com/" (a URL-prefix property: exactly that scheme, host and path). A bare "example.com" or a URL without its trailing slash is resolved against the properties this account can see, preferring the domain property; the response's `site` says which property was read. gsc_list_sites lists them.
typeNoWhich Google surface: web (default, Search's main results), image, video, news (the News tab in Search), discover, googleNews (news.google.com and the News app), webMultimodal (Lens, Circle to Search, image uploads). discover and googleNews have no query dimension and no position.web
depthNoRows fetched per period (1-5000), top keys by clicks. Defaults to 1000. Deeper finds smaller movers and fewer false new/lost keys, but grouping by query or page is what spends the 10-minute and daily load quotas, and the cost grows with the rows asked for — twice over, since both periods are queried. Raise it only when `truncated` is set and the tail matters.
limitNoHow many gainers, losers, new and lost keys to return, each. Defaults to 25.
metricNoWhat to rank gainers and losers by. Defaults to clicks. For position lower is better, so a gainer's change is negative.clicks
currentNoThe period to explain. Defaults to the 28 days ending 3 days ago (Pacific).
filtersNoFilters, all AND-ed together, e.g. [{"dimension":"page","operator":"contains","expression":"/blog/"}]. Filtering by page or query costs as much load quota as grouping by it.
previousNoThe baseline. Defaults to the same number of days immediately before `current`; with only one bound given, the other is set so it is as long as `current`. Must not overlap it. Pass the same dates a year earlier for a year-over-year view.
dimensionYesThe one dimension to compare by, e.g. page for "which pages lost traffic".

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavioral context: two queries of `depth` rows each, 10-minute/daily load quota cost, that `returned_totals` sum fetched rows only (not the property, with anonymized queries missing by query), and that `truncated` is set when depth fills. It does not describe pagination or the shape of the diff entries themselves, keeping it just below the top tier.

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

Conciseness5/5

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

Front-loads the answer to 'what does this do', then defaults, then cost warnings, then caveats — in descending order of decision value. Dense but every sentence carries operational information; nothing is filler.

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

Completeness5/5

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

Despite 9 parameters, nested period objects and no output schema, the description covers defaults, cost, truncation semantics and return categories well enough to call it confidently. The remaining unknowns (diff entry shape) are minor compared to what is disclosed.

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

Parameters3/5

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

Schema coverage is 100% and every parameter is thoroughly documented in the schema itself. The description adds little beyond that except the year-over-year hint (same dates a year earlier) and tying `depth` to `truncated`; the default windows and non-overlap rule are already stated in the schema.

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

Purpose5/5

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

Opens with a specific comparative verb and resource: 'What changed between two periods, by one dimension', and enumerates the output categories (gainers, losers, new keys, lost keys, returned_totals). An agent can distinguish it from the single-period query siblings immediately.

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

Usage Guidelines5/5

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

Explicitly names the alternative it replaces — 'prefer it over two gsc_query_search_analytics calls and diffing them by eye' — and gives trigger questions ('what dropped?', 'which pages grew?'). It also states a usage constraint: 'do not loop it' because of quota cost.

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