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