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

| Account | Customer ID | Vertical | Notes | |---------|-------------|----------|-------| | RDC SEM Main | see accessible_customers | Buy/Mixed | Primary B2C search | | RDC Rentals | see accessible_customers | Rent | Rentals vertical | | RDC Seller | see accessible_customers | Sell | Seller marketplace | | RDC New Construction | see accessible_customers | NC | Builder campaigns |

Run list_accessible_customers to get current account IDs

Core Resources

| Resource | Use Case | Key Metrics Available | |----------|----------|----------------------| | campaign | Campaign settings, status, budget | bidding strategy, status, dates | | ad_group | Ad group settings, bids | CPC bids, status, targeting | | ad_group_ad | Ad creative, approval status | ad strength, policy status | | ad_group_criterion | Keywords, audiences | quality score, bids | | search_term_view | Search query data | search terms, match type | | keyword_view | Keyword performance | joins with metrics | | geographic_view | Geo performance | location type | | campaign_budget | Budget settings | amount, delivery method |

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)

| Metric | Calculation | |--------|-------------| | Cost | cost_micros / 1,000,000 | | CPC | cost_micros / clicks / 1,000,000 | | CTR | clicks / impressions | | Conv Rate | conversions / clicks | | CPA | cost_micros / conversions / 1,000,000 | | ROAS | conversions_value / (cost_micros / 1,000,000) |

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:

| Google Ads Field | Snowflake Field | Table | |------------------|-----------------|-------| | campaign.id | campaign_id | sem_summary | | campaign.name | campaign_name | sem_summary | | N/A (calculated) | google_click_id | clickstream_detail |

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

| Metric | Description | |--------|-------------| | metrics.auction_insight_search_impression_share | % of impressions you received vs. total eligible | | metrics.auction_insight_search_overlap_rate | How often competitor showed alongside you | | metrics.auction_insight_search_position_above_rate | How often competitor ranked above you | | metrics.auction_insight_search_top_impression_percentage | % of impressions at top of page | | metrics.auction_insight_search_absolute_top_impression_percentage | % of impressions in position #1 | | metrics.auction_insight_search_outranking_share | % of auctions where you outranked competitor |

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