Skip to main content
AdLoop reads your Google Ads account (campaigns, ads, keywords, search terms, negatives, recommendations, Performance Max and audiences), runs Keyword Planner research, and changes things through the same preview → dry run → confirm_and_apply gate as every other write. New campaigns and responsive search ads are created PAUSED. AdLoop builds and edits Search campaigns; other campaign types can be analysed but not built. Google Ads shares one Google connection with Google Analytics, Tag Manager, Search Console and Merchant Center.

Connect

The onboarding wizard (later: Settings → Google → Connect Google account) asks which Google products your AI may use and requests only those permissions. Keep Google Ads ticked; Google’s consent dialog then asks for access to your Ads data. Google offers no read-only permission for Ads, so for “analyse but never change” use a read-only API key.Then pick the account. Accounts you reach directly appear in the list; picking a manager account (MCC) opens a second list with the accounts under it, and AdLoop reaches the chosen account through the manager. I do not use Google Ads leaves the Ads tools switched off. Agencies connect Google once under Settings → Google and pick an Ads account per client under Settings → Clients (see Clients).Disconnect Google account revokes the grant at Google and deletes the stored token. Because all Google products share one grant, Analytics and the others disconnect with it.

Behaviour worth knowing

  • Money is in account currency. The read tools compute metrics.cost, metrics.cpa and average CPC for you. Only run_gaql returns Google’s raw cost_micros (divide by 1,000,000).
  • Compact mode for audits. get_campaign_performance, get_keyword_performance, get_search_terms and get_ad_performance accept compact=true: account totals, the top ten rows and ready-made offender lists (zero-conversion spenders, low quality scores, wasteful search terms, thin ads) instead of every row.
  • Keyword Planner needs your market. discover_keywords and estimate_budget default to Germany and English; pass the geo_target_id and language_id you actually target.
  • Performance Max: edit, don’t build. get_pmax_performance reports asset groups with their Ad Strength and a network breakdown; most PMax traffic lands in Google’s catch-all MIXED network, so an exact Search vs YouTube vs Display split is not available. Existing asset groups can be edited (assets, signals, product exclusions, status); new PMax campaigns are still built in Google Ads.
  • Recommendations are read, not applied. get_recommendations returns Google’s suggestions with estimated impact and flags budget raises that mainly benefit Google; acting on one means drafting the change yourself.
  • Ads clicks above GA4 sessions are normal in the EU. See Consent and data gaps.

Safety specifics

Everything on the safety model applies. On top of that, for Google Ads:
  • The dry run asks Google. confirm_and_apply with dry_run=true sends the exact mutates to Google in validate-only mode: Google checks them and executes nothing. DRY_RUN_FAILED carries Google’s error and means the real apply would fail the same way. Steps that depend on an object an earlier step would create (keywords for a list that does not exist yet, say) cannot be validated and are counted as skipped.
  • Budgets and bids are capped. max_daily_budget caps every budget AdLoop sets. max_bid_increase_pct (default 100) caps raises of an ad group’s manual CPC and of an existing Maximize Clicks ceiling; a first-time ceiling has no baseline and is not capped.
  • Broad match needs Smart Bidding. draft_campaign refuses BROAD keywords on a campaign without Smart Bidding (Maximize Conversions, Maximize Conversion Value, Target CPA or Target ROAS); draft_keywords and draft_ad_group flag them in the preview. Campaign-level broad match (keyword_match_type="BROAD" on update_campaign) follows the same rule, checked again at apply, and needs a double confirmation: Google converts every phrase and exact keyword in the campaign to broad match, and turning the setting off later does not restore them. Moving a broad match campaign off Smart Bidding is refused unless the same call turns broad match off.
  • Targeting is mandatory. New campaigns need geo and language targets.
  • Landing pages must load. Final URLs of ads and sitelinks are fetched at draft time; an error page blocks the draft. If the site is only rate-limiting or briefly down, the preview warns and lets you proceed.
  • What is created paused. Campaigns and responsive search ads are created PAUSED. New ad groups are created enabled but cannot serve until one of their ads is enabled.
  • Rewriting an ad is not free. Changing headlines or descriptions with update_responsive_search_ad keeps the ad’s ID, but Google treats the creative as new: its asset-combination learning and performance history reset and it goes back through policy review. The preview says so. URL and display-path edits do not have this effect.
  • Location lists replace, exclusions survive. update_campaign replaces the positive geo and language targets with the list you pass. Negative location exclusions are kept and listed in the preview; add them with add_negative_locations.
  • Shared budgets and portfolios are named. A budget can fund several campaigns, and a portfolio bid strategy can bid for several. When update_campaign changes a shared budget, the preview names the other campaigns and needs a double confirmation, because the new amount covers all of them. A bidding change on a campaign in a portfolio takes it out of the portfolio, with the same double confirmation. If the budget, its sharing or the portfolio changes before the apply, nothing is sent.
  • Removal is final. remove_entity cannot be undone; prefer pause_entity.

Tools

Reads: list_accounts, get_campaign_performance (with search impression share and the share lost to budget or rank), get_ad_performance (full RSA copy and policy status, with disapproved and limited ads flagged), get_change_history (who changed what in the last 30 days, in the interface, through the API or by auto-applied recommendations), get_keyword_performance (quality scores), get_search_terms, get_negative_keywords, get_negative_keyword_lists, get_negative_keyword_list_keywords, get_negative_keyword_list_campaigns, get_recommendations, get_pmax_performance, get_pmax_assets and get_detailed_asset_performance (PMax assets and top asset combinations), get_audience_performance, get_demographic_targeting, run_gaql (any Google Ads Query Language query). Planning: discover_keywords and estimate_budget (Keyword Planner, read-only). Writes (all previewed):
  • Structure: draft_campaign, draft_shopping_campaign (Standard Shopping for a linked Merchant Center feed), draft_ad_group, update_campaign (bidding, budget, locations, languages, location options, URL options, campaign-level broad match, networks, Maximize Clicks CPC ceiling), update_ad_group (name, manual CPC bid).
  • Ads: draft_responsive_search_ad, update_responsive_search_ad.
  • Keywords and exclusions: draft_keywords, add_negative_keywords, add_negative_locations, draft_demographic_targeting (age, gender, parental status, income; exclusions by default).
  • Shared negative keyword lists: propose_negative_keyword_list (create and attach), add_to_negative_keyword_list, attach_shared_set_to_campaigns, detach_shared_set_from_campaigns.
  • Campaign assets: draft_sitelinks, draft_callouts, draft_structured_snippets, draft_image_assets (from public image URLs everywhere, uploaded images, or local files when self-hosted; the image is fetched only from public addresses, and if it changes between preview and apply, the apply is refused). For an image without a public URL, see Uploading images.
  • Asset scope and edits: callouts and structured snippets go where the id points: an ad group (ad_group_id), a campaign (campaign_id), or the whole account with scope="account", which reaches every campaign without assets of its own. Sitelinks and business logos (draft_image_assets with field_types=["BUSINESS_LOGO"]) go to a campaign or, with scope="account", to the account. draft_business_name_asset sets the business name for a campaign or the account, and link_asset_to_customer links existing assets account-wide. update_callout, update_sitelink and update_structured_snippet change an asset in place, so it keeps its ID and history and changes everywhere it is linked. The apply checks the asset first and stops if someone edited it in Google Ads after the preview.
  • Calls, schedules, promotions and prices: draft_call_asset shows a phone number with the ads; the number needs its country_code and is checked against it. add_ad_schedule adds schedule windows to a campaign, in the account time zone. A campaign without a schedule serves at all hours, so its first windows switch off every other hour; that preview needs a double confirmation. draft_promotion and draft_price_asset take amounts in the account currency, which the preview names, and need a language_code; a promotion can also be limited to certain hours with ad_schedule. update_call_asset and update_promotion edit in place and keep every field you don’t pass.
  • Conversion actions: draft_create_conversion_action, draft_update_conversion_action, draft_remove_conversion_action.
  • Performance Max: draft_asset_group_assets (add and remove text, image and YouTube assets in one change), get_asset_group_signals and draft_asset_group_signals (search themes, audience signal), draft_pmax_product_exclusions (exclude products by item id, brand or custom label).
  • Status: pause_entity, enable_entity, remove_entity (campaigns, ad groups, ads, keywords, PMax asset groups).
The full list with parameters is in the tool reference; the toolset slug is ads. The tools that join Ads with Analytics (analyze_campaign_conversions, attribution_check, landing_page_analysis) are in the tracking toolset, see Tracking audit.

Building a campaign

  1. Research. discover_keywords from seed keywords or a URL, then estimate_budget for the chosen keywords to see expected clicks and cost.
  2. draft_campaign creates the budget, the campaign (PAUSED), its first ad group, keywords, and geo and language targeting in one plan. More ad groups follow with draft_ad_group.
  3. draft_responsive_search_ad per ad group: 3 to 15 headlines of up to 30 characters, 2 to 4 descriptions of up to 90, display paths of up to 15. Headlines and descriptions can be pinned to a position, at some cost to Ad Strength. Several can share a position and rotate there (pin your keyword headlines to position 1, for example), as long as every position can still be filled by a pinned or a separate unpinned asset.
  4. Assets: sitelinks, callouts and structured snippets on the campaign.
  5. Shared negatives: a new campaign does not inherit your shared negative keyword lists; attach them with attach_shared_set_to_campaigns.
  6. Enable the ad, then the campaign, with enable_entity.

Shopping and Performance Max

Standard Shopping. draft_shopping_campaign builds a campaign that advertises a Merchant Center feed: budget, campaign (paused), a product ad group with its Shopping ad and one “All products” group, in one request that the dry run has Google validate. The Merchant Center account has to be linked to the Ads account; the draft checks it. Shopping takes no keywords and no language targeting (the feed’s language applies). Bidding is manual CPC, Maximize clicks or target ROAS, and product_bid is always needed because Google sets it on the product group. Check get_merchant_feed_health before enabling: disapproved products do not serve. Editing Performance Max.
  • Assets: draft_asset_group_assets adds new headlines, long headlines, descriptions, images and YouTube videos and removes old ones in the same change. Replacing an asset that way never drops the group below Google’s minimums (three headlines, one long headline, two descriptions with one of at most 60 characters). Images can be public URLs or uploads; they are sorted into landscape, square or portrait by their aspect ratio.
  • Signals: draft_asset_group_signals adds search themes or sets the group’s audience signal. Signals steer Performance Max; they do not restrict where it serves.
  • Product exclusions: draft_pmax_product_exclusions takes the complete list of item ids, brands or custom label values to exclude from a retail asset group. Asset groups with nested product filters are left to the Google Ads interface.
  • Status: pause_entity and enable_entity take asset_group.
Product performance. get_shopping_product_performance sums spend, clicks, conversions, CPA and ROAS per product across Shopping and Performance Max campaigns, and lists the products that spent without converting. Check those for price, stock and landing page before taking them out with draft_pmax_product_exclusions or a lower product bid. Which products the feed itself blocks comes from get_merchant_product_issues.

Audiences

get_audience_lists shows the account’s remarketing and customer lists (size for Search and Display, open or closed), custom segments and combined segments; search_audience_segments finds Google’s in-market and affinity segments by name. get_audience_targeting shows what a campaign or ad group has attached and its audience mode. draft_audience_attachment attaches audiences in one of three ways:
  • Observation (the default): the audience adjusts bids and shows up in reports, and the campaign keeps its reach.
  • Targeting: the ads only reach people in the audience. Impressions usually drop sharply, so it needs a double confirmation.
  • Exclusion (exclude=True): keeps people out, e.g. recent buyers on a prospecting campaign.
The draft refuses what Google doesn’t allow: custom segments on Search, combined segments outside Search, audiences at both campaign and ad group level, and targeting with a list too small to serve on Search (under 1,000 users). Performance Max takes audiences as asset group signals instead. Remove an audience with remove_entity and the remove_id from get_audience_targeting. Creating audiences stays in the Google Ads interface.

Not covered yet

Creating audiences, ad schedules and bid adjustments, building new Performance Max campaigns, splitting Shopping product groups by brand or label, Demand Gen and video campaigns, experiments, offline conversion uploads on AdLoop Cloud (the self-hosted edition has them), and applying Google’s recommendations. Use the Google Ads interface for these; AdLoop can still report on the campaigns.

Operations and limits

On AdLoop Cloud, every Google Ads tool call counts toward your workspace’s daily operations: reads, Keyword Planner lookups, drafts, dry runs and applies, and the tracking tools that read Ads. health_check and list_accounts are not counted. See plans and limits. Self-hosted, the only limits are the ones Google sets for your Cloud project’s access level.

What AdLoop stores

On AdLoop Cloud: an encrypted refresh token, your Google email address, the permissions you granted, and the selected Ads account (ID, name, currency, and the manager account it is reached through). Campaign and performance data pass through and are never stored; the change log records what was changed. Files you upload are the exception: they are kept encrypted for as short as the upload needs (images 24 hours, conversion CSVs until a draft has read them, two hours at most). Self-hosted, the token stays in ~/.adloop/token.json and the audit log in ~/.adloop/audit.log on your machine. See the privacy policy for the full description.

Uploading images

An image on your computer, or one you attached in the chat, has no public URL, and an AI app cannot pass the file itself to a tool. Ask for an upload instead (the AI calls upload_images):
  • Apps that show AdLoop cards (Claude, ChatGPT, VS Code and others with MCP Apps): an upload card appears in the chat. Drop PNG, JPEG or GIF files on it, up to 5 MB each. The card posts the upload ids into the chat when it is done.
  • Other apps on AdLoop Cloud: the AI gives you an upload link, valid for 30 minutes. Open it in the browser and drop the images, then tell the AI you are done. A coding agent that has the files on disk can upload them itself with curl -T.
  • Self-hosted: the card works in apps that show it; otherwise pass local files directly with image_paths.
The AI then creates the assets from the upload ids (draft_image_assets with upload_ids), with the usual preview and approval. On AdLoop Cloud, uploads also work for Reddit image and carousel ads. Uploads are deleted 24 hours after the upload.

Offline conversion uploads

Calls and leads that turned into customers offline can go back to Google Ads from a CSV in Google’s upload template: draft_upload_call_conversions matches calls by the caller’s phone number, draft_upload_enhanced_conversions_for_leads matches leads by hashed email, phone or name and address. The conversion action named in the file must exist (type UPLOAD_CALLS or UPLOAD_CLICKS); the draft checks it, previews the rows with redacted samples, consent and skipped rows, and uploads only after approval.
  • Self-hosted: pass the file as csv_path, or upload it through the card (upload_conversion_csv) and pass its upload_id.
  • AdLoop Cloud: not available yet; it arrives with the next version of the data processing agreement, because the files hold your customers’ personal data. It will work through the upload card or an upload link.
The file is deleted as soon as a draft has read it, after two hours at the latest. Lead names, emails and phone numbers are hashed (SHA-256) while drafting; callers’ numbers go to Google as they are, because Google matches calls by number. The change log never contains numbers, emails or names.