Skip to main content
AdLoop reads your GA4 property: custom reports with any dimensions and metrics, realtime data, funnels, model-based attribution, the property’s configuration and the events it receives. It can also change the property’s key events, annotations, custom dimensions and metrics and data retention, and set up conversion tracking into Google Ads in one step, each through the same preview → confirm_and_apply gate as every other write. Combined with Google Ads, it answers the questions neither tool answers alone: real cost per conversion, landing pages that get paid traffic but do not convert, and whether conversions reach Google Ads at all. Analytics shares one Google connection with Google Ads, Tag Manager, Search Console and Merchant Center. How this compares with Google’s own Analytics MCP server: Google Analytics MCP, explained.

Connect

The onboarding wizard (later: Settings → Google → Connect Google account) asks which Google products your AI may use. Keep Google Analytics (GA4) ticked; Google’s consent dialog then asks to view your Analytics data and to manage your Analytics settings. The manage permission is only used by the write tools below (key events, annotations, custom dimensions and metrics, data retention, and the link to Google Ads), each applied after your approval; Google has no narrower permission for them.Then pick the property. I do not use Google Analytics switches the Analytics tools off; a workspace needs at least one of Google Ads or Analytics, so an Analytics-only workspace works too. Agencies pick a property per client under Settings → Clients (see Clients).If you untick the manage permission in Google’s dialog, reports keep working and only the write tools are unavailable; the dashboard shows the missing permission, and reconnecting restores it with all settings kept.

Reports

  • GA4’s own names. run_ga4_report takes dimensions and metrics by their GA4 API names (sessionSource, pagePath, deviceCategory, sessions, totalUsers, keyEvents, …). list_ga4_dimensions_and_metrics lists every name the property offers, custom ones included. Dates are today, yesterday, NdaysAgo or YYYY-MM-DD; without a range the report covers the last seven days.
  • Filters with OR. Conditions in dimension_filter and metric_filter must all hold; a group {"any_of": [...]} matches when any of its conditions holds, {"all_of": [...]} when all do, and both take "not": true.
  • Several periods at once. compare_start/compare_end adds a comparison period; date_ranges takes up to four named periods, for example October this year and last year. Rows then carry the period’s name.
  • Numbers you can trust, or a note why not. GA4 thresholds rows with few users (usually because of Google signals), samples large reports, and groups rows into “(other)” at its row limits. Each of these makes a report differ from the GA4 interface, and insights[] says when it happened. It also warns when the property is close to its daily API quota.
  • Annotations in context. Reports over time (a date dimension) or comparing periods return the property’s annotations within those dates, so a jump in the rows comes with the note someone left that day.
  • Row limits are visible. A report returns 100 rows unless you raise limit, and total_row_count tells you how many exist.
  • Realtime for deploys. run_realtime_report shows active users and events right now, filtered (for example on the event you just shipped), sorted, and for up to two minute windows such as the last five minutes against the 25 before.
  • Fewer sessions than ad clicks is normal. GA4 only sees visitors who accepted analytics cookies, while Google Ads counts every click. In EU traffic a ratio of two to five clicks per session is common and not a tracking fault. The tracking tools (analyze_campaign_conversions, attribution_check, landing_page_analysis) take this into account. Background in Consent and data gaps.

Funnels and attribution

run_ga4_funnel measures how many users get from one step to the next. Steps are event names exactly as they fire, or pages ({"page": "/checkout"} matches page views whose URL contains the text), optionally “directly followed” or “within N minutes” of the previous step. The result lists users, completion and abandonment per step, the overall completion rate and the biggest drop. breakdown splits every step by a dimension such as device or channel, next_action shows what users did next instead of continuing. A closed funnel (the default) counts only users who start at step 1. run_ga4_attribution is GA4’s model-based view of conversions: conversions, revenue, ad cost and ROAS by channel, campaign, source, country or device, attributed by data-driven or last-click attribution rather than by session. COMPARE runs both models and shows each row’s share of the credit under both, with the channels that gain or lose most named in insights[]. Conversions can be named by key event (["purchase"]). Ad cost and ROAS need Google Ads linked to the property. Both use Google’s Data API v1alpha, the same endpoints GA4’s explorations and advertising reports use. Google is still rolling the attribution report out; a property without it gets an explanation and a fallback (run_ga4_report with keyEvents by channel) instead of an error.

Property setup

get_ga4_property returns the property’s configuration in one call: time zone, currency, standard or 360, the linked Google Ads accounts, the data streams with their measurement IDs, data retention and the number of key events. audit_ga4_property checks the settings that quietly cost data and returns them as warnings, notes and passes:
  • data retention left at GA4’s two-month default, which cuts explorations and funnels short;
  • no Google Ads link, or the Ads account AdLoop works with not being the linked one;
  • data streams that sent nothing in the last seven days;
  • key events that never fired in 28 days, or no key events at all;
  • enhanced measurement per web stream, and Google signals with the thresholding they cause;
  • custom dimension and metric slots nearly used up.
Whether Google Ads actually receives the key events is check_key_event_imports in the tracking audit: it reads Google Ads too. What the checks find is fixed with the tools under Changes: two-month retention with draft_ga4_data_retention, a missing Ads link or import with draft_conversion_tracking_setup.

Changes

All of them are previewed and applied with confirm_and_apply or on the approval card. The Admin API has no validate-only mode, so the dry run re-reads what the plan changes instead: a create checks for duplicates and the property’s limits again, an update, delete or archive checks that nobody changed the item in GA4 since the preview. Either way a failed check stops the apply.
  • Key events. draft_key_event marks an event as a key event, with counting method ONCE_PER_EVENT (purchases) or ONCE_PER_SESSION (sign-ups) and an optional default value (a lead worth 20 EUR). For an event that already is one, it changes the counting method or value instead and the preview shows before and after. draft_delete_key_event stops an event counting as a conversion; the event keeps firing. Both apply to future data only, and for Google Ads to optimise on a key event the property must be linked and the conversion imported.
  • Annotations. draft_ga4_annotation creates, changes or deletes a note on a date or date range (list_ga4_annotations lists them). Annotations Google created itself cannot be changed.
  • Custom dimensions and metrics. draft_ga4_custom_dimension registers an event parameter, user property or ecommerce item parameter as a dimension; draft_ga4_custom_metric a numeric event parameter as a metric. Both rename and archive too. The draft refuses a parameter that is already registered, a taken display name and a property without free slots (list_ga4_custom_definitions shows them). GA4 fills a new definition only from the moment it exists, and its parameter name and scope cannot change later; the preview says both. Archiving cannot be undone and asks for a double confirmation.
  • Audiences. draft_ga4_audience creates an audience from events: users who sent any of include_events, without those who sent any of exclude_events. ["session_start"] is every visitor, ["purchase"] is buyers, and visitors without purchase are the people who came but did not buy. A linked Google Ads account receives the audience as a remarketing list within one to two days, ready for draft_audience_attachment. GA4 fixes the events and the membership duration (1 to 540 days) at creation: afterwards only the name and description can change, and archiving is permanent, so it asks for a double confirmation. list_ga4_audiences shows what exists and checks whether audiences reach Google Ads at all: the Ads link, personalized advertising on it and Google signals. A list serves only from 100 active users in the last 30 days, and visitors who decline your consent banner do not join. Audiences built in GA4 with page or sequence conditions are listed but cannot be created here yet.
  • Data retention. draft_ga4_data_retention sets how long GA4 keeps event- and user-level data: 2 or 14 months on a standard property, up to 50 on GA4 360. It limits explorations, funnels and other user-level reports; standard reports are aggregated and not affected. Longer retention only helps from now on. Shorter retention makes GA4 delete the older data, so it asks for a double confirmation. If your privacy policy names how long Analytics data is kept, update it with the setting.
Your Google user needs edit access to the property (Marketer or Editor for key events, Editor for custom definitions and data retention).

Conversion tracking into Google Ads, in one step

For Google Ads to bid on a GA4 conversion, six things have to be right in two products: the property linked to the Ads account, the event marked as a key event, auto-tagging on in Google Ads, the conversion imported (Google Ads creates a hidden conversion action per key event when you link, and it records nothing until imported), the import set to primary, and its goal used for bidding. draft_conversion_tracking_setup reads all of them and plans only what is missing, on one approval card. Ask your AI to “set up conversion tracking for sign_up”, or let it offer the tool after check_key_event_imports finds a gap.
  • Without events, it takes the key events that fired in the last 28 days. Events that never fired are left out and named, because the website has to send them first (tracking code).
  • Imports are primary by default; primary=false imports them as secondary conversions (reported, not bid on).
  • A new link keeps personalized advertising off, so GA4 shares no audiences or remarketing data with Google Ads, unless you ask for it (ads_personalization). Linking needs Editor on the property and admin access to the Ads account.
  • Google Ads creates the conversion action for a newly linked property or a new key event by itself, but not instantly. The preview lists those events under “After this”; running the setup again later imports them.
  • data_retention=14 lengthens retention in the same plan.
The dry run sends the Google Ads steps to Google in validate-only mode and re-reads the GA4 ones. Each step checks its target again before acting and skips itself when it is already done, so if one step fails, the error names it and confirming the same plan again continues from there.

Annotations for ad changes

When AdLoop applies a change that moves traffic, such as a budget, bidding, targeting or status change in Google Ads or Reddit Ads, the result carries a ready annotation for GA4 (suggested_annotation: title, date, description), and the approval card mentions it in its chat message. Your AI offers to add it; writing it to GA4 is a separate change you approve, because the property may be a client’s. Later, the jump in the GA4 charts has its explanation.

Tools

Reads: get_account_summaries (accounts and properties you can reach), get_ga4_property, audit_ga4_property, run_ga4_report, run_realtime_report, run_ga4_funnel, run_ga4_attribution, get_tracking_events (every event the property received, with counts), list_key_events, list_ga4_dimensions_and_metrics, list_ga4_annotations, list_ga4_custom_definitions, list_ga4_audiences. Writes (previewed): draft_key_event, draft_delete_key_event, draft_ga4_annotation, draft_ga4_custom_dimension, draft_ga4_custom_metric, draft_ga4_audience, draft_ga4_data_retention, and draft_conversion_tracking_setup (GA4 and Google Ads together). The full list with parameters is in the tool reference; the toolset slug is ga4. The tools that join Analytics with Google Ads or your codebase (analyze_campaign_conversions, attribution_check, check_key_event_imports, draft_conversion_tracking_setup, landing_page_analysis, validate_tracking, generate_tracking_code) are in the tracking toolset, and the three-way audit across your code, Tag Manager and GA4 (audit_event_coverage) is in gtm. How they fit together is on Tracking audit.

Operations and limits

On AdLoop Cloud, every Analytics tool, writes included, is unmetered and does not count toward your operations. The tracking tools that also read or change Google Ads do count, draft_conversion_tracking_setup included. See plans and limits. Google’s own GA4 API quotas apply on every setup.

What AdLoop stores

On AdLoop Cloud: the encrypted refresh token shared by all Google products, your Google email address, the permissions you granted, and the selected property (ID and name). Report data passes through and is never stored. Self-hosted, the token stays in ~/.adloop/token.json on your machine. See the privacy policy for the full description.