analytics-insights

Analytics Insights

Operator skill for the Google measurement stack — GA4, GTM, Search Console, and BigQuery — driven directly from chat. Build a tracking plan, run reports, mark conversions, audit existing setup, and query the warehouse without leaving the conversation.

Out of scope — defer to other skills

| Request | Send them to | | --- | --- | | Keyword research, AI-search visibility, full SEO audit | seo-research (HyperSEO toolkit — broader and richer than GSC for keyword work) | | Google Ads campaign performance | google-ads (campaign-level) — but GA4-side conversion attribution lives here | | Meta / Facebook ads metrics | meta-ads | | Email program metrics | email-lifecycle (provider-side) |

GSC and HyperSEO overlap on search-performance data. Rule of thumb: use GSC here for the user's own site's impression / click / position data. Use HyperSEO (in seo-research) for keyword research, competitor data, AI-search visibility.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• At least one of these connected at https://app.hyperfx.ai/integrations:
• Google Analytics — GA4 reports, custom metrics / dimensions, key-event (conversion) management.
• Google Tag Manager — tag / trigger / variable / workspace / version management.
• Google Search Console — search-performance data, sitemaps, URL inspection.
• BigQuery — SQL queries against the GA4 export (or any other dataset).

If google_analytics_run_ga4_report, gtm_tag, google_search_console_get_performance_data, and bigquery_execute_query are all missing from the agent's tool list, stop and tell the user to enable the Hyper MCP and connect at least one of these integrations.

Tool surface

| Group | Tools | | --- | --- | | GA4 — reporting | google_analytics_run_ga4_report, google_analytics_list_accounts, google_analytics_list_properties, google_analytics_get_property | | GA4 — properties & data streams | google_analytics_create_ga4_property, google_analytics_update_property, google_analytics_delete_property, google_analytics_create_data_stream, google_analytics_list_data_streams, google_analytics_get_data_stream, google_analytics_update_data_stream, google_analytics_delete_data_stream, google_analytics_get_data_retention_settings (read-only — no update variant in MCP), google_analytics_acknowledge_user_data_collection | | GA4 — key events (conversions) | google_analytics_create_key_event, google_analytics_list_key_events, google_analytics_get_key_event, google_analytics_update_key_event, google_analytics_delete_key_event | | GA4 — custom metrics / dimensions | google_analytics_create_custom_metric, google_analytics_list_custom_metrics, google_analytics_get_custom_metric, google_analytics_update_custom_metric, google_analytics_archive_custom_metric, google_analytics_create_custom_dimension, google_analytics_list_custom_dimensions, google_analytics_get_custom_dimension, google_analytics_update_custom_dimension, google_analytics_archive_custom_dimension | | GTM (note: prefixed gtm_*, not google_tag_manager_*) | gtm_account, gtm_container, gtm_workspace, gtm_tag, gtm_trigger, gtm_variable, gtm_built_in_variable, gtm_folder, gtm_environment, gtm_version, gtm_version_header, gtm_user_permission, gtm_client, gtm_template, gtm_transformation, gtm_zone, gtm_destination | | Google Search Console | google_search_console_get_performance_data, google_search_console_list_sites, google_search_console_list_sitemaps, google_search_console_get_sitemap, google_search_console_submit_sitemap, google_search_console_delete_sitemap, google_search_console_submit_url | | BigQuery | bigquery_execute_query, bigquery_insert_rows |

Critical rules

1. GA4 property IDs — arg name differs by tool. Three patterns: (a) Reporting tools (run_ga4_report, get_property) take property_id="properties/123456789". (b) Create and list tools (create_key_event, list_key_events, create_custom_dimension, list_custom_dimensions, etc.) take parent="properties/123456789". (c) Get/update/delete tools operate on a specific resource and take name= with the full resource path (e.g. "properties/123456789/keyEvents/12345"). All three need the properties/ prefix in some form — passing a bare numeric ID silently fails. When in doubt, check the tool's schema for which arg is marked required.
2. Date ranges are inclusive on both ends. start_date="2026-04-01" and end_date="2026-04-30" returns 30 days, not 29. Same for relative dates: 7daysAgo to today is 8 days, not 7.
3. GA4 sampling kicks in above ~10M events. For high-volume properties, the GA4 API silently samples results. If precision matters (board reporting, financial attribution), use the BigQuery GA4 export instead — see [references/bigquery-ga4-export.md](./references/bigquery-ga4-export.md).
4. Conversions in GA4 are "key events". GA4 renamed "conversions" to "key events" in 2024. The tools reflect this — use google_analytics_create_key_event to mark an event as a conversion. Don't get confused by older docs.
5. GTM changes need a workspace + version + publish. Tags / triggers / variables created in a workspace are not live until the workspace is committed to a new version and that version is published. Use gtm_workspace → modify → gtm_version (create) → publish.
6. GSC data has a 2–3 day lag. Don't query "yesterday" in GSC and expect data — query 3+ days back for stable numbers. GA4 has a 24-48h lag for some metrics.
7. Apple Mail Privacy Protection inflates GA4 "engaged" sessions from email. Don't trust email-driven engagement numbers in GA4 alone — cross-reference with the email provider's own click data.

Workflow — pick the right path

The skill covers four distinct jobs. Pick first; the workflows are different.

| The user wants… | Path | Reference | | --- | --- | --- | | A report ("how did we do last month?") | Phase R | — | | To set up tracking ("we need to measure X") | Phase T | [references/ga4-tracking-plan.md](./references/ga4-tracking-plan.md) | | To audit existing GTM / GA4 ("why is conversion data wonky?") | Phase A | [references/gtm-audit.md](./references/gtm-audit.md) | | Precise / unsampled / cross-source analysis | Phase B | [references/bigquery-ga4-export.md](./references/bigquery-ga4-export.md) |

Phase R — Run a report (most common path)

Quick-read option: For instant, no-sampling queries against cached GA4 data, try google_analytics_query_insights first — it's faster than the full API path and avoids the ~10M-event sampling threshold. Call it with a query= SQL string; the tool description lists available columns and the cached table name. If it returns "No data cached", read the suggestion field for the workspace-specific table name and retry. For cached GSC data, use google_search_console_query_insights with the same pattern. Fall through to Step 4 below for metrics not in the cache.

1. Confirm the property. google_analytics_list_accounts() → google_analytics_list_properties(filter="parent:accounts/<account_id>"). Ask the user to pick if there are multiple. Save the properties/<id> for the rest of the conversation.
2. Pick the date range. Always confirm. "Last 30 days" is start_date="30daysAgo", end_date="yesterday" (avoid today — partial-day data is unstable).
3. Pick metrics + dimensions. Don't blast 12 metrics × 6 dimensions in one report — the result is unreadable. Pick the 2–3 metrics that answer the user's question and the 1–2 dimensions that segment them meaningfully.
4. Run the report.

google_analytics_run_ga4_report(
  property_id="properties/123456789",
  start_date="30daysAgo",
  end_date="yesterday",
  metrics=["activeUsers", "sessions", "conversion