Skip to main content
Glama
acamolese

Google Search Console Audit MCP

by acamolese
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

gsc_query

Read-onlyIdempotent

Pull Search Analytics performance data—clicks, impressions, CTR, position—for any date range and dimension, with filters and pagination.

Instructions

Query the Search Analytics report: clicks, impressions, CTR, position.

This is the general-purpose tool. With no dates it covers the last 28 days ending today (UTC), with data_state=all so today's partial data is included, matching what the Search Console UI shows.

Example: site_url="sc-domain:example.com", dimensions="query,page", period="last_28_days", row_limit=100.

Returns a # meta ... line then a TSV table, or JSON with meta and rows. The meta names the exact range, the row count, whether more rows exist and the start_row to pass next.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNoRolling window length ending today.
typeNoweb, image, video, news, discover or googleNews.web
periodNoNamed range: last_7_days, last_28_days, last_3_months, last_month, this_month, last_16_months.
date_toNoEnd date YYYY-MM-DD. Defaults to today.
filtersNoList of {dimension, operator, expression}. Operators: equals, notEquals, contains, notContains, includingRegex, excludingRegex.
no_cacheNoBypass the response cache for this call.
site_urlYes`sc-domain:example.com` for a domain property, or `https://example.com/` with the trailing slash for a URL-prefix property. Call gsc_sites if unsure.
date_fromNoStart date YYYY-MM-DD. Overrides period and days.
row_limitNoRows returned. Default 100, capped at 1000.
start_rowNoZero-based pagination offset.
data_stateNo`all` (default, includes today's partial data) or `final`.
dimensionsNoComma-separated dimensions: query, page, country, device, date, searchAppearance, hour. `hour` covers only the last 10 days.query
response_formatNo`tsv` (default, compact) or `json`.tsv
aggregation_typeNoauto, byPage or byProperty.auto
filter_group_typeNoOnly `and` is supported by the API within one group.and

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv3.0.1
    • addedInput schema / properties / aggregation_type
      Added value: +{
+  "default": "auto",
+  "description": "auto, byPage or byProperty.",
+  "title": "Aggregation Type",
+  "type": "string"
+}
    • addedInput schema / properties / data_state
      Added value: +{
+  "default": "",
+  "description": "`all` (default, includes today's partial data) or `final`.",
+  "title": "Data State",
+  "type": "string"
+}
    • addedInput schema / properties / date_from / default
      Added value: +""
    • addedInput schema / properties / date_from / description
      Added value: +"Start date YYYY-MM-DD. Overrides period and days."
    • addedInput schema / properties / date_to / default
      Added value: +""
    • addedInput schema / properties / date_to / description
      Added value: +"End date YYYY-MM-DD. Defaults to today."
    • addedInput schema / properties / days
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Rolling window length ending today.",
+  "title": "Days"
+}
    • addedInput schema / properties / dimensions / description
      Added value: +"Comma-separated dimensions: query, page, country, device, date, searchAppearance, hour. `hour` covers only the last 10 days."
    • addedInput schema / properties / filter_group_type
      Added value: +{
+  "default": "and",
+  "description": "Only `and` is supported by the API within one group.",
+  "title": "Filter Group Type",
+  "type": "string"
+}
    • addedInput schema / properties / filters
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "List of {dimension, operator, expression}. Operators: equals, notEquals, contains, notContains, includingRegex, excludingRegex.",
+  "title": "Filters"
+}
    • addedInput schema / properties / no_cache
      Added value: +{
+  "default": false,
+  "description": "Bypass the response cache for this call.",
+  "title": "No Cache",
+  "type": "boolean"
+}
    • addedInput schema / properties / period
      Added value: +{
+  "default": "",
+  "description": "Named range: last_7_days, last_28_days, last_3_months, last_month, this_month, last_16_months.",
+  "title": "Period",
+  "type": "string"
+}
    • addedInput schema / properties / response_format
      Added value: +{
+  "default": "tsv",
+  "description": "`tsv` (default, compact) or `json`.",
+  "title": "Response Format",
+  "type": "string"
+}
    • addedInput schema / properties / row_limit / description
      Added value: +"Rows returned. Default 100, capped at 1000."
    • addedInput schema / properties / site_url / description
      Added value: +"`sc-domain:example.com` for a domain property, or `https://example.com/` with the trailing slash for a URL-prefix property. Call gsc_sites if unsure."
    • addedInput schema / properties / start_row
      Added value: +{
+  "default": 0,
+  "description": "Zero-based pagination offset.",
+  "title": "Start Row",
+  "type": "integer"
+}
    • addedInput schema / properties / type
      Added value: +{
+  "default": "web",
+  "description": "web, image, video, news, discover or googleNews.",
+  "title": "Type",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "site_url",
-  "date_from",
-  "date_to"
-]New value: +[
+  "site_url"
+]
  2. First observedv2.0.2

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context beyond the schema and annotations: the default 28-day end-to-today window, inclusion of today's partial data via data_state=all, the TSV or JSON output shape, and the meta fields needed for pagination such as start_row and whether more rows exist.

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?

The description is compact and front-loaded: purpose first, then key defaults, then an example, then the return envelope. Every sentence earns its place, and the example is a high-signal compact illustration of how the parameters combine.

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?

Given the large 15-parameter schema with 100% coverage, plus an output schema and strong annotations, the description supplies exactly the missing context: default period semantics, UI parity, API-style pagination, and a representative call. An agent has enough to both select and invoke the tool 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?

Schema description coverage is 100%, so the baseline is 3, and the schema already documents every parameter clearly. The description adds value with a concrete example tying site_url, dimensions, period, and row_limit together, and it clarifies default date behavior and the pagination contract. That moves it above baseline without duplicating 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?

The description opens with a specific verb and resource: 'Query the Search Analytics report: clicks, impressions, CTR, position.' It then labels the tool as 'the general-purpose tool,' which distinguishes it from specialized sibling tools like gsc_quick_wins or gsc_ctr_gaps. This gives an agent a clear and immediate sense of scope.

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

Usage Guidelines4/5

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

The description provides clear context: it covers defaults, date behavior, and the UI-matching data_state, and it demonstrates usage with an explicit example. It identifies the tool as the general-purpose option, implicitly routing agents away from specialized siblings, though it does not name those alternatives or state explicit when-not-to-use conditions.

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

Deploy Server

Other Tools