Skip to main content
Glama

Rank Checker by GSC Wizard

Get ranking changes between two periods

get_ranking_changes
Read-only

Use this when the user asks which queries or pages moved up or down between two periods: each is filed as new, lost, improved or declined (improved = better, lower average position). Not for pages losing clicks over time: use find_decaying_content. limit (1-10000, default 50) applies PER BUCKET; counts gives the full size of each bucket before that cut. Buckets run largest first: improved and declined by the size of positionDelta (prevPosition minus position; a new or lost key's missing side reads 0), new by clicks, lost by prevClicks. ctr is a 0-100 percentage. Each period reads its top scanLimit keys by clicks (warehouse: max(limit*10, 1000), capped at 50000; live API: 25000), and counts are measured within them. The warehouse reads every key in either period's top scanLimit in both periods, so new and lost are real; on the live API the reads are independent, so a key just below one cut can show as new or lost. Query movers are only the queries Google lists: on most properties a large share of clicks has no query row (analyze_sampling_impact measures it). Served from the GSC Wizard ClickHouse warehouse when available, otherwise the live Search Console API (see dataSource). Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).

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": {
      "siteUrl": "<siteUrl>"
    },
    "name": "get_ranking_changes"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
endDateNoOptional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null".
siteUrlYes
dimensionNoquery
startDateNoOptional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null".
searchTypeNoSearch type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), webMultimodal (Google Lens, Circle to Search and image uploads; data from 2026-02-20; not part of all), or all (web + image + video + news + discover combined, position impression-weighted, like the app's "All" filter). Discover, googleNews and webMultimodal carry no query dimension, so query-level results for them are empty; Discover and googleNews also carry no position: it reads null, not 0.web
comparisonEndDateNoOptional. End of the baseline / comparison period as YYYY-MM-DD. Omit both comparison dates to use the same-length period immediately before the current window; give only this one to end a baseline of the same length here.
comparisonStartDateNoOptional. Start of the baseline / comparison period as YYYY-MM-DD. Omit both comparison dates to use the same-length period immediately before the current window; give only this one to start a baseline of the same length here.

Output Schema

NameRequiredDescriptionDefault
newNo
hintNo
kindNoWidget variant: "kpis", "table", or "sections".
kpisNoKPI cards (kind="kpis").
lostNo
noteNoCaveat about the result, when the tool returned one.
rowsNoData rows (kind="table"), each with every field of the tool's own row; columns name the ones drawn.
notesNoCaveats about the result, when the tool returned several.
rangeNoThe window the numbers cover.
scopeNoThe brand, content group or topic cluster filter these numbers are narrowed to; absent when the call was unscoped and the numbers cover the whole property.
titleNo
blocksNoStacked sub-blocks (kind="sections").
countsNoget_ranking_changes: the full size of each bucket before `limit`.
deltasNoget_site_summary: current minus previous (ctrPoints in percentage points).
reasonNo
sourceNo
thenByNoSecondary sort field, when the tool states one.
accountNo
columnsNoColumn defs (kind="table").
currentNoget_site_summary: the window's totals (ctr 0-100, impression-weighted avgPosition).
summaryNoMetric totals keyed by GA4 metric name.
warningNoA caveat that changes how the numbers read.
coverageNoHow much of the property total the returned rows cover, with the property totals inline. Quote totals from here; do not sum the rows.
declinedNo
improvedNo
nextStepNo
orderingNoSort order per list, when the result holds several lists.
previousNoget_site_summary: the comparison window's totals.
sortedByNoRow field the rows are sorted by.
timeZoneNoGA4 property's IANA reporting time zone.
dailyRowsNoget_site_summary: the window day by day, oldest first.
dimensionNo
emptyTextNo
scanLimitNo
siteScopeNoSet when GA4 numbers were narrowed to this site's hostnames because the property is shared with other sites.
sortOrderNo"asc" or "desc".
thenOrderNoThe tie-break's direction, present only when it differs from sortOrder.
totalRowsNo
assistantsNoget_ga4_llm_traffic: one row per AI assistant (the table rows).
comparisonNoThe comparison window (get_site_summary, get_ranking_changes).
dataSourceNoWhere the numbers were read from: the warehouse or the live API.
hasRevenueNo
paginationNoWhere this page of rows sits in the whole result, and how to fetch the next one.
timeseriesNoget_ga4_overview with includeTimeseries: daily points, oldest first.
partialDaysNoRequested days after settledThrough; their numbers are still incomplete.
prevSummaryNoThe comparison period's totals; null when it has no GA4 data.
currencyCodeNo
dataMaturityNo
emptyBecauseNo
ga4OnlyCountNo
gscOnlyCountNo
hasEcommerceNo
landingPagesNoget_ga4_llm_traffic: landing pages of AI assistant sessions.
matchedCountNo
methodLimitsNo
hasComparisonNo
notConfiguredNo
totalSessionsNo
prevTimeseriesNoThe comparison period's daily points; null when it has no GA4 data.
reauthRequiredNo
settledThroughNoLast day the data is complete through.
comparisonRangeNoThe comparison window of a GA4 view tool; null when there is none.
ecommerceSummaryNo
sourceTimeseriesNoget_ga4_llm_traffic with includeDailySplit: daily sessions per assistant.
comparisonHasDataNofalse when the comparison period has no data at all, so there is no comparison.
matchedClickShareNoA 0-1 fraction of the named-query clicks the estimates cover.
prevTotalSessionsNo
previousDailyRowsNoget_site_summary: the comparison window day by day, oldest first; absent for a window over 180 days.
llmShareOfSessionsNoA 0-1 fraction.
coverageUnavailableNoWhy coverage is null, when it is.
warehouseLatestDateNoNewest day the warehouse holds for the property; days after it in the range are missing, not zero.
prevEcommerceSummaryNo
prevLlmShareOfSessionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the read-only annotations, it discloses a lot: warehouse vs live API sourcing with different scan semantics, how new/lost are computed per source, the ~2-3 day data lag, the 28-day default window, and the limitation that query movers only cover queries Google lists. These are substantive behavioral traits an agent could not infer from annotations.

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

Conciseness4/5

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

Front-loaded with the use case and exclusion, and every sentence carries operational detail. It is dense and runs several caveats together without visual separation, so an agent must parse a long block, but there is little true 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?

An output schema exists so return values need not be explained, and the description still covers data sources, fallback behavior, scan mechanics, defaults, and key caveats. For an 8-parameter tool with warehouse/live divergence, this is complete enough to call correctly.

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

Parameters4/5

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

At 63% schema coverage the description adds real meaning: limit is per-bucket with 1-10000 range and default 50, counts are measured within the scanLimit window, ctr is a 0-100 percentage, and date omission triggers a 28-day window. It does not explicitly discuss dimension or comparison dates beyond what the schema states, leaving a minor gap.

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 trigger ("when the user asks which queries or pages moved up or down between two periods") plus the four outcome categories (new, lost, improved, declined) and even defines improved as lower average position. This clearly separates it from sibling tools like find_decaying_content.

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?

Gives explicit when-to-use (ranking movement between periods), explicit when-not-to-use ("Not for pages losing clicks over time: use find_decaying_content"), and points to analyze_sampling_impact for a related measurement question. Alternatives are named with the condition that selects them.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.