Initialize the Google Ads API connection with OAuth credentials.

This must be called before using any other Google Ads tools. Provide your developer token, OAuth2 credentials, and optionally an MCC login customer ID if you're accessing client accounts.

Args: developer_token: API developer token client_id: OAuth2 client ID client_secret: OAuth2 client secret refresh_token: OAuth2 refresh token login_customer_id: Optional MCC account ID (without hyphens)

Returns: Confirmation message with initialization status

List all Google Ads accounts accessible with current credentials.

Returns details about all accounts you have access to, including customer IDs, names, currency codes, and whether they are manager accounts.

Args: response_format: Output format: 'markdown' for readable or 'json' for structured data

Returns: List of accessible accounts with their details

Execute a custom Google Ads Query Language (GAQL) query.

For advanced users who want to write their own GAQL queries. Use the Google Ads Query Builder to construct queries: https://developers.google.com/google-ads/api/fields/latest/overview_query_builder

Args: customer_id: Customer ID (without hyphens) query: GAQL query string response_format: Output format ('json' or 'markdown')

Returns: Query results in specified format

Get comprehensive performance metrics for campaigns.

Retrieves key performance indicators including cost, clicks, impressions, CTR, conversions, and more for campaigns in the specified date range. Supports filtering by status and cost thresholds.

Args: customer_id: Customer ID without hyphens (e.g., '1234567890') date_range: Predefined date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_90_DAYS) campaign_status: Filter by status list e.g. ['ENABLED', 'PAUSED'] min_cost: Minimum cost filter in currency units limit: Maximum number of campaigns to return (1-100) response_format: Output format: 'markdown' or 'json'

Returns: Campaign performance data with metrics and analysis

View actual search queries that triggered your ads.

Shows the search terms report with performance metrics to identify new keyword opportunities and negative keyword candidates.

Args: customer_id: Customer ID without hyphens campaign_id: Optional campaign ID to filter date_range: Date range for the report limit: Maximum number of search terms to return response_format: Output format: 'markdown' or 'json'

Returns: Search terms with performance metrics

Get AI-powered optimization recommendations from Google.

Retrieve Google's automated recommendations for improving campaign performance, including keyword suggestions, bid adjustments, and budget recommendations.

Args: customer_id: Customer ID without hyphens recommendation_types: Filter by recommendation types (e.g., ['KEYWORD', 'TARGET_CPA_OPT']) limit: Maximum number of recommendations (1-100) response_format: Output format: 'markdown' or 'json'

Returns: List of actionable optimization recommendations

Create a new Google Ads campaign.

Args: customer_id: Customer ID (without hyphens) campaign_name: Name for the campaign campaign_type: Type of campaign (SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX, APP, LOCAL) daily_budget: Daily budget in currency units (e.g., 50.00 for $50/day) bidding_strategy: Bidding strategy (MANUAL_CPC, MAXIMIZE_CONVERSIONS, TARGET_CPA, TARGET_ROAS, etc.) status: Initial status (ENABLED or PAUSED, default: PAUSED for safety) enable_search_network: Target Google search network (default: True) enable_search_partners: Target search partner sites (default: False) enable_display_network: Target display network (default: False) start_date: Campaign start date in YYYY-MM-DD format (optional) end_date: Campaign end date in YYYY-MM-DD format (optional) target_cpa: Target CPA in currency units (required for TARGET_CPA strategy) target_roas: Target ROAS as decimal (required for TARGET_ROAS strategy)

Returns: Success message with campaign details

Update campaign settings.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update campaign_name: New campaign name (optional) status: New status (ENABLED, PAUSED, or REMOVED) (optional) start_date: New start date in YYYY-MM-DD format (optional) end_date: New end date in YYYY-MM-DD format (optional)

Returns: Success message with updated fields

Update campaign status (enable, pause, or remove).

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID status: New status (ENABLED, PAUSED, or REMOVED)

Returns: Success message

Update campaign daily budget.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID daily_budget: New daily budget in currency units (e.g., 100.00 for $100/day)

Returns: Success message with budget details

Set location targeting for a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID location_ids: List of geo target constant IDs to target negative_location_ids: List of geo target constant IDs to exclude (optional)

Returns: Success message

Note: Common location IDs:

• 2840: United States

• 2826: United Kingdom

• 2124: Canada

• 2036: Australia Use Google Ads location targeting tool to find specific IDs

Set language targeting for a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID language_codes: List of language constant IDs

Returns: Success message

Note: Common language IDs:

• 1000: English

• 1003: Spanish

• 1002: French

• 1001: German

• 1005: Chinese (Simplified)

Get detailed information about a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID

Returns: Detailed campaign information

Set ad scheduling (dayparting) for a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID schedules: List of schedule dictionaries with: - day_of_week: Day name (MONDAY, TUESDAY, etc.) or numeric (0=Sunday, 6=Saturday) - start_hour: Hour to start (0-23) - start_minute: Minute to start (0, 15, 30, 45) - end_hour: Hour to end (0-24) - end_minute: Minute to end (0, 15, 30, 45) - bid_modifier: Optional bid adjustment (1.2 = +20%, 0.8 = -20%)

Returns: Success message with schedule summary

Example: schedules = [ { "day_of_week": "MONDAY", "start_hour": 9, "start_minute": 0, "end_hour": 17, "end_minute": 0, "bid_modifier": 1.2 } ]

Duplicate an existing campaign with all settings.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to duplicate new_name: Name for the new campaign include_ad_groups: Whether to copy ad groups and their content (default: False)

Returns: Success message with new campaign details

Note: The new campaign will be created in PAUSED status for safety.

Create a shared budget that can be used across multiple campaigns.

Args: customer_id: Customer ID (without hyphens) budget_name: Name for the shared budget daily_amount: Daily budget amount in currency units (e.g., 100.00 for $100/day) delivery_method: Budget delivery method (STANDARD or ACCELERATED, default: STANDARD)

Returns: Success message with budget resource name

Note: After creating a shared budget, use google_ads_assign_shared_budget to assign it to campaigns.

Assign a shared budget to a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update budget_resource_name: Resource name of the shared budget (from google_ads_create_shared_budget)

Returns: Success message

Note: The campaign will switch from its individual budget to the shared budget.

Add placement and IP exclusions to a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID placement_exclusions: List of URLs/apps to exclude (e.g., ["example.com", "youtube.com/channel/ABC"]) ip_exclusions: List of IP addresses to exclude (e.g., ["192.168.1.1", "10.0.0.0/24"])

Returns: Success message with exclusion summary

Note:

• Placement exclusions prevent ads from showing on specific websites, YouTube channels, or apps

• IP exclusions prevent ads from showing to specific IP addresses (useful for excluding office IPs)

• CIDR notation supported for IP ranges (e.g., "10.0.0.0/24")

Set the Final URL suffix for a campaign. The suffix is appended to all ad landing page URLs in this campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update url_suffix: URL parameters to append (e.g., 'utm_source=google&utm_medium=cpc&sm_kw=bollards'). Pass empty string to clear.

Returns: Success message with the applied suffix

Get current Final URL suffixes and tracking URL templates for campaigns and their ad groups.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter to a specific campaign. If omitted, returns all enabled campaigns.

Returns: Formatted table of URL suffixes and tracking templates

Create a new ad group within a campaign.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to create ad group in ad_group_name: Name for the ad group cpc_bid: Cost-per-click bid in currency units (e.g., 1.50 for $1.50) status: Initial status (ENABLED or PAUSED, default: PAUSED) ad_group_type: Optional ad group type (SEARCH_STANDARD, DISPLAY_STANDARD, etc.)

Returns: Success message with ad group details

Note: Ad groups are created PAUSED by default for safety.

Update ad group settings.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID to update ad_group_name: New ad group name (optional) status: New status (ENABLED, PAUSED, or REMOVED) (optional) cpc_bid: New CPC bid in currency units (optional)

Returns: Success message with updated fields

Update ad group status (enable, pause, or remove).

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID status: New status (ENABLED, PAUSED, or REMOVED)

Returns: Success message

Update ad group CPC bid.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID cpc_bid: New CPC bid in currency units (e.g., 1.50 for $1.50)

Returns: Success message with bid details

Get detailed information about an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID

Returns: Detailed ad group information

List ad groups with optional filters.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter by status: Optional status to filter by (ENABLED, PAUSED)

Returns: List of ad groups with key metrics

Get performance metrics for an ad group over a date range.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Performance metrics

Update status for multiple ad groups at once.

Args: customer_id: Customer ID (without hyphens) ad_group_ids: List of ad group IDs to update status: New status for all ad groups (ENABLED, PAUSED, or REMOVED)

Returns: Success message with count of updated ad groups

Example: ad_group_ids = ["123456789", "987654321", "456789123"]

Set the Final URL suffix for an ad group. This overrides the campaign-level suffix for ads in this ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID to update url_suffix: URL parameters to append (e.g., 'utm_source=google&utm_medium=cpc&sm_kw=removable-bollards'). Pass empty string to clear and inherit campaign suffix.

Returns: Success message with the applied suffix

Bulk set Final URL suffixes for multiple ad groups in one API call.

Args: customer_id: Customer ID (without hyphens) ad_group_suffixes: JSON string containing array of objects with 'ad_group_id' and 'url_suffix'. Example: [{"ad_group_id": "123", "url_suffix": "sm_kw=bollards"}, {"ad_group_id": "456", "url_suffix": "sm_kw=wheel-stops"}]

Returns: Success message with count of updated ad groups

Add keywords to an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keywords: List of keyword dicts with 'text' and 'match_type' (EXACT, PHRASE, BROAD) cpc_bid: Optional default CPC bid for all keywords in currency units

Returns: Success message with keyword count

Example: keywords = [ {"text": "running shoes", "match_type": "PHRASE"}, {"text": "nike shoes", "match_type": "EXACT"}, {"text": "athletic footwear", "match_type": "BROAD"} ]

Add negative keywords to an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keywords: List of keyword dicts with 'text' and 'match_type'

Returns: Success message

Example: keywords = [ {"text": "cheap", "match_type": "BROAD"}, {"text": "free", "match_type": "BROAD"} ]

Add negative keywords to a shared negative keyword list (account-level).

This adds keywords to an existing shared negative keyword list that can be applied across multiple campaigns for account-level negative keyword management.

Args: customer_id: Customer ID (without hyphens) shared_set_id: The ID of the shared negative keyword list keywords: List of keyword dicts with 'text' and 'match_type'

Returns: Success message with count of keywords added

Example: keywords = [ {"text": "cheap", "match_type": "BROAD"}, {"text": "free", "match_type": "BROAD"}, {"text": "jobs", "match_type": "BROAD"} ]

Update keyword CPC bid.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID cpc_bid: New CPC bid in currency units (e.g., 1.50 for $1.50)

Returns: Success message

Update keyword status (enable, pause, or remove).

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID status: New status (ENABLED, PAUSED, or REMOVED)

Returns: Success message

Get keyword performance metrics.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Optional ad group ID to filter by date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Keyword performance report

List all keywords in an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID

Returns: List of keywords

Get detailed quality score information for a keyword.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Keyword criterion ID

Returns: Quality score details

Get search terms that triggered ads for keywords in an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID criterion_id: Optional specific keyword criterion ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Search terms report with performance data

Bulk add multiple keywords with the same match type.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID keyword_texts: List of keyword text strings match_type: Match type for all keywords (EXACT, PHRASE, or BROAD, default: PHRASE) cpc_bid: Optional CPC bid for all keywords in currency units

Returns: Success message

Example: keyword_texts = ["running shoes", "athletic shoes", "sport shoes"]

Update bids for multiple keywords at once.

Args: customer_id: Customer ID (without hyphens) bid_updates: List of dicts with 'ad_group_id', 'criterion_id', 'cpc_bid'

Returns: Success message

Example: bid_updates = [ {"ad_group_id": "123", "criterion_id": "456", "cpc_bid": 2.50}, {"ad_group_id": "123", "criterion_id": "789", "cpc_bid": 3.00} ]

Get traffic estimates for keywords.

Args: customer_id: Customer ID (without hyphens) keywords: List of keyword texts to estimate location_ids: Optional location IDs for targeting (e.g., ["2840"] for United States)

Returns: Traffic estimates

Note: This is a placeholder. Full implementation requires Keyword Plan API setup.

Get keyword ideas from Google Ads Keyword Planner.

Generate keyword suggestions based on seed keywords or a webpage URL. Includes search volume, competition level, and bid estimates.

Args: customer_id: Google Ads customer ID (10 digits, no hyphens) seed_keywords: Comma-separated seed keywords (e.g., "running shoes,nike") page_url: Optional URL to extract keywords from location_ids: Comma-separated location criterion IDs (default: 2840 = US) language_id: Language criterion ID (default: 1000 = English) keyword_plan_network: Network - GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS, or YOUTUBE response_format: Output format (markdown or json)

Returns: Keyword ideas with metrics (search volume, competition, bids)

Example: google_ads_keyword_ideas( customer_id="1234567890", seed_keywords="running shoes,athletic footwear", location_ids="2840", # US language_id="1000" # English )

Common Location IDs: - 2840: United States - 2826: United Kingdom - 2124: Canada - 2036: Australia

Competition Levels: - LOW: Easy to rank for - MEDIUM: Moderate competition - HIGH: Very competitive

Forecast traffic metrics for specific keywords.

Get projected impressions, clicks, and costs for keywords over a future time period.

Args: customer_id: Google Ads customer ID (10 digits, no hyphens) keywords_json: JSON array of keywords with text and match_type Example: [{"text": "running shoes", "match_type": "BROAD"}] location_ids: Comma-separated location criterion IDs (default: 2840 = US) language_id: Language criterion ID (default: 1000 = English) cpc_bid: CPC bid amount for forecast (default: 1.0) date_interval: Forecast period - NEXT_WEEK, NEXT_MONTH, or NEXT_QUARTER response_format: Output format (markdown or json)

Returns: Traffic forecast with projected metrics

Example: google_ads_keyword_forecast( customer_id="1234567890", keywords_json='[{"text": "running shoes", "match_type": "BROAD"}, {"text": "nike shoes", "match_type": "PHRASE"}]', cpc_bid=2.5, date_interval="NEXT_MONTH" )

Match Types: - BROAD: Matches variations and related searches - PHRASE: Matches phrase and close variants - EXACT: Matches exact keyword only

Date Intervals: - NEXT_WEEK: 7-day forecast - NEXT_MONTH: 30-day forecast - NEXT_QUARTER: 90-day forecast

Create a Responsive Search Ad (RSA).

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID headlines: List of 3-15 headline texts (max 30 chars each) descriptions: List of 2-4 description texts (max 90 chars each) final_urls: List of final URLs (landing pages) path1: Optional display path 1 (max 15 chars) path2: Optional display path 2 (max 15 chars) status: Initial status (ENABLED or PAUSED, default: PAUSED)

Returns: Success message with ad details

Example: headlines = [ "Premium Running Shoes", "Free Shipping Today", "Shop Nike & Adidas" ] descriptions = [ "Browse our selection of top running shoes", "30-day money back guarantee" ] final_urls = ["https://example.com/shoes"]

Update ad status (enable, pause, or remove).

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID status: New status (ENABLED, PAUSED, or REMOVED)

Returns: Success message

List all ads in an ad group.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID

Returns: List of ads with details

Get detailed information about an ad.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID

Returns: Detailed ad information

Get ad performance metrics.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Optional ad group ID to filter date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Ad performance report

Check ad approval and policy status.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID ad_id: Ad ID

Returns: Approval status details

Update status for multiple ads at once.

Args: customer_id: Customer ID (without hyphens) status_updates: List of dicts with 'ad_group_id' and 'ad_id' status: New status for all ads (ENABLED, PAUSED, or REMOVED)

Returns: Success message

Example: status_updates = [ {"ad_group_id": "123", "ad_id": "456"}, {"ad_group_id": "123", "ad_id": "789"} ]

Compare performance between two ads (A/B testing).

Args: customer_id: Customer ID (without hyphens) ad_id_1: First ad ID ad_id_2: Second ad ID date_range: Date range for comparison

Returns: Comparison report

Create a portfolio bidding strategy for shared use across campaigns.

Portfolio bidding strategies allow you to apply the same automated bidding strategy across multiple campaigns, enabling Google's AI to optimize bids based on a larger pool of data.

Strategy Types:

• TARGET_CPA: Optimize for target cost per acquisition

• TARGET_ROAS: Optimize for target return on ad spend

• MAXIMIZE_CONVERSIONS: Get the most conversions within budget

• MAXIMIZE_CONVERSION_VALUE: Maximize total conversion value

• TARGET_IMPRESSION_SHARE: Target specific impression share percentage

• MANUAL_CPC: Manual bidding with optional enhanced CPC

Args: customer_id: Customer ID (without hyphens) strategy_name: Name for the bidding strategy (e.g., "High Value Customers") strategy_type: Strategy type (TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, etc.) target_cpa: Target cost per acquisition in currency units (required for TARGET_CPA) target_roas: Target return on ad spend as decimal (e.g., 4.0 = 400% ROAS) (for TARGET_ROAS) target_impression_share: Target impression share 0.0-1.0 (e.g., 0.75 = 75%) (for TARGET_IMPRESSION_SHARE) impression_share_location: Where to target impressions (ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE) max_cpc_bid: Maximum CPC bid limit in currency units (optional for TARGET_IMPRESSION_SHARE) enhanced_cpc: Enable enhanced CPC for MANUAL_CPC strategy

Returns: Success message with strategy ID and configuration details

Example: google_ads_create_bidding_strategy( customer_id="1234567890", strategy_name="Target CPA - $25", strategy_type="TARGET_CPA", target_cpa=25.00 )

Update an existing portfolio bidding strategy's settings.

Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID to update strategy_name: New name for the strategy (optional) target_cpa: New target CPA in currency units (for TARGET_CPA strategies) target_roas: New target ROAS as decimal (for TARGET_ROAS strategies) target_impression_share: New target impression share 0.0-1.0 (for TARGET_IMPRESSION_SHARE) max_cpc_bid: New maximum CPC bid limit (for TARGET_IMPRESSION_SHARE)

Returns: Success message with updated configuration

Example: google_ads_update_bidding_strategy( customer_id="1234567890", bidding_strategy_id="12345", target_cpa=30.00 )

Assign a portfolio bidding strategy to a campaign.

This replaces the campaign's current bidding strategy with the specified portfolio strategy, allowing Google's AI to optimize bids across all campaigns using this strategy.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID to update bidding_strategy_id: Portfolio bidding strategy ID to assign

Returns: Success message confirming assignment

Example: google_ads_assign_bidding_strategy( customer_id="1234567890", campaign_id="111111111", bidding_strategy_id="12345" )

Get performance metrics for a portfolio bidding strategy.

Shows aggregate performance across all campaigns using this strategy, including impressions, clicks, conversions, and cost metrics.

Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Performance metrics in markdown format

Example: google_ads_get_bidding_strategy_performance( customer_id="1234567890", bidding_strategy_id="12345", date_range="LAST_30_DAYS" )

Set bid adjustments for different device types.

Bid modifiers allow you to increase or decrease bids based on the device used by the searcher. Values range from 0.1 (90% decrease) to 10.0 (900% increase).

Common adjustments:

• 1.0 = No change (default)

• 1.5 = Increase bids by 50%

• 0.7 = Decrease bids by 30%

• 0.1 = Decrease bids by 90% (effectively pause)

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID mobile_modifier: Bid modifier for mobile devices (0.1 to 10.0) desktop_modifier: Bid modifier for desktop devices (0.1 to 10.0) tablet_modifier: Bid modifier for tablet devices (0.1 to 10.0)

Returns: Success message with applied adjustments

Example: google_ads_set_device_bid_adjustments( customer_id="1234567890", campaign_id="111111111", mobile_modifier=1.3, # Increase mobile bids by 30% desktop_modifier=1.0, # No change for desktop tablet_modifier=0.8 # Decrease tablet bids by 20% )

Set bid adjustments for ad scheduling (dayparting).

Control when your ads show and adjust bids based on time of day and day of week. This is useful for targeting business hours, weekends, or other high-converting periods.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID schedules: List of schedule configurations, each containing: - day_of_week: Day (MONDAY, TUESDAY, etc.) - start_hour: Start hour (0-23) - start_minute: Start minute (0, 15, 30, 45) - end_hour: End hour (0-24) - end_minute: End minute (0, 15, 30, 45) - bid_modifier: Bid adjustment (0.1 to 10.0)

Returns: Success message with created schedules

Example: google_ads_set_ad_schedule_bid_adjustments( customer_id="1234567890", campaign_id="111111111", schedules=[ { "day_of_week": "MONDAY", "start_hour": 9, "start_minute": 0, "end_hour": 17, "end_minute": 0, "bid_modifier": 1.5 # Increase bids 50% during business hours }, { "day_of_week": "SATURDAY", "start_hour": 0, "start_minute": 0, "end_hour": 24, "end_minute": 0, "bid_modifier": 0.7 # Decrease bids 30% on weekends } ] )

List all bid adjustments for a campaign (devices, locations, demographics, ad schedule).

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID

Returns: All bid adjustments in markdown format

Example: google_ads_list_bid_adjustments( customer_id="1234567890", campaign_id="111111111" )

Get bid simulation data showing potential performance at different bid levels.

Bid simulators use historical data to project how different bid amounts would have affected impressions, clicks, cost, and conversions. This helps you find the optimal bid level for your goals.

Note: Simulations require at least 7 days of historical data.

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID for campaign-level simulation criterion_id: Optional keyword criterion ID for keyword-level simulation

Returns: Bid simulation data with projected performance at different bid levels

Example: google_ads_get_bid_simulator( customer_id="1234567890", campaign_id="111111111" )

Get AI-powered bid recommendations from Google Ads.

Google's recommendation engine analyzes your account performance and suggests specific bid changes to improve results. Recommendations may include:

• Keyword bid adjustments

• Campaign budget increases

• Bidding strategy changes

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter recommendations

Returns: List of bid recommendations with projected impact

Example: google_ads_get_bid_recommendations( customer_id="1234567890", campaign_id="111111111" )

List all portfolio bidding strategies in the account.

Args: customer_id: Customer ID (without hyphens)

Returns: List of all portfolio bidding strategies with basic info

Example: google_ads_list_bidding_strategies( customer_id="1234567890" )

Get full configuration details for a portfolio bidding strategy.

Args: customer_id: Customer ID (without hyphens) bidding_strategy_id: Bidding strategy ID

Returns: Complete strategy configuration and settings

Example: google_ads_get_bidding_strategy_details( customer_id="1234567890", bidding_strategy_id="12345" )

Get optimization recommendations from Google Ads.

Google's AI analyzes your account and suggests specific optimizations to improve performance. Recommendations can include keyword additions, budget increases, bidding strategy changes, and more.

Args: customer_id: Customer ID (without hyphens) recommendation_types: Optional list of recommendation types to filter (e.g., ["KEYWORD", "CAMPAIGN_BUDGET", "TARGET_CPA_OPT_IN"]) campaign_id: Optional campaign ID to filter recommendations response_format: Output format (markdown or json)

Returns: List of recommendations with projected impact

Example: google_ads_get_recommendations( customer_id="1234567890", recommendation_types=["KEYWORD", "CAMPAIGN_BUDGET"] )

Common Recommendation Types:

• KEYWORD: Add new keywords

• CAMPAIGN_BUDGET: Increase budget

• TARGET_CPA_OPT_IN: Switch to Target CPA bidding

• TARGET_ROAS_OPT_IN: Switch to Target ROAS bidding

• RESPONSIVE_SEARCH_AD: Create responsive search ads

• KEYWORD_MATCH_TYPE: Change keyword match types

• USE_BROAD_MATCH_KEYWORD: Use broad match keywords

Apply a single optimization recommendation.

This will automatically implement the suggested optimization. For example:

• KEYWORD recommendations will add the keyword to your account

• CAMPAIGN_BUDGET recommendations will increase the budget

• Bidding strategy recommendations will change the bidding strategy

Args: customer_id: Customer ID (without hyphens) recommendation_resource_name: Resource name of the recommendation to apply (obtained from google_ads_get_recommendations)

Returns: Success message confirming application

Example: google_ads_apply_recommendation( customer_id="1234567890", recommendation_resource_name="customers/1234567890/recommendations/12345" )

Warning: This will make changes to your account. Review the recommendation details carefully before applying.

Dismiss a recommendation without applying it.

Use this when you don't want to apply a recommendation and want to remove it from your recommendations list.

Args: customer_id: Customer ID (without hyphens) recommendation_resource_name: Resource name of the recommendation to dismiss

Returns: Success message confirming dismissal

Example: google_ads_dismiss_recommendation( customer_id="1234567890", recommendation_resource_name="customers/1234567890/recommendations/12345" )

Apply multiple recommendations at once.

This is useful for applying several recommendations efficiently in a single operation.

Args: customer_id: Customer ID (without hyphens) recommendation_resource_names: List of recommendation resource names to apply

Returns: Success message with count of applied recommendations

Example: google_ads_bulk_apply_recommendations( customer_id="1234567890", recommendation_resource_names=[ "customers/1234567890/recommendations/12345", "customers/1234567890/recommendations/12346", "customers/1234567890/recommendations/12347" ] )

Warning: This will make changes to your account. Review all recommendations carefully before applying in bulk.

Dismiss multiple recommendations at once.

Args: customer_id: Customer ID (without hyphens) recommendation_resource_names: List of recommendation resource names to dismiss

Returns: Success message with count of dismissed recommendations

Example: google_ads_bulk_dismiss_recommendations( customer_id="1234567890", recommendation_resource_names=[ "customers/1234567890/recommendations/12345", "customers/1234567890/recommendations/12346" ] )

Get the account's optimization score (0-100%).

The optimization score represents how well your account is set up to perform. A score of 100% means your account is fully optimized based on Google's recommendations. Lower scores indicate room for improvement.

The score is calculated based on:

• Available recommendations

• Recommendation priority

• Potential performance impact

Args: customer_id: Customer ID (without hyphens)

Returns: Optimization score with breakdown by recommendation type

Example: google_ads_get_optimization_score( customer_id="1234567890" )

Get aggregate insights about recommendations and their potential impact.

This provides a high-level summary of all recommendations, grouped by type, with total projected impact across all recommendations.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter

Returns: Aggregate recommendation insights with total potential impact

Example: google_ads_get_recommendation_insights( customer_id="1234567890" )

Apply all recommendations of a specific type.

This is useful for bulk-applying all recommendations of a certain category, such as all KEYWORD recommendations or all CAMPAIGN_BUDGET recommendations.

Args: customer_id: Customer ID (without hyphens) recommendation_type: Type of recommendations to apply (KEYWORD, CAMPAIGN_BUDGET, TARGET_CPA_OPT_IN, etc.) max_to_apply: Optional maximum number of recommendations to apply

Returns: Success message with count of applied recommendations

Example: google_ads_apply_recommendations_by_type( customer_id="1234567890", recommendation_type="KEYWORD", max_to_apply=10 )

Common Types:

• KEYWORD: Add suggested keywords

• CAMPAIGN_BUDGET: Increase budgets

• TARGET_CPA_OPT_IN: Enable Target CPA bidding

• TARGET_ROAS_OPT_IN: Enable Target ROAS bidding

• RESPONSIVE_SEARCH_AD: Create RSAs

Warning: This will make changes to your account. Review recommendations of this type carefully before bulk applying.

Get history of applied and dismissed recommendations.

This shows what recommendations were applied or dismissed in a given time period, along with who made the changes.

Args: customer_id: Customer ID (without hyphens) start_date: Start date (YYYY-MM-DD) end_date: End date (YYYY-MM-DD)

Returns: Recommendation change history

Example: google_ads_get_recommendation_history( customer_id="1234567890", start_date="2025-11-01", end_date="2025-12-16" )

Auto-apply low-risk, high-impact recommendations.

This tool identifies "safe" recommendations that are unlikely to negatively impact performance and applies them automatically. Safe recommendations include:

• Keyword match type upgrades (exact → phrase → broad)

• Responsive search ad suggestions

• Search partners opt-in

• Optimize ad rotation

Higher risk recommendations (budget increases, bidding strategy changes) are excluded and should be reviewed manually.

Args: customer_id: Customer ID (without hyphens) dry_run: If True, shows what would be applied without actually applying (default: True)

Returns: List of recommendations that were (or would be) applied

Example: # Preview what would be applied google_ads_auto_apply_safe_recommendations( customer_id="1234567890", dry_run=True )

# Actually apply the recommendations
google_ads_auto_apply_safe_recommendations(
    customer_id="1234567890",
    dry_run=False
)

Warning: Even "safe" recommendations can impact performance. Use dry_run=True first to review what would be applied.

Create a remarketing user list (audience).

User lists allow you to target specific groups of users based on their interactions with your business. Types include:

• CRMBASED: Customer Match lists (email, phone, address)

• RULE_BASED: Website visitors matching URL patterns

Args: customer_id: Customer ID (without hyphens) list_name: Name for the user list (e.g., "Newsletter Subscribers") description: Optional description membership_days: How long users stay in the list (1-540 days, default: 540) list_type: Type of list (CRMBASED or RULE_BASED) url_contains: For RULE_BASED lists, URL patterns to match (OR logic). e.g. ["arcadium.com.au"] or ["/escape-rooms", "/pricing"]

Returns: Success message with user list ID

Example: google_ads_create_user_list( customer_id="1234567890", list_name="All Site Visitors", description="All visitors to our website", membership_days=90, list_type="RULE_BASED", url_contains=["example.com"] )

Note: RULE_BASED lists require remarketing tags on your website/app.

Upload Customer Match data (emails, phones, addresses).

Customer Match allows you to use your customer data to reach them on Google Search, YouTube, Gmail, and Display Network. Data is hashed before upload for privacy.

You can either upload to an existing list (provide user_list_id) or create a new list (provide list_name).

Args: customer_id: Customer ID (without hyphens) user_list_id: Existing user list ID to upload to (optional) list_name: Name for new list (required if user_list_id not provided) emails: List of email addresses phones: List of phone numbers (E.164 format recommended: +12345678900) first_names: List of first names (must match emails/phones index) last_names: List of last names (must match emails/phones index) countries: List of country codes (e.g., "US", "UK") zip_codes: List of postal codes

Returns: Success message with upload job details

Example: google_ads_upload_customer_match( customer_id="1234567890", list_name="Email Newsletter Subscribers", emails=[ "customer1@example.com", "customer2@example.com", "customer3@example.com" ] )

Privacy Note: All data is automatically hashed with SHA256 before upload. Google cannot see the original data.

Match Rate: Typically 30-70% of uploaded records will match to Google users.

Get Customer Match upload status, match rate, and list size.

Check this 24-48 hours after uploading to see how many records matched and if the list is large enough for targeting (minimum 1,000).

Args: customer_id: Customer ID (without hyphens) user_list_id: User list ID to check

Returns: Upload status, match rate, and list sizes

Example: google_ads_get_customer_match_status( customer_id="1234567890", user_list_id="12345" )

Add audience targeting to a campaign.

Two modes available:

• OBSERVATION: Monitor audience performance without restricting reach

• TARGETING: Restrict campaign to only show ads to this audience

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID user_list_id: User list ID to target targeting_mode: OBSERVATION (monitor) or TARGETING (restrict reach)

Returns: Success message

Example (Observation): google_ads_add_audience_to_campaign( customer_id="1234567890", campaign_id="111111111", user_list_id="12345", targeting_mode="OBSERVATION" )

Example (Targeting): google_ads_add_audience_to_campaign( customer_id="1234567890", campaign_id="222222222", user_list_id="12345", targeting_mode="TARGETING" )

Recommendation: Start with OBSERVATION mode to gather performance data before switching to TARGETING mode.

Add audience targeting to an ad group.

Similar to campaign-level audience targeting, but applied at the ad group level for more granular control.

Args: customer_id: Customer ID (without hyphens) ad_group_id: Ad group ID user_list_id: User list ID to target targeting_mode: OBSERVATION or TARGETING

Returns: Success message

Example: google_ads_add_audience_to_ad_group( customer_id="1234567890", ad_group_id="222222222", user_list_id="12345", targeting_mode="OBSERVATION" )

Exclude audiences from a campaign.

Prevent your ads from showing to specific audiences. Common use cases:

• Exclude existing customers from acquisition campaigns

• Exclude converters from remarketing campaigns

• Exclude low-value segments

Args: customer_id: Customer ID (without hyphens) campaign_id: Campaign ID user_list_ids: List of user list IDs to exclude

Returns: Success message

Example: google_ads_set_audience_exclusions( customer_id="1234567890", campaign_id="111111111", user_list_ids=["12345", "12346", "12347"] )

Use Case: Exclude "Past Purchasers" list from new customer acquisition campaign

Get performance metrics by audience.

See which audiences are driving the best results in terms of clicks, conversions, and ROI.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID to filter date_range: Date range (TODAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Performance breakdown by audience

Example: google_ads_get_audience_performance( customer_id="1234567890", campaign_id="111111111", date_range="LAST_30_DAYS" )

List all user lists (audiences) in the account.

Args: customer_id: Customer ID (without hyphens) list_type: Optional filter by type (CRMBASED, RULE_BASED, SIMILAR, LOGICAL)

Returns: List of all user lists with details

Example: google_ads_list_user_lists( customer_id="1234567890", list_type="CRMBASED" )

Search for Google's predefined audiences (In-Market, Affinity).

Google provides hundreds of pre-built audience segments based on user interests and purchase intent. Search to find relevant audiences for your business.

Args: customer_id: Customer ID (without hyphens) search_term: Search term (e.g., "coffee", "fitness", "travel")

Returns: List of matching Google audiences

Example: google_ads_search_google_audiences( customer_id="1234567890", search_term="coffee" )

Common Categories:

• In-Market: Users actively researching products (high purchase intent)

• Affinity: Users with sustained interest in a topic

• Custom Intent: Create your own based on keywords/URLs

Get detailed information about a specific user list.

Args: customer_id: Customer ID (without hyphens) user_list_id: User list ID

Returns: Detailed user list information

Example: google_ads_get_user_list_details( customer_id="1234567890", user_list_id="12345" )

Create a conversion action for tracking.

Args: customer_id: Customer ID (without hyphens) conversion_name: Name for the conversion (e.g., "Purchase", "Lead Form") category: Conversion category (PURCHASE, SIGNUP, LEAD, etc.) origin: Where conversions occur (WEBSITE, APP, CALL_FROM_ADS, IMPORT) value: Optional default conversion value always_use_default_value: If True, always use default value (ignore transaction-specific values) count_type: ONE (count once per click) or MANY (count every conversion) click_lookback_days: Attribution window for clicks (1-90 days) view_lookback_days: Attribution window for views (1-30 days)

Returns: Success message with conversion action ID and tag snippet

Example: google_ads_create_conversion_action( customer_id="1234567890", conversion_name="Purchase", category="PURCHASE", origin="WEBSITE", value=50.00, count_type="ONE" )

Categories: PURCHASE, SIGNUP, LEAD, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, PHONE_CALL_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, etc.

List all conversion actions in the account.

Args: customer_id: Customer ID (without hyphens) include_removed: Include removed conversions response_format: Output format (markdown or json)

Returns: List of all conversion actions

Example: google_ads_list_conversion_actions( customer_id="1234567890" )

Get the tracking tag/snippet for a website conversion action.

Returns the Global Site Tag and Event Snippet that must be installed on your website to track conversions.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID

Returns: Tracking tag code snippets

Example: google_ads_get_conversion_tag( customer_id="1234567890", conversion_action_id="12345" )

Upload offline conversion data (CRM conversions, phone orders, store visits).

Use this to import conversions that happen offline but originated from Google Ads clicks. You must have the GCLID (Google Click ID) for each conversion.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID (must be IMPORT origin) conversions: List of conversion dictionaries with: - gclid: Google Click ID (required) - conversion_date_time: When conversion occurred (required) Format: "YYYY-MM-DD HH:MM:SS+TZ" (e.g., "2025-12-16 14:30:00-08:00") - conversion_value: Conversion value (optional) - currency_code: Currency code (optional, e.g., "USD")

Returns: Upload success message with count

Example: google_ads_upload_offline_conversions( customer_id="1234567890", conversion_action_id="12345", conversions=[ { "gclid": "Cj0KCQiA...", "conversion_date_time": "2025-12-15 10:30:00-08:00", "conversion_value": 150.00, "currency_code": "USD" }, { "gclid": "Cj0KCQiB...", "conversion_date_time": "2025-12-15 14:20:00-08:00", "conversion_value": 200.00, "currency_code": "USD" } ] )

GCLID Capture: Add {lpurl}?gclid={gclid} to landing page URLs to capture GCLID.

Upload call conversion data for phone calls that converted.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Call conversion action ID call_conversions: List with: - caller_id: Phone number that called (E.164 format: +12345678900) - call_start_date_time: When call started - conversion_date_time: When call qualified as conversion - conversion_value: Optional conversion value - currency_code: Optional currency

Returns: Upload success message

Example: google_ads_upload_call_conversions( customer_id="1234567890", conversion_action_id="12345", call_conversions=[ { "caller_id": "+12025551234", "call_start_date_time": "2025-12-15 10:30:00-08:00", "conversion_date_time": "2025-12-15 10:35:00-08:00", "conversion_value": 500.00, "currency_code": "USD" } ] )

Get conversion performance metrics.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Optional specific conversion date_range: Date range

Returns: Conversion performance data

Example: google_ads_get_conversion_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )

Set attribution model for a conversion action.

Attribution models determine how credit for conversions is assigned to touchpoints in the customer journey.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID attribution_model: Attribution model to use

Returns: Success message

Example: google_ads_set_attribution_model( customer_id="1234567890", conversion_action_id="12345", attribution_model="DATA_DRIVEN" )

Attribution Models:

• LAST_CLICK: 100% credit to last click (default)

• FIRST_CLICK: 100% credit to first click

• LINEAR: Equal credit across all clicks

• TIME_DECAY: More credit to recent clicks

• POSITION_BASED: 40% first, 40% last, 20% middle

• DATA_DRIVEN: Google's ML model (recommended, requires sufficient data)

Recommendation: Use DATA_DRIVEN for accounts with 300+ conversions/month.

Upload store sales data (in-store purchases from online clicks).

This is a specialized form of offline conversion upload for retail businesses tracking in-store purchases that originated from online ads.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Store sales conversion action ID store_sales: List of sales with gclid, timestamp, value

Returns: Upload success message

Example: google_ads_upload_store_sales( customer_id="1234567890", conversion_action_id="12345", store_sales=[ { "gclid": "Cj0KCQiA...", "conversion_date_time": "2025-12-15 15:45:00-08:00", "conversion_value": 85.50, "currency_code": "USD" } ] )

Note: This uses the same upload mechanism as offline conversions.

Get account-wide conversion summary.

Args: customer_id: Customer ID (without hyphens) date_range: Date range

Returns: Summary of all conversions

Example: google_ads_conversion_summary_report( customer_id="1234567890", date_range="LAST_30_DAYS" )

Update conversion action settings.

Args: customer_id: Customer ID (without hyphens) conversion_action_id: Conversion action ID to update conversion_value: New default value status: New status (ENABLED, PAUSED, REMOVED)

Returns: Success message

Example: google_ads_update_conversion_action( customer_id="1234567890", conversion_action_id="12345", conversion_value=75.00, status="ENABLED" )

Get account-level performance overview.

Provides high-level metrics for the entire Google Ads account including impressions, clicks, cost, conversions, and impression share.

Args: customer_id: Customer ID (without hyphens) date_range: Date range (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.)

Returns: Account performance metrics

Example: google_ads_account_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )

Get performance by geographic location.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range

Returns: Performance breakdown by location

Example: google_ads_geographic_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )

Get performance by device type (mobile, desktop, tablet).

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range

Returns: Performance breakdown by device

Example: google_ads_device_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )

Get performance by hour of day and day of week.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range

Returns: Performance breakdown by time

Example: google_ads_time_performance( customer_id="1234567890", date_range="LAST_30_DAYS" )

Compare performance between two time periods.

Args: customer_id: Customer ID (without hyphens) current_start: Current period start (YYYY-MM-DD) current_end: Current period end (YYYY-MM-DD) previous_start: Previous period start (YYYY-MM-DD) previous_end: Previous period end (YYYY-MM-DD)

Returns: Period-over-period comparison with changes

Example: google_ads_compare_periods( customer_id="1234567890", current_start="2025-12-01", current_end="2025-12-15", previous_start="2025-11-01", previous_end="2025-11-15" )

Get search impression share metrics showing visibility in auctions.

Args: customer_id: Customer ID (without hyphens) campaign_id: Optional campaign ID filter date_range: Date range

Returns: Impression share data

Example: google_ads_search_impression_share( customer_id="1234567890", date_range="LAST_30_DAYS" )

Compare performance across multiple campaigns side-by-side.

Analyze and compare metrics across 2-10 campaigns to identify best performers, optimize budget allocation, and find underperforming campaigns.

Args: customer_id: Google Ads customer ID (10 digits, no hyphens) campaign_ids: Comma-separated campaign IDs (e.g., "123,456,789") date_range: Date range - LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, etc. response_format: Output format (markdown or json)

Returns: Comparative analysis with rankings and insights

Example: google_ads_campaign_comparison( customer_id="1234567890", campaign_ids="111111,222222,333333", date_range="LAST_30_DAYS" )

Comparison Metrics: - Impressions, clicks, CTR - Cost and average CPC - Conversions and cost per conversion - Conversion value and ROAS - Share of total (% of overall performance)

Use Cases: - Identify top performers for budget increases - Find underperformers to optimize or pause - Compare A/B test campaigns - Analyze campaign strategy effectiveness - Guide budget reallocation decisions