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
- AdLoop Cloud
- Self-hosted
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.cpaand average CPC for you. Onlyrun_gaqlreturns Google’s rawcost_micros(divide by 1,000,000). - Compact mode for audits.
get_campaign_performance,get_keyword_performance,get_search_termsandget_ad_performanceacceptcompact=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_keywordsandestimate_budgetdefault to Germany and English; pass thegeo_target_idandlanguage_idyou actually target. - Performance Max: edit, don’t build.
get_pmax_performancereports asset groups with their Ad Strength and a network breakdown; most PMax traffic lands in Google’s catch-allMIXEDnetwork, 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_recommendationsreturns 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_applywithdry_run=truesends the exact mutates to Google in validate-only mode: Google checks them and executes nothing.DRY_RUN_FAILEDcarries 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_budgetcaps 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_campaignrefuses BROAD keywords on a campaign without Smart Bidding (Maximize Conversions, Maximize Conversion Value, Target CPA or Target ROAS);draft_keywordsanddraft_ad_groupflag them in the preview. Campaign-level broad match (keyword_match_type="BROAD"onupdate_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_adkeeps 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_campaignreplaces the positive geo and language targets with the list you pass. Negative location exclusions are kept and listed in the preview; add them withadd_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_campaignchanges 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_entitycannot be undone; preferpause_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 withscope="account", which reaches every campaign without assets of its own. Sitelinks and business logos (draft_image_assetswithfield_types=["BUSINESS_LOGO"]) go to a campaign or, withscope="account", to the account.draft_business_name_assetsets the business name for a campaign or the account, andlink_asset_to_customerlinks existing assets account-wide.update_callout,update_sitelinkandupdate_structured_snippetchange 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_assetshows a phone number with the ads; the number needs itscountry_codeand is checked against it.add_ad_scheduleadds 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_promotionanddraft_price_assettake amounts in the account currency, which the preview names, and need alanguage_code; a promotion can also be limited to certain hours withad_schedule.update_call_assetandupdate_promotionedit 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_signalsanddraft_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).
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
- Research.
discover_keywordsfrom seed keywords or a URL, thenestimate_budgetfor the chosen keywords to see expected clicks and cost. draft_campaigncreates the budget, the campaign (PAUSED), its first ad group, keywords, and geo and language targeting in one plan. More ad groups follow withdraft_ad_group.draft_responsive_search_adper 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.- Assets: sitelinks, callouts and structured snippets on the campaign.
- Shared negatives: a new campaign does not inherit your shared negative keyword lists; attach them with
attach_shared_set_to_campaigns. - 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_assetsadds 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_signalsadds 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_exclusionstakes 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_entityandenable_entitytakeasset_group.
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.
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 thetracking 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 callsupload_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.
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 itsupload_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.