/utm-builder

name: utm-builder
description: UTM Parameter Strategy & Builder — naming conventions, GA4 channel grouping rules, auto-tagging, common mistakes, and BigQuery validation queries
version: "1.1.3"
author: Cogny AI
platforms: []
user-invocable: true
argument-hint: "<query or topic>"
allowed-tools:
  - WebSearch
  - Read
  - Write
  - Bash
  # GA4 tools (when connected via Cogny MCP)
  - mcp__cogny__refresh_mcp_discovery
  - mcp__cogny__mcp__Google_Analytics_4__tool_list_account_summaries
  - mcp__cogny__mcp__Google_Analytics_4__tool_run_report
  - mcp__cogny__mcp__Google_Analytics_4__tool_get_property
  - mcp__cogny__mcp__Google_Analytics_4__tool_list_data_streams
  # Google Ads tools
  - mcp__cogny__mcp__Google_Ads__tool_execute_gaql
  # Other sources for a live UTM audit (when connected, read-only)
  - mcp__cogny__list_integrations
  - mcp__cogny__mcp__Plausible__breakdown
  - mcp__cogny__mcp__Fathom_Analytics__list_sites
  - mcp__cogny__mcp__Fathom_Analytics__aggregate
  - mcp__cogny__mcp__Meta_Ads__tool_list_ad_accounts
  - mcp__cogny__mcp__Meta_Ads__tool_get_ads
  - mcp__cogny__mcp__X_Ads__tool_list_ad_accounts
  - mcp__cogny__mcp__X_Ads__tool_get_cards
  - mcp__cogny__mcp__LinkedIn_Ads__tool_list_ad_accounts
  - mcp__cogny__mcp__LinkedIn_Ads__tool_get_creatives

UTM Parameter Strategy & Builder Reference

Complete guide to UTM parameter strategy, naming conventions, GA4 default channel grouping rules, auto-tagging behavior, common mistakes, and BigQuery validation queries for marketing attribution.

Full docs: https://cogny.com/docs/utm-strategy

Usage

/utm-builder                          # Full UTM strategy overview
/utm-builder naming conventions       # Show naming convention rules
/utm-builder channel grouping         # GA4 default channel grouping rules
/utm-builder meta ads                 # Meta Ads UTM template
/utm-builder audit                    # BigQuery validation queries
/utm-builder build google cpc         # Generate UTM URL for Google Ads

Instructions

You are a UTM strategy and marketing attribution expert. Use this reference to help users build correct UTM URLs, audit existing UTM naming conventions, understand GA4 default channel grouping rules, and validate attribution data in BigQuery.

When the user asks a question, find the relevant section below and provide precise, actionable answers. When building UTM URLs, always enforce lowercase and hyphen-separated naming conventions.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of UTM strategy fundamentals.

When connected to Cogny MCP tools, you can pull live GA4 data and Google Ads data to audit real UTM implementations.

Works with

Works with zero accounts: building UTMs and the naming rules need nothing connected. For `/utm-builder audit`:

| Job | Primary | Also answered by | No account | |-----|---------|------------------|------------| | UTMs as they arrive on the site | GA4 `tool_run_report` | Plausible `breakdown`, Fathom Analytics `aggregate` | BigQuery queries below | | UTMs as set in the ads | Google Ads `tool_execute_gaql` | Meta `tool_get_ads`, LinkedIn `tool_get_creatives`, X `tool_get_cards` | ask for an export | | Fix a Meta ad set's URL tags | — | Meta `tool_update_ad_set_url_tags` (write: not pre-approved, asks first) | — |

See "Live UTM Audit" below.

---

The Five UTM Parameters

| Parameter | Required | Purpose | Example | |-----------|----------|---------|---------| | `utm_source` | Yes | Platform or publisher sending traffic | `google`, `facebook`, `linkedin`, `newsletter` | | `utm_medium` | Yes | Marketing channel type | `cpc`, `paid-social`, `email`, `organic-social` | | `utm_campaign` | Yes | Specific campaign name | `spring-sale-2025`, `brand-awareness-q1` | | `utm_term` | No | Paid search keywords | `running+shoes`, `crm+software` | | `utm_content` | No | Creative variant or link placement | `hero-banner`, `sidebar-cta`, `blue-variant` |

Parameter Details

**utm_source** — Where did the click physically happen?

utm_source=google          # Google Ads or Google organic
utm_source=facebook        # Meta Ads (Facebook/Instagram)
utm_source=linkedin        # LinkedIn Ads or organic
utm_source=twitter         # X Ads or organic. GA4 still lists X as "twitter": "x" lands in Organic Search, "x.com" in Referral, "xads" in Paid Other
utm_source=klaviyo         # Email via Klaviyo
utm_source=tiktok          # TikTok Ads
utm_source=partner-blog    # A specific referral partner

**utm_medium** — The channel type. This is the most important parameter for GA4 default channel grouping. If utm_medium is wrong, traffic lands in the wrong channel.

utm_medium=cpc             # Cost-per-click (paid search)
utm_medium=paid-social     # Paid social ads (needs a social utm_source; see channel rules)
utm_medium=email           # Email marketing
utm_medium=organic-social  # Organic social posts
utm_medium=display         # Display/banner ads
utm_medium=affiliate       # Affiliate traffic
utm_medium=referral        # Partner/referral traffic
utm_medium=video           # Lands in Organic Video; for paid video use utm_source=youtube + utm_medium=cpc

**utm_campaign** — Campaign name with consistent structure:

utm_campaign=spring-sale-2025
utm_campaign=brand-awareness-q1-2025
utm_campaign=retargeting-cart-abandoners

**utm_term** — Keyword or targeting term:

utm_term=running-shoes
utm_term=best-crm-software

**utm_content** — Creative variant or placement:

utm_content=hero-image-v1
utm_content=sidebar-cta
utm_content=video-30s

GA4 Default Channel Grouping Rules

GA4 classifies every session into a default channel group from its `source`, `medium` and `campaign`. Rules below are for manually tagged (UTM) traffic. Google's page lists the channels alphabetically and doesn't document an evaluation order, so read the table as conditions, not a ranked list; when a combination looks a