Lists campaigns in a Google Ads account with optional status filtering. Returns one row per campaign with id, name, status, channel_type (SEARCH / DISPLAY / VIDEO / etc.), bidding_strategy_type, serving_status, primary_status, and daily_budget. Read-only. Use this to audit account structure or find a campaign_id before calling campaigns.get / update / update_status. For a single campaign's full details use google_ads_campaigns_get instead.

Fetches the full detail record for a single campaign by ID. Returns the same fields as campaigns.list plus start_date, end_date, network_settings, geo_target_type, and bidding_strategy_system_status. Read-only. Use this when you already have a campaign_id; for discovery use google_ads_campaigns_list.

Creates a new Search or Display campaign in the specified Google Ads account. Returns the new campaign's resource_name and id. Mutating — counts against daily write quota. Reversible via rollback_apply (reversal pauses the campaign rather than deleting it). Requires a pre-existing budget_id; to create a budget first, call google_ads_budget_create. For later edits use google_ads_campaigns_update or google_ads_campaigns_update_status.

Updates one or more settings on an existing campaign. Partial update — only fields provided are changed; omitted fields are preserved. Returns the updated campaign record. Mutating and reversible via rollback_apply (rollback restores the previous field values). For status-only changes (ENABLED / PAUSED / REMOVED) prefer google_ads_campaigns_update_status, which is a lighter-weight call and maps cleanly to pause/resume workflows.

Sets the delivery status of a single campaign to ENABLED, PAUSED, or REMOVED. Lightweight — writes only the status field. Returns the campaign ID and new status. Reversible via rollback_apply for ENABLED ↔ PAUSED; REMOVED is a soft delete that can be reversed by setting status back to PAUSED within 30 days. Use this for pause/resume; use google_ads_campaigns_update to change name, bidding, or other settings.

Explains why a campaign is not serving or is under-delivering. Returns an ordered list of issues drawn from serving_status, primary_status, and primary_status_reasons (e.g. LIMITED_BY_BUDGET, AD_GROUPS_PAUSED, KEYWORDS_DISAPPROVED, NO_ELIGIBLE_ADS), each annotated with a plain-language description and a remediation hint. Read-only — does not change anything. Use this before pulling raw performance reports; it narrows the problem space.

Lists ad groups in a Google Ads account, optionally scoped to a single parent campaign and/or filtered by status. Returns id, name, campaign_id, status, type (SEARCH_STANDARD / DISPLAY_STANDARD / etc.), cpc_bid_micros, and ad_rotation_mode per ad group. Read-only. Use this to locate an ad_group_id before calling ad_groups.create / update or ads.create; if you already have the id, fetch it directly via ads.list filtered by ad_group_id.

Creates a new ad group inside an existing campaign. Returns the new ad_group's resource_name and id. Mutating — reversible via rollback_apply (rollback pauses the ad group rather than deleting it). The parent campaign must be ENABLED or PAUSED; creating under a REMOVED campaign fails. After creation, add ads with google_ads_ads_create and keywords with google_ads_keywords_add.

Updates one or more settings on an existing ad group. Partial update — only provided fields are changed. Returns the updated ad group. Mutating, reversible via rollback_apply. Does not cascade to ads or keywords under this ad group; use google_ads_ads_update / update_status and google_ads.keywords.* for those.

Lists ads in a Google Ads account, optionally scoped to one ad group and/or filtered by status. Returns id, ad_group_id, status, type (RESPONSIVE_SEARCH_AD / RESPONSIVE_DISPLAY_AD / etc.), final_urls, approval_status, and a creative summary (headlines / descriptions for RSAs). Read-only. Use this to find an ad_id before calling ads.update / update_status or to audit creative inventory. For disapproval details, follow up with google_ads_ads_policy_details.

Creates a Responsive Search Ad (RSA) in the specified ad group. Returns the new ad's resource_name, id, and initial approval_status (usually UNDER_REVIEW for ~1 business day). Mutating, reversible via rollback_apply (rollback pauses the ad). Google Ads requires 3–15 headlines and 2–4 descriptions. For display/banner ads use google_ads_ads_create_display instead; the two creative formats are not interchangeable.

Creates a Responsive Display Ad (RDA) in a DISPLAY campaign's ad group. Marketing/square/logo image paths point to local files; mureo uploads each file to Google Ads as an ImageAsset before composing the ad. Returns the new ad's resource_name, id, and the generated asset IDs. Mutating, reversible via rollback_apply. For Search campaigns use google_ads_ads_create; the ad_group must belong to a DISPLAY campaign or this call fails with a channel-mismatch error.

Updates the creative copy of an existing Responsive Search Ad by replacing headlines and/or descriptions. Returns the updated ad. Google Ads does not support in-place edit of RSA creative assets — this call typically replaces the ad with a new one under the same ID, which resets learning and triggers re-review. Mutating, reversible via rollback_apply. For status-only changes (pause/resume) use google_ads_ads_update_status, which is lighter-weight and does not reset learning.

Sets the delivery status of a single ad to ENABLED, PAUSED, or REMOVED. Lightweight — writes only the status field and does not reset learning signals. Returns the ad ID and new status. Reversible via rollback_apply. Use this for pause/resume; use google_ads_ads_update to change the creative copy itself.

Fetches the Google Ads policy review result for a single ad, including approval_status (APPROVED / APPROVED_LIMITED / DISAPPROVED / UNDER_REVIEW), a list of policy_topic_entries with topic (e.g. DESTINATION_NOT_WORKING, RESTRICTED_CONTENT), evidence, and an appeal eligibility flag. Read-only. Call this after google_ads_ads_list surfaces a non-APPROVED ad to understand the specific disapproval reasons.

Fetches the campaign-budget record attached to a campaign. Returns budget_id, name, amount_micros, delivery_method (STANDARD / ACCELERATED), period (DAILY), and reference_count (how many campaigns share this budget). Read-only. Shared budgets are common — confirm reference_count before calling google_ads_budget_update, since changes affect all linked campaigns.

Sets the daily amount on an existing campaign budget. Mutating and reversible via rollback_apply (rollback restores the prior amount). Returns the updated budget. If the budget is shared across multiple campaigns, the change affects all of them — call google_ads_budget_get first to check reference_count. The amount parameter is in the account's currency unit (JPY / USD / etc.), not micros.

Creates a new campaign budget that can be attached to one or more campaigns. Returns the new budget's id and resource_name. Mutating, reversible via rollback_apply. Typical flow: budget.create → campaigns.create with the returned budget_id. To edit an existing budget's amount use google_ads_budget_update instead of creating a second budget.

Lists all Google Ads accounts accessible under the configured manager (MCC) account or directly under the authenticated user. Returns one row per accessible customer with id (10-digit), descriptive_name, currency_code, time_zone, and manager flag. Read-only. Use this at the start of a session to choose which customer_id to pass into subsequent calls; most other tools fall back to GOOGLE_ADS_CUSTOMER_ID if customer_id is omitted.

Lists keyword criteria in a Google Ads account, optionally scoped to a campaign and/or ad group and filtered by status. Returns criterion_id, ad_group_id, text, match_type, status, cpc_bid_micros (if overridden), quality_score, and approval_status per keyword. Read-only. Use this to locate a criterion_id before calling keywords.pause / remove, or to audit keyword coverage. For quality-score diagnostics use google_ads_keywords_diagnose.

Adds one or more keyword criteria to a single ad group. Returns the created criterion_ids keyed by their input position. Mutating, reversible via rollback_apply (rollback pauses the keywords rather than removing them). Duplicate text+match_type pairs inside the same ad group are rejected by Google Ads — call google_ads_keywords_cross_adgroup_duplicates first if you are adding at scale.

Removes (soft-deletes) a single keyword criterion from an ad group. Returns the removed criterion_id. Destructive and reversible via rollback_apply, but rollback re-adds the keyword as a fresh criterion — the original quality score and learning are lost. For temporary suspension prefer google_ads_keywords_pause, which preserves all signals.

Generates new keyword ideas from seed terms using the Google Ads Keyword Planner API. Returns suggested keyword text, avg_monthly_searches, competition (LOW / MEDIUM / HIGH), top_of_page_bid_low_micros, and top_of_page_bid_high_micros. Read-only — produces ideas but does not add anything to the account. Use google_ads_keywords_add to materialize the ones you want.

Reports quality-score and delivery-status issues across every keyword in a campaign. Returns keywords grouped by severity — LOW_QUALITY_SCORE (< 5/10), BELOW_FIRST_PAGE_BID, RARELY_SHOWN, DISAPPROVED — each with criterion_id, text, ad_group_id, and a remediation hint (raise bid, tighten match type, etc.). Read-only. Use this before pulling raw search-terms reports; it triages where attention should go.

Lists campaign-level negative keyword criteria for a single campaign. Returns criterion_id, text, and match_type per entry. Read-only. Ad group-level negatives are not included here — they live on the ad group and are managed through google_ads_negative_keywords_add_to_ad_group.

Adds one or more campaign-level negative keywords. These apply to every ad group in the campaign. Returns created criterion_ids. Mutating, reversible via rollback_apply. For negatives scoped to a single ad group use google_ads_negative_keywords_add_to_ad_group instead — campaign-level negatives can over-block if applied too broadly.

Sets the status of a single keyword criterion to PAUSED. Lightweight and non-destructive — quality score and historical stats are preserved, and the keyword can be resumed by calling google_ads_keywords_add with the same text+match_type (or re-enabled via the Google Ads UI). Returns the criterion ID and new status. Reversible via rollback_apply. Use this instead of google_ads_keywords_remove whenever the suspension might be temporary.

Removes a single campaign-level negative keyword. Returns the removed criterion_id. Destructive — the exclusion is lifted immediately on the next serving cycle, which can increase unwanted traffic. Reversible via rollback_apply (re-adds the negative). For ad group-level negatives there is currently no explicit remove tool — use the Google Ads UI or raise an issue if needed.

Adds one or more ad group-level negative keywords. Scope is narrower than campaign-level negatives — exclusions apply only to the specified ad group. Returns created criterion_ids. Mutating, reversible via rollback_apply. Prefer this over google_ads_negative_keywords_add when the exclusion is only wrong in one ad group's context.

Analyses recent search-term performance and returns suggested negative keywords that waste spend relative to a target CPA. Returns candidates with text, suggested match_type, spend, conversions, and rationale (e.g. 'spend > 3x target CPA, 0 conversions'). Read-only — suggestions are not applied. Use google_ads_negative_keywords_add / add_to_ad_group to materialize the ones you want after operator review.

Runs a holistic keyword-portfolio audit for a campaign and returns grouped recommendations: pause candidates (zero-spend or zero-conversion), bid-raise candidates (below first-page bid), match-type-tighten candidates (broad stealing spend), and unused keyword-planner ideas. Each item includes criterion_id, text, spend, conversions, and a reason string. Read-only — recommendations are not applied. Materialize accepted ones via google_ads_keywords_pause / add / negative_keywords.add.

Finds the same text+match_type keyword appearing across multiple ad groups in a campaign. Returns groups of duplicate criteria with per-ad-group spend, conversions, and quality score, plus a consolidation recommendation (which copy to keep, which to pause/remove). Read-only. Duplicates compete in the auction and hurt aggregate quality score — run this before a keyword restructuring sprint.

List sitelink assets attached to a Google Ads campaign, merging campaign-level and account-level entries. Returns [{id, resource_name, link_text, description1, description2, final_urls:[string], level ('campaign'|'account')}]. Account-level sitelinks apply to the whole customer and are deduplicated by id. Read-only. Use this to audit extensions before calling google_ads_sitelinks_create (20 per-campaign limit) or google_ads_sitelinks_remove. For callouts use google_ads_callouts_list.

Create a sitelink Asset and link it to a Google Ads campaign in a two-step mutate (AssetService then CampaignAssetService). Returns {resource_name} of the created asset on success, or {error:true, error_type:'validation_error', message} when the campaign already has 20 campaign-level sitelinks (hardcoded _MAX_SITELINKS_PER_CAMPAIGN limit). Mutating — reversible only by google_ads_sitelinks_remove using the returned asset_id. The asset is newly minted per call; identical text produces duplicate assets unless deduplicated upstream.

Detach a sitelink asset from a Google Ads campaign by removing the CampaignAsset link. Returns {resource_name} of the removed campaign-asset association. Destructive — unlinks the asset from the campaign so it stops serving, but does not delete the underlying Asset row. Re-linking requires google_ads_sitelinks_create with the same text/URL. To list current sitelinks use google_ads_sitelinks_list.

List callout extension assets linked to a Google Ads campaign. Returns [{id, resource_name, callout_text}]. Unlike google_ads_sitelinks_list, this only scans campaign_asset rows (no account-level merge). Read-only. Use this to audit coverage before calling google_ads_callouts_create (hardcoded limit: 20 callouts per campaign) or google_ads_callouts_remove.

Create a callout Asset and link it to a Google Ads campaign in a two-step mutate (AssetService then CampaignAssetService). Returns {resource_name} of the newly created asset, or {error:true, error_type:'validation_error', message} when the campaign already has 20 callouts (_MAX_CALLOUTS_PER_CAMPAIGN limit). Mutating — reversible only by google_ads_callouts_remove. The asset is minted per call, so identical text creates duplicate asset rows. For sitelink variants use google_ads_sitelinks_create.

Detach a callout asset from a Google Ads campaign by removing the CampaignAsset link. Returns {resource_name} of the removed campaign-asset association. Destructive — the callout stops serving on the campaign but the Asset row itself is not deleted. Re-enabling requires google_ads_callouts_create with the same text. For the sibling list operation use google_ads_callouts_list.

List every conversion action configured on the Google Ads customer, ordered by numeric id. Returns [{id (string), name, type (ConversionActionType enum string, e.g. 'WEBPAGE'), status ('ENABLED'|'HIDDEN'|'REMOVED'|'UNSPECIFIED'|'UNKNOWN'), category (enum string, e.g. 'PURCHASE', 'SIGNUP')}]. Read-only. Use this to discover conversion_action_id values before calling .get, .update, .remove, or .tag. For CV performance metrics use google_ads_conversions_performance.

Fetch one conversion action's configuration from Google Ads by numeric ID. Returns {id, name, type (ConversionActionType enum string, e.g. 'WEBPAGE'), status ('ENABLED'|'HIDDEN'|'REMOVED'|'UNSPECIFIED'|'UNKNOWN'), category (enum string, e.g. 'PURCHASE', 'SIGNUP')} or null when no row matches. Read-only; does NOT return value settings or lookback-window values — use the Google Ads UI for those. For the HTML/JS tag snippet to embed on a site use google_ads_conversions_tag; for full listings use google_ads_conversions_list.

Report Google Ads conversions broken down by conversion_action and date, with optional campaign filter. Returns {period, campaign_id, total_conversions, actions:[{campaign_id, campaign_name, conversion_action_name, conversions, conversions_value, first_date, last_date, cost_per_conversion}] (sorted by conversions desc), daily_details:[{date, campaign_id, campaign_name, conversion_action_name, conversions, conversions_value}], landing_pages:[{date, landing_page_url, campaign_id, campaign_name, conversions, conversions_value, clicks}]}. Only rows with conversions > 0 are included. cost_per_conversion is computed via a separate GAQL because GAQL cannot SELECT cost_per_conversion alongside segments.conversion_action_name. Read-only. For campaign-level metrics use google_ads_performance_report.

Create a new Google Ads conversion action. Returns {resource_name:'customers//conversionActions/'} of the newly created row. Mutating — the conversion action is persisted with status ENABLED by default. Reversible via google_ads_conversions_update with status='REMOVED' or google_ads_conversions_remove. Name must be <= 256 characters. Category defaults to 'DEFAULT'. For updating an existing action use google_ads_conversions_update.

Update fields on an existing Google Ads conversion action via FieldMask mutate. Returns {resource_name} of the updated row. Mutating — partial update: only the fields you pass are modified, the rest are preserved. At least one updatable field must be supplied (name, category, status, default_value, always_use_default_value, click_through_lookback_window_days, view_through_lookback_window_days) or the call raises ValueError. To delete/archive an action use status 'REMOVED' here or call google_ads_conversions_remove.

Archive (status=REMOVED) a Google Ads conversion action. Returns {resource_name} of the removed row. Destructive — historical data remains but the action stops counting toward 'Conversions'. Re-enabling requires google_ads_conversions_update with status='ENABLED'. For soft-hide that keeps the row visible use google_ads_conversions_update with status='HIDDEN'.

Fetch the HTML/JavaScript tag snippets for a Google Ads conversion action so you can install them on the advertiser's site. Returns [{type (TagSnippetType enum string, e.g. 'WEBPAGE', 'WEBPAGE_ONCLICK'), page_header (the block that goes in ), event_snippet (the goal event snippet)}]. Empty list when no snippets are configured (e.g. UPLOAD_CLICKS actions have no web tag). Read-only. For configuration metadata use google_ads_conversions_get.

List Google's current automated recommendations for the account. Returns [{resource_name, type (RecommendationType enum string, e.g. 'KEYWORD', 'TEXT_AD', 'TARGET_CPA_OPT_IN', 'MAXIMIZE_CONVERSIONS_OPT_IN'), impact:{base_metrics:{impressions, clicks, cost_micros}}, campaign_id (resource path when scoped to a campaign)}]. Read-only. Filter by campaign_id to scope to one campaign, or by recommendation_type to scope to one kind. To apply a recommendation use google_ads_recommendations_apply with resource_name from this list.

Apply one Google Ads recommendation by resource name. Returns {resource_name} of the applied recommendation. Mutating — the underlying change (new keyword, ad copy, bidding strategy switch, etc.) is committed to the campaign immediately and is NOT reversible through this tool. The resource_name format 'customers//recommendations/' is re-validated server-side to prevent injection. To list candidates use google_ads_recommendations_list; some recommendation types also change budget, device, or schedule settings.

Get the device targeting state for a Google Ads campaign. Always returns three entries (DESKTOP, MOBILE, TABLET in that order), each shaped {criterion_id (string or null when no explicit criterion exists), device_type ('DESKTOP'|'MOBILE'|'TABLET'), bid_modifier (float or null), enabled (bool — True when no criterion exists OR bid_modifier != 0.0; False when bid_modifier==0 meaning delivery is off)}. Read-only. The 'enabled=False' semantics are mureo's convention: Google represents 'don't serve' as bid_modifier=0.0 (i.e. -100%). For modifying, use google_ads_device_targeting_set or google_ads_bid_adjustments_update.

Toggle device delivery on a Google Ads campaign by setting bid_modifier=1.0 on enabled devices and 0.0 on disabled ones. Iterates all three devices individually so one failure does not abort the others. Returns {message, enabled_devices (sorted list), disabled_devices (sorted list), updated (list of resource_names that succeeded), errors (list of '(): ' strings, or null)}. Mutating — existing device criteria are UPDATE-ed, missing ones are CREATE-ed. Reversible only by calling this tool again with a different enabled_devices. enabled_devices must be non-empty (passing an empty array raises ValueError). For fine-grained non-zero bid modifiers use google_ads_bid_adjustments_update.

List every campaign_criterion row that has a non-null bid_modifier on a Google Ads campaign. Returns [{criterion_id, type (CriterionType enum string, e.g. 'DEVICE', 'LOCATION', 'AD_SCHEDULE'), bid_modifier (float), device_type ('DESKTOP'|'MOBILE'|'TABLET' for DEVICE criteria; 'UNKNOWN()' for non-DEVICE rows such as LOCATION or AD_SCHEDULE, where n is the raw device-type enum ordinal — never null)}]. Read-only. For the device-summary view (all three devices, even implicit ones) use google_ads_device_targeting_get. For location-only use google_ads_location_targeting_list.

Update the bid_modifier of a single campaign_criterion. Returns {resource_name} of the updated criterion. Mutating — FieldMask-based partial update on bid_modifier only; other criterion fields are preserved. Reversible by another call to this tool. bid_modifier must be 0.1-10.0 (0.1 = -90%, 1.0 = neutral, 10.0 = +900%); values outside this range raise ValueError. To toggle a device on/off with bid_modifier 0.0 use google_ads_device_targeting_set instead (this tool rejects 0.0).

List every LOCATION campaign_criterion on a Google Ads campaign. Returns [{criterion_id, geo_target_constant (resource path, e.g. 'geoTargetConstants/2392' for Japan), bid_modifier (float or null)}]. Read-only. Geo target constant IDs map to countries/regions/cities — look up via Google's GeoTargetConstantService. For adding or removing locations use google_ads_location_targeting_update; for schedule-based targeting use google_ads_schedule_targeting_list.

Add and/or remove location criteria on a Google Ads campaign in a single mutate. Returns [{resource_name}] — one entry per operation executed (adds first, then removes). Mutating — adds create new criteria, removes delete them by criterion_id. Reversible only by calling this tool again with the inverse operations. At least one of add_locations / remove_criterion_ids must be provided. Locations can be passed as bare numeric IDs or as full 'geoTargetConstants/' paths; bare IDs are auto-prefixed.

List the ad-schedule (day-of-week + hour-of-day) targeting criteria attached to a Google Ads campaign. Returns one row per schedule criterion with criterion_id (string), day_of_week (string form of the DayOfWeek enum, e.g. 'MONDAY'..'SUNDAY'), start_hour (integer 0-23), end_hour (integer 0-24; 24 denotes end-of-day), start_minute and end_minute (string form of the MinuteOfHour enum: 'ZERO', 'FIFTEEN', 'THIRTY', or 'FORTY_FIVE'), and bid_modifier (float, or null when unset). Read-only; returns an empty list when the campaign has no schedule targeting (meaning: 24/7 delivery). Use this to audit schedule coverage or collect criterion_ids before calling google_ads_schedule_targeting_update (which is what you use to add or remove entries). For device-level modifiers use google_ads_device_targeting_get; for geo targeting use google_ads_location_targeting_list.

Add and/or remove ad-schedule criteria on a Google Ads campaign in a single mutate. Returns [{resource_name}] — one entry per operation (adds first, then removes). Mutating — new schedule criteria default to start_minute/end_minute=ZERO (on the hour). Reversible only by calling this tool again with inverse operations. At least one of add_schedules / remove_criterion_ids must be provided. For the read-only listing use google_ads_schedule_targeting_list.

List the most recent change_event rows on a Google Ads account, sorted newest-first and capped at 100. Returns [{change_date_time (Google-formatted timestamp string returned verbatim from the API — typically 'YYYY-MM-DD HH:MM:SS.ffffff+00:00' but no format coercion is applied, so callers should parse defensively), change_resource_type (enum string e.g. 'CAMPAIGN', 'CAMPAIGN_BUDGET', 'AD_GROUP', 'AD', 'CAMPAIGN_BID_MODIFIER'), resource_change_operation ('CREATE'|'UPDATE'|'REMOVE' as enum string), changed_fields (list of dotted field paths), user_email}]. Read-only. Defaults to the last 14 days when dates are omitted; the API rejects an open-ended range so mureo always fills one. Use this for audit-trail diagnosis. For narrower bid/budget-only filtering use google_ads_cost_increase_investigate.

Aggregate campaign-level performance metrics for a Google Ads account over a reporting window. Returns one row per campaign shaped as {campaign_id, campaign_name, metrics}, where the metrics object contains impressions, clicks, cost_micros, cost (currency-formatted), conversions, ctr, average_cpc_micros, average_cpc, cost_per_conversion_micros, and cost_per_conversion. Read-only; no mutation. Use this for campaign-level totals. For per-ad breakdowns use google_ads_ad_performance_report; for Google Search vs. Search Partners splits use google_ads_network_performance_report; for query-level detail use google_ads_search_terms_report; for conversion-action slicing use google_ads_conversions_performance.

List actual user search queries that triggered ads in the account over a reporting window. Returns one row per search term shaped as {search_term, metrics}, where the metrics object contains impressions, clicks, cost_micros, cost (currency-formatted), conversions, and ctr. The rows are filterable by campaign_id and/or ad_group_id but those IDs are NOT echoed back in the output — scope your query before calling. Read-only. Use this for raw query logs when you need to eyeball the terms yourself. For rule-based add/exclude candidates use google_ads_search_terms_review; for intent-class distribution use google_ads_search_terms_analyze; for campaign-level aggregates without query breakdown use google_ads_performance_report.

Score every search term in a Google Ads campaign against six hardcoded rules and split them into add / exclude / watch buckets. Returns {campaign_id, ad_group_id, period, target_cpa, target_cpa_source, add_candidates, exclude_candidates, watch_candidates, summary:{total_search_terms, add_count, exclude_count, watch_count}, intent_analysis?}. Each candidate has {search_term, action, match_type ('EXACT'|'PHRASE'), score (40-90), reason, metrics:{conversions, clicks, cost, ctr}}. target_cpa is resolved from the explicit argument first, then the campaign's bidding strategy, then last-30-days actual CPA; target_cpa_source reports which path ('explicit'|'bidding_strategy'|'actual'|'none'). New terms absent from the previous period are routed to watch_candidates. Read-only — emits candidates but does not add or exclude anything. Default period is LAST_7_DAYS. For keyword/N-gram overlap stats use google_ads_search_terms_analyze; for the raw query log use google_ads_search_terms_report.

Interpret a campaign's impression-share metrics and surface human-readable insights about competitive position. Returns {campaign_id, campaign_name, period, impression_share_metrics:{search_impression_share, search_rank_lost_is, search_budget_lost_is, search_top_is, search_abs_top_is, note}, insights:[strings], note}. Each impression-share value is a percentage (0-100, rounded to 1 decimal) or None. Insights fire when IS < 50/70%, rank-lost > 20%, budget-lost > 20%, or abs-top-IS < 20%. Read-only. Note: Google Ads API v23 removed competitor-level auction_insight (domain overlap, outranking share); only impression-share proxies are returned. For the raw metrics without insights use google_ads_auction_insights_get; full competitor data is only available in the Google Ads UI.

Detect rising/falling CPC trends in a Google Ads campaign over a reporting window using daily segmentation and linear regression. Returns {campaign_id, campaign_name, period, data_points, daily_data:[{date, average_cpc, clicks, impressions, cost}], trend:{direction ('rising'|'falling'|'stable'|'insufficient_data'), slope_per_day, change_rate_per_day_pct? (present only when direction is not 'insufficient_data' — i.e. when at least 2 daily data points are available), avg_cpc, min_cpc, max_cpc}, insights:[strings]}. Direction is 'rising' when daily change > +1%, 'falling' when < -1%. Days with zero clicks are excluded from the GAQL. Insights call out week-over-week surges >15% and days exceeding 2x average CPC. Read-only. For device or auction-share investigation use google_ads_device_analyze or google_ads_auction_insights_analyze.

Compare Google Ads campaign performance across device segments (Desktop / Mobile / Tablet). Returns {campaign_id, campaign_name, period, devices:[{device_type, impressions, clicks, cost, conversions, ctr (percent), average_cpc, cpa, cvr (percent)}], insights:[strings]}, sorted by cost descending. cpa is None when conversions == 0. Insights fire for devices with spend and zero conversions, worst/best CPA ratios > 1.5x, and Mobile CTR less than half of Desktop CTR. Read-only. Returns a 'message' field and empty devices list when no device-segmented data exists. For applying device bid modifiers use google_ads_bid_adjustments_update or google_ads_device_targeting_set; for the raw ad-schedule criteria (hour-of-day targeting config, NOT performance segmentation by hour) use google_ads_schedule_targeting_list.

Report Google Ads performance split by ad network — Google Search vs. Search Partners. Returns one row per (campaign, network) shaped as {campaign_id, campaign_name, network_type ('SEARCH'|'SEARCH_PARTNERS'), network_label ('Google Search'|'Search Partners'), impressions, clicks, cost, conversions, ctr (percent), average_cpc, cost_per_conversion}. Display, YouTube, and Discover rows are filtered out. ctr, average_cpc, and cost_per_conversion are rounded to whole-unit currency. Read-only. Use this to decide whether to toggle Search Partners. For overall campaign totals use google_ads_performance_report; for per-ad breakdowns use google_ads_ad_performance_report.

Report per-ad performance across Google Ads ad_group_ad rows. Returns one row per ad shaped as {ad_id, ad_type, status ('ENABLED'|'PAUSED'|'REMOVED'), ad_group_id, ad_group_name, campaign_id, campaign_name, metrics} where metrics contains impressions, clicks, cost_micros, cost (currency), conversions, ctr, average_cpc_micros, average_cpc, cost_per_conversion_micros, cost_per_conversion. Filterable by ad_group_id and/or campaign_id (both optional, both numeric). Read-only; no mutation. For ENABLED-only A/B comparison within a single ad group with WINNER/LOSER verdicts use google_ads_ad_performance_compare; for campaign-level aggregates use google_ads_performance_report.

Analyze keyword/search-term overlap and N-gram distribution for a Google Ads campaign. Returns {campaign_id, period, registered_keywords_count, search_terms_count, overlap_rate (0.0-1.0), ngram_distribution:{unigrams, bigrams, trigrams} (each top-10 of {text, count, cost, conversions}), keyword_candidates:[{search_term, conversions, cost, clicks}] (CV>0 and not yet registered), negative_candidates:[{search_term, cost, clicks, impressions}] (top 20 by cost with cost>0 and conversions=0), insights:[strings]}. Read-only. For rule-scored add/exclude/watch buckets use google_ads_search_terms_review; for the raw unscored term log use google_ads_search_terms_report.

Diagnose a single Google Ads campaign by composing current-vs-previous comparison, top search terms, Google recommendations, and recent change history. Returns {campaign_id, period, campaign (get_campaign shape), performance_current, performance_previous, changes:{impressions_change_pct, clicks_change_pct, cost_change_pct, conversions_change_pct}, cpa_current? (only when current-period conversions > 0), cpa_previous? (only when previous-period conversions > 0), cpa_change_pct? (only when both above are present), top_search_terms (top 20 by cost), recommendations_from_google (up to 10), recent_changes (up to 10), issues:[strings], insights:[strings], recommendations:[strings]}. Any subcomponent that fails is replaced with the string 'Retrieval failed' rather than aborting the call. Read-only. Default period is LAST_7_DAYS. For cost-spike root-cause analysis use google_ads_cost_increase_investigate; for account-wide health use google_ads_health_check_all.

Investigate the root cause of a Google Ads cost spike or CPA deterioration by comparing the last 7 days against the prior 7 days. Returns {campaign_id, performance_current_7d, performance_previous_7d, changes, cost_breakdown:{cpc_current, cpc_previous, cpc_change_pct, clicks_current, clicks_previous, clicks_change_pct}, new_search_terms (top 20 by cost), wasteful_search_terms (top 20 zero-CV terms with cost), bid_budget_changes (up to 10 CAMPAIGN/CAMPAIGN_BUDGET/AD_GROUP/CAMPAIGN_BID_MODIFIER events from change history), existing_negative_keywords_count, negative_keyword_candidates (up to 10), findings:[strings], recommended_actions:[strings]}. The comparison window is hardcoded to LAST_7_DAYS. Read-only. For a broader diagnostic composite use google_ads_performance_analyze; for CPA-vs-target monitoring use google_ads_monitoring_cpa_goal.

Screen every campaign in the Google Ads account by primary_status and run detailed delivery diagnostics on up to 5 problem/warning campaigns. Returns {total_campaigns, enabled_count, paused_count, removed_count, healthy_campaigns (ELIGIBLE), warning_campaigns (other primary_status among ENABLED), problem_campaigns (NOT_ELIGIBLE/ENDED/REMOVED among ENABLED — each: {campaign_id, name, primary_status}), detailed_diagnostics:[{campaign_id, name, issues, warnings, recommendations}] (up to 5; problem-first, then warning), summary:{total_enabled, healthy, warning, problem, message}}. Read-only. For single-campaign delivery diagnosis use google_ads_campaigns_diagnose; for CPA-goal monitoring use google_ads_monitoring_cpa_goal.

Rank ENABLED ads within a single Google Ads ad group and assign WINNER / LOSER / INSUFFICIENT_DATA verdicts. Returns {ad_group_id, period, ads:[{ad_id, impressions, clicks, conversions, cost, ctr, cvr, cpa, score (ctr*cvr, or ctr when conversions=0), rank, verdict, headlines?, descriptions?}], winner, recommendation, insights:[strings]}. Ads with impressions < 100 are flagged INSUFFICIENT_DATA; all ads tied at the top score receive WINNER, the rest LOSER. Read-only — does not pause or rotate ads. For cross-ad-group per-ad reporting use google_ads_ad_performance_report; for RSA asset-level splits use google_ads_rsa_assets_analyze.

Score budget allocation efficiency across every ENABLED Google Ads campaign. Returns {period, total_cost, total_conversions, campaigns:[{campaign_id, name, cost, conversions, cost_share, cv_share, efficiency_ratio (cv_share / cost_share), verdict ('EFFICIENT' when ratio > 1.2, 'INEFFICIENT' when < 0.8, 'NORMAL' otherwise, 'NO_COST' when cost==0), cpa}], recommendations:[strings], insights:[strings]}. Per-campaign cost/conversions come from get_performance_report — individual failures are silently treated as zero. Read-only. For a concrete DECREASE/INCREASE reallocation plan use google_ads_budget_reallocation; to change a single budget use google_ads_budget_update.

Propose a budget reallocation plan by cutting up to 20% from INEFFICIENT campaigns and distributing the freed amount equally across EFFICIENT campaigns. Returns the full google_ads_budget_efficiency payload plus {reallocation_plan:[{campaign_id, campaign_name, action ('DECREASE'|'INCREASE'), current_daily_budget, proposed_daily_budget, change_amount, reason}], total_freed, summary}. When the account has no campaigns with spend in the window, the response short-circuits to just {...efficiency payload, reallocation_plan:[], summary:'No campaigns with spend in period'} and the total_freed key is omitted — parse defensively. Reductions below 100 (currency units) are skipped. Current daily budgets are fetched via get_budget — failures fall back to 0. Read-only — emits a plan only, does not apply any budget changes. To actually apply a change use google_ads_budget_update; for the efficiency scoring alone use google_ads_budget_efficiency.

Fetch raw impression-share metrics for one Google Ads campaign. Returns a list with a single entry: {campaign_id, campaign_name, search_impression_share, search_rank_lost_is, search_budget_lost_is, search_top_is, search_abs_top_is, note} — every IS field is a percentage (0-100, float, rounded to 1 decimal) or None. On failure returns a single-element list with {error:'auction_insights_unavailable'|'no_data', reason, hint}. Read-only. Note: Google Ads API v23 removed competitor-level auction_insight (domain, overlap, outranking); only impression-share proxies are returned. For a version with human-readable insights layered on top use google_ads_auction_insights_analyze.

Split Responsive Search Ad asset performance within a Google Ads campaign into headlines and descriptions. Returns {campaign_id, period, headlines:[{text, performance_label ('BEST'|'GOOD'|'LOW'|'POOR'|'LEARNING'|'PENDING'|'UNKNOWN'), impressions, clicks, conversions, cost, ctr (percent)}], descriptions (same shape), best_headlines (performance_label == 'BEST'), worst_headlines ('LOW'|'POOR'), best_descriptions, worst_descriptions, insights:[strings]}. Rows sorted by impressions descending. Read-only. For an audit version with replacement recommendations use google_ads_rsa_assets_audit; for ad-level A/B use google_ads_ad_performance_compare.

Audit Responsive Search Ad assets against Google's quantity and quality guidance and emit replacement recommendations. Returns {campaign_id, period, headline_count, description_count, label_distribution:{:count}, best_headlines, worst_headlines, best_descriptions, worst_descriptions, recommendations:[{type ('add_headlines'|'add_descriptions'|'replace_headline'|'replace_description'|'wait_for_data'), priority ('HIGH'|'MEDIUM'|'LOW'), message, asset_text?, performance_label?}], recommendation_count}. HIGH priorities fire when headlines < 8 or descriptions < 3. LOW 'wait_for_data' fires when LEARNING+UNKNOWN > 50% of assets. Read-only; does not modify any assets. For the raw per-asset performance breakdown use google_ads_rsa_assets_analyze.

Run three B2B-specific optimization checks (ad schedule, device CPA disparity, informational-query ratio) against a Google Ads campaign. Returns {campaign_id, campaign_name, period, suggestion_count, suggestions:[{category ('schedule'|'device'|'search_terms'), priority ('HIGH'|'MEDIUM'|'LOW'), message}]}. Schedule fires HIGH when no ad schedule is set, MEDIUM for weekend delivery. Device fires MEDIUM when Mobile CPA > Desktop CPA * 1.3, LOW when Tablet has zero conversions with spend. Search-terms fires MEDIUM when informational patterns exceed 20% of queries. Read-only. Use this when the advertiser self-identifies as B2B. For general campaign diagnosis use google_ads_performance_analyze.

Fetch a landing page over HTTP(S) and extract structured content for ad-copy alignment. Returns title, meta_description, h1_texts, h2_texts, main_text (truncated to 1500 chars), cta_texts, features (list-item snippets, capped at 30), prices (JP yen patterns), brand_name, industry_hints, og_title, og_description, and structured_data (up to 5 JSON-LD blocks). On fetch or parse failure, returns the same shape with an error field set instead of raising. Side effect: issues one outbound HTTP GET to the URL with a 15s timeout, a 500KB body cap, up to 5 redirects, and a 'MarketingAgent/1.0' User-Agent; SSRF-protected against localhost, private / link-local / reserved IP ranges, and cloud metadata endpoints (redirect targets are re-validated). The Google Ads customer context is unused by the analysis itself — passing customer_id only scopes credential routing. Use this for ad-copy vs. LP message-match and keyword-extraction workflows. For Google's indexing/coverage view of the same URL use search_console_url_inspection_inspect; for a batched workflow that combines LP analysis with existing ads, search terms, and keyword suggestions use google_ads_creative_research.

Collect every input an LLM needs to draft or refresh Google Ads creative for a single campaign. Returns {campaign_id, url, lp_analysis (same shape as google_ads_landing_page_analyze), existing_ads:[{ad_id, headlines, descriptions, final_urls, impressions, clicks, conversions, ctr}] (top 5 RSA ads by impressions, REMOVED excluded), search_term_insights:{high_cv_terms (top 10 by conversions), high_click_terms (top 10 by clicks), total_terms}, keyword_suggestions (KeywordPlanIdeaService output for up to 5 seeds derived from LP title + h1 + meta_description), existing_keywords (list_keywords output), context_summary (string)}. Any failing sub-step is replaced with the literal string '取得失敗' so the envelope never raises. Side effect: one outbound LP fetch (same SSRF policy as google_ads_landing_page_analyze) plus several GAQL queries. For just the LP use google_ads_landing_page_analyze; for just RSA asset diagnostics use google_ads_rsa_assets_analyze.

Check whether a Google Ads campaign is actively delivering yesterday by composing campaign info, delivery diagnostics, and yesterday's performance. Returns {campaign_id, campaign, diagnosis:{issues, warnings, recommendations, ...}, performance (list of yesterday rows with metrics), status ('critical'|'warning'|'healthy'), issues:[strings], summary, suggested_workflow?}. 'critical' fires when delivery diagnostics have issues, the campaign is not ENABLED, or yesterday impressions == 0. 'warning' fires for diagnostic warnings or impressions 1-9. suggested_workflow is set to 'delivery_fix' when status != 'healthy'. Read-only. For the raw diagnostics without the yesterday composite use google_ads_campaigns_diagnose; for CPA-target evaluation use google_ads_monitoring_cpa_goal.

Evaluate a Google Ads campaign's last-7-days CPA against a user-supplied target and integrate cost-increase analysis. Returns {campaign_id, target_cpa, current_cpa (float or None when conversions==0), cost_analysis (full google_ads_cost_increase_investigate payload), wasteful_terms (top 5 zero-CV cost terms from cost_analysis), deviation_pct, status ('healthy' when current<=target, 'warning' when <=target1.2 or when CV==0, 'critical' when >target1.2), issues:[strings], summary, suggested_workflow?}. The CPA window is hardcoded to LAST_7_DAYS. Read-only; does not change bids. For account-wide rollup use google_ads_health_check_all; for daily CV-count vs target use google_ads_monitoring_cv_goal.

Evaluate a Google Ads campaign's daily conversion rate against a target and identify the dominant bottleneck. Returns {campaign_id, target_cv_daily, current_cv_daily (7-day conversions / 7), performance_analysis (full google_ads_performance_analyze payload), deviation_pct, status ('healthy' when >= target, 'warning' when >= target0.8, 'critical' otherwise), bottleneck ('impression'|'ctr'|'cvr'), issues:[strings], summary, suggested_workflow?}. Bottleneck routing: 'impression' when analyze insights mention impression drops or impressions<clicks10; 'ctr' when CTR<2%; 'cvr' otherwise. The evaluation window is hardcoded to LAST_7_DAYS. Read-only. For CPA-target evaluation use google_ads_monitoring_cpa_goal; for the underlying composite use google_ads_performance_analyze.

Diagnose a Google Ads campaign that is not acquiring conversions by composing tracking config, bidding alignment, last-7-days funnel, delivery diagnostics, and search-term quality. Returns {campaign_id, conversion_tracking:{total_actions, enabled_actions, has_issue, actions}, bidding_cv_alignment:{strategy, is_smart_bidding, cv_tracking_configured, issue}, funnel:{period:'LAST_7_DAYS', impressions, clicks, conversions, cost, ctr, cvr, bottleneck ('no_delivery'|'no_clicks'|'no_conversions'|None)}, delivery_diagnosis:{issues, warnings, recommendations}, search_term_quality:{total_terms, zero_cv_terms, zero_cv_cost, top_wasteful_terms} (null when clicks==0), status ('critical'|'warning'|'healthy'), issues:[strings], summary, suggested_workflow?, recommended_actions:[{priority, action, description}]}. The evaluation window is hardcoded to LAST_7_DAYS. Read-only; generates an action plan but does not execute anything. For CPA monitoring use google_ads_monitoring_cpa_goal; for CV-count monitoring use google_ads_monitoring_cv_goal.

Capture a URL screenshot in PNG format (for message match evaluation)

Upload a local image file to Google Ads as an image Asset for use in Responsive Display Ads or image extensions. Returns {resource_name ('customers//assets/'), id (asset id as string), name (asset display name or basename)}. Mutating — creates a new Asset row in the customer account; removal must be done through the Google Ads UI (there is no corresponding delete tool). The file is validated before upload: max 5 MB, extensions must be jpg/jpeg/png/gif. Side effect: reads file_path from the local filesystem of the MCP server host and POSTs the raw bytes to Google. For creating the ad that references this asset afterwards use google_ads_ads_create_display.

Lists campaigns in a Meta Ads account with optional status filtering. Returns id, name, status (ACTIVE / PAUSED / DELETED / ARCHIVED), effective_status, objective (OUTCOME_SALES / OUTCOME_LEADS / etc.), buying_type, daily_budget, and lifetime_budget per campaign. Read-only. Use this to find a campaign_id before calling campaigns.get or the pause/enable helpers. For a single campaign's full detail record use meta_ads_campaigns_get.

Fetches the full detail record for a single campaign by ID. Returns the same fields as campaigns.list plus special_ad_categories, spend_cap, start_time, stop_time, and issues_info (non-empty when status is WITH_ISSUES). Read-only. Use this when a campaign_id is already known; for discovery use meta_ads_campaigns_list.

Creates a new campaign in the specified Meta Ads account. Returns the new campaign id. Mutating, reversible via rollback_apply (rollback sets status to PAUSED rather than deleting). Default initial status is PAUSED — explicitly pass status='ACTIVE' only if the operator has confirmed immediate spend. A campaign acts as a container; ad sets (where budgets and targeting live) and ads must be created separately via meta_ads_ad_sets_create and meta_ads_ads_create.

Updates fields on an existing campaign. Partial update — only the supplied fields are changed. Returns the updated campaign. Mutating, reversible via rollback_apply. For status-only transitions prefer meta_ads_campaigns_pause / meta_ads_campaigns_enable, which are safer and map to a single explicit operator intent.

Pauses a single campaign by setting its status to PAUSED. Cascades to active ad sets and ads — nothing underneath the campaign will serve while it is PAUSED. Lightweight and reversible via rollback_apply or meta_ads_campaigns_enable. Returns the campaign id and new status. Use for immediate stop-spend situations; use meta_ads_campaigns_update with status='DELETED' to soft-delete instead.

Resumes a paused campaign by setting its status to ACTIVE. Ad sets and ads underneath retain their own status — if they are still PAUSED they do NOT auto-resume; call meta_ads_ad_sets_enable / meta_ads_ads_enable for those too. Returns the campaign id and new status. Reversible via rollback_apply or meta_ads_campaigns_pause.

Lists ad sets in a Meta Ads account, optionally scoped to a single parent campaign. Returns id, name, campaign_id, status, effective_status, daily_budget, lifetime_budget, optimization_goal, billing_event, and targeting_summary per ad set. Read-only. Ad sets are where budgets and targeting live — use this to audit delivery settings or to find an ad_set_id before creating ads.

Creates a new ad set inside an existing campaign. Returns the new ad_set id. Mutating, reversible via rollback_apply (rollback sets status to PAUSED). Targeting is passed as a Meta targeting spec object; at minimum supply geo_locations and age bounds. Default initial status is PAUSED — only ACTIVE when the operator has confirmed spend. After creation, attach ads with meta_ads_ads_create.

Updates one or more settings on an existing ad set. Partial update — only provided fields are changed. Returns the updated ad set. Mutating, reversible via rollback_apply. For status-only transitions prefer meta_ads_ad_sets_pause / meta_ads_ad_sets_enable. Changing targeting replaces the entire targeting spec — fetch the current spec via meta_ads_ad_sets_get and merge client-side to avoid data loss.

Fetches the full detail record for a single ad set, including the complete targeting spec and budget/bidding configuration. Returns id, name, campaign_id, status, effective_status, daily_budget, lifetime_budget, optimization_goal, billing_event, targeting (full spec), start_time, end_time, and delivery_estimate (if available). Read-only. Call this before meta_ads_ad_sets_update when you plan to modify targeting, so you can merge instead of overwrite.

Pauses a single ad set by setting its status to PAUSED. Ads under this ad set stop serving while it is PAUSED, even if their own status is ACTIVE. Lightweight, reversible via rollback_apply or meta_ads_ad_sets_enable. Returns the ad_set_id and new status. Does not affect sibling ad sets.

Resumes a paused ad set by setting its status to ACTIVE. The parent campaign must also be ACTIVE for the ad set to actually serve. Ads underneath retain their own status — PAUSED ads do not auto-resume. Returns the ad_set_id and new status. Reversible via rollback_apply or meta_ads_ad_sets_pause.

Lists ads in a Meta Ads account, optionally scoped to one ad set. Returns id, name, ad_set_id, campaign_id, status, effective_status, creative_id, and ad_review_feedback per ad. Read-only. Use this to find an ad_id before calling ads.update / pause / enable, or to audit which creatives are in flight. For the creative itself (image URL, copy), follow up with meta_ads_creatives_list.

Creates a new ad inside an existing ad set, binding it to a pre-existing creative. Returns the new ad id. Mutating, reversible via rollback_apply. Default initial status is PAUSED. The creative must already exist — use meta_ads_creatives_create (or sibling constructors like meta_ads_creatives_create_carousel) to produce a creative_id before calling this tool.

Updates fields on an existing ad. Partial update. Returns the updated ad. Mutating, reversible via rollback_apply. The ad's creative cannot be swapped via this call — creative changes require creating a replacement ad with a new creative_id and pausing the old one. For status-only transitions use meta_ads_ads_pause / meta_ads_ads_enable.

Fetches the full detail record for a single ad, including creative_id and ad_review_feedback (populated when the ad is in WITH_ISSUES). Returns id, name, ad_set_id, campaign_id, status, effective_status, creative_id, configured_status, issues_info, and ad_review_feedback. Read-only. Call this when an ad shows up as WITH_ISSUES in ads.list — ad_review_feedback explains the policy rejection.

Pauses a single ad by setting its status to PAUSED. Lightweight; the ad stops serving immediately. Reversible via rollback_apply or meta_ads_ads_enable. Returns the ad_id and new status. Does not affect the parent ad set or sibling ads. Use for creative-level pause; use meta_ads_ad_sets_pause to stop a whole ad set.