Skip to main content
Glama
kLOsk

AdLoop: Google Ads, Reddit Ads & GA4

by kLOsk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Search Console report

run_gsc_report
Read-only

Query Google Search Console analytics to get clicks, impressions, CTR, and average position by query, page, device, and date; diagnose organic traffic drops and find keyword opportunities.

Instructions

Run a Google Search Console search analytics report.

Returns clicks, impressions, CTR, and average position broken down by the requested dimensions. Useful for diagnosing organic traffic drops, finding keyword opportunities, and cross-referencing with GA4 and Ads data. One request returns at most 25,000 rows; a full page carries next_start_row for the following request. With data_state "all" the response metadata names the first date whose data is still incomplete.

Queries the Search Console API: https://developers.google.com/webmaster-tools/v1/searchanalytics/query

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum rows to return (default 100, max 25000 per request; higher values are capped at 25000).
site_urlNoThe GSC property URL (e.g. "https://example.com/" or "sc-domain:example.com"), as listed by list_gsc_sites. Defaults to the configured Search Console site (gsc.site_url).
start_rowNoZero-based offset of the first row, for paging past the 25,000-row cap (pass the previous response's next_start_row).
data_stateNo"final" (default) returns finalized data only; "all" adds fresh data from the last days that can still change; "hourly_all" is the state the hour dimension uses.final
dimensionsNoOne or more of "query", "page", "country", "device", "date", "searchAppearance" (search result feature, e.g. rich results) or "hour" (hourly rows for roughly the last 10 days; switches data_state to "hourly_all"). Defaults to ["query"].
search_typeNo"web" (default), "image", "video", "news", "discover", or "googleNews".web
date_range_endNoEnd date, same formats as date_range_start.today
aggregation_typeNo"auto" (default), "byPage" (aggregate by canonical URL) or "byProperty" (aggregate by property; not combinable with grouping or filtering by page).auto
date_range_startNoStart date as ISO "YYYY-MM-DD" or a relative value like "7daysAgo", "30daysAgo", "today".7daysAgo
dimension_filter_groupsNoOptional list of GSC DimensionFilterGroup objects to filter by query, page, country, or device, e.g. [{"filters": [{"dimension": "query", "operator": "contains", "expression": "analytics"}]}]. searchAppearance is filterable too.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.27.1
    • addedInput schema / properties / aggregation_type
      Added value: +{
+  "default": "auto",
+  "description": "\"auto\" (default), \"byPage\" (aggregate by canonical\nURL) or \"byProperty\" (aggregate by property; not combinable with\ngrouping or filtering by page).",
+  "type": "string"
+}
    • addedInput schema / properties / data_state
      Added value: +{
+  "default": "final",
+  "description": "\"final\" (default) returns finalized data only; \"all\"\nadds fresh data from the last days that can still change;\n\"hourly_all\" is the state the hour dimension uses.",
+  "type": "string"
+}
    • addedInput schema / properties / date_range_end / description
      Added value: +"End date, same formats as date_range_start."
    • addedInput schema / properties / date_range_start / description
      Added value: +"Start date as ISO \"YYYY-MM-DD\" or a relative value\nlike \"7daysAgo\", \"30daysAgo\", \"today\"."
    • addedInput schema / properties / dimension_filter_groups / description
      Added value: +"Optional list of GSC DimensionFilterGroup\nobjects to filter by query, page, country, or device, e.g.\n[{\"filters\": [{\"dimension\": \"query\", \"operator\": \"contains\",\n\"expression\": \"analytics\"}]}]. searchAppearance is filterable too."
    • addedInput schema / properties / dimensions / description
      Added value: +"One or more of \"query\", \"page\", \"country\", \"device\",\n\"date\", \"searchAppearance\" (search result feature, e.g. rich\nresults) or \"hour\" (hourly rows for roughly the last 10 days;\nswitches data_state to \"hourly_all\"). Defaults to [\"query\"]."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum rows to return (default 100, max 25000 per request;\nhigher values are capped at 25000)."
    • addedInput schema / properties / search_type / description
      Added value: +"\"web\" (default), \"image\", \"video\", \"news\", \"discover\",\nor \"googleNews\"."
    • addedInput schema / properties / site_url / description
      Added value: +"The GSC property URL (e.g. \"https://example.com/\" or\n\"sc-domain:example.com\"), as listed by list_gsc_sites. Defaults to\nthe configured Search Console site (gsc.site_url)."
    • addedInput schema / properties / start_row
      Added value: +{
+  "default": 0,
+  "description": "Zero-based offset of the first row, for paging past the\n25,000-row cap (pass the previous response's next_start_row).",
+  "type": "integer"
+}
  2. Addedv0.12.0

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the readOnly/openWorld/destructive annotations, it discloses operational traits an agent needs: a hard 25,000-row cap, the next_start_row paging handoff, and the data_state 'all' freshness metadata quirk. This is meaningful behavioral context for paginated, freshness-sensitive reporting.

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-loads purpose, then returns, usage, and behavioral caveats, ending with the API reference. Well ordered and mostly waste-free, though the metrics list slightly overlaps the schema's return shape and the doc URL is tangential.

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

Completeness4/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 spelled out. The description covers the key operational gaps (row cap, pagination, data freshness), leaving only auth/rate-limit context unstated for a 10-parameter read-only tool.

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 description coverage is 100%, so the schema already documents every parameter including limit, start_row, dimensions, and data_state. The description reiterates the row cap and data_state behavior but adds little syntax or format detail not already in the schema, matching the baseline-3 rule.

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

Purpose4/5

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

States a specific verb and resource ('Run a Google Search Console search analytics report') and lists the exact metrics returned. It implicitly separates itself from run_ga4_report by framing GSC data as the input to cross-referencing, but never names an alternative tool directly.

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?

Gives clear use contexts (diagnosing organic traffic drops, finding keyword opportunities, cross-referencing with GA4/Ads data). It does not state when to prefer run_ga4_report or get_search_terms instead, so there are no explicit exclusions or alternatives.

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