gsc_dimensional_trend
The ONLY governed tool for Google Search Console metrics OVER TIME BY a drill field — for example weekly clicks by page, country, device, category, intent, query, rank bucket, traffic source, language, or geo. One user request must produce exactly ONE call for the entire date_range. Copy every requested flow metric into that one call; NEVER split a multi-metric request into separate calls. Copy an explicit comparison period into comparison_range; NEVER merge the two ranges or route a dimensional comparison through compare_periods. The tool natively returns multi-metric series and compares the SAME stable entity set across both periods. Average-position dimensional trends return an immediate zero-query capability note. It ranks entities across the full primary range and returns stable day/week/month/quarter series; never emulate this by calling gsc_breakdown once per bucket.
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": {
"date_range": "<date_range>",
"group_by": "<group_by>",
"granularity": "<granularity>",
"date_range_mode": "<date_range_mode>"
},
"name": "gsc_dimensional_trend"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Convenience filter for branded or non-branded demand. | |
| top_n | No | Number of ranked range-summary rows; up to five leading values are plotted. | |
| intent | No | Convenience filter for one resolved customer keyword group. | |
| medium | No | Source medium; defaults to google/organic. | |
| source | No | Where Google search performance data is read from. Use "bigquery" ONLY when the user explicitly asks for BigQuery as the source AND describe_data_sources reports it available from live customer configuration — it returns far more granular per-query data (privacy-suppressed impressions appear under "[anonymized by google]"). | default |
| filters | No | Optional curated GSC filters. Resolve values before filtering. regex/not_regex only apply to query/page. | |
| metrics | No | Copy ALL metrics named by the user into this ONE array and make ONE tool call. NEVER split a multi-metric request across calls. Any combination of clicks, impressions, and CTR is supported; position intentionally returns an explicit zero-query capability note. | |
| sort_by | No | Ranking metric. It must be one of the requested metrics; defaults to the first requested metric. | |
| group_by | Yes | REQUIRED — the field whose leading values should be plotted over time. | |
| date_range | Yes | The PRIMARY analysis period only. If the user supplied a second explicit period, keep it separate in comparison_range and make exactly one gsc_dimensional_trend call. | |
| granularity | Yes | REQUIRED time bucket: day, week, month, or quarter. Quattr weeks run Sunday through Saturday. | |
| date_range_mode | Yes | REQUIRED for this trend tool. Use "calendar" for YTD or another explicit calendar period: keep the requested start and return only complete buckets inside it. Use "rolling" for "last N days/weeks/months/quarters": preserve N complete buckets by shifting the full window backward when needed. | |
| comparison_range | No | Copy the user's explicit comparison period here. NEVER merge it into date_range and NEVER substitute compare_periods. The tool compares the same primary-period entity set across both bucketed periods. |