google-ads

Google Ads

Strategic guide for building new Google Ads campaigns. Research first, consult intelligently, validate everything, and use the blueprint flow for controlled creation.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Google Ads integration connected at https://app.hyperfx.ai/integrations.

If google_ads_list_accounts is not in the tool list, stop and tell the user to enable Hyper MCP and connect Google Ads.

Out of scope

• Ongoing optimization (search-term cleanup, bid adjustments, ad testing, restructuring existing campaigns) → defer to a future google-ads-operator skill.
• Creative generation (headlines, descriptions, images) → [ad-creative-generation](../ad-creative-generation).
• Cross-platform campaign launches → use this skill for Google, then invoke meta-ads / tiktok-ads separately.

Tool surface

| Tool | Purpose | | --- | --- | | google_ads_list_accounts | Discover accessible accounts (and MCC sub-accounts). | | google_ads_execute_gaql | Run a GAQL query (conversion actions, search term reports, etc.). | | google_ads_search_locations | Resolve human-readable location names to IDs. | | google_ads_list_assets, google_ads_upload_image_asset | Manage image assets for Display / PMax. | | google_ads_preview_blueprint, google_ads_create_from_blueprint | Validate + create Search/Display campaigns. | | google_ads_preview_pmax_blueprint, google_ads_create_from_pmax_blueprint | Validate + create Performance Max campaigns. |

Phase 1: Initial Setup

Call google_ads_list_accounts() to list accessible accounts.

• If multiple: ask the user to select one.
• If single: inform the user and proceed.

CRITICAL: Verify account access before any operations.

Phase 2: Discovery & Research (MANDATORY)

Research Steps

1. Get the real domain (ask; don't infer).
2. Scan the site end-to-end: home, product/service, pricing, about, FAQs, locations, contact, landing pages.
3. Understand funnel & goals: primary conversions, CTAs, forms/checkout, thank-you pages.
4. Extract messaging: value props, differentiators, proof, offers.

Conversion Tracking Check

Before asking questions, run the purpose-built diagnostic (simpler than a hand-rolled GAQL query):

google_ads_diagnose_conversion_tracking(customer_id="<from list_accounts>")

This returns all conversion actions, their status, and any tracking signal issues in one call. If the user's MCP doesn't expose google_ads_diagnose_conversion_tracking, fall back to GAQL:

google_ads_execute_gaql(
  customer_id="<from list_accounts>",
  query="""
    SELECT conversion_action.id, conversion_action.name,
           conversion_action.status, conversion_action.type
    FROM conversion_action
    WHERE conversion_action.status = 'ENABLED'
  """
)

google_ads_execute_gaql vs google_ads_run_gaql: execute_gaql works on manager accounts (MCC) and sub-accounts. run_gaql is only available on non-manager accounts. Use execute_gaql consistently — it works everywhere.

Market & Keyword Research

• Inspect SERPs, competitors, and themes.
• Propose keyword candidates (intent-aligned).
• Identify initial negatives.

Confirm Criticals

• Daily budget (+currency).
• Served geos.
• Constraints.
• Tracking status.

Phase 3: Consultation

Act as a partner, not order-taker:

• Present findings (site + GAQL + market).
• Recommend bidding (default Smart Bidding when tracking exists) with trade-offs.
• Propose structure (campaign → themed ad groups → keywords + match types).
• Suggest locations via google_ads_search_locations(customer_id="...", location_names="New York"). Note: location_names is a single string, not an array — pass a city, state, country, or postal code and the tool returns matching geo target IDs.
• Set budget expectations via benchmark ranges.
• Show reasoning for each choice.

Phase 4: Pre-Creation Summary (Must Be Approved)

Campaign Strategy for [Business Name]

Sources: [URL], GAQL
Conversion Setup: [GAQL findings]
Primary Goal: [objective + why]
Bidding: [strategy + why]
Budget: $[X]/day (expectations)
Locations: [targets + rationale]
Keyword Themes: [themes + match types + 2-3 examples]
Messaging: [angles pulled from site]
Trade-offs/Risks: [bullets]

Approve to proceed?

Wait for explicit approval. No emojis. No assumptions.

Phase 5: Campaign Creation (Blueprint System)

CRITICAL: Always use the blueprint system for campaign creation. It validates locally, fills smart defaults, resolves locations, and rolls back on failure.

Workflow: Preview → Confirm → Create

1. Build the blueprint JSON from research.
2. Call the preview tool to validate and show the user what will be created.
3. Get explicit user approval.
4. Call the create tool.

Search & Display Campaigns

Preview: google_ads_preview_blueprint(blueprint={...}) Create: google_ads_create_from_blueprint(blueprint={...})

{
  "customer_id": "1234567890",
  "name": "Campaign Name",
  "budget_amount_micros": 50000000,
  "advertising_channel_type": "SEARCH",
  "bidding_strategy": "MAXIMIZE_CLICKS",
  "status": "PAUSED",
  "location_names": ["New York", "Los Angeles"],  // array in blueprints; note: google_ads_search_locations takes a single string for manual lookup
  "conversion_action_ids": ["1234567890"],
  "ad_schedules": [
    {"day_of_week": "MONDAY", "start_hour": 9, "end_hour": 17}
  ],
  "sitelinks": [
    {"link_text": "Free Trial", "final_urls": ["https://example.com/trial"]}
  ],
  "callouts": [{"callout_text": "Free Shipping"}],
  "ad_groups": [
    {
      "name": "Ad Group 1",
      "keywords": [
        {"text": "marketing software", "match_type": "PHRASE"},
        {"text": "competitor brand", "match_type": "EXACT", "negative": true}
      ],
      "ads": [
        {
          "headlines": ["Headline 1", "Headline 2", "Headline 3"],
          "descriptions": ["Description 1", "Description 2"],
          "final_urls": ["https://example.com"]
        }
      ],
      "audiences": [{"audience_id": "1234567890"}]
    }
  ]
}

For Display campaigns, set "advertising_channel_type": "DISPLAY" and use display_ads instead of ads:

"display_ads": [{
  "headlines": ["Headline 1", "Headline 2", "Headline 3"],
  "long_headline": "Longer headline up to 90 characters",
  "descriptions": ["Description 1", "Description 2"],
  "business_name": "Business Name",
  "final_urls": ["https://example.com"],
  "marketing_image_asset_ids": ["1234567890"],
  "square_marketing_image_asset_ids": ["1234567891"],
  "logo_asset_ids": ["1234567892"]
}]

CRITICAL (Display): All three image asset types are REQUIRED:

- marketing_image_asset_ids — landscape 1.91:1 (e.g. 1200×628).

- square_marketing_image_asset_ids — square 1:1 (e.g. 1200×1200).

- logo_asset_ids — square 1:1 or landscape 4:1.

Performance Max Campaigns

Preview: google_ads_preview_pmax_blueprint(blueprint={...}) Create: google_ads_create_from_pmax_blueprint(blueprint={...})

{
  "customer_id": "1234567890",
  "name": "PMax Campaign",
  "budget_amount_micros": 50000000,
  "bidding_strategy": "MAXIMIZE_CONVERSIONS",
  "status": "PAUSED",
  "location_names": ["United States"],
  "conversion_action_ids": ["1234567890"],
  "asset_groups": [
    {
      "name": "Asset Group 1",
      "headlines": ["Headline 1", "Headline 2", "Headline 3"],
      "long_headlines": ["Longer headline up to 90 characters"],
      "descriptions": ["Description 1", "Description 2"],
      "business_name": "Business Name",
      "final_urls": ["https://example.com"],
      "marketing_image_asset_ids": ["1234567890"],
      "square_marketing_image_asset_ids": ["1234567891"],
      "logo_asset_ids": ["1234567892"]
    }
  ]
}

CRITICAL (PMax): All three image asset types are REQUIRED with correct aspect