Google Ads MCP Navigator

Google Ads MCP Navigator

This skill provides efficient navigation of the Google Ads MCP tool, reducing context overhead by documenting common query patterns, curated field lists, and RDC-specific account configurations.

Quick Reference

RDC Account IDs

Run list_accessible_customers to get current account IDs

Core Resources

Metrics Resource

All performance metrics come from the metrics resource and must be joined with a primary resource.

Workflow

1. Identify the analysis type:

   • Campaign performance → campaign + metrics
   • Keyword analysis → ad_group_criterion or keyword_view + metrics
   • Search query mining → search_term_view + metrics
   • Auction insights → auction_insight resource (special)
   • Geographic performance → geographic_view + metrics

2. Load field references:

   • Campaign fields → references/campaign_fields.md
   • Metrics fields → references/metrics_fields.md
   • Segment fields → references/segment_fields.md

3. Apply required conditions:

   • Always filter by date range (required for metrics)
   • Filter by campaign status for active-only analysis
   • Use segments for dimensional breakdowns

Essential Field Lists

Campaign Performance (Minimal)

Fields: campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, 
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, 
        metrics.conversions_value
Resource: campaign
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Keyword Performance (Minimal)

Fields: ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type,
        ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks,
        metrics.cost_micros, metrics.conversions
Resource: ad_group_criterion
Conditions: ad_group_criterion.type = 'KEYWORD', segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Search Terms (Minimal)

Fields: search_term_view.search_term, search_term_view.status, 
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions
Resource: search_term_view
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Geographic Performance (Minimal)

Fields: geographic_view.location_type, segments.geo_target_region,
        metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions
Resource: geographic_view
Conditions: segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'

Common Query Patterns

Campaign Summary (Last 30 Days)

resource: "campaign"
fields: [
    "campaign.id",
    "campaign.name", 
    "campaign.status",
    "campaign.advertising_channel_type",
    "campaign.bidding_strategy_type",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions",
    "metrics.conversions_value",
    "metrics.search_impression_share"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "campaign.status = 'ENABLED'"
]

Keyword Quality Score Analysis

resource: "ad_group_criterion"
fields: [
    "campaign.name",
    "ad_group.name",
    "ad_group_criterion.keyword.text",
    "ad_group_criterion.keyword.match_type",
    "ad_group_criterion.quality_info.quality_score",
    "ad_group_criterion.quality_info.creative_quality_score",
    "ad_group_criterion.quality_info.post_click_quality_score",
    "ad_group_criterion.quality_info.search_predicted_ctr",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros"
]
conditions: [
    "ad_group_criterion.type = 'KEYWORD'",
    "ad_group_criterion.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Search Query Mining

resource: "search_term_view"
fields: [
    "campaign.name",
    "ad_group.name",
    "search_term_view.search_term",
    "search_term_view.status",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions",
    "metrics.conversions_value"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "metrics.impressions > 0"
]
orderings: ["metrics.cost_micros DESC"]
limit: 1000

Daily Performance Trend

resource: "campaign"
fields: [
    "segments.date",
    "campaign.name",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'",
    "campaign.status = 'ENABLED'"
]
orderings: ["segments.date ASC"]

Device Performance

resource: "campaign"
fields: [
    "campaign.name",
    "segments.device",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Hour of Day Analysis

resource: "campaign"
fields: [
    "campaign.name",
    "segments.hour",
    "metrics.impressions",
    "metrics.clicks",
    "metrics.cost_micros",
    "metrics.conversions"
]
conditions: [
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Metric Calculations

Derived Metrics (Calculate Post-Query)

Impression Share Metrics

• search_impression_share - % of eligible impressions received
• search_budget_lost_impression_share - Lost due to budget
• search_rank_lost_impression_share - Lost due to rank
• search_absolute_top_impression_share - % in position 1

Date Handling

Critical: The Google Ads API requires explicit date formatting.

• Format: YYYY-MM-DD (e.g., 2024-12-01)
• Always use explicit dates, not literals like TODAY or LAST_30_DAYS
• Date conditions use segments.date

Date Range Examples

# Last 7 days (calculate actual dates)
conditions: [
    "segments.date >= '2024-12-10'",
    "segments.date <= '2024-12-17'"
]

# Specific month
conditions: [
    "segments.date >= '2024-11-01'",
    "segments.date <= '2024-11-30'"
]

Status Values

Campaign Status

• ENABLED - Active
• PAUSED - Paused by user
• REMOVED - Deleted

Ad Group Criterion Status

• ENABLED - Active keyword
• PAUSED - Paused keyword
• REMOVED - Deleted keyword

Search Term Status

• ADDED - Added as keyword
• EXCLUDED - Added as negative
• ADDED_EXCLUDED - Both
• NONE - Not actioned

Channel Types

Advertising Channel Types

• SEARCH - Search Network
• DISPLAY - Display Network
• SHOPPING - Shopping campaigns
• VIDEO - YouTube/Video
• PERFORMANCE_MAX - PMax campaigns
• LOCAL - Local campaigns
• SMART - Smart campaigns
• DEMAND_GEN - Demand Gen campaigns

Integration with Snowflake

Cross-reference Google Ads data with RDC Snowflake tables:

Joining Pattern

Query Google Ads for campaign IDs, then use in Snowflake:

SELECT * FROM rdc_marketing.agg_reporting.sem_summary
WHERE campaign_id IN (12345, 67890)  -- From Google Ads query
  AND event_date >= DATEADD('day', -30, CURRENT_DATE());

Auction Insights

Auction Insights provides competitive intelligence showing how your ads perform against other advertisers in the same auctions. Available for Search and Shopping campaigns only.

Key Segment

• segments.auction_insight_domain - Returns competitor domain names (required for auction insights)

Auction Insight Metrics

Campaign-Level Auction Insights

resource: "campaign"
fields: [
    "campaign.id",
    "campaign.name",
    "segments.auction_insight_domain",
    "metrics.auction_insight_search_impression_share",
    "metrics.auction_insight_search_overlap_rate",
    "metrics.auction_insight_search_position_above_rate",
    "metrics.auction_insight_search_top_impression_percentage",
    "metrics.auction_insight_search_absolute_top_impression_percentage",
    "metrics.auction_insight_search_outranking_share"
]
conditions: [
    "campaign.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Keyword-Level Auction Insights

resource: "ad_group_criterion"
fields: [
    "campaign.name",
    "ad_group.name",
    "ad_group_criterion.keyword.text",
    "segments.auction_insight_domain",
    "metrics.auction_insight_search_impression_share",
    "metrics.auction_insight_search_overlap_rate",
    "metrics.auction_insight_search_position_above_rate"
]
conditions: [
    "ad_group_criterion.type = 'KEYWORD'",
    "ad_group_criterion.status = 'ENABLED'",
    "segments.date >= 'YYYY-MM-DD'",
    "segments.date <= 'YYYY-MM-DD'"
]

Interpreting Results

• Treat Analysis as Relative to historical performance: rather than relying on a hard threshold, develop an understanding of previous behavior vs. current behavior, and interpret the difference. When there is no previous behavior to compare, use the following rules.
• High overlap rate (>50%): Frequent direct competition
• Position above rate >50%: Competitor usually beats you
• Outranking share: Combines position wins + showing when they didn't
• Results include your own domain as benchmark

See references/auction_insights.md for comprehensive guidance.

Reference Documents

• campaign_fields.md - All campaign resource fields
• metrics_fields.md - All metrics fields with descriptions
• segment_fields.md - All segmentation options
• keyword_fields.md - Keyword and criterion fields
• auction_insights.md - Competitive analysis and auction insights

Tips for Efficient Queries

1. Minimize fields - Only request fields you need
2. Use limits - Add limit for exploratory queries
3. Filter early - Use conditions to reduce data volume
4. Segment wisely - Each segment dimension multiplies rows
5. Check status - Filter to ENABLED for active items only
6. Date ranges - Shorter ranges = faster queries
7. Batch accounts - Query one customer_id at a time