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](https://app.hyperfx.ai/mcp) - **At least one of these connected** at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps): - **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_ga4_reports_run`, `google_tag_manager_tags_manage`, `google_search_console_performance_get`, 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. ### How to run the tools in this skill Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you: | Surface | Find a tool | Run it | | --- | --- | --- | | MCP client (Claude, Cursor, Codex, ChatGPT) | `search("<what you want to do>")`, then `describe("<name>")` | `call("<name>", {...})` | | Hyper CLI | `hyperai search "<what you want to do>"`, then `hyperai describe <name>` | `hyperai call <name> --json '{...}'` | If a tool is not found, its integration is not connected or not enabled for the workspace: stop and tell the user which integration to connect. ## Tool surface | Group | Tools | | --- | --- | | GA4 — reporting | `google_analytics_ga4_reports_run`, `google_analytics_accounts_list`, `google_analytics_properties_list`, `google_analytics_properties_get` | | GA4 — properties & data streams | `google_analytics_ga4_properties_create`, `google_analytics_properties_update`, `google_analytics_properties_delete`, `google_analytics_data_streams_create`, `google_analytics_data_streams_list`, `google_analytics_data_streams_get`, `google_analytics_data_streams_update`, `google_analytics_data_streams_delete`, `google_analytics_data_retention_get` *(read-only — no update variant in MCP)*, `google_analytics_data_collection_acknowledge` | | GA4 — key events (conversions) | `google_analytics_key_events_create`, `google_analytics_key_events_list`, `google_analytics_key_events_get`, `google_analytics_key_events_update`, `google_analytics_key_events_delete` | | GA4 — custom metrics / dimensions | `google_analytics_custom_metrics_create`, `google_analytics_custom_metrics_list`, `google_analytics_custom_metrics_get`, `google_analytics_custom_metrics_update`, `google_analytics_custom_metrics_archive`, `google_analytics_custom_dimensions_create`, `google_analytics_custom_dimensions_list`, `google_analytics_custom_dimensions_get`, `google_analytics_custom_dimensions_update`, `google_analytics_custom_dimensions_archive` | | GTM | `google_tag_manager_accounts_manage`, `google_tag_manager_containers_manage`, `google_tag_manager_workspaces_manage`, `google_tag_manager_tags_manage`, `google_tag_manager_triggers_manage`, `google_tag_manager_variables_manage`, `google_tag_manager_built_in_variables_manage`, `google_tag_manager_folders_manage`, `google_tag_manager_environments_manage`, `google_tag_manager_versions_manage`, `google_tag_manager_version_headers_manage`, `google_tag_manager_user_permissions_manage`, `google_tag_manager_clients_manage`, `google_tag_manager_templates_manage`, `google_tag_manager_transformations_manage`, `google_tag_manager_zones_manage`, `google_tag_manager_destinations_manage` | | Google Search Console | `google_search_console_performance_get`, `google_search_console_sites_list`, `google_search_console_sitemaps_list`, `google_search_console_sitemaps_get`, `google_search_console_sitemaps_submit`, `google_search_console_sitemaps_delete`, `google_search_console_urls_submit` | | 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_key_events_create` 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 `google_tag_manager_workspaces_manage` → modify → `google_tag_manager_versions_manage` (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) **Warehouse option:** When the workspace has an analytics warehouse connection, discover its tables and schema and query them through `database_query`. Read Warehouse Data Status for the selected connection and report its last successful refresh; do not assume an hourly cache or unsampled data. Otherwise use `google_analytics_ga4_reports_run` for GA4 and `google_search_console_performance_get` for GSC. Keep account IDs, dates and metric definitions explicit. 1. **Confirm the property.** `google_analytics_accounts_list()` → `google_analytics_properties_list(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_ga4_reports_run( property_id="properties/123456789", start_date="30daysAgo", end_date="yesterday", metrics=["activeUsers", "sessions", "conversions", "totalRevenue"], dimensions=["sessionDefaultChannelGroup", "deviceCategory"], ) ``` 5. **Present results as a table.** Always show the raw numbers alongside any interpretation. "Organic search drove 12,400 sessions (+18% MoM)" beats "organic was up." 6. **One follow-on if the data flags it.** If a metric stands out (e.g., conversion rate dropped 40% on mobile), run *one* targeted follow-up report — don't speculate. #### Common GA4 metrics & dimensions The GA4 API uses camelCase names. The most useful: **Metrics:** `activeUsers`, `sessions`, `screenPageViews`, `bounceRate`, `engagementRate`, `averageSessionDuration`, `conversions`, `eventCount`, `totalRevenue`, `transactions`, `purchaseRevenue`, `userEngagementDuration`. **Dimensions:** `country`, `city`, `deviceCategory`, `operatingSystem`, `browser`, `sessionDefaultChannelGroup`, `sessionSource`, `sessionMedium`, `sessionCampaignName`, `pagePath`, `eventName`, `date`, `hour`, `landingPage`. For the full list, the user can browse the [GA4 Data API reference](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema). ### Phase T — Set up tracking The GA4 API can create properties, data streams, key events, custom metrics, and custom dimensions — but it **can't deploy GTM tags into the page**. That step is GTM-side (or hard-coded in the site). The skill workflow: 1. **Tracking plan first.** Define what events you need to fire, where they fire, and which ones are conversions (key events). Full template in [`references/ga4-tracking-plan.md`](./references/ga4-tracking-plan.md). 2. **GA4-side setup** — create custom dimensions / metrics, mark key events: ``` google_analytics_custom_dimensions_create( parent="properties/123456789", parameter_name="plan_tier", display_name="Plan Tier", scope="EVENT", ) google_analytics_key_events_create( parent="properties/123456789", event_name="purchase", counting_method="ONCE_PER_EVENT", ) ``` 3. **GTM-side setup** — create/update tags + triggers + variables in a workspace, then version + publish: ``` google_tag_manager_workspaces_manage(operation="create", account_id="...", container_id="...", name="purchase-tracking-v3") google_tag_manager_tags_manage(operation="create", workspace_path="...", tag_definition={...}) google_tag_manager_triggers_manage(operation="create", workspace_path="...", trigger_definition={...}) google_tag_manager_variables_manage(operation="create", workspace_path="...", variable_definition={...}) google_tag_manager_versions_manage(operation="create", workspace_path="...", version_name="purchase-tracking-v3") # then publish via the GTM UI or version operation ``` 4. **Validate** — see Phase A. ### Phase A — Audit (the existing setup is broken or suspect) Most "our analytics is wrong" complaints are one of: | Symptom | Likely cause | How to confirm | | --- | --- | --- | | Conversion event not appearing in GA4 | Event firing in GTM but not reaching GA4 (wrong measurement ID, blocked by consent gate, ad blocker) | `google_analytics_ga4_reports_run` for `eventName=purchase` over the last 7d → if 0, check GTM | | Conversion count wildly off | Event firing on every page (not just confirmation), or duplicate tags | Audit GTM tags via `google_tag_manager_tags_manage(operation="list")`, check for multiple tags firing on the same trigger | | Revenue reported differently in GA4 vs the platform of record | Currency mismatch, refund handling, attribution window | Pull both side-by-side, look for refund / currency rows | | Suddenly mobile traffic dropped to ~0 | Tag firing only on desktop trigger, or a recent GTM publish broke the mobile container | `google_tag_manager_versions_manage(operation="list")` to find recent publishes, diff with previous version | | GSC clicks ≠ GA4 organic sessions | Always different — different definitions. Don't try to reconcile exactly. | Expected; document and move on | Detailed audit walkthrough in [`references/gtm-audit.md`](./references/gtm-audit.md). ### Phase B — BigQuery GA4 export (precision / cross-source analysis) For unsampled data, custom attribution, joining GA4 with order-DB / CRM data, or cohort analysis. Requires the GA4 → BigQuery export to be turned on in the GA4 admin (free for standard properties since 2023). ``` bigquery_execute_query( query=""" SELECT event_date, COUNT(DISTINCT user_pseudo_id) AS users, COUNTIF(event_name = 'purchase') AS purchases, SUM(IF(event_name = 'purchase', ecommerce.purchase_revenue, 0)) AS revenue FROM `your-project.analytics_123456789.events_*` WHERE _TABLE_SUFFIX BETWEEN '20260401' AND '20260430' GROUP BY event_date ORDER BY event_date """ ) ``` Schema, common queries, and the full attribution-modeling workflow in [`references/bigquery-ga4-export.md`](./references/bigquery-ga4-export.md).