Skip to main content
Glama

Rank Checker by GSC Wizard

Top search queries

query_top_queries
Read-only

Use this when the user asks which search queries bring a property the most clicks. Returns the top queries over a date range: a wrapper around query_search_analytics. Not for totals: use get_site_summary. Rows are sorted by clicks, highest first; ctr is a 0-100 percentage. Query rows cover only the queries Google lists: coverage.hiddenClicksShare (0-1) is the share of clicks with no query row, so quote totals from coverage.siteTotals, or coverage.filteredTotals when coverage.scope is "filtered", not summed rows. Served from the ClickHouse warehouse (longer history) when available, else the live Search Console API (dataSource says which). 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": "query_top_queries"
  }
}

Input Schema

NameRequiredDescriptionDefault
brandNoOptional. Narrow to queries matching the property's branded keywords ('branded') or to all others ('non_branded'). Needs branded keywords set (update_site brandedKeywords); see get_filter_options.
limitNoRows to return per call (default 100, max 1000).
offsetNoRows to skip. Use pagination.nextOffset from a previous call to get the next page.
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
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
contentGroupIdNoOptional. Narrow to pages in this content group (id from get_filter_options or list_content_groups). Groups whose rules cannot be applied as a filter are refused; get_filter_options says which.
topicClusterIdNoOptional. Narrow to queries in this topic cluster (id from get_filter_options or list_topic_clusters). Clusters whose keywords cannot be applied as a filter are refused.

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.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes well beyond that, disclosing sort order (clicks descending), ctr units (0-100), the query-row coverage limitation and hiddenClicksShare caveat with the correct totals source, the data-source fallback (ClickHouse vs live API with dataSource indicator), and the 2-3 day data lag.

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

Conciseness4/5

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

The description is front-loaded with the use case and exclusion before the caveats, and almost every sentence carries operative information. It is dense and long in one paragraph, and the coverage/output-detail material could arguably be shortened given an output schema exists, but 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?

For a 9-parameter analytics tool with real subtleties (hidden clicks, filtered scope, source fallback, settle lag), the description covers the traps an agent would otherwise get wrong: summing rows instead of quoting coverage totals, and assuming data through today. Combined with rich schema and an output schema, an agent has what it needs to call and interpret this correctly.

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

Parameters3/5

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

Schema coverage is 89%, so the schema already documents every parameter including enums and date formats. The description restates date omission behavior ('omit startDate/endDate to analyze the last 28 settled days') but adds little meaning for brand, limit, offset, contentGroupId, or topicClusterId beyond what the schema says; baseline 3 applies.

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

Purpose5/5

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

The first sentence states a specific verb and resource ('which search queries bring a property the most clicks') and the next names it as a wrapper around query_search_analytics, which lets an agent place it relative to a sibling without opening either schema.

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

Usage Guidelines5/5

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

The description gives an explicit trigger ('Use this when the user asks which search queries...'), an explicit exclusion with a redirect ('Not for totals: use get_site_summary'), and identifies the underlying general tool (query_search_analytics). Nothing about when to pick this tool is left to inference.

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.