Tools Reference

You don't call these tools yourself: your AI client picks them from your question. This page helps you phrase questions, and explains what the answers are based on. All 12 tools are read-only.

Property IDs are the numeric GA4 IDs, such as 123456789 (properties/123456789 works too). Measurement IDs like G-XXXXXXX don't work. get_account_summaries lists the IDs, so you can just name the property in your question.

Connection tools

Your AI client uses these to connect the computer to your free Tag Pilot account and Google. You don't need a terminal: just say "connect GA4", or ask a data question.

connect

Starts connecting (or reuses a connect already in progress) and returns a clickable link and a code like ABCD-1234. Open the link in any browser, check the code, approve, and allow Google access. Clients that support MCP URL elicitation also offer to open the link for you. If the computer is already connected, it says so. No parameters.

connection_status

Whether this computer is connected:

Data tools called before the computer is connected return the same link and code, and the AI client retries your question once you've approved.

Property and setup tools

get_account_summaries

Every GA4 account and property the signed-in Google account can read: account ID and name, and for each property its ID, name and type. Your AI client usually calls this first. No parameters.

"Which GA4 properties do I have access to?"

get_property_details

A property's time zone, currency, industry, service level (standard or 360), create and update times, and its data streams with their web measurement IDs (G-…), default URLs or app IDs.

"What currency and time zone is the Shop property set to, and which measurement ID does its web stream use?"

list_google_ads_links

Google Ads accounts linked to a property: customer ID, whether ads personalization is on, and who created the link and when.

"Is Google Ads linked to this property? Which customer IDs?"

list_property_annotations

Reporting annotations: notes on dates or date ranges, such as releases, tracking changes or campaigns, including ones Google added. Handy to explain a jump in the data.

"Sessions dropped in early October. Are there any annotations around that time?"

get_custom_dimensions_and_metrics

The property's custom dimensions (with scope: event, user or item) and custom metrics, with the API names to use in reports, such as customEvent:payment_type or customUser:plan.

"Which custom dimensions does this property have? Is there one for the logged-in user type?"

Report tools

run_report

The main GA4 report (Data API runReport): metrics broken down by dimensions over one or more date ranges.

Standard dimension and metric names are in Google's API schema. Custom ones come from get_custom_dimensions_and_metrics.

"Top 10 landing pages by sessions in the last 7 days, with engagement rate."

run_realtime_report

Active users and events in the last 30 minutes (60 on GA4 360). Useful to check that a tracking change is live.

"I just published the GTM container. Are add_to_cart events coming in right now?"

run_funnel_report

How many users reach each step of a funnel and where they drop off (Data API runFunnelReport). Google's funnel API is still in alpha, so it can change or fail more often than other reports.

Each step has:

A step needs event_name, conditions or both. The empty operator isn't available in funnel steps. Each step in the result has activeUsers, funnelStepCompletionRate, funnelStepAbandonments and funnelStepAbandonmentRate.

"Show the funnel view_item → add_to_cart → begin_checkout → purchase for the last 30 days, split by device."

Tag Pilot tracking-health checks

These two checks are opinionated rules of thumb built from a few run_report calls. Every result shows what it measured, and the thresholds below are Tag Pilot's suggestions, not GA4 rules. They use the same GA4 quota as the equivalent reports.

check_duplicate_transactions

Counts purchase events per transaction_id to find purchases tracked more than once (usually thank-you page reloads, or the same order sent by both a browser tag and a server-side or Measurement Protocol tag), and purchases with no transaction_id at all. Uses 3 report calls.

The result has a summary (purchase events, distinct and duplicated transaction IDs, extra purchase events, duplicate rate, purchases without an ID), findings in plain words, and top_duplicates with each ID's purchase event count and revenue. It flags a duplicate rate of 2% or more, and 1% or more of purchases without an ID.

"Do we have duplicate purchases in GA4 this month?"

check_traffic_attribution

How sessions split by default channel group, with the attribution problems flagged. Uses 4 report calls.

The result has total_sessions, the shares in percent, findings with likely causes, sessions per channel, and the top source / medium pairs of Unassigned sessions. It flags:

"Check traffic attribution on the Shop property for September and explain the Unassigned traffic."

Report inputs

Dates

A date is YYYY-MM-DD, today, yesterday or NdaysAgo (e.g. 7daysAgo, 28daysAgo). The default range is the last 28 full days: 28daysAgo to yesterday. Dates are in the property's time zone.

[{"start_date": "2026-09-01", "end_date": "2026-09-30"}]

Pass up to 4 ranges to compare periods. Each row then gets a dateRange column with the range's name (or date_range_0, date_range_1, … when unnamed):

[
  {"start_date": "7daysAgo", "end_date": "yesterday", "name": "this_week"},
  {"start_date": "14daysAgo", "end_date": "8daysAgo", "name": "last_week"}
]

Filters

A filter is a list of conditions that must all match. {"any": [...]} groups conditions where at least one must match, and "not": true negates a condition:

[
  {"field": "eventName", "op": "exact", "value": "purchase"},
  {"field": "country", "op": "in_list", "values": ["Poland", "Germany"], "not": true},
  {"any": [
    {"field": "pagePath", "op": "begins_with", "value": "/shop"},
    {"field": "pagePath", "op": "partial_regex", "value": "product"}
  ]}
]

Text matching ignores case unless you add "case_sensitive": true. Dimension filters (dimension_filter) and metric filters (metric_filter) are separate, as in GA4: a metric filter such as [{"field": "sessions", "op": "gt", "value": 100}] applies after aggregation.

Sorting

[{"field": "sessions", "desc": true}]

The field must be one of the request's dimensions or metrics. For dimensions you can add "dimension_order": alphanumeric, case_insensitive_alphanumeric or numeric (for number-like dimensions stored as text).

Results

Reports come back as JSON your AI client reads for you:

{
  "row_count": 214,
  "returned": 100,
  "next_offset": 100,
  "rows": [{"date": "20261026", "sessionDefaultChannelGroup": "Organic Search", "sessions": 321}],
  "currency_code": "EUR",
  "time_zone": "Europe/Warsaw",
  "notes": ["Subject to thresholding: …"]
}

• next_offset appears when more rows exist; the next call passes it as offset.
• totals, maximums and minimums appear when requested with metric_aggregations.
• notes explain caveats: thresholding, sampling, values grouped into (other), or why a result is empty. See Troubleshooting.
• property_quota appears with return_property_quota: true.