Skip to main content
Glama
kLOsk

AdLoop: Google Ads, Reddit Ads & GA4

by kLOsk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Analytics report

run_ga4_report
Read-only

Run custom GA4 reports with dimensions, metrics, filters, sorting, paging, and comparison periods to analyze website and marketing performance.

Instructions

Run a custom GA4 report with optional filters, ordering, paging and a comparison period.

Returns the property, the date range, the dimension and metric headers, one row per dimension combination (values as strings), row_count and total_row_count (plus next_offset while more rows remain). At least one dimension or metric is required. With compare_start/compare_end the comparison period is a second date range: every row then carries a dateRange value of "current" or "comparison", and date_ranges maps both labels to their dates. Invalid filters or ordering return "Validation failed" with details, before anything is sent.

Queries the GA4 Data API. Dimensions and metrics: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of rows returned (positive).
offsetNoZero-based row offset for paging; pass next_offset from the previous result to get the following page.
metricsNoGA4 metric API names, e.g. sessions, totalUsers, newUsers, screenPageViews, keyEvents, eventCount, bounceRate.
order_byNoSort order as [{"field": <name>, "desc": true|false}]; each field must be one of the requested dimensions or metrics.
dimensionsNoGA4 dimension API names, e.g. date, pagePath, sessionSource, sessionMedium, country, deviceCategory, eventName. Custom ones (customEvent:...) and every valid name are listed by list_ga4_dimensions_and_metrics.
compare_endNoEnd of the comparison period.
property_idNoGA4 property as "properties/123456789" (see get_account_summaries). If empty, uses the default from config.
compare_startNoStart of the comparison period (same formats as date_range_start). Set together with compare_end.
metric_filterNoConditions on metrics, applied after aggregation, all of which must hold (AND). Each is {"field": <metric>, "op": <op>, "value": <number>}; op is EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL (or =, <, <=, >, >=), or BETWEEN with "value": [from, to]. Optional "not": true. Example: [{"field": "sessions", "op": ">", "value": 100}].
date_range_endNoEnd date, same formats as date_range_start.today
date_range_startNoStart date: "today", "yesterday", "NdaysAgo" (e.g. "7daysAgo", "28daysAgo", "90daysAgo"), or "YYYY-MM-DD".7daysAgo
dimension_filterNoConditions on dimensions, all of which must hold (AND). Each is {"field": <dimension>, "op": <match>, "value": <string>}; op is EXACT (default), BEGINS_WITH, ENDS_WITH, CONTAINS, FULL_REGEXP, PARTIAL_REGEXP, or IN_LIST with "values": [<strings>]. Optional keys: "case_sensitive" (default false) and "not": true to exclude matches. Example: [{"field": "sessionDefaultChannelGroup", "op": "EXACT", "value": "Paid Search"}].

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.27.1
    • addedInput schema / properties / compare_end
      Added value: +{
+  "default": "",
+  "description": "End of the comparison period.",
+  "type": "string"
+}
    • addedInput schema / properties / compare_start
      Added value: +{
+  "default": "",
+  "description": "Start of the comparison period (same formats as\ndate_range_start). Set together with compare_end.",
+  "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: \"today\", \"yesterday\", \"NdaysAgo\" (e.g.\n\"7daysAgo\", \"28daysAgo\", \"90daysAgo\"), or \"YYYY-MM-DD\"."
    • addedInput schema / properties / dimension_filter
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Conditions on dimensions, all of which must hold\n(AND). Each is {\"field\": <dimension>, \"op\": <match>, \"value\":\n<string>}; op is EXACT (default), BEGINS_WITH, ENDS_WITH,\nCONTAINS, FULL_REGEXP, PARTIAL_REGEXP, or IN_LIST with \"values\":\n[<strings>]. Optional keys: \"case_sensitive\" (default false) and\n\"not\": true to exclude matches. Example: [{\"field\":\n\"sessionDefaultChannelGroup\", \"op\": \"EXACT\", \"value\": \"Paid\nSearch\"}]."
+}
    • addedInput schema / properties / dimensions / description
      Added value: +"GA4 dimension API names, e.g. date, pagePath,\nsessionSource, sessionMedium, country, deviceCategory, eventName.\nCustom ones (customEvent:...) and every valid name are listed by\nlist_ga4_dimensions_and_metrics."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum number of rows returned (positive)."
    • addedInput schema / properties / metric_filter
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Conditions on metrics, applied after aggregation, all\nof which must hold (AND). Each is {\"field\": <metric>, \"op\": <op>,\n\"value\": <number>}; op is EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL,\nGREATER_THAN, GREATER_THAN_OR_EQUAL (or =, <, <=, >, >=), or\nBETWEEN with \"value\": [from, to]. Optional \"not\": true.\nExample: [{\"field\": \"sessions\", \"op\": \">\", \"value\": 100}]."
+}
    • addedInput schema / properties / metrics / description
      Added value: +"GA4 metric API names, e.g. sessions, totalUsers, newUsers,\nscreenPageViews, keyEvents, eventCount, bounceRate."
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "Zero-based row offset for paging; pass next_offset from the\nprevious result to get the following page.",
+  "type": "integer"
+}
    • addedInput schema / properties / order_by
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Sort order as [{\"field\": <name>, \"desc\": true|false}]; each\nfield must be one of the requested dimensions or metrics."
+}
    • addedInput schema / properties / property_id / description
      Added value: +"GA4 property as \"properties/123456789\" (see\nget_account_summaries). If empty, uses the default from config."
  2. First observedv0.9.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description goes beyond that by disclosing error behavior ('Validation failed' with details, before anything is sent), the comparison-period semantics (dateRange values 'current'/'comparison', date_ranges mapping), and paging via next_offset — genuinely useful behavioral context for a read tool.

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?

Purpose is front-loaded, followed by constraints and comparison semantics. Some sentences restate the return shape (property, headers, row_count, next_offset) that the output schema already provides, which is mildly redundant, but the description remains organized and free of filler.

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?

For a 12-parameter tool with an output schema present, the description covers the key non-schema constraint (at least one dimension or metric), error behavior, and comparison-period mechanics. Given the output schema carries return values, the remaining omission (no explicit sibling routing) keeps it just short of fully complete.

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. The description adds a real constraint that the schema does not encode (0 required parameters): 'At least one dimension or metric is required', plus the semantic framing of compare_start/compare_end as a second date range. That is meaningful semantics beyond the schema, though most per-parameter detail lives in the schema.

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 custom GA4 report') with the scope qualifier 'custom', which implicitly separates it from standard/realtime reporting. The GA4 API reference and property/date-range framing make the tool's identity clear. It does not explicitly name which sibling to prefer instead (e.g., run_realtime_report, run_gsc_report, run_gaql), so it stops short of full sibling differentiation.

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

Usage Guidelines3/5

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

Usage is implied through constraints ('At least one dimension or metric is required') and a routing pointer for valid names ('list_ga4_dimensions_and_metrics'). There is no explicit when-to-use/when-not guidance relative to run_realtime_report, run_gsc_report, or run_gaql, so the agent must infer the boundary from the GA4 scope alone.

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