Permet à un client IA de lire et de modifier les campagnes Google Ads, Reddit Ads et GA4, avec un aperçu affiché avant chaque modification.
Aussi connu sous kLOsk/adloop
- Étoiles
- 302
- Outils
- 145
- Téléchargements, 30 jours
- 7 695
- Dernière version
- 0.44.1
- Dernier commit
- 12 nov. 2026
- Licence
- MIT
Qu'est-ce que AdLoop MCP ?
Permet à un client IA de lire et de modifier les campagnes Google Ads, Reddit Ads et GA4, avec un aperçu affiché avant chaque modification. Il expose 145 outils, comme health_check, get_account_summaries, run_ga4_report.
Résumé généré à partir du README du projet
À propos du MCP server AdLoop
AdLoop permet aux développeurs marketing et aux ingénieurs growth de gérer la publicité numérique et l'analyse via une interface de chat unique. En se connectant à Google Ads, Reddit Ads et GA4, cet outil permet à un assistant IA d'effectuer des audits multiplateformes complexes, comme la comparaison des clics publicitaires avec les données de session GA4 pour identifier les lacunes de suivi. Il fonctionne à la fois comme un package Python auto-hébergé installé via pip et comme un service cloud hébergé qui s'intègre à des plateformes telles que Claude.ai, ChatGPT, Cursor et Gemini.
Les utilisateurs peuvent effectuer des diagnostics approfondis en utilisant des outils comme health_check pour vérifier la connectivité ou run_ga4_report pour extraire des métriques de performance personnalisées. Le serveur offre un accès en écriture pour modifier des campagnes, ajouter des mots-clés négatifs ou rédiger des annonces textuelles responsives, mais inclut un mécanisme de sécurité où chaque modification nécessite un aperçu et une approbation manuelle. Cela empêche les dépenses budgétaires accidentelles en garantissant que l'IA ne peut pas appliquer de changements sans une confirmation explicite de l'utilisateur via une carte d'approbation dans l'interface du client.
Ce que vous pouvez faire avec
- 1Auditer les lacunes de suivi des conversionsCroisez les clics publicitaires avec les sessions GA4 pour déterminer si les baisses de conversion sont causées par un suivi défectueux ou par des problèmes sur les pages de destination.
- 2Optimiser les dépenses publicitaires en langage naturelIdentifiez les termes de recherche non pertinents et ajoutez-les en tant que mots-clés négatifs directement depuis votre environnement de développement.
- 3Gérer les modifications de campagne en toute sécuritéCréez de nouvelles campagnes publicitaires ou modifiez des paramètres tout en vous assurant que chaque action est examinée avant sa mise en ligne.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer AdLoop MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller AdLoop MCP dans Claude Code
$ claude mcp add adloop -- uvx adloopInstaller AdLoop MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"adloop": {
"command": "uvx",
"args": [
"adloop"
]
}
}
}Installer AdLoop MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"adloop": {
"type": "stdio",
"command": "uvx",
"args": [
"adloop"
]
}
}
}Installer AdLoop MCP dans VS Code CLI
$ code --add-mcp '{"name":"adloop","type":"stdio","command":"uvx","args":["adloop"]}'Installer AdLoop MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"adloop": {
"command": "uvx",
"args": [
"adloop"
]
}
}
}Installer AdLoop MCP dans Codex
$ codex mcp add adloop -- uvx adloopInstaller AdLoop MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.adloop] command = "uvx" args = ["adloop"]
Installer AdLoop MCP dans Gemini CLI
$ gemini mcp add -s user adloop uvx -- adloopInstaller AdLoop MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"adloop": {
"command": "uvx",
"args": [
"adloop"
]
}
}
}Démarré par HostedMCP le 16 nov. 2026
Nous avons lancé cette commande pour adloop 0.44.1 dans un conteneur isolé, sans réseau ni clé. Il a répondu et listé 145 outils.
Outils MCP AdLoop 145
Lu sur le serveur avec tools/listhealth_checkLecture seuleTest AdLoop connectivity — checks OAuth token, GA4 API, Google Ads API, and (when configured) the Reddit Ads and Microsoft Advertising APIs. Returns the status of each service and actionable guidance when something is broken, which makes it the diagnostic for failures in other tools. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/
get_account_summariesLecture seuleList all GA4 accounts and properties accessible by the authenticated user. Serves as the discovery step for which GA4 properties are available. Returns account names, property names, and property IDs. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
run_ga4_reportLecture seuleRun a custom GA4 report with optional filters, ordering, paging and a comparison period. Returns the property, the date range, the dimension and metric headers, one row per dimension combination (values as strings), row_count and total_row_count (plus next_offset while more rows remain). At least one dimension or metric is required. With compare_start/compare_end the comparison period is a second date range: every row then carries a dateRange value of "current" or "comparison", and date_ranges maps both labels to their dates. Invalid filters or ordering return "Validation failed" with details, before anything is sent. insights[] says when GA4 thresholded or sampled the data, grouped rows into "(other)", or the property is close to its API quota, because each makes numbers differ from the GA4 interface. Reports over time (a date-type dimension) or comparing periods also return the property's annotations in those dates, which often explain a jump in the rows. Queries the GA4 Data API. Dimensions and metrics: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema
run_realtime_reportLecture seuleRun a GA4 realtime report showing current active users and events. Useful for checking if tracking is firing correctly after code changes: filter on the event that just shipped, or compare the last few minutes with the minutes before. Returns the dimension and metric headers and one row per dimension combination over the realtime window (the last 30 minutes unless minute_ranges says otherwise). When a filter matches nothing, insights[] lists the usual causes. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
get_ga4_propertyLecture seuleShow a GA4 property's configuration in one call: details, linked Google Ads accounts, data streams and data retention. Returns the property's display name, time zone, currency, industry, service level (standard or 360), type and create time; every linked Google Ads account (customer ID, whether it is a manager account, personalized advertising); every data stream with its measurement ID or app ID; how many months event and user data are kept; and the number of key events. insights[] flags settings that cost data: two-month retention, no Google Ads link while key events exist, the configured Ads account not being linked, a property in the trash. A part the user may not read is listed under unavailable instead of failing the call. Reads the GA4 Admin API (properties.get, googleAdsLinks.list, dataStreams.list, getDataRetentionSettings, keyEvents.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
get_tracking_eventsLecture seuleList all GA4 events and their volume for the given date range. Returns every distinct event name with its total event count, sorted by count (highest first). Shows what tracking is configured and active. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
list_key_eventsLecture seuleList the key events (conversions) configured on a GA4 property. Returns each key event's event name, counting method (ONCE_PER_EVENT or ONCE_PER_SESSION), create time, whether GA4 allows deleting it, whether it is a custom event, and its resource name, sorted by event name, plus the total. Reads the GA4 Admin API (keyEvents.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
list_ga4_dimensions_and_metricsLecture seuleList the dimensions and metrics a GA4 property can report on, including custom ones. Returns the exact API names valid in run_ga4_report for this property: each with its UI name, category, whether it is a custom definition (customEvent:..., customUser:...), and deprecated API names; metrics also carry their type and, for calculated metrics, the expression. Reads the GA4 Data API metadata (properties.getMetadata), which uses no report quota. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
run_ga4_funnelLecture seuleRun a GA4 funnel report: how many users go from one step to the next, and where they drop off. Steps are event names or pages, in order. Returns per step the users, completion rate to the next step, abandonments and abandonment rate, plus how many started and finished, the overall completion rate and the biggest drop (after which step most users leave). With breakdown, the same per value of a dimension (e.g. deviceCategory); with next_action, the most common next event or page after each step, i.e. what users do instead. Uses the GA4 Data API v1alpha (runFunnelReport), the endpoint behind GA4's funnel explorations; data reaches back as far as the property's data retention. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
run_ga4_attributionLecture seuleShow which channels, campaigns or sources get the credit for conversions under GA4's attribution models, or compare data-driven with last click. The view of GA4's Advertising workspace: conversions, revenue, ad cost and ROAS per channel (or campaign, source, country, device) attributed by the model, not by session. attribution_model COMPARE runs data-driven and last click side by side and returns each row's share of the credit under both and the shift in percentage points, with insights naming the channels that gain or lose most. Conversions can be named by key event name; empty means all. Uses the GA4 Data API v1alpha (runReport with a conversion spec), which Google is still rolling out: a property without it gets an explanation and the fallback. Ad cost and ROAS need Google Ads linked to the property. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
audit_ga4_propertyLecture seuleAudit a GA4 property's setup in one call: the settings that quietly cost data or conversions. Checks data retention (two months is GA4's default and cuts explorations short), the Google Ads link (and whether the configured Ads account is linked), each data stream's activity in the last 7 days, key events that never fired in 28 days or no key events at all, enhanced measurement per web stream, Google signals (and the thresholding they cause), the custom dimension and metric limits, and a property in the trash. Returns checks with status warn, info or ok (warnings first), a summary count, and the warnings as insights[]; a check the user may not read is listed under unavailable. Reads GA4 only (Admin API, part v1alpha, and two small Data API reports); for whether Google Ads imports the key events, run check_key_event_imports. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
list_ga4_annotationsLecture seuleList a GA4 property's annotations, the notes GA4 shows on a date or date range in its charts. Returns each annotation's ID (resource name), title, description, color, and its date or start and end date, newest first; Google's own annotations are marked system_generated. With a date range, only the annotations that overlap it. The first stop for "what happened on that day?" next to get_change_history in Google Ads. Reads the GA4 Admin API v1alpha (reportingDataAnnotations.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
| health_check | Test AdLoop connectivity — checks OAuth token, GA4 API, Google Ads API, and (when configured) the Reddit Ads and Microsoft Advertising APIs. Returns the status of each service and actionable guidance when something is broken, which makes it the diagnostic for failures in other tools. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/ | Lecture seule |
| get_account_summaries | List all GA4 accounts and properties accessible by the authenticated user. Serves as the discovery step for which GA4 properties are available. Returns account names, property names, and property IDs. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| run_ga4_report | Run a custom GA4 report with optional filters, ordering, paging and a comparison period. Returns the property, the date range, the dimension and metric headers, one row per dimension combination (values as strings), row_count and total_row_count (plus next_offset while more rows remain). At least one dimension or metric is required. With compare_start/compare_end the comparison period is a second date range: every row then carries a dateRange value of "current" or "comparison", and date_ranges maps both labels to their dates. Invalid filters or ordering return "Validation failed" with details, before anything is sent. insights[] says when GA4 thresholded or sampled the data, grouped rows into "(other)", or the property is close to its API quota, because each makes numbers differ from the GA4 interface. Reports over time (a date-type dimension) or comparing periods also return the property's annotations in those dates, which often explain a jump in the rows. Queries the GA4 Data API. Dimensions and metrics: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema | Lecture seule |
| run_realtime_report | Run a GA4 realtime report showing current active users and events. Useful for checking if tracking is firing correctly after code changes: filter on the event that just shipped, or compare the last few minutes with the minutes before. Returns the dimension and metric headers and one row per dimension combination over the realtime window (the last 30 minutes unless minute_ranges says otherwise). When a filter matches nothing, insights[] lists the usual causes. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| get_ga4_property | Show a GA4 property's configuration in one call: details, linked Google Ads accounts, data streams and data retention. Returns the property's display name, time zone, currency, industry, service level (standard or 360), type and create time; every linked Google Ads account (customer ID, whether it is a manager account, personalized advertising); every data stream with its measurement ID or app ID; how many months event and user data are kept; and the number of key events. insights[] flags settings that cost data: two-month retention, no Google Ads link while key events exist, the configured Ads account not being linked, a property in the trash. A part the user may not read is listed under unavailable instead of failing the call. Reads the GA4 Admin API (properties.get, googleAdsLinks.list, dataStreams.list, getDataRetentionSettings, keyEvents.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| get_tracking_events | List all GA4 events and their volume for the given date range. Returns every distinct event name with its total event count, sorted by count (highest first). Shows what tracking is configured and active. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| list_key_events | List the key events (conversions) configured on a GA4 property. Returns each key event's event name, counting method (ONCE_PER_EVENT or ONCE_PER_SESSION), create time, whether GA4 allows deleting it, whether it is a custom event, and its resource name, sorted by event name, plus the total. Reads the GA4 Admin API (keyEvents.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| list_ga4_dimensions_and_metrics | List the dimensions and metrics a GA4 property can report on, including custom ones. Returns the exact API names valid in run_ga4_report for this property: each with its UI name, category, whether it is a custom definition (customEvent:..., customUser:...), and deprecated API names; metrics also carry their type and, for calculated metrics, the expression. Reads the GA4 Data API metadata (properties.getMetadata), which uses no report quota. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| run_ga4_funnel | Run a GA4 funnel report: how many users go from one step to the next, and where they drop off. Steps are event names or pages, in order. Returns per step the users, completion rate to the next step, abandonments and abandonment rate, plus how many started and finished, the overall completion rate and the biggest drop (after which step most users leave). With breakdown, the same per value of a dimension (e.g. deviceCategory); with next_action, the most common next event or page after each step, i.e. what users do instead. Uses the GA4 Data API v1alpha (runFunnelReport), the endpoint behind GA4's funnel explorations; data reaches back as far as the property's data retention. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| run_ga4_attribution | Show which channels, campaigns or sources get the credit for conversions under GA4's attribution models, or compare data-driven with last click. The view of GA4's Advertising workspace: conversions, revenue, ad cost and ROAS per channel (or campaign, source, country, device) attributed by the model, not by session. attribution_model COMPARE runs data-driven and last click side by side and returns each row's share of the credit under both and the shift in percentage points, with insights naming the channels that gain or lose most. Conversions can be named by key event name; empty means all. Uses the GA4 Data API v1alpha (runReport with a conversion spec), which Google is still rolling out: a property without it gets an explanation and the fallback. Ad cost and ROAS need Google Ads linked to the property. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| audit_ga4_property | Audit a GA4 property's setup in one call: the settings that quietly cost data or conversions. Checks data retention (two months is GA4's default and cuts explorations short), the Google Ads link (and whether the configured Ads account is linked), each data stream's activity in the last 7 days, key events that never fired in 28 days or no key events at all, enhanced measurement per web stream, Google signals (and the thresholding they cause), the custom dimension and metric limits, and a property in the trash. Returns checks with status warn, info or ok (warnings first), a summary count, and the warnings as insights[]; a check the user may not read is listed under unavailable. Reads GA4 only (Admin API, part v1alpha, and two small Data API reports); for whether Google Ads imports the key events, run check_key_event_imports. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| list_ga4_annotations | List a GA4 property's annotations, the notes GA4 shows on a date or date range in its charts. Returns each annotation's ID (resource name), title, description, color, and its date or start and end date, newest first; Google's own annotations are marked system_generated. With a date range, only the annotations that overlap it. The first stop for "what happened on that day?" next to get_change_history in Google Ads. Reads the GA4 Admin API v1alpha (reportingDataAnnotations.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
Afficher les 145 outilsAfficher moins d'outils
list_ga4_audiencesLecture seuleList a GA4 property's audiences and check whether they reach Google Ads. GA4 shares its audiences with every linked Google Ads account that allows personalized advertising; there they are remarketing lists (get_audience_lists) that draft_audience_attachment puts on a campaign. Returns each audience's resource name, display name, description, membership duration and the events that include or exclude users (audiences built with other conditions in GA4's editor carry custom_conditions and the raw conditions; "All Users" and "Purchasers", which GA4 creates itself, carry predefined), the audience slots used against the limit (100, or 400 on a 360 property), and google_ads_readiness: checks for the Google Ads link, personalized advertising on it, Google signals, consent and list size, each with a status (ok, warn or info). insights repeats the warnings. Reads the GA4 Admin API (audiences.list, googleAdsLinks.list, googleSignalsSettings). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
list_ga4_custom_definitionsLecture seuleList a GA4 property's custom dimensions and custom metrics, with how many slots are left. Returns each custom dimension's resource name, parameter name, display name, scope (EVENT, USER or ITEM) and description, and each custom metric's resource name, parameter name, display name, measurement unit and description, plus usage per kind against the property's limit (standard: 50 event, 25 user, 10 item dimensions, 50 metrics; 360: 125, 100, 25, 125). Use it before draft_ga4_custom_dimension or draft_ga4_custom_metric. For the field names to use in reports, see list_ga4_dimensions_and_metrics. Reads the GA4 Admin API (customDimensions.list, customMetrics.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
list_gsc_sitesLecture seuleList all Google Search Console properties the authenticated user can access. Serves as the discovery step for the site URLs that search analytics reports (run_gsc_report) take. Returns the site URL and permission level for each property. Search Console API: https://developers.google.com/webmaster-tools
run_gsc_reportLecture seuleRun a Google Search Console search analytics report. Returns clicks, impressions, CTR, and average position broken down by the requested dimensions. Useful for diagnosing organic traffic drops, finding keyword opportunities, and cross-referencing with GA4 and Ads data. One request returns at most 25,000 rows; a full page carries next_start_row for the following request. With data_state "all" the response metadata names the first date whose data is still incomplete. Queries the Search Console API: https://developers.google.com/webmaster-tools/v1/searchanalytics/query
analyze_page_speedLecture seuleRun PageSpeed Insights for a landing page — Lighthouse + real-user data. Returns the performance score (0-100), lab Core Web Vitals (LCP, CLS, TBT, FCP), CrUX field data from real Chrome users where available (p75 LCP/INP/CLS/FCP/TTFB + FAST/AVERAGE/SLOW ratings), and the top improvement opportunities with estimated savings. When the page itself has too little traffic for field data, the origin-wide field data is returned instead, marked field.scope="origin". Typical input is an ad final_url: slow landing pages depress Quality Score and waste paid clicks. Takes 10-30s; that is normal for a Lighthouse run. PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/about
list_merchant_accountsLecture seuleList Google Merchant Center accounts the connected user can access. Returns each account's numeric ID, name and whether it is a test account. Provides the account_id used by get_merchant_feed_health; not needed when merchant.account_id is set in the config. Merchant API: https://developers.google.com/merchant/api/overview
get_merchant_feed_healthLecture seuleMerchant Center feed health — disapproved products + account issues. Disapproved feed items silently starve Shopping and Performance Max campaigns; this reports approved/pending/disapproved counts per reporting context (Shopping ads, free listings, ...), the top product issues by affected products (with documentation links), and account-level issues — CRITICAL ones stop offers serving entirely. Product-status data lags reality by ~30 minutes. Merchant API: https://developers.google.com/merchant/api/overview
get_merchant_product_issuesLecture seuleThe products behind the feed-health counts, each with its issues. Lists products by status with offer id, title, brand, click potential and every item issue: its code, the attribute it concerns, severity per reporting context with the affected countries, and whether the merchant has to act or Google is still processing. Products with high click potential come first, because fixing them recovers the most traffic. issues_by_code counts the products per issue. Data lags feed changes by about 30 minutes. Merchant API: https://developers.google.com/merchant/api/overview
list_accountsLecture seuleList accessible Google Ads accounts. Returns account names, IDs, status, and whether each is a manager account. When more accounts exist than `limit`, the response has 'truncated: true'; a much higher limit (e.g. list_accounts(limit=1000)) returns the full list. Workflows that target a specific account need no enumeration at all: get_campaign_performance, run_gaql, etc. take customer_id directly. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_campaign_performanceLecture seuleGet campaign-level performance metrics for a date range. Returns campaign name, status, type, impressions, clicks, cost, conversions, CPA, ROAS, CTR for each campaign, plus Search impression share and the share lost to budget and to ad rank (fractions with matching *_pct percentages; null for campaigns that do not serve on Search or had no impressions). Insights flag converting campaigns that lose a significant share of impressions to budget. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_ad_performanceLecture seuleGet ad-level performance data including headlines, descriptions, and metrics. Returns ad type, headlines, descriptions, final URL, impressions, clicks, CTR, conversions, cost for each ad, plus its policy approval status, review status and policy topic names. Disapproved and limited-by-policy ads are listed under policy_issues with their spend. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_keyword_performanceLecture seuleGet keyword metrics including quality scores and competitive data. Returns keyword text, match type, quality score, impressions, clicks, CTR, CPC, conversions for each keyword. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_search_termsLecture seuleGet search terms report — what users actually typed before clicking your ads. Critical for finding negative keyword opportunities and understanding user intent. Returns search term, campaign, ad group, impressions, clicks, conversions. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_negative_keywordsLecture seuleList existing negative keywords for a campaign or all campaigns. Shows the existing negatives, which reveals duplicates before new negative keywords are added. Returns each negative's campaign, keyword text, match type, and a resource_id ("campaignId~criterionId") as taken by remove_entity, plus the total count. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_negative_keyword_listsLecture seuleList all shared negative keyword lists (SharedSets) in the account. Returns each list's ID, name, status, and keyword count. Useful before propose_negative_keyword_list: a suitable list may already exist and just need attaching to a campaign. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_negative_keyword_list_keywordsLecture seuleList the keywords inside a shared negative keyword list. Returns each negative keyword's text, match type, and a resource_id ("sharedSetId~criterionId"), with the total keyword count. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_negative_keyword_list_campaignsLecture seuleList which campaigns a shared negative keyword list is attached to. Returns each list-to-campaign attachment with the list and campaign IDs and names. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_recommendationsLecture seuleRetrieve Google's auto-generated recommendations with estimated impact. Returns each recommendation's ID, type, associated campaign/ad group, current (base) and projected (potential) metrics, and the estimated improvement. Includes insights that flag budget-increase recommendations (their projected gain comes from spending more) and highlight high-impact suggestions. The `recommendation.id` is what draft_dismiss_recommendations takes. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_dismiss_recommendationsActionDismiss Google Ads recommendations — returns a PREVIEW. Turns down recommendations you will not take (e.g. "add broad match" on a deliberately narrow account) so they stop reappearing in get_recommendations. Nothing in the account changes, and Google can show a dismissed recommendation again later, so a single confirmation is enough. Each ID must be an active recommendation: unknown or already dismissed IDs are refused by name. The preview lists each one's type, campaign and estimated improvement, so the user sees what they are turning down. DismissRecommendation has no validate-only mode: the dry run re-reads the account and checks every recommendation is still active instead of sending the call to Google. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_recommendation_subscriptionsLecture seuleList the recommendation types Google applies automatically (auto-apply). A subscription makes Google apply every new recommendation of its type without asking, so changes reach the account with no preview. Returns each subscription's type, status (ENABLED or PAUSED), create_date_time and modify_date_time. A type that is not listed is not auto-applied. insights[] names every ENABLED type and flags one modified in the last 30 days, so a recurring audit can catch auto-apply being switched on. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_recommendation_subscriptionsActionPause auto-apply for recommendation types — returns a PREVIEW. Pausing is the only change this tool can make: it sets each type's subscription to PAUSED, so Google stops applying those recommendations on its own. Their recommendations still appear in get_recommendations. Re-enabling auto-apply is deliberately not supported; it lets Google change the account without a preview, so it stays a decision for the Google Ads UI. Pausing reduces automation, so a single confirmation is enough. Each type must have an ENABLED subscription (see get_recommendation_subscriptions); a type with none, or one already paused, is refused by name. The dry run sends the request to Google with validate_only. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_pmax_performanceLecture seuleGet Performance Max campaign and asset group performance. Returns two result sets. campaigns: PMax campaign metrics broken down by ad_network_type (SEARCH, CONTENT, YOUTUBE_SEARCH, YOUTUBE_WATCH, MIXED). MIXED is a catch-all that Google uses for most PMax traffic — full channel splits are not available via the API. asset_groups: per-asset-group metrics including ad_strength (EXCELLENT, GOOD, AVERAGE, POOR). Includes insights flagging weak ad strength, zero-conversion asset groups, and network type distribution. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_pmax_assetsLecture seuleList the assets of Performance Max campaigns with type, status and content. Returns each asset's field_type (HEADLINE, DESCRIPTION, MARKETING_IMAGE, YOUTUBE_VIDEO, etc.), primary_status (ELIGIBLE, NOT_ELIGIBLE, PAUSED, PENDING), and content (text or image URL), plus by_status and by_field_type summaries. Per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. get_detailed_asset_performance reports which asset combinations Google selects most — the closest proxy for individual asset quality. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_detailed_asset_performanceLecture seuleGet top-performing asset combinations for Performance Max campaigns. Shows which headline + description + image combinations Google selects most often. Returns each combination with the assets used and their field types. This data helps identify which creative elements work well together. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_audience_performanceLecture seuleGet audience segment performance metrics. Returns performance by audience type — remarketing lists (USER_LIST), in-market segments (USER_INTEREST), affinity, demographics (AGE_RANGE, GENDER), etc. Shows display_name, impressions, clicks, cost, conversions, CTR, and CPC for each audience. Works for campaigns with explicit audience targeting (Search, Display). PMax audience targeting is automatic and may not appear in this report. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_demographic_targetingLecture seuleList demographic targeting criteria (age, gender, parental status, income). Takes exactly one of ad_group_id or campaign_id. Returns each criterion's value, whether it's negative (excluded) or positive (narrowing), status, and a remove_id (composite resource ID) that can be passed directly to remove_entity with entity_type='ad_group_criterion' or 'campaign_criterion'. By default, Google Ads serves ads to ALL demographic segments — a criterion only appears here once a segment has been actively excluded or narrowed. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_change_historyLecture seuleList recent account changes: who changed what, when, and through which tool. Answers "what changed before the drop?". Returns each change newest first with its time, the user's email, the client it came through (Google Ads UI, API, Google Ads scripts, Editor, automated rules, auto-applied recommendations, ...), the changed resource type, the operation (CREATE, UPDATE, REMOVE), the changed field paths, and the campaign and ad group names. Also returns counts by resource type, client, user and day, plus insights on auto-applied recommendations and budget or bidding changes. Google Ads keeps change history for 30 days, so older start dates are moved to the earliest available day. Reads the change_event resource: https://developers.google.com/google-ads/api/docs/change-event
analyze_campaign_conversionsLecture seuleCampaign clicks → GA4 conversions mapping — the real cost-per-conversion. Combines Google Ads campaign metrics with GA4 session/conversion data to reveal click-to-session ratios (GDPR indicator), compare Ads-reported vs GA4-reported conversions, and compute cost-per-GA4-conversion. Also returns non-paid channel conversion rates for comparison context. GA4 conversions are the property's key events (GA4 metric keyEvents). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
landing_page_analysisLecture seuleAnalyze which landing pages convert and which don't. Combines ad final URLs with GA4 page-level data. Returns paid traffic sessions, conversion rates, bounce rates, and engagement per landing page, and identifies pages that get ad clicks but zero conversions and orphaned URLs. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
attribution_checkLecture seuleCompare Ads-reported conversions vs GA4 — find tracking discrepancies. Checks whether conversions reported by Google Ads match what GA4 records, diagnoses GDPR consent gaps, attribution model differences, and missing conversion event configuration. Returns both sides' totals with the discrepancy and diagnostic insights. GA4 conversions are the property's key events (GA4 metric keyEvents). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_conversion_tracking_setupActionSet up conversion tracking from GA4 into Google Ads in one approved plan, returning a PREVIEW of only the missing steps. Use it when the user wants their conversions (sign-ups, purchases, leads) tracked and used for bidding, or after audit_ga4_property or check_key_event_imports found a gap. It reads both products and plans what is missing, in order: link the GA4 property to the Google Ads account, mark the events as GA4 key events, turn on auto-tagging, import the conversion actions Google Ads created for the key events (they start hidden and record nothing), make them primary, and use their goal for bidding. Steps already in place are listed under already_done. Google Ads creates the conversion action for a newly linked property or new key event by itself, not instantly: such events come back as "After this" warnings, and running the tool again later imports them. NO_CHANGE when everything is set up. The website must send the events; this tool cannot add tracking code (see generate_tracking_code). Nothing changes until confirm_and_apply applies it: the dry run validates the Google Ads steps with validate_only and re-reads the GA4 ones, and every step skips itself if already done, so confirming again after a failed step continues where it stopped. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
check_key_event_importsLecture seuleCheck that every GA4 key event reaches Google Ads: imported, used for bidding, and actually receiving conversions. Matches the property's key events with the Google Ads conversion actions that import them (by GA4 property and event name), and compares GA4's key events from Google Ads traffic (google / cpc) with the conversions Google Ads recorded for each import. insights[] names key events no conversion action imports, imports that are only secondary (reported, not bid on), imports that stay at zero while GA4 counts Google Ads conversions (a broken link or auto-tagging), and imports of events that are no longer key events. Imports from other GA4 properties are listed separately. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
audit_event_coverageLecture seuleThree-way audit: codebase events ↔ GTM tags ↔ GA4 actual fires. Fetches the LIVE GTM container, joins it against GA4 event counts for the date range, and returns a per-event matrix with one of these statuses: ok — tag active and event firing ok_auto_collected — GA4 Enhanced Measurement event, no tag needed no_tag_no_fire — codebase event, no GTM tag, never fires tag_paused — GTM tag exists but is paused tag_active_but_not_firing — tag is active but no GA4 hits gtm_only_firing — GA4 event from a tag, not in codebase gtm_paused_but_firing — only paused tag(s), not in codebase, yet GA4 still fires (event comes from elsewhere) gtm_only_not_firing — tag exists, not in codebase, no fires ga4_only — fires in GA4, no tag, no codebase ref ga4_fires_no_tag — codebase event firing without a GTM tag auto_event_only — Enhanced Measurement event with no codebase ref The result also lists dynamic-event tags ({{Event}} variables) and Custom HTML tags that the audit cannot interpret automatically. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_accountsLecture seuleList all GTM accounts the AdLoop service account / OAuth user can read. The first-time discovery step: provides the account_id that audit_event_coverage takes. Returns each account's ID and name. An empty list means the service account hasn't been added to any GTM container with at least Read permission. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_containersLecture seuleList all containers under a GTM account. Returns container_id (the numeric ID needed by audit_event_coverage), public_id (the GTM-XXXXXXX string shown in the UI), name, and usage context (web / iOS / Android / amp / server). Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_tagsLecture seuleList every tag in the LIVE GTM container, or in one workspace. Each tag includes type, status, parsed parameters, the GA4 event name (for GA4 event tags), and resolved firing/blocking trigger names. Complements audit_event_coverage for inspecting specific tags. With workspace_id the list shows that workspace's unpublished state, so a just-drafted tag is visible; `source` says which state was read. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
get_gtm_tagLecture seuleGet the full RAW configuration for a single GTM tag. Includes every parameter, firing/blocking triggers (with their filter conditions resolved to text), priority, pause status, sampling, and monitoring metadata. Suited to inspecting a tag flagged by audit_event_coverage. An unknown tag_id returns an error with the available tag IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_triggersLecture seuleList every trigger in the LIVE GTM container, or in one workspace. Each trigger has its filter conditions parsed to readable text (e.g. "{{Page Path}} matches RegExp ^/service-promotions/"). Helps diagnose why a tag fires or doesn't fire on specific pages. With workspace_id the list shows that workspace's unpublished state. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
get_gtm_triggerLecture seuleGet the full RAW configuration for a single GTM trigger. Includes filters, auto-event filters, custom-event filters, validation settings, and a list of every tag that uses this trigger. Helps diagnose why a tag with a specific trigger ID does or doesn't fire. An unknown trigger_id returns an error with the available trigger IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_variablesLecture seuleList GTM variables — both custom and enabled built-in. Without workspace_id both come from the live container version (the Default Workspace supplies the built-ins only when the live version lists none; built_in_source names where they came from). With workspace_id both come from that workspace's unpublished state. Variables matter because triggers reference them: if a trigger uses {{Form ID}} but Form ID isn't enabled, the trigger never matches. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_workspacesLecture seuleList workspaces (drafts) under a GTM container. Returns each workspace's ID, name and description; the IDs are what `get_gtm_workspace_diff` takes. Most containers have a single Default Workspace; multiple workspaces appear when the team uses parallel drafts. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
get_gtm_workspace_diffLecture seuleShow drafted-but-not-published changes in a GTM workspace. Returns the list of entities (tags, triggers, variables) added, modified, or deleted relative to the live published version, plus any merge conflicts. Common cause of "I edited a tag but nothing happened" — the workspace was never published. is_clean=true means no pending changes and no conflicts. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
list_gtm_versionsLecture seuleList GTM container version headers (newest first). Version headers include version_id, name, archived flag and entity counts. The Tag Manager API returns no creation or publish time and no author for a version, and does not mark which versions were published; get_gtm_version returns a version's notes and get_gtm_version_diff what changed between two versions. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
get_gtm_versionLecture seuleGet metadata + entity counts for a single GTM container version. Returns name, description (the version notes), fingerprint, and lists of tag/trigger/variable names at that point in time. The API returns no timestamps or author for a version. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
get_gtm_version_diffLecture seuleCompare two GTM container versions: what a publish changed. Returns added, removed and changed tags, triggers and variables (with names, types and the changed fields; parameters and trigger conditions are diffed key by key), plus built-in variables enabled or disabled. By default compares the live version with the version created before it. The Tag Manager API does not mark which versions were published, so that default "before" version may never have been live. Makes two or three Tag Manager API calls. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_gtm_tagActionDraft creating or updating a Tag Manager tag — returns a PREVIEW. Without tag_id this creates a tag in a workspace; with tag_id it updates the existing tag. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set, and Custom HTML (html) is refused as well unless gtm.allow_custom_html is set. Returns the resolved workspace, the tag type, the fields that would change and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_gtm_triggerActionDraft creating or updating a Tag Manager trigger — returns a PREVIEW. Without trigger_id this creates a trigger in a workspace; with trigger_id it updates the existing one. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set. Returns the resolved workspace, the trigger fields that would change and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_gtm_variableActionDraft creating or updating a Tag Manager variable: returns a PREVIEW. Without variable_id this creates a variable in a workspace; with variable_id it updates the existing one. Data Layer Variables, the usual source for GA4 ecommerce values, take data_layer_key (e.g. "ecommerce.value") instead of raw parameters. Tags and triggers use a variable as {{name}}; renaming one they reference is refused, because the references would break (the GTM UI renames safely). Custom JavaScript variables run code on the site and are refused unless gtm.allow_custom_html is set. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_delete_gtm_entityActionDraft deleting a Tag Manager tag, trigger or variable — returns a PREVIEW. The entity is removed from a workspace and stays on the site until the workspace is published. A trigger that any tag still references, or a variable that a tag, trigger or other variable uses as {{name}}, is refused up front, with the references named. Refused unless gtm.write_enabled is set. Returns the entity that would be deleted, the resolved workspace and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_publish_gtm_workspaceActionDraft publishing a Tag Manager workspace LIVE — returns a PREVIEW. Every pending change in the workspace goes live, including changes other people made in the GTM UI; the preview lists them all. Apply refuses when the workspace changed after the preview, has merge conflicts, or reports compiler errors in a quick preview, and it refuses a Custom HTML tag being added or changed while gtm.allow_custom_html is off. Refused unless gtm.write_enabled is set. Returns the pending changes, the version that is live now (for a one-step rollback), the version name that would be created and a plan_id. That gate matches the tag type html; a Custom JavaScript variable or a custom template tag (cvt_…), which can inject a script, is not covered and needs review in the GTM UI. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
draft_rollback_gtm_versionActionDraft republishing an older Tag Manager version LIVE; returns a PREVIEW. A rollback publishes an existing container version again. The preview diffs the live version against the target, so it lists every tag, trigger and variable that changes on the site, and it pins the live version: apply refuses when another version went live after the preview, or when the target was modified or archived. Workspaces are not changed. Refused unless gtm.write_enabled is set, and refused when the target adds or changes a Custom HTML tag while gtm.allow_custom_html is off. Returns the diff, previous_live_version_id (the version that restores today's state), the target version and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2
run_gaqlLecture seuleExecute an arbitrary GAQL (Google Ads Query Language) query. For queries beyond the dedicated report tools. Returns the result rows in the requested format with the query echoed back; cost fields stay in raw micros (cost_micros / 1,000,000 = account currency). A failing query returns an error with a hint. Queries the Google Ads API. GAQL syntax and fields: https://developers.google.com/google-ads/api/docs/query/overview
get_audience_listsLecture seuleThe account's own audiences: remarketing and customer lists, custom segments, combined segments. Each user list comes with its type, membership status (OPEN or CLOSED), size for Search and Display, eligibility and membership duration; custom and combined segments with their id and description. Insights flag lists below the 100 active users Search needs and closed lists. Use the ids with draft_audience_attachment; for Google's in-market and affinity segments use search_audience_segments. Google Ads API: https://developers.google.com/google-ads/api/docs/start
search_audience_segmentsLecture seuleFind Google's in-market and affinity segments by name, with the segment_id to attach. In-market segments are people actively researching a purchase; affinity segments are long-term interests. Matching is on the segment name, in English, e.g. "running", "insurance", "travel". Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_audience_targetingLecture seuleAudiences attached to one campaign or ad group, its exclusions, and the audience mode. audience_mode is "observation" (audiences only adjust bids and report), "targeting" (ads only reach the audiences) or "not set". Every audience and exclusion carries a remove_id for remove_entity (entity_type "campaign_criterion" or "ad_group_criterion"). Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_audience_attachmentActionDraft attaching audiences to a campaign or ad group as observation, targeting or exclusion: returns a PREVIEW. Observation (the default) keeps the reach: the audiences adjust bids and show up in reports. Targeting narrows delivery to the audiences and needs a double confirmation. Exclusions keep the people out and leave the mode alone. The draft refuses combinations Google does not allow (custom segments on Search, combined segments outside Search, audiences at both campaign and ad group level) and lists that cannot serve; Performance Max is refused with a pointer to draft_asset_group_signals. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_shopping_product_performanceLecture seuleSpend, clicks, conversions, CPA and ROAS per product across Shopping and Performance Max. Each product (item id) is summed over the campaigns it ran in. Returns the account totals, the top products by spend, and the products that spent without a conversion, with insights on what to do with them. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_asset_group_signalsLecture seuleSearch themes and the audience signal of a Performance Max asset group, plus the account's audiences. Returns each search theme and audience signal with its signal_id and approval status, the enabled audiences of the account that can become the group's audience signal (audience_id, name), and insights when a group has no themes or no audience signal. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_asset_group_signalsActionDraft adding search themes or an audience signal to a Performance Max asset group, or removing signals — PREVIEW. Signals are hints that steer Performance Max, not targeting. A group has at most one audience signal and up to 50 search themes; replacing the audience means removing the current one in the same draft. Themes already on the group are skipped. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_pmax_product_exclusionsActionDraft which products a retail Performance Max asset group excludes — returns a PREVIEW. Sets the full list of excluded values on one product dimension (item id, brand or a custom label); everything else stays included. Pass the complete list each time: values left out are included again, and an empty list includes all products. Works on asset groups that advertise all products or are already split on that one dimension; more complex product filters are refused and stay a job for Google Ads. The filter is rebuilt in one atomic request. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_asset_group_assetsActionDraft adding and/or removing assets of a Performance Max asset group — returns a PREVIEW. Adds new text, image and YouTube assets and unlinks existing ones in one atomic request, so an asset is replaced without the group dropping below Google's minimums (3 headlines, 1 long headline, 2 descriptions, one of them at most 60 characters). Texts already in the group are skipped. Images are checked and sorted by aspect ratio; removed assets stay in the account's asset library. The preview lists the asset counts per type after the change. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_shopping_campaignActionDraft a Standard Shopping campaign that advertises a Merchant Center feed — returns a PREVIEW. Creates the budget, the campaign (PAUSED), a product ad group with its Shopping ad, and one "All products" product group, in one atomic request. The Merchant Center account must be linked to the Google Ads account; the draft checks that. Shopping campaigns take no keywords and no language targeting (the feed's language applies). Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_campaignActionDraft a full campaign structure — returns a PREVIEW, does NOT create anything. Creates: CampaignBudget + Campaign (PAUSED) + AdGroup + optional Keywords + geo targeting + language targeting + optional geo exclusions and ad schedule, all in one atomic request. Ads are NOT included — draft_responsive_search_ad adds them once the campaign exists. Only SEARCH campaigns can be created: Performance Max needs an asset group with all its assets in one request, and DISPLAY, SHOPPING and VIDEO need channel-specific settings and ad group types, so the draft refuses them. Returns a preview with a plan_id plus any warnings (e.g. a daily budget below 5x target CPA, MANUAL_CPC); nothing changes until confirm_and_apply applies the returned plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_ad_groupActionDraft a new ad group within an existing campaign — returns a PREVIEW, does NOT create. Creates an ad group (ENABLED, type SEARCH_STANDARD) in the specified campaign, optionally with keywords in the same atomic operation. Only SEARCH campaigns are supported. Ads are not included, so the ad group cannot serve until one of its ads is created and enabled. Returns a preview with a plan_id plus warnings (BROAD keywords on a non-Smart-Bidding campaign, a duplicate ad group name, a CPC bid that Smart Bidding ignores); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_campaignActionDraft an update to an existing campaign — returns a PREVIEW, does NOT apply. Only the parameters passed are changed; omitted ones stay as they are, and at least one change is required. Replacing geo targets keeps the campaign's negative geo exclusions (the preview lists them) unless geo_exclude_ids is passed too. A budget change shows the current amount; when the budget is shared with other campaigns, the preview names them and needs a double confirmation, because the new amount covers all of them. A bidding change on a campaign in a portfolio bid strategy takes it out of the portfolio, also with a double confirmation. Returns a preview with a plan_id plus any warnings; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_responsive_search_adActionDraft a Responsive Search Ad — returns a PREVIEW, does NOT create the ad. The preview shows exactly what will be created; confirm_and_apply executes the returned plan_id. The ad is created PAUSED. final_url is checked for reachability first and an unreachable URL is refused. Several headlines may pin to the same position (Google rotates them there) as long as every position stays fillable, by an asset pinned to it or by a distinct unpinned one. Mixed plain-string and dict entries are allowed within a single call (e.g. brand pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8 headlines or 3 descriptions. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_responsive_search_adActionUpdate mutable fields on an existing RSA in place — returns a PREVIEW. Edits an existing RSA without creating a new ad; the ad keeps its ID. Google Ads API v23 (``AdService.MutateAds``) permits in-place mutation of ``final_urls``, ``path1``, ``path2``, ``headlines``, and ``descriptions``. At least one mutation must be requested. IMPORTANT: replacing headlines or descriptions is NOT a free in-place edit. Even though the ad ID is preserved, swapping the creative text RESETS the ad's asset-combination learning and performance history and sends the ad BACK THROUGH Google policy review — Google treats the creative as new for optimization. URL-only and path-only edits do not incur this. When headlines/descriptions change, the returned preview includes a ``warnings`` entry stating this trade-off before anything is applied. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_keywordsActionDraft keyword additions — returns a PREVIEW, does NOT add keywords. Returns a preview with a plan_id, plus a warning when BROAD keywords go into a campaign without Smart Bidding; nothing changes until confirm_and_apply applies the returned plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_custom_conversion_goalsLecture seuleRead the custom conversion goals and the campaign goal configuration. Returns every custom goal with its name, status and conversion actions, plus — optionally for one campaign — the goal config the campaign uses (`goal_config_level` CUSTOMER or CAMPAIGN and the assigned custom goal). A custom conversion goal bundles conversion actions into a named set that a campaign can be pointed at. Ahead of drafting, this shows which goals exist, which actions they contain and what a campaign currently uses. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_custom_conversion_goalActionCreate a custom conversion goal — returns a PREVIEW. The goal bundles conversion actions into a named set that campaigns can then be pointed at with draft_assign_custom_conversion_goal. Only the goal is created: conversion actions are read for validation and never modified. It is always created ENABLED — a goal created as REMOVED would be invisible to every other tool, so there is nothing to plan. If a goal with the same name and exactly the same conversion actions already exists, nothing is planned and the result says `already_exists` with that goal's ID (REMOVED goals do not count). A name that exists with different actions is changed with draft_update_custom_conversion_goal. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_update_custom_conversion_goalActionRename and/or re-scope an existing custom conversion goal — PREVIEW. conversion_action_ids REPLACES the whole action list, it does not append. An empty parameter stays unchanged. The preview shows the action list before and after. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_assign_custom_conversion_goalActionPoint a campaign at a custom conversion goal — returns a PREVIEW. Sets goal_config_level=CAMPAIGN and the goal on that campaign's conversion goal config. Nothing else changes: conversion actions, bidding, budgets and the account-level goals stay as they are. A campaign must have at least one goal configured when it switches to campaign level — Google answers EMPTY_CONVERSION_GOALS otherwise. That is why this tool assigns a goal instead of clearing goals; draft_clear_custom_conversion_goal goes back to the account level. If the campaign already uses exactly this goal, nothing is planned and the result says `already_configured`. The preview carries a note that changing what a campaign optimises for restarts its Smart Bidding learning period. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_clear_custom_conversion_goalActionPut a campaign back on the account-level goals — returns a PREVIEW. Sets goal_config_level=CUSTOMER and clears the custom goal: the rollback for draft_assign_custom_conversion_goal. The account-level goals themselves are not touched. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
add_negative_keywordsActionDraft negative keyword additions — returns a PREVIEW. Negative keywords prevent your ads from showing for irrelevant searches. They are added at campaign level. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
add_negative_locationsActionDraft negative geo location additions — returns a PREVIEW. Excludes cities/regions from a campaign while keeping broader positive targets such as State of Sao Paulo. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
propose_negative_keyword_listActionDraft a shared negative keyword list and attach it to a campaign — returns a PREVIEW. Creates a reusable negative keyword list (shared set) that can later be applied to multiple campaigns, whereas add_negative_keywords adds negatives directly to one campaign. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
add_to_negative_keyword_listActionAppend keywords to an EXISTING shared negative keyword list — returns a PREVIEW. Adds terms to a list that already exists (propose_negative_keyword_list creates a new list instead); get_negative_keyword_list_keywords shows the terms already in a list. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
attach_shared_set_to_campaignsActionAttach an existing shared set to one or more campaigns — returns a PREVIEW. Creates CampaignSharedSet linkages so the campaigns inherit the shared set's criteria (e.g. negative keywords). Most commonly used to attach a shared negative keyword list to newly-built campaigns; get_negative_keyword_list_campaigns lists existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
detach_shared_set_from_campaignsActionDetach a shared set from one or more campaigns — returns a PREVIEW. Removes CampaignSharedSet linkages so the campaigns no longer inherit the shared set's criteria. The shared set itself is unchanged; only the per-campaign attachment is removed. get_negative_keyword_list_campaigns lists the existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_ai_max_settingsLecture seuleRead the AI Max controls of Search campaigns, per campaign and ad group. Returns for every campaign: id, name, status, advertising channel type, campaign.ai_max_setting.enable_ai_max, campaign.ai_max_setting.bundling_required (output only) and the full campaign.asset_automation_settings list. Each campaign also carries its non-REMOVED ad groups with ad_group.ai_max_ad_group_setting.disable_search_term_matching. Shows the current state ahead of draft_ai_max_settings, and what the account actually looks like after confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_campaign_settingsLecture seuleRead every setting that decides how far a Search campaign reaches, in one call. Returns one flat record per campaign: status, bidding strategy and its target or CPC ceiling, daily budget and whether it is shared, the Google Search / search partner / Display network flags, the location option (positive_geo_target_type) and its negative counterpart, campaign-level broad match (keyword_match_type), the tracking template, final URL suffix and custom parameters, and the AI Max state get_ai_max_settings reports (enable_ai_max, asset automation per type). Money is in the account currency (`currency`). Each campaign lists its `widening_settings`: search partners or Display on, a presence-or-interest location option, broad match on, AI Max on, an automation opted in. `insights[]` names the campaigns that have any. Made for recurring audits: the same call every week diffs cleanly. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_ai_max_settingsActionDraft AI Max controls for a Search campaign — returns a PREVIEW. AI Max is the container that makes brand exclusions usable in Search: Google rejects a brand list on a plain Search campaign ("For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns"). Turning AI Max on while leaving its automations running is the trap, so both belong to the same plan. An automation the caller never mentioned is refused outright (the plan says which switch to pass); one named explicitly (disable_search_term_matching=False, text_asset_automation="OPTED_IN") is planned with requires_double_confirm=True, because switching to AI Max with its automations is a real configuration some accounts want. Reads the campaign and its ad groups first, so the preview names concrete ad groups and shows current values per knob. Returns a preview with a plan_id; nothing is written until confirm_and_apply runs. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_prepare_brand_exclusionsActionDraft the safe standard state for brand exclusions — returns a PREVIEW. Exactly one combination, nothing else: enable_ai_max = true, disable_search_term_matching = true (all non-removed ad groups), TEXT_ASSET_AUTOMATION = OPTED_OUT and FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION = OPTED_OUT. No bidding, keyword, match type, ad, URL or budget change, and no brand list is attached — attaching stays a separate step with propose_brand_list / attach_brand_list_to_campaigns once this state is verified in the account. Returns a preview with a plan_id (purpose brand_exclusions); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_demographic_targetingActionDraft demographic targeting (age/gender/parental status/income) — returns a PREVIEW. By default, Google Ads serves to all demographic segments. This tool adds criteria that EXCLUDE a segment (negative=True, default) or NARROW targeting to it (negative=False — uncommon). Takes exactly one of ad_group_id or campaign_id, and at least one of the four demographic lists must contain a value. Returns a preview with a plan_id, plus warnings when the change narrows targeting, excludes 'undetermined' users, or excludes nearly a whole dimension; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_ad_groupActionDraft an ad group update for name and/or manual CPC bid — returns a PREVIEW. A bid change applies only when the campaign uses MANUAL_CPC: automated bidding strategies ignore ad-group CPC bids, so such a change is refused (for Maximize Clicks the campaign cpc_bid_ceiling, set through update_campaign, is the active constraint). Bid increases above the configured safety.max_bid_increase_pct are refused. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_calloutsActionDraft callout assets for an ad group, a campaign or the account — returns a PREVIEW. Creates callout assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking (every campaign without callouts of its own) needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_structured_snippetsActionDraft structured snippet assets for an ad group, a campaign or the account — returns a PREVIEW. Creates structured snippet assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_call_assetActionDraft a call asset (a phone number shown with the ads) — returns a PREVIEW. Creates the call asset and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Google reviews the number before it serves. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_call_assetActionDraft changing a call asset in place — returns a PREVIEW. Only the fields passed change. The asset keeps its ID and its links, so the change shows everywhere it is linked. The preview shows the current values and pins them; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
add_ad_scheduleActionDraft ad schedule windows for a campaign — returns a PREVIEW. Adds the windows; existing ones stay. The preview lists the current windows (each with the remove_id that remove_entity takes as a campaign_criterion) and the account time zone the hours are in. Overlapping windows and more than six a day are refused. A campaign without any window serves at all hours, so its first windows restrict it to them: that preview needs a double confirmation. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_promotionActionDraft a promotion asset ("20% off winter tyres") — returns a PREVIEW. Creates the promotion and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. The final_url is checked for reachability. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_promotionActionDraft changing a promotion asset in place — returns a PREVIEW. Only the fields passed change; everything else stays as it is. The asset keeps its ID and history, and the change shows everywhere it is linked. Passing money_off replaces a percent_off (and the other way round); passing promotion_code replaces an orders_over_amount (and the other way round). The preview shows old and new values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_price_assetActionDraft a price asset (the row of prices under an ad) — returns a PREVIEW. Creates a price asset with 3-8 offerings and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Every offering URL is checked for reachability. Google disapproves prices that differ from the landing page. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_business_name_assetActionDraft a business name asset for a campaign or the account — returns a PREVIEW. Creates a text asset and links it as the business name shown with the ads. Google links business names at campaign or account level only. Account-wide needs scope="account" and no campaign_id. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
link_asset_to_customerActionDraft linking existing assets at account level — returns a PREVIEW. Account-level assets serve on every eligible campaign that has no asset of the same type linked at campaign or ad-group level. Each asset is checked to exist and to match its field type. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_calloutActionDraft changing a callout asset in place — returns a PREVIEW. Only what is passed changes. The asset keeps its ID and performance history, and the change shows everywhere it is linked. The preview pins the current values; if someone edits the asset in Google Ads before the apply, nothing is sent. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_sitelinkActionDraft changing a sitelink asset in place — returns a PREVIEW. Only the fields passed change; empty fields stay as they are. The asset keeps its ID and performance history everywhere it is linked. A new final_url is checked for reachability. The preview pins the current values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
update_structured_snippetActionDraft changing a structured snippet asset in place — returns a PREVIEW. Replaces the snippet's values (and header, if given). The asset keeps its ID and performance history everywhere it is linked. The preview pins the current header and values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_image_assetsActionDraft image assets from local files, public image URLs or uploads — returns a PREVIEW. At least one image in total is required across image_paths, image_urls and upload_ids. Images must be PNG, JPEG or GIF and at most 5120 KB (Google's limit). URL images are downloaded now and checked; applying re-downloads them and refuses if the image changed since the preview. Returns a preview with a plan_id and a per-image summary; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
pause_entityActionDraft pausing a campaign, ad group, ad, or keyword — returns a PREVIEW. Pausing is reversible with enable_entity. Returns a preview with a plan_id (target status PAUSED); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
enable_entityActionDraft enabling a paused campaign, ad group, ad, or keyword — returns a PREVIEW. Returns a preview with a plan_id (target status ENABLED); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
remove_entityActionDraft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE. Removed entities cannot be re-enabled; pause_entity is the reversible way to temporarily disable something. Returns a preview with a plan_id and requires_double_confirm=true; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_sitelinksActionDraft sitelink extensions for a campaign or the account — returns a PREVIEW. Sitelinks appear as additional links below your ad, increasing click area and directing users to specific pages. Every final_url is fetched and an unreachable URL (HTTP 4xx/5xx) blocks the draft. Google recommends at least 4 sitelinks per campaign; fewer than 2 may not show. Returns a preview with a plan_id and any warnings; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
confirm_and_applyActionExecute a previously previewed change. IMPORTANT: Defaults to dry_run=True (validate only). Only an explicit dry_run=false applies the change to the ad account (Google Ads or Reddit Ads — the plan knows which platform it targets). Forced dry runs: when real changes are switched off (live changes off for the workspace in AdLoop Cloud, or safety.require_dry_run in a self-hosted config), dry_run=false is IGNORED and the result is still DRY_RUN_SUCCESS, with 'dry_run_forced_by' and 'remediation' fields. 'remediation' says how the user switches that setting; until it is changed, repeated calls with dry_run=false change nothing. Two-phase apply: if 'safety.two_phase_apply: true' is set (always on for AdLoop Cloud tenants), dry_run=false is REFUSED with status DRY_RUN_REQUIRED until this plan_id has completed one dry_run=true pass. The sequence is: dry run, review of its result, then the real apply. Google Ads plans: the dry run sends the exact mutates to Google with validate_only=True, so Google checks the change and executes nothing (`checks` counts the validated calls). Steps that build on an object an earlier step would create cannot be validated and are counted as skipped. Reddit plans: Reddit has no validate-only mode, so the dry run re-reads the target entity and re-checks the safety caps (returned as `checks`). A DRY_RUN_FAILED result means the change does not go through as previewed. The real apply fails the same way, unless Google rejected only part of the request: then it carries out the rest and reports those operations again. Returns a status with the plan_id and operation: DRY_RUN_SUCCESS, DRY_RUN_FAILED, DRY_RUN_REQUIRED, BLOCKED, APPLIED, PARTIAL_UPLOAD, PARTIAL_APPLY, UNKNOWN_OUTCOME or APPLY_IN_PROGRESS. BLOCKED means the operation was added to safety.blocked_operations after the draft: nothing ran and the plan stays pending. APPLIED results carry the created or changed resource names under 'result'. PARTIAL_UPLOAD belongs to the upload tools: the batches it lists are already in the account, so the plan is retired. 'sent_total', 'accepted_total', 'rejected_total' and 'resume_from_line' say how far the upload got and at which CSV line a new draft continues; when a batch's fate is unknown, 'unknown_status', 'uncertain_lines' and 'row_errors' name the rows whose outcome has to be checked first. PARTIAL_APPLY and UNKNOWN_OUTCOME come from platforms without transactional writes: part of the change is in the account ('created' names it), or a create was never answered. The plan is retired; read the account back and draft only what is missing. APPLY_IN_PROGRESS means an earlier call claimed this plan first, so this call executed nothing. Approval cards: in AI apps that show AdLoop's approval card with the preview, dry_run=false is REFUSED with status APPROVE_ON_CARD, because only the user's click on the card applies the change. Dry runs still work. The workspace owner can allow approval in chat as well. Confirmation dialogs: in apps that show dialogs instead, dry_run=false first asks the user in a dialog. A declined dialog returns NOT_CONFIRMED; an app that receives the dialog but never answers it gets CONFIRMATION_UNANSWERED on the next call, with the ways out. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/
upload_imagesLecture seuleLet the user upload images (PNG, JPEG, GIF up to 5 MB) for ad assets. For images without a public URL, such as a file on the user's computer or an image attached in the chat. An attached image cannot reach a tool, so the user drops the same file on the card. Apps that show AdLoop's cards display an upload card where the user drops the files; the card then posts the upload ids into the chat. On AdLoop Cloud in other apps the result carries an upload link for the user (or a coding agent, with curl). Uploads expire after a day. The ids go into upload_ids of draft_image_assets, or as "upload:<id>" into the image fields of draft_reddit_ad. Returns the current uploads and how to add more. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/
upload_conversion_csvLecture seuleLet the user upload a conversion CSV for an offline conversion upload. For the CSV behind draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads when the file is not on the machine running AdLoop, as on AdLoop Cloud. Apps that show AdLoop's cards display an upload card where the user drops the .csv file; the card then posts the upload id into the chat. Other apps on AdLoop Cloud get an upload link for the user (or a coding agent, with curl). The file holds personal data (phone numbers, emails), so it is kept for two hours at most and deleted as soon as a draft has read it. Returns the CSV uploads waiting to be used and how to add one. Google Ads API: https://developers.google.com/google-ads/api/docs/start
list_uploadsLecture seuleList the files the user uploaded to AdLoop that have not expired. Returns each upload's upload_id, kind (image or csv), name, type, size, dimensions (images) or lines (CSVs) and hours until it expires: images last a day, conversion CSVs two hours or until a draft reads them. The ids of files the user sent through an upload link show up here. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/
draft_key_eventActionDraft marking a GA4 event as a key event (conversion), or changing an existing one — returns a PREVIEW. The fix for "the event fires but isn't tracked as a conversion": attribution_check / validate_tracking diagnose it, this closes the loop. When the event already is a key event, the plan changes its counting method or default value instead and the preview shows before and after; nothing to change returns NO_CHANGE. Applies to future data only. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_delete_key_eventActionDraft removing a GA4 key event so the event no longer counts as a conversion, returning a PREVIEW. The event itself keeps firing and stays in event reports; only its key-event status goes, for future data (key events already recorded are not reclassified). The draft resolves the event name against the property's key events (keyEvents.list), so the preview names the exact key event, its counting method and create time; an unknown name returns the existing key events, and one GA4 marks as not deletable is refused. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it (GA4 Admin API keyEvents.delete). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_ga4_annotationActionDraft creating, changing or deleting a GA4 annotation (a note on a date or date range in GA4's charts), returning a PREVIEW. Use it to mark what explains a change in the data: a site relaunch, a price change, a campaign start, a tracking fix. Create needs title and date; update and delete need the annotation's ID from list_ga4_annotations, and an update changes only the fields passed (the preview shows before and after). Annotations Google created itself cannot be changed. Nothing changes until confirm_and_apply applies it; the dry run re-reads the annotation and refuses if it was changed in GA4 after the preview. GA4 Admin API v1alpha (reportingDataAnnotations). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_ga4_audienceActionDraft creating, renaming or archiving a GA4 audience — returns a PREVIEW. An audience is the users who sent certain events. A linked Google Ads account receives it as a remarketing list within one to two days, to attach to campaigns with draft_audience_attachment: this is how to build a list of site visitors, of buyers, or of visitors who did not buy. GA4 fixes the events and the membership duration at creation; afterwards only the name and description can change, and archiving is permanent (it needs a double confirmation). The draft refuses a taken name and a full property, and the preview warns when the property's audiences would not reach Google Ads (see list_ga4_audiences). Nothing changes until confirm_and_apply applies the plan_id. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_ga4_custom_dimensionActionDraft registering, changing or archiving a GA4 custom dimension, returning a PREVIEW. Registering makes an event parameter (EVENT scope), a user property (USER) or an ecommerce item parameter (ITEM) reportable as a dimension. Before anything reaches Google the draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the dimension only from now on and that parameter_name and scope cannot change later. Update changes display_name, description or (USER scope) disallow_ads_personalization; archive removes it from reports and frees the slot, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customDimensions). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_ga4_custom_metricActionDraft registering, changing or archiving a GA4 custom metric, returning a PREVIEW. Registering makes a numeric event parameter reportable as a metric. The draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the metric only from now on. Update changes display_name, description, measurement_unit or restricted_metric_type; archive removes it from reports, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customMetrics). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_ga4_data_retentionActionDraft a change to how long GA4 keeps event- and user-level data, returning a PREVIEW. GA4 defaults to 2 months, which cuts explorations, funnels and other user-level reports short; standard properties allow 14 months, GA4 360 up to 50. Standard reports are aggregated and not affected. Lengthening applies from now on (data already deleted does not come back); shortening deletes older data for good and needs a double confirmation. The preview shows before and after and reminds the user that a privacy policy naming a retention period must match. NO_CHANGE when the settings already match. Nothing changes until confirm_and_apply applies it; the dry run re-reads the settings and refuses if they changed in GA4 after the preview. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1
draft_create_conversion_actionActionDraft a new Google Ads ConversionAction — returns a PREVIEW. Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it. SMART_CAMPAIGN_* and GOOGLE_HOSTED types are auto-managed by Google and rejected with MUTATE_NOT_ALLOWED. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_update_conversion_actionActionDraft a partial UPDATE of an existing ConversionAction — returns PREVIEW. Only parameters passed non-empty/non-default are sent to the API. Covers renaming, demoting a Primary to Secondary, changing value, adjusting the call-duration threshold, changing attribution, or moving the action to another goal with category. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject mutations with MUTATE_NOT_ALLOWED at apply time. Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_remove_conversion_actionActionDraft a REMOVAL of a ConversionAction — returns a PREVIEW. Removal stops counting and drops the action from goal lists; historical data is preserved but the action is irreversible. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject removal with MUTATE_NOT_ALLOWED. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_upload_call_conversionsActionDraft an offline CALL-conversion upload from a CSV — returns a PREVIEW. Uploads call conversions via ConversionUploadService.UploadCallConversions, matching the call against the ad click by the caller's phone number. The CSV must have columns: Caller's Phone Number, Call Start Time, Conversion Name, Conversion Time, Conversion Value, Conversion Currency. The Conversion Name must match an existing UPLOAD_CALLS-type conversion action — verified against the account while drafting, so a typo fails here rather than after the upload. Optional `Ad User Data` and `Ad Personalization` columns carry consent per row. The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it. PII: the caller phone number is required RAW by Google (it cannot be hashed), so it lives in the plan's apply-only payload — the preview shows redacted ids and counts, the audit log and `plan.changes` show neither. Apply uploads exactly what you previewed (no CSV re-read). Phone numbers are normalized with libphonenumber semantics: a number carries no country code needs ``default_region``, an extension is dropped, and the German trunk marker in "+49 (0)89 …" is handled. Rows whose number stays unusable are skipped and reported in `skipped_rows` instead of being uploaded to no effect. Rows that repeat inside one file are named in `dedup_warnings`. A call upload has no dedup key at Google, so each of them still goes out as its own conversion — the warning is the only place that says so. Returns a preview with a plan_id, the row counts, the consent the rows actually carry (`consent_summary`) and the skipped rows; nothing is uploaded until that preview is confirmed. Google Ads API: https://developers.google.com/google-ads/api/docs/start
draft_upload_enhanced_conversions_for_leadsActionDraft an Enhanced Conversions for LEADS upload from a CSV — PREVIEW. Uploads lead conversions via ConversionUploadService.UploadClickConversions with user_identifiers, matching hashed customer PII back to the Google users who clicked the ads. The CSV holds RAW PII in columns: Email, Phone Number, First Name, Last Name (plus Conversion Name, Conversion Time, Conversion Value, Conversion Currency; optional Order ID dedup key, and optional `Ad User Data` / `Ad Personalization` consent columns). PII is normalized and SHA-256-hashed AT PREVIEW TIME — only the hashes are stored in the plan. Raw email/phone/name never land in the plan or the audit log. A cell that already is a SHA-256 hex digest (a CRM export that hashes before writing) is used as it is. The target conversion action must be UPLOAD_CLICKS-type. An Order ID column makes re-uploads dedup instead of double-counting. Rows that repeat inside one file are named in `dedup_warnings`. Rows sharing an Order ID count once at Google; two rows with different Order IDs are two real orders and are not reported. The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it. Returns a preview with a plan_id, the row counts, the consent the rows actually carry (`consent_summary`) and the skipped rows; nothing is uploaded until that preview is confirmed. Google Ads API: https://developers.google.com/google-ads/api/docs/start
validate_trackingLecture seuleCompare tracking events found in the codebase against actual GA4 data. Takes the event names found in the codebase's gtag('event', ...) or dataLayer.push calls and checks which ones actually fire in GA4. Returns matched events with their GA4 counts, events missing from GA4, unexpected GA4 events, auto-collected events (page_view, session_start, etc.), insights on likely causes, and the date range. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
generate_tracking_codeLecture seuleGenerate a GA4 event tracking JavaScript snippet. Produces ready-to-paste gtag code for the specified event. Includes recommended parameters for well-known GA4 events (sign_up, purchase, etc.). Optionally checks GA4 to warn if the event already fires. Returns the javascript snippet, already_exists / existing_count from GA4, and notes (duplicates, marking it as a key event, GDPR consent). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start
estimate_budgetLecture seuleForecast clicks, cost, and conversions for a set of keywords. Uses Google Ads Keyword Planner to estimate campaign performance without creating anything. Essential for budget planning before launching campaigns. Per-keyword max_cpc values are collapsed to a campaign-level manual CPC cap (the highest one) — the Ads API forecast takes no per-keyword bids. Returns estimated clicks, cost, avg CPC, conversions and avg CPA for the forecast period, daily estimates, and insights. Google Ads API: https://developers.google.com/google-ads/api/docs/start
discover_keywordsLecture seuleDiscover new keyword ideas using Google Ads Keyword Planner. Mirrors the "Discover new keywords" UI in Keyword Planner: start with keywords (seed_keywords), start with a website (url), or both together for more targeted ideas. At least one of seed_keywords or url is required. Returns keyword ideas sorted by avg monthly search volume, with competition level (LOW/MEDIUM/HIGH) and top-of-page bid range, plus the seeds used and insights. Google Ads API: https://developers.google.com/google-ads/api/docs/start
suggest_brandsLecture seuleResolve a brand name to the brands Google recognizes for it. Mirrors the brand picker in the Google Ads UI (BrandSuggestionService.SuggestBrands): takes a free-text name such as "EscapeGame München" or "NoWayOut" and returns the matching brands with their ID, display name, state, and associated URLs. The returned brand ID is the Commercial Knowledge Graph ID. Brand criteria — brand lists, brand exclusions — target that ID, not a display name, so a name is resolved here before it can go into a brand list. Google Ads API: https://developers.google.com/google-ads/api/docs/start
check_brand_namesLecture seuleCheck a list of brand names against Google's brand knowledge graph. One SuggestBrands call per name, for the case where a shortlist has to be triaged instead of a single name resolved: which of these brands does Google know at all, and what is the ID of each? Returns checked / matched / no_match counts and one result per name with status "matched" (with a best-match brand plus all candidates) or "no_match" (empty candidate list — a normal answer, not an error). exact_match marks a candidate whose name matches the query apart from case and punctuation; anything else is a Google suggestion, not a guarantee. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_brand_listsLecture seuleList all brand lists (SharedSets of type BRANDS) in the account. Returns each list's ID, name, status, and member count, plus the total — the basis for reusing an existing list with add_to_brand_list instead of duplicating it with propose_brand_list. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_brand_list_brandsLecture seuleList the brands inside a brand list. Returns the brands and their total. Each entry carries brand.entity_id (the Commercial KG MID that suggest_brands returns as id), the display name, primary URL, status and a criterion_id — the latter is what remove_from_brand_list needs. Google Ads API: https://developers.google.com/google-ads/api/docs/start
get_brand_list_campaignsLecture seuleList which campaigns a brand list is attached to. Brand lists attach as CampaignCriterion rows of type BRAND_LIST (not as CampaignSharedSet like negative keyword lists). Returns each attachment's campaign ID, name and status, the criterion, and `role`: "excluded" when the criterion is negative, "targeted" when it restricts targeting to the list. Google Ads API: https://developers.google.com/google-ads/api/docs/start
propose_brand_listActionDraft a brand list and optionally attach it to campaigns — returns a PREVIEW. Creates a SharedSet of type BRANDS, fills it with brands, and — when campaign_ids is given — attaches it to those campaigns. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
add_to_brand_listActionAppend brands to an EXISTING brand list — returns a PREVIEW. For a list that already exists and only needs more brands (propose_brand_list creates a new list instead). The shared_set_id comes from get_brand_lists; get_brand_list_brands shows the brands already in the list, which makes a brand that would be added twice visible. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
remove_from_brand_listActionRemove brands from a brand list — returns a PREVIEW. SharedCriteria have no status field, so removal is the only way to take a brand out of a list — there is nothing to pause. Removing a brand does not detach the list from any campaign. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
attach_brand_list_to_campaignsActionAttach an existing brand list to one or more campaigns — returns a PREVIEW. Creates a CampaignCriterion.brand_list per campaign. This is NOT the CampaignSharedSet linkage used for negative keyword lists — brand lists are criteria, and `negative` decides the role. The shared_set_id comes from get_brand_lists; get_brand_list_campaigns lists existing attachments. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
detach_brand_list_from_campaignsActionDetach a brand list from one or more campaigns — returns a PREVIEW. Removes the CampaignCriterion rows linking the list to those campaigns; the list itself and its brands are unchanged. get_brand_list_campaigns lists the existing attachments. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start
| list_ga4_audiences | List a GA4 property's audiences and check whether they reach Google Ads. GA4 shares its audiences with every linked Google Ads account that allows personalized advertising; there they are remarketing lists (get_audience_lists) that draft_audience_attachment puts on a campaign. Returns each audience's resource name, display name, description, membership duration and the events that include or exclude users (audiences built with other conditions in GA4's editor carry custom_conditions and the raw conditions; "All Users" and "Purchasers", which GA4 creates itself, carry predefined), the audience slots used against the limit (100, or 400 on a 360 property), and google_ads_readiness: checks for the Google Ads link, personalized advertising on it, Google signals, consent and list size, each with a status (ok, warn or info). insights repeats the warnings. Reads the GA4 Admin API (audiences.list, googleAdsLinks.list, googleSignalsSettings). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| list_ga4_custom_definitions | List a GA4 property's custom dimensions and custom metrics, with how many slots are left. Returns each custom dimension's resource name, parameter name, display name, scope (EVENT, USER or ITEM) and description, and each custom metric's resource name, parameter name, display name, measurement unit and description, plus usage per kind against the property's limit (standard: 50 event, 25 user, 10 item dimensions, 50 metrics; 360: 125, 100, 25, 125). Use it before draft_ga4_custom_dimension or draft_ga4_custom_metric. For the field names to use in reports, see list_ga4_dimensions_and_metrics. Reads the GA4 Admin API (customDimensions.list, customMetrics.list). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Lecture seule |
| list_gsc_sites | List all Google Search Console properties the authenticated user can access. Serves as the discovery step for the site URLs that search analytics reports (run_gsc_report) take. Returns the site URL and permission level for each property. Search Console API: https://developers.google.com/webmaster-tools | Lecture seule |
| run_gsc_report | Run a Google Search Console search analytics report. Returns clicks, impressions, CTR, and average position broken down by the requested dimensions. Useful for diagnosing organic traffic drops, finding keyword opportunities, and cross-referencing with GA4 and Ads data. One request returns at most 25,000 rows; a full page carries next_start_row for the following request. With data_state "all" the response metadata names the first date whose data is still incomplete. Queries the Search Console API: https://developers.google.com/webmaster-tools/v1/searchanalytics/query | Lecture seule |
| analyze_page_speed | Run PageSpeed Insights for a landing page — Lighthouse + real-user data. Returns the performance score (0-100), lab Core Web Vitals (LCP, CLS, TBT, FCP), CrUX field data from real Chrome users where available (p75 LCP/INP/CLS/FCP/TTFB + FAST/AVERAGE/SLOW ratings), and the top improvement opportunities with estimated savings. When the page itself has too little traffic for field data, the origin-wide field data is returned instead, marked field.scope="origin". Typical input is an ad final_url: slow landing pages depress Quality Score and waste paid clicks. Takes 10-30s; that is normal for a Lighthouse run. PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/about | Lecture seule |
| list_merchant_accounts | List Google Merchant Center accounts the connected user can access. Returns each account's numeric ID, name and whether it is a test account. Provides the account_id used by get_merchant_feed_health; not needed when merchant.account_id is set in the config. Merchant API: https://developers.google.com/merchant/api/overview | Lecture seule |
| get_merchant_feed_health | Merchant Center feed health — disapproved products + account issues. Disapproved feed items silently starve Shopping and Performance Max campaigns; this reports approved/pending/disapproved counts per reporting context (Shopping ads, free listings, ...), the top product issues by affected products (with documentation links), and account-level issues — CRITICAL ones stop offers serving entirely. Product-status data lags reality by ~30 minutes. Merchant API: https://developers.google.com/merchant/api/overview | Lecture seule |
| get_merchant_product_issues | The products behind the feed-health counts, each with its issues. Lists products by status with offer id, title, brand, click potential and every item issue: its code, the attribute it concerns, severity per reporting context with the affected countries, and whether the merchant has to act or Google is still processing. Products with high click potential come first, because fixing them recovers the most traffic. issues_by_code counts the products per issue. Data lags feed changes by about 30 minutes. Merchant API: https://developers.google.com/merchant/api/overview | Lecture seule |
| list_accounts | List accessible Google Ads accounts. Returns account names, IDs, status, and whether each is a manager account. When more accounts exist than `limit`, the response has 'truncated: true'; a much higher limit (e.g. list_accounts(limit=1000)) returns the full list. Workflows that target a specific account need no enumeration at all: get_campaign_performance, run_gaql, etc. take customer_id directly. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_campaign_performance | Get campaign-level performance metrics for a date range. Returns campaign name, status, type, impressions, clicks, cost, conversions, CPA, ROAS, CTR for each campaign, plus Search impression share and the share lost to budget and to ad rank (fractions with matching *_pct percentages; null for campaigns that do not serve on Search or had no impressions). Insights flag converting campaigns that lose a significant share of impressions to budget. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_ad_performance | Get ad-level performance data including headlines, descriptions, and metrics. Returns ad type, headlines, descriptions, final URL, impressions, clicks, CTR, conversions, cost for each ad, plus its policy approval status, review status and policy topic names. Disapproved and limited-by-policy ads are listed under policy_issues with their spend. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_keyword_performance | Get keyword metrics including quality scores and competitive data. Returns keyword text, match type, quality score, impressions, clicks, CTR, CPC, conversions for each keyword. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_search_terms | Get search terms report — what users actually typed before clicking your ads. Critical for finding negative keyword opportunities and understanding user intent. Returns search term, campaign, ad group, impressions, clicks, conversions. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_negative_keywords | List existing negative keywords for a campaign or all campaigns. Shows the existing negatives, which reveals duplicates before new negative keywords are added. Returns each negative's campaign, keyword text, match type, and a resource_id ("campaignId~criterionId") as taken by remove_entity, plus the total count. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_negative_keyword_lists | List all shared negative keyword lists (SharedSets) in the account. Returns each list's ID, name, status, and keyword count. Useful before propose_negative_keyword_list: a suitable list may already exist and just need attaching to a campaign. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_negative_keyword_list_keywords | List the keywords inside a shared negative keyword list. Returns each negative keyword's text, match type, and a resource_id ("sharedSetId~criterionId"), with the total keyword count. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_negative_keyword_list_campaigns | List which campaigns a shared negative keyword list is attached to. Returns each list-to-campaign attachment with the list and campaign IDs and names. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_recommendations | Retrieve Google's auto-generated recommendations with estimated impact. Returns each recommendation's ID, type, associated campaign/ad group, current (base) and projected (potential) metrics, and the estimated improvement. Includes insights that flag budget-increase recommendations (their projected gain comes from spending more) and highlight high-impact suggestions. The `recommendation.id` is what draft_dismiss_recommendations takes. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_dismiss_recommendations | Dismiss Google Ads recommendations — returns a PREVIEW. Turns down recommendations you will not take (e.g. "add broad match" on a deliberately narrow account) so they stop reappearing in get_recommendations. Nothing in the account changes, and Google can show a dismissed recommendation again later, so a single confirmation is enough. Each ID must be an active recommendation: unknown or already dismissed IDs are refused by name. The preview lists each one's type, campaign and estimated improvement, so the user sees what they are turning down. DismissRecommendation has no validate-only mode: the dry run re-reads the account and checks every recommendation is still active instead of sending the call to Google. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| get_recommendation_subscriptions | List the recommendation types Google applies automatically (auto-apply). A subscription makes Google apply every new recommendation of its type without asking, so changes reach the account with no preview. Returns each subscription's type, status (ENABLED or PAUSED), create_date_time and modify_date_time. A type that is not listed is not auto-applied. insights[] names every ENABLED type and flags one modified in the last 30 days, so a recurring audit can catch auto-apply being switched on. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_recommendation_subscriptions | Pause auto-apply for recommendation types — returns a PREVIEW. Pausing is the only change this tool can make: it sets each type's subscription to PAUSED, so Google stops applying those recommendations on its own. Their recommendations still appear in get_recommendations. Re-enabling auto-apply is deliberately not supported; it lets Google change the account without a preview, so it stays a decision for the Google Ads UI. Pausing reduces automation, so a single confirmation is enough. Each type must have an ENABLED subscription (see get_recommendation_subscriptions); a type with none, or one already paused, is refused by name. The dry run sends the request to Google with validate_only. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| get_pmax_performance | Get Performance Max campaign and asset group performance. Returns two result sets. campaigns: PMax campaign metrics broken down by ad_network_type (SEARCH, CONTENT, YOUTUBE_SEARCH, YOUTUBE_WATCH, MIXED). MIXED is a catch-all that Google uses for most PMax traffic — full channel splits are not available via the API. asset_groups: per-asset-group metrics including ad_strength (EXCELLENT, GOOD, AVERAGE, POOR). Includes insights flagging weak ad strength, zero-conversion asset groups, and network type distribution. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_pmax_assets | List the assets of Performance Max campaigns with type, status and content. Returns each asset's field_type (HEADLINE, DESCRIPTION, MARKETING_IMAGE, YOUTUBE_VIDEO, etc.), primary_status (ELIGIBLE, NOT_ELIGIBLE, PAUSED, PENDING), and content (text or image URL), plus by_status and by_field_type summaries. Per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. get_detailed_asset_performance reports which asset combinations Google selects most — the closest proxy for individual asset quality. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_detailed_asset_performance | Get top-performing asset combinations for Performance Max campaigns. Shows which headline + description + image combinations Google selects most often. Returns each combination with the assets used and their field types. This data helps identify which creative elements work well together. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_audience_performance | Get audience segment performance metrics. Returns performance by audience type — remarketing lists (USER_LIST), in-market segments (USER_INTEREST), affinity, demographics (AGE_RANGE, GENDER), etc. Shows display_name, impressions, clicks, cost, conversions, CTR, and CPC for each audience. Works for campaigns with explicit audience targeting (Search, Display). PMax audience targeting is automatic and may not appear in this report. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_demographic_targeting | List demographic targeting criteria (age, gender, parental status, income). Takes exactly one of ad_group_id or campaign_id. Returns each criterion's value, whether it's negative (excluded) or positive (narrowing), status, and a remove_id (composite resource ID) that can be passed directly to remove_entity with entity_type='ad_group_criterion' or 'campaign_criterion'. By default, Google Ads serves ads to ALL demographic segments — a criterion only appears here once a segment has been actively excluded or narrowed. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_change_history | List recent account changes: who changed what, when, and through which tool. Answers "what changed before the drop?". Returns each change newest first with its time, the user's email, the client it came through (Google Ads UI, API, Google Ads scripts, Editor, automated rules, auto-applied recommendations, ...), the changed resource type, the operation (CREATE, UPDATE, REMOVE), the changed field paths, and the campaign and ad group names. Also returns counts by resource type, client, user and day, plus insights on auto-applied recommendations and budget or bidding changes. Google Ads keeps change history for 30 days, so older start dates are moved to the earliest available day. Reads the change_event resource: https://developers.google.com/google-ads/api/docs/change-event | Lecture seule |
| analyze_campaign_conversions | Campaign clicks → GA4 conversions mapping — the real cost-per-conversion. Combines Google Ads campaign metrics with GA4 session/conversion data to reveal click-to-session ratios (GDPR indicator), compare Ads-reported vs GA4-reported conversions, and compute cost-per-GA4-conversion. Also returns non-paid channel conversion rates for comparison context. GA4 conversions are the property's key events (GA4 metric keyEvents). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| landing_page_analysis | Analyze which landing pages convert and which don't. Combines ad final URLs with GA4 page-level data. Returns paid traffic sessions, conversion rates, bounce rates, and engagement per landing page, and identifies pages that get ad clicks but zero conversions and orphaned URLs. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| attribution_check | Compare Ads-reported conversions vs GA4 — find tracking discrepancies. Checks whether conversions reported by Google Ads match what GA4 records, diagnoses GDPR consent gaps, attribution model differences, and missing conversion event configuration. Returns both sides' totals with the discrepancy and diagnostic insights. GA4 conversions are the property's key events (GA4 metric keyEvents). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_conversion_tracking_setup | Set up conversion tracking from GA4 into Google Ads in one approved plan, returning a PREVIEW of only the missing steps. Use it when the user wants their conversions (sign-ups, purchases, leads) tracked and used for bidding, or after audit_ga4_property or check_key_event_imports found a gap. It reads both products and plans what is missing, in order: link the GA4 property to the Google Ads account, mark the events as GA4 key events, turn on auto-tagging, import the conversion actions Google Ads created for the key events (they start hidden and record nothing), make them primary, and use their goal for bidding. Steps already in place are listed under already_done. Google Ads creates the conversion action for a newly linked property or new key event by itself, not instantly: such events come back as "After this" warnings, and running the tool again later imports them. NO_CHANGE when everything is set up. The website must send the events; this tool cannot add tracking code (see generate_tracking_code). Nothing changes until confirm_and_apply applies it: the dry run validates the Google Ads steps with validate_only and re-reads the GA4 ones, and every step skips itself if already done, so confirming again after a failed step continues where it stopped. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| check_key_event_imports | Check that every GA4 key event reaches Google Ads: imported, used for bidding, and actually receiving conversions. Matches the property's key events with the Google Ads conversion actions that import them (by GA4 property and event name), and compares GA4's key events from Google Ads traffic (google / cpc) with the conversions Google Ads recorded for each import. insights[] names key events no conversion action imports, imports that are only secondary (reported, not bid on), imports that stay at zero while GA4 counts Google Ads conversions (a broken link or auto-tagging), and imports of events that are no longer key events. Imports from other GA4 properties are listed separately. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| audit_event_coverage | Three-way audit: codebase events ↔ GTM tags ↔ GA4 actual fires. Fetches the LIVE GTM container, joins it against GA4 event counts for the date range, and returns a per-event matrix with one of these statuses: ok — tag active and event firing ok_auto_collected — GA4 Enhanced Measurement event, no tag needed no_tag_no_fire — codebase event, no GTM tag, never fires tag_paused — GTM tag exists but is paused tag_active_but_not_firing — tag is active but no GA4 hits gtm_only_firing — GA4 event from a tag, not in codebase gtm_paused_but_firing — only paused tag(s), not in codebase, yet GA4 still fires (event comes from elsewhere) gtm_only_not_firing — tag exists, not in codebase, no fires ga4_only — fires in GA4, no tag, no codebase ref ga4_fires_no_tag — codebase event firing without a GTM tag auto_event_only — Enhanced Measurement event with no codebase ref The result also lists dynamic-event tags ({{Event}} variables) and Custom HTML tags that the audit cannot interpret automatically. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_accounts | List all GTM accounts the AdLoop service account / OAuth user can read. The first-time discovery step: provides the account_id that audit_event_coverage takes. Returns each account's ID and name. An empty list means the service account hasn't been added to any GTM container with at least Read permission. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_containers | List all containers under a GTM account. Returns container_id (the numeric ID needed by audit_event_coverage), public_id (the GTM-XXXXXXX string shown in the UI), name, and usage context (web / iOS / Android / amp / server). Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_tags | List every tag in the LIVE GTM container, or in one workspace. Each tag includes type, status, parsed parameters, the GA4 event name (for GA4 event tags), and resolved firing/blocking trigger names. Complements audit_event_coverage for inspecting specific tags. With workspace_id the list shows that workspace's unpublished state, so a just-drafted tag is visible; `source` says which state was read. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| get_gtm_tag | Get the full RAW configuration for a single GTM tag. Includes every parameter, firing/blocking triggers (with their filter conditions resolved to text), priority, pause status, sampling, and monitoring metadata. Suited to inspecting a tag flagged by audit_event_coverage. An unknown tag_id returns an error with the available tag IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_triggers | List every trigger in the LIVE GTM container, or in one workspace. Each trigger has its filter conditions parsed to readable text (e.g. "{{Page Path}} matches RegExp ^/service-promotions/"). Helps diagnose why a tag fires or doesn't fire on specific pages. With workspace_id the list shows that workspace's unpublished state. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| get_gtm_trigger | Get the full RAW configuration for a single GTM trigger. Includes filters, auto-event filters, custom-event filters, validation settings, and a list of every tag that uses this trigger. Helps diagnose why a tag with a specific trigger ID does or doesn't fire. An unknown trigger_id returns an error with the available trigger IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_variables | List GTM variables — both custom and enabled built-in. Without workspace_id both come from the live container version (the Default Workspace supplies the built-ins only when the live version lists none; built_in_source names where they came from). With workspace_id both come from that workspace's unpublished state. Variables matter because triggers reference them: if a trigger uses {{Form ID}} but Form ID isn't enabled, the trigger never matches. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_workspaces | List workspaces (drafts) under a GTM container. Returns each workspace's ID, name and description; the IDs are what `get_gtm_workspace_diff` takes. Most containers have a single Default Workspace; multiple workspaces appear when the team uses parallel drafts. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| get_gtm_workspace_diff | Show drafted-but-not-published changes in a GTM workspace. Returns the list of entities (tags, triggers, variables) added, modified, or deleted relative to the live published version, plus any merge conflicts. Common cause of "I edited a tag but nothing happened" — the workspace was never published. is_clean=true means no pending changes and no conflicts. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| list_gtm_versions | List GTM container version headers (newest first). Version headers include version_id, name, archived flag and entity counts. The Tag Manager API returns no creation or publish time and no author for a version, and does not mark which versions were published; get_gtm_version returns a version's notes and get_gtm_version_diff what changed between two versions. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| get_gtm_version | Get metadata + entity counts for a single GTM container version. Returns name, description (the version notes), fingerprint, and lists of tag/trigger/variable names at that point in time. The API returns no timestamps or author for a version. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| get_gtm_version_diff | Compare two GTM container versions: what a publish changed. Returns added, removed and changed tags, triggers and variables (with names, types and the changed fields; parameters and trigger conditions are diffed key by key), plus built-in variables enabled or disabled. By default compares the live version with the version created before it. The Tag Manager API does not mark which versions were published, so that default "before" version may never have been live. Makes two or three Tag Manager API calls. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Lecture seule |
| draft_gtm_tag | Draft creating or updating a Tag Manager tag — returns a PREVIEW. Without tag_id this creates a tag in a workspace; with tag_id it updates the existing tag. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set, and Custom HTML (html) is refused as well unless gtm.allow_custom_html is set. Returns the resolved workspace, the tag type, the fields that would change and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| draft_gtm_trigger | Draft creating or updating a Tag Manager trigger — returns a PREVIEW. Without trigger_id this creates a trigger in a workspace; with trigger_id it updates the existing one. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set. Returns the resolved workspace, the trigger fields that would change and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| draft_gtm_variable | Draft creating or updating a Tag Manager variable: returns a PREVIEW. Without variable_id this creates a variable in a workspace; with variable_id it updates the existing one. Data Layer Variables, the usual source for GA4 ecommerce values, take data_layer_key (e.g. "ecommerce.value") instead of raw parameters. Tags and triggers use a variable as {{name}}; renaming one they reference is refused, because the references would break (the GTM UI renames safely). Custom JavaScript variables run code on the site and are refused unless gtm.allow_custom_html is set. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| draft_delete_gtm_entity | Draft deleting a Tag Manager tag, trigger or variable — returns a PREVIEW. The entity is removed from a workspace and stays on the site until the workspace is published. A trigger that any tag still references, or a variable that a tag, trigger or other variable uses as {{name}}, is refused up front, with the references named. Refused unless gtm.write_enabled is set. Returns the entity that would be deleted, the resolved workspace and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| draft_publish_gtm_workspace | Draft publishing a Tag Manager workspace LIVE — returns a PREVIEW. Every pending change in the workspace goes live, including changes other people made in the GTM UI; the preview lists them all. Apply refuses when the workspace changed after the preview, has merge conflicts, or reports compiler errors in a quick preview, and it refuses a Custom HTML tag being added or changed while gtm.allow_custom_html is off. Refused unless gtm.write_enabled is set. Returns the pending changes, the version that is live now (for a one-step rollback), the version name that would be created and a plan_id. That gate matches the tag type html; a Custom JavaScript variable or a custom template tag (cvt_…), which can inject a script, is not covered and needs review in the GTM UI. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| draft_rollback_gtm_version | Draft republishing an older Tag Manager version LIVE; returns a PREVIEW. A rollback publishes an existing container version again. The preview diffs the live version against the target, so it lists every tag, trigger and variable that changes on the site, and it pins the live version: apply refuses when another version went live after the preview, or when the target was modified or archived. Workspaces are not changed. Refused unless gtm.write_enabled is set, and refused when the target adds or changes a Custom HTML tag while gtm.allow_custom_html is off. Returns the diff, previous_live_version_id (the version that restores today's state), the target version and a plan_id. Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2 | Action |
| run_gaql | Execute an arbitrary GAQL (Google Ads Query Language) query. For queries beyond the dedicated report tools. Returns the result rows in the requested format with the query echoed back; cost fields stay in raw micros (cost_micros / 1,000,000 = account currency). A failing query returns an error with a hint. Queries the Google Ads API. GAQL syntax and fields: https://developers.google.com/google-ads/api/docs/query/overview | Lecture seule |
| get_audience_lists | The account's own audiences: remarketing and customer lists, custom segments, combined segments. Each user list comes with its type, membership status (OPEN or CLOSED), size for Search and Display, eligibility and membership duration; custom and combined segments with their id and description. Insights flag lists below the 100 active users Search needs and closed lists. Use the ids with draft_audience_attachment; for Google's in-market and affinity segments use search_audience_segments. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| search_audience_segments | Find Google's in-market and affinity segments by name, with the segment_id to attach. In-market segments are people actively researching a purchase; affinity segments are long-term interests. Matching is on the segment name, in English, e.g. "running", "insurance", "travel". Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_audience_targeting | Audiences attached to one campaign or ad group, its exclusions, and the audience mode. audience_mode is "observation" (audiences only adjust bids and report), "targeting" (ads only reach the audiences) or "not set". Every audience and exclusion carries a remove_id for remove_entity (entity_type "campaign_criterion" or "ad_group_criterion"). Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_audience_attachment | Draft attaching audiences to a campaign or ad group as observation, targeting or exclusion: returns a PREVIEW. Observation (the default) keeps the reach: the audiences adjust bids and show up in reports. Targeting narrows delivery to the audiences and needs a double confirmation. Exclusions keep the people out and leave the mode alone. The draft refuses combinations Google does not allow (custom segments on Search, combined segments outside Search, audiences at both campaign and ad group level) and lists that cannot serve; Performance Max is refused with a pointer to draft_asset_group_signals. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| get_shopping_product_performance | Spend, clicks, conversions, CPA and ROAS per product across Shopping and Performance Max. Each product (item id) is summed over the campaigns it ran in. Returns the account totals, the top products by spend, and the products that spent without a conversion, with insights on what to do with them. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_asset_group_signals | Search themes and the audience signal of a Performance Max asset group, plus the account's audiences. Returns each search theme and audience signal with its signal_id and approval status, the enabled audiences of the account that can become the group's audience signal (audience_id, name), and insights when a group has no themes or no audience signal. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_asset_group_signals | Draft adding search themes or an audience signal to a Performance Max asset group, or removing signals — PREVIEW. Signals are hints that steer Performance Max, not targeting. A group has at most one audience signal and up to 50 search themes; replacing the audience means removing the current one in the same draft. Themes already on the group are skipped. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_pmax_product_exclusions | Draft which products a retail Performance Max asset group excludes — returns a PREVIEW. Sets the full list of excluded values on one product dimension (item id, brand or a custom label); everything else stays included. Pass the complete list each time: values left out are included again, and an empty list includes all products. Works on asset groups that advertise all products or are already split on that one dimension; more complex product filters are refused and stay a job for Google Ads. The filter is rebuilt in one atomic request. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_asset_group_assets | Draft adding and/or removing assets of a Performance Max asset group — returns a PREVIEW. Adds new text, image and YouTube assets and unlinks existing ones in one atomic request, so an asset is replaced without the group dropping below Google's minimums (3 headlines, 1 long headline, 2 descriptions, one of them at most 60 characters). Texts already in the group are skipped. Images are checked and sorted by aspect ratio; removed assets stay in the account's asset library. The preview lists the asset counts per type after the change. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_shopping_campaign | Draft a Standard Shopping campaign that advertises a Merchant Center feed — returns a PREVIEW. Creates the budget, the campaign (PAUSED), a product ad group with its Shopping ad, and one "All products" product group, in one atomic request. The Merchant Center account must be linked to the Google Ads account; the draft checks that. Shopping campaigns take no keywords and no language targeting (the feed's language applies). Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_campaign | Draft a full campaign structure — returns a PREVIEW, does NOT create anything. Creates: CampaignBudget + Campaign (PAUSED) + AdGroup + optional Keywords + geo targeting + language targeting + optional geo exclusions and ad schedule, all in one atomic request. Ads are NOT included — draft_responsive_search_ad adds them once the campaign exists. Only SEARCH campaigns can be created: Performance Max needs an asset group with all its assets in one request, and DISPLAY, SHOPPING and VIDEO need channel-specific settings and ad group types, so the draft refuses them. Returns a preview with a plan_id plus any warnings (e.g. a daily budget below 5x target CPA, MANUAL_CPC); nothing changes until confirm_and_apply applies the returned plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_ad_group | Draft a new ad group within an existing campaign — returns a PREVIEW, does NOT create. Creates an ad group (ENABLED, type SEARCH_STANDARD) in the specified campaign, optionally with keywords in the same atomic operation. Only SEARCH campaigns are supported. Ads are not included, so the ad group cannot serve until one of its ads is created and enabled. Returns a preview with a plan_id plus warnings (BROAD keywords on a non-Smart-Bidding campaign, a duplicate ad group name, a CPC bid that Smart Bidding ignores); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_campaign | Draft an update to an existing campaign — returns a PREVIEW, does NOT apply. Only the parameters passed are changed; omitted ones stay as they are, and at least one change is required. Replacing geo targets keeps the campaign's negative geo exclusions (the preview lists them) unless geo_exclude_ids is passed too. A budget change shows the current amount; when the budget is shared with other campaigns, the preview names them and needs a double confirmation, because the new amount covers all of them. A bidding change on a campaign in a portfolio bid strategy takes it out of the portfolio, also with a double confirmation. Returns a preview with a plan_id plus any warnings; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_responsive_search_ad | Draft a Responsive Search Ad — returns a PREVIEW, does NOT create the ad. The preview shows exactly what will be created; confirm_and_apply executes the returned plan_id. The ad is created PAUSED. final_url is checked for reachability first and an unreachable URL is refused. Several headlines may pin to the same position (Google rotates them there) as long as every position stays fillable, by an asset pinned to it or by a distinct unpinned one. Mixed plain-string and dict entries are allowed within a single call (e.g. brand pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8 headlines or 3 descriptions. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_responsive_search_ad | Update mutable fields on an existing RSA in place — returns a PREVIEW. Edits an existing RSA without creating a new ad; the ad keeps its ID. Google Ads API v23 (``AdService.MutateAds``) permits in-place mutation of ``final_urls``, ``path1``, ``path2``, ``headlines``, and ``descriptions``. At least one mutation must be requested. IMPORTANT: replacing headlines or descriptions is NOT a free in-place edit. Even though the ad ID is preserved, swapping the creative text RESETS the ad's asset-combination learning and performance history and sends the ad BACK THROUGH Google policy review — Google treats the creative as new for optimization. URL-only and path-only edits do not incur this. When headlines/descriptions change, the returned preview includes a ``warnings`` entry stating this trade-off before anything is applied. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_keywords | Draft keyword additions — returns a PREVIEW, does NOT add keywords. Returns a preview with a plan_id, plus a warning when BROAD keywords go into a campaign without Smart Bidding; nothing changes until confirm_and_apply applies the returned plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| get_custom_conversion_goals | Read the custom conversion goals and the campaign goal configuration. Returns every custom goal with its name, status and conversion actions, plus — optionally for one campaign — the goal config the campaign uses (`goal_config_level` CUSTOMER or CAMPAIGN and the assigned custom goal). A custom conversion goal bundles conversion actions into a named set that a campaign can be pointed at. Ahead of drafting, this shows which goals exist, which actions they contain and what a campaign currently uses. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_custom_conversion_goal | Create a custom conversion goal — returns a PREVIEW. The goal bundles conversion actions into a named set that campaigns can then be pointed at with draft_assign_custom_conversion_goal. Only the goal is created: conversion actions are read for validation and never modified. It is always created ENABLED — a goal created as REMOVED would be invisible to every other tool, so there is nothing to plan. If a goal with the same name and exactly the same conversion actions already exists, nothing is planned and the result says `already_exists` with that goal's ID (REMOVED goals do not count). A name that exists with different actions is changed with draft_update_custom_conversion_goal. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_update_custom_conversion_goal | Rename and/or re-scope an existing custom conversion goal — PREVIEW. conversion_action_ids REPLACES the whole action list, it does not append. An empty parameter stays unchanged. The preview shows the action list before and after. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_assign_custom_conversion_goal | Point a campaign at a custom conversion goal — returns a PREVIEW. Sets goal_config_level=CAMPAIGN and the goal on that campaign's conversion goal config. Nothing else changes: conversion actions, bidding, budgets and the account-level goals stay as they are. A campaign must have at least one goal configured when it switches to campaign level — Google answers EMPTY_CONVERSION_GOALS otherwise. That is why this tool assigns a goal instead of clearing goals; draft_clear_custom_conversion_goal goes back to the account level. If the campaign already uses exactly this goal, nothing is planned and the result says `already_configured`. The preview carries a note that changing what a campaign optimises for restarts its Smart Bidding learning period. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_clear_custom_conversion_goal | Put a campaign back on the account-level goals — returns a PREVIEW. Sets goal_config_level=CUSTOMER and clears the custom goal: the rollback for draft_assign_custom_conversion_goal. The account-level goals themselves are not touched. The returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| add_negative_keywords | Draft negative keyword additions — returns a PREVIEW. Negative keywords prevent your ads from showing for irrelevant searches. They are added at campaign level. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| add_negative_locations | Draft negative geo location additions — returns a PREVIEW. Excludes cities/regions from a campaign while keeping broader positive targets such as State of Sao Paulo. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| propose_negative_keyword_list | Draft a shared negative keyword list and attach it to a campaign — returns a PREVIEW. Creates a reusable negative keyword list (shared set) that can later be applied to multiple campaigns, whereas add_negative_keywords adds negatives directly to one campaign. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| add_to_negative_keyword_list | Append keywords to an EXISTING shared negative keyword list — returns a PREVIEW. Adds terms to a list that already exists (propose_negative_keyword_list creates a new list instead); get_negative_keyword_list_keywords shows the terms already in a list. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| attach_shared_set_to_campaigns | Attach an existing shared set to one or more campaigns — returns a PREVIEW. Creates CampaignSharedSet linkages so the campaigns inherit the shared set's criteria (e.g. negative keywords). Most commonly used to attach a shared negative keyword list to newly-built campaigns; get_negative_keyword_list_campaigns lists existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| detach_shared_set_from_campaigns | Detach a shared set from one or more campaigns — returns a PREVIEW. Removes CampaignSharedSet linkages so the campaigns no longer inherit the shared set's criteria. The shared set itself is unchanged; only the per-campaign attachment is removed. get_negative_keyword_list_campaigns lists the existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| get_ai_max_settings | Read the AI Max controls of Search campaigns, per campaign and ad group. Returns for every campaign: id, name, status, advertising channel type, campaign.ai_max_setting.enable_ai_max, campaign.ai_max_setting.bundling_required (output only) and the full campaign.asset_automation_settings list. Each campaign also carries its non-REMOVED ad groups with ad_group.ai_max_ad_group_setting.disable_search_term_matching. Shows the current state ahead of draft_ai_max_settings, and what the account actually looks like after confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_campaign_settings | Read every setting that decides how far a Search campaign reaches, in one call. Returns one flat record per campaign: status, bidding strategy and its target or CPC ceiling, daily budget and whether it is shared, the Google Search / search partner / Display network flags, the location option (positive_geo_target_type) and its negative counterpart, campaign-level broad match (keyword_match_type), the tracking template, final URL suffix and custom parameters, and the AI Max state get_ai_max_settings reports (enable_ai_max, asset automation per type). Money is in the account currency (`currency`). Each campaign lists its `widening_settings`: search partners or Display on, a presence-or-interest location option, broad match on, AI Max on, an automation opted in. `insights[]` names the campaigns that have any. Made for recurring audits: the same call every week diffs cleanly. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| draft_ai_max_settings | Draft AI Max controls for a Search campaign — returns a PREVIEW. AI Max is the container that makes brand exclusions usable in Search: Google rejects a brand list on a plain Search campaign ("For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns"). Turning AI Max on while leaving its automations running is the trap, so both belong to the same plan. An automation the caller never mentioned is refused outright (the plan says which switch to pass); one named explicitly (disable_search_term_matching=False, text_asset_automation="OPTED_IN") is planned with requires_double_confirm=True, because switching to AI Max with its automations is a real configuration some accounts want. Reads the campaign and its ad groups first, so the preview names concrete ad groups and shows current values per knob. Returns a preview with a plan_id; nothing is written until confirm_and_apply runs. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_prepare_brand_exclusions | Draft the safe standard state for brand exclusions — returns a PREVIEW. Exactly one combination, nothing else: enable_ai_max = true, disable_search_term_matching = true (all non-removed ad groups), TEXT_ASSET_AUTOMATION = OPTED_OUT and FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION = OPTED_OUT. No bidding, keyword, match type, ad, URL or budget change, and no brand list is attached — attaching stays a separate step with propose_brand_list / attach_brand_list_to_campaigns once this state is verified in the account. Returns a preview with a plan_id (purpose brand_exclusions); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_demographic_targeting | Draft demographic targeting (age/gender/parental status/income) — returns a PREVIEW. By default, Google Ads serves to all demographic segments. This tool adds criteria that EXCLUDE a segment (negative=True, default) or NARROW targeting to it (negative=False — uncommon). Takes exactly one of ad_group_id or campaign_id, and at least one of the four demographic lists must contain a value. Returns a preview with a plan_id, plus warnings when the change narrows targeting, excludes 'undetermined' users, or excludes nearly a whole dimension; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_ad_group | Draft an ad group update for name and/or manual CPC bid — returns a PREVIEW. A bid change applies only when the campaign uses MANUAL_CPC: automated bidding strategies ignore ad-group CPC bids, so such a change is refused (for Maximize Clicks the campaign cpc_bid_ceiling, set through update_campaign, is the active constraint). Bid increases above the configured safety.max_bid_increase_pct are refused. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_callouts | Draft callout assets for an ad group, a campaign or the account — returns a PREVIEW. Creates callout assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking (every campaign without callouts of its own) needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_structured_snippets | Draft structured snippet assets for an ad group, a campaign or the account — returns a PREVIEW. Creates structured snippet assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_call_asset | Draft a call asset (a phone number shown with the ads) — returns a PREVIEW. Creates the call asset and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Google reviews the number before it serves. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_call_asset | Draft changing a call asset in place — returns a PREVIEW. Only the fields passed change. The asset keeps its ID and its links, so the change shows everywhere it is linked. The preview shows the current values and pins them; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| add_ad_schedule | Draft ad schedule windows for a campaign — returns a PREVIEW. Adds the windows; existing ones stay. The preview lists the current windows (each with the remove_id that remove_entity takes as a campaign_criterion) and the account time zone the hours are in. Overlapping windows and more than six a day are refused. A campaign without any window serves at all hours, so its first windows restrict it to them: that preview needs a double confirmation. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_promotion | Draft a promotion asset ("20% off winter tyres") — returns a PREVIEW. Creates the promotion and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. The final_url is checked for reachability. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_promotion | Draft changing a promotion asset in place — returns a PREVIEW. Only the fields passed change; everything else stays as it is. The asset keeps its ID and history, and the change shows everywhere it is linked. Passing money_off replaces a percent_off (and the other way round); passing promotion_code replaces an orders_over_amount (and the other way round). The preview shows old and new values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_price_asset | Draft a price asset (the row of prices under an ad) — returns a PREVIEW. Creates a price asset with 3-8 offerings and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Every offering URL is checked for reachability. Google disapproves prices that differ from the landing page. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_business_name_asset | Draft a business name asset for a campaign or the account — returns a PREVIEW. Creates a text asset and links it as the business name shown with the ads. Google links business names at campaign or account level only. Account-wide needs scope="account" and no campaign_id. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| link_asset_to_customer | Draft linking existing assets at account level — returns a PREVIEW. Account-level assets serve on every eligible campaign that has no asset of the same type linked at campaign or ad-group level. Each asset is checked to exist and to match its field type. Returns a preview with a plan_id. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_callout | Draft changing a callout asset in place — returns a PREVIEW. Only what is passed changes. The asset keeps its ID and performance history, and the change shows everywhere it is linked. The preview pins the current values; if someone edits the asset in Google Ads before the apply, nothing is sent. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_sitelink | Draft changing a sitelink asset in place — returns a PREVIEW. Only the fields passed change; empty fields stay as they are. The asset keeps its ID and performance history everywhere it is linked. A new final_url is checked for reachability. The preview pins the current values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| update_structured_snippet | Draft changing a structured snippet asset in place — returns a PREVIEW. Replaces the snippet's values (and header, if given). The asset keeps its ID and performance history everywhere it is linked. The preview pins the current header and values; an edit in Google Ads before the apply stops it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_image_assets | Draft image assets from local files, public image URLs or uploads — returns a PREVIEW. At least one image in total is required across image_paths, image_urls and upload_ids. Images must be PNG, JPEG or GIF and at most 5120 KB (Google's limit). URL images are downloaded now and checked; applying re-downloads them and refuses if the image changed since the preview. Returns a preview with a plan_id and a per-image summary; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| pause_entity | Draft pausing a campaign, ad group, ad, or keyword — returns a PREVIEW. Pausing is reversible with enable_entity. Returns a preview with a plan_id (target status PAUSED); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| enable_entity | Draft enabling a paused campaign, ad group, ad, or keyword — returns a PREVIEW. Returns a preview with a plan_id (target status ENABLED); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| remove_entity | Draft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE. Removed entities cannot be re-enabled; pause_entity is the reversible way to temporarily disable something. Returns a preview with a plan_id and requires_double_confirm=true; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_sitelinks | Draft sitelink extensions for a campaign or the account — returns a PREVIEW. Sitelinks appear as additional links below your ad, increasing click area and directing users to specific pages. Every final_url is fetched and an unreachable URL (HTTP 4xx/5xx) blocks the draft. Google recommends at least 4 sitelinks per campaign; fewer than 2 may not show. Returns a preview with a plan_id and any warnings; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| confirm_and_apply | Execute a previously previewed change. IMPORTANT: Defaults to dry_run=True (validate only). Only an explicit dry_run=false applies the change to the ad account (Google Ads or Reddit Ads — the plan knows which platform it targets). Forced dry runs: when real changes are switched off (live changes off for the workspace in AdLoop Cloud, or safety.require_dry_run in a self-hosted config), dry_run=false is IGNORED and the result is still DRY_RUN_SUCCESS, with 'dry_run_forced_by' and 'remediation' fields. 'remediation' says how the user switches that setting; until it is changed, repeated calls with dry_run=false change nothing. Two-phase apply: if 'safety.two_phase_apply: true' is set (always on for AdLoop Cloud tenants), dry_run=false is REFUSED with status DRY_RUN_REQUIRED until this plan_id has completed one dry_run=true pass. The sequence is: dry run, review of its result, then the real apply. Google Ads plans: the dry run sends the exact mutates to Google with validate_only=True, so Google checks the change and executes nothing (`checks` counts the validated calls). Steps that build on an object an earlier step would create cannot be validated and are counted as skipped. Reddit plans: Reddit has no validate-only mode, so the dry run re-reads the target entity and re-checks the safety caps (returned as `checks`). A DRY_RUN_FAILED result means the change does not go through as previewed. The real apply fails the same way, unless Google rejected only part of the request: then it carries out the rest and reports those operations again. Returns a status with the plan_id and operation: DRY_RUN_SUCCESS, DRY_RUN_FAILED, DRY_RUN_REQUIRED, BLOCKED, APPLIED, PARTIAL_UPLOAD, PARTIAL_APPLY, UNKNOWN_OUTCOME or APPLY_IN_PROGRESS. BLOCKED means the operation was added to safety.blocked_operations after the draft: nothing ran and the plan stays pending. APPLIED results carry the created or changed resource names under 'result'. PARTIAL_UPLOAD belongs to the upload tools: the batches it lists are already in the account, so the plan is retired. 'sent_total', 'accepted_total', 'rejected_total' and 'resume_from_line' say how far the upload got and at which CSV line a new draft continues; when a batch's fate is unknown, 'unknown_status', 'uncertain_lines' and 'row_errors' name the rows whose outcome has to be checked first. PARTIAL_APPLY and UNKNOWN_OUTCOME come from platforms without transactional writes: part of the change is in the account ('created' names it), or a create was never answered. The plan is retired; read the account back and draft only what is missing. APPLY_IN_PROGRESS means an earlier call claimed this plan first, so this call executed nothing. Approval cards: in AI apps that show AdLoop's approval card with the preview, dry_run=false is REFUSED with status APPROVE_ON_CARD, because only the user's click on the card applies the change. Dry runs still work. The workspace owner can allow approval in chat as well. Confirmation dialogs: in apps that show dialogs instead, dry_run=false first asks the user in a dialog. A declined dialog returns NOT_CONFIRMED; an app that receives the dialog but never answers it gets CONFIRMATION_UNANSWERED on the next call, with the ways out. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/ | Action |
| upload_images | Let the user upload images (PNG, JPEG, GIF up to 5 MB) for ad assets. For images without a public URL, such as a file on the user's computer or an image attached in the chat. An attached image cannot reach a tool, so the user drops the same file on the card. Apps that show AdLoop's cards display an upload card where the user drops the files; the card then posts the upload ids into the chat. On AdLoop Cloud in other apps the result carries an upload link for the user (or a coding agent, with curl). Uploads expire after a day. The ids go into upload_ids of draft_image_assets, or as "upload:<id>" into the image fields of draft_reddit_ad. Returns the current uploads and how to add more. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/ | Lecture seule |
| upload_conversion_csv | Let the user upload a conversion CSV for an offline conversion upload. For the CSV behind draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads when the file is not on the machine running AdLoop, as on AdLoop Cloud. Apps that show AdLoop's cards display an upload card where the user drops the .csv file; the card then posts the upload id into the chat. Other apps on AdLoop Cloud get an upload link for the user (or a coding agent, with curl). The file holds personal data (phone numbers, emails), so it is kept for two hours at most and deleted as soon as a draft has read it. Returns the CSV uploads waiting to be used and how to add one. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| list_uploads | List the files the user uploaded to AdLoop that have not expired. Returns each upload's upload_id, kind (image or csv), name, type, size, dimensions (images) or lines (CSVs) and hours until it expires: images last a day, conversion CSVs two hours or until a draft reads them. The ids of files the user sent through an upload link show up here. Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/ | Lecture seule |
| draft_key_event | Draft marking a GA4 event as a key event (conversion), or changing an existing one — returns a PREVIEW. The fix for "the event fires but isn't tracked as a conversion": attribution_check / validate_tracking diagnose it, this closes the loop. When the event already is a key event, the plan changes its counting method or default value instead and the preview shows before and after; nothing to change returns NO_CHANGE. Applies to future data only. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_delete_key_event | Draft removing a GA4 key event so the event no longer counts as a conversion, returning a PREVIEW. The event itself keeps firing and stays in event reports; only its key-event status goes, for future data (key events already recorded are not reclassified). The draft resolves the event name against the property's key events (keyEvents.list), so the preview names the exact key event, its counting method and create time; an unknown name returns the existing key events, and one GA4 marks as not deletable is refused. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it (GA4 Admin API keyEvents.delete). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_ga4_annotation | Draft creating, changing or deleting a GA4 annotation (a note on a date or date range in GA4's charts), returning a PREVIEW. Use it to mark what explains a change in the data: a site relaunch, a price change, a campaign start, a tracking fix. Create needs title and date; update and delete need the annotation's ID from list_ga4_annotations, and an update changes only the fields passed (the preview shows before and after). Annotations Google created itself cannot be changed. Nothing changes until confirm_and_apply applies it; the dry run re-reads the annotation and refuses if it was changed in GA4 after the preview. GA4 Admin API v1alpha (reportingDataAnnotations). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_ga4_audience | Draft creating, renaming or archiving a GA4 audience — returns a PREVIEW. An audience is the users who sent certain events. A linked Google Ads account receives it as a remarketing list within one to two days, to attach to campaigns with draft_audience_attachment: this is how to build a list of site visitors, of buyers, or of visitors who did not buy. GA4 fixes the events and the membership duration at creation; afterwards only the name and description can change, and archiving is permanent (it needs a double confirmation). The draft refuses a taken name and a full property, and the preview warns when the property's audiences would not reach Google Ads (see list_ga4_audiences). Nothing changes until confirm_and_apply applies the plan_id. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_ga4_custom_dimension | Draft registering, changing or archiving a GA4 custom dimension, returning a PREVIEW. Registering makes an event parameter (EVENT scope), a user property (USER) or an ecommerce item parameter (ITEM) reportable as a dimension. Before anything reaches Google the draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the dimension only from now on and that parameter_name and scope cannot change later. Update changes display_name, description or (USER scope) disallow_ads_personalization; archive removes it from reports and frees the slot, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customDimensions). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_ga4_custom_metric | Draft registering, changing or archiving a GA4 custom metric, returning a PREVIEW. Registering makes a numeric event parameter reportable as a metric. The draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the metric only from now on. Update changes display_name, description, measurement_unit or restricted_metric_type; archive removes it from reports, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customMetrics). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_ga4_data_retention | Draft a change to how long GA4 keeps event- and user-level data, returning a PREVIEW. GA4 defaults to 2 months, which cuts explorations, funnels and other user-level reports short; standard properties allow 14 months, GA4 360 up to 50. Standard reports are aggregated and not affected. Lengthening applies from now on (data already deleted does not come back); shortening deletes older data for good and needs a double confirmation. The preview shows before and after and reminds the user that a privacy policy naming a retention period must match. NO_CHANGE when the settings already match. Nothing changes until confirm_and_apply applies it; the dry run re-reads the settings and refuses if they changed in GA4 after the preview. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 | Action |
| draft_create_conversion_action | Draft a new Google Ads ConversionAction — returns a PREVIEW. Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it. SMART_CAMPAIGN_* and GOOGLE_HOSTED types are auto-managed by Google and rejected with MUTATE_NOT_ALLOWED. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_update_conversion_action | Draft a partial UPDATE of an existing ConversionAction — returns PREVIEW. Only parameters passed non-empty/non-default are sent to the API. Covers renaming, demoting a Primary to Secondary, changing value, adjusting the call-duration threshold, changing attribution, or moving the action to another goal with category. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject mutations with MUTATE_NOT_ALLOWED at apply time. Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_remove_conversion_action | Draft a REMOVAL of a ConversionAction — returns a PREVIEW. Removal stops counting and drops the action from goal lists; historical data is preserved but the action is irreversible. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject removal with MUTATE_NOT_ALLOWED. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_upload_call_conversions | Draft an offline CALL-conversion upload from a CSV — returns a PREVIEW. Uploads call conversions via ConversionUploadService.UploadCallConversions, matching the call against the ad click by the caller's phone number. The CSV must have columns: Caller's Phone Number, Call Start Time, Conversion Name, Conversion Time, Conversion Value, Conversion Currency. The Conversion Name must match an existing UPLOAD_CALLS-type conversion action — verified against the account while drafting, so a typo fails here rather than after the upload. Optional `Ad User Data` and `Ad Personalization` columns carry consent per row. The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it. PII: the caller phone number is required RAW by Google (it cannot be hashed), so it lives in the plan's apply-only payload — the preview shows redacted ids and counts, the audit log and `plan.changes` show neither. Apply uploads exactly what you previewed (no CSV re-read). Phone numbers are normalized with libphonenumber semantics: a number carries no country code needs ``default_region``, an extension is dropped, and the German trunk marker in "+49 (0)89 …" is handled. Rows whose number stays unusable are skipped and reported in `skipped_rows` instead of being uploaded to no effect. Rows that repeat inside one file are named in `dedup_warnings`. A call upload has no dedup key at Google, so each of them still goes out as its own conversion — the warning is the only place that says so. Returns a preview with a plan_id, the row counts, the consent the rows actually carry (`consent_summary`) and the skipped rows; nothing is uploaded until that preview is confirmed. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| draft_upload_enhanced_conversions_for_leads | Draft an Enhanced Conversions for LEADS upload from a CSV — PREVIEW. Uploads lead conversions via ConversionUploadService.UploadClickConversions with user_identifiers, matching hashed customer PII back to the Google users who clicked the ads. The CSV holds RAW PII in columns: Email, Phone Number, First Name, Last Name (plus Conversion Name, Conversion Time, Conversion Value, Conversion Currency; optional Order ID dedup key, and optional `Ad User Data` / `Ad Personalization` consent columns). PII is normalized and SHA-256-hashed AT PREVIEW TIME — only the hashes are stored in the plan. Raw email/phone/name never land in the plan or the audit log. A cell that already is a SHA-256 hex digest (a CRM export that hashes before writing) is used as it is. The target conversion action must be UPLOAD_CLICKS-type. An Order ID column makes re-uploads dedup instead of double-counting. Rows that repeat inside one file are named in `dedup_warnings`. Rows sharing an Order ID count once at Google; two rows with different Order IDs are two real orders and are not reported. The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it. Returns a preview with a plan_id, the row counts, the consent the rows actually carry (`consent_summary`) and the skipped rows; nothing is uploaded until that preview is confirmed. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| validate_tracking | Compare tracking events found in the codebase against actual GA4 data. Takes the event names found in the codebase's gtag('event', ...) or dataLayer.push calls and checks which ones actually fire in GA4. Returns matched events with their GA4 counts, events missing from GA4, unexpected GA4 events, auto-collected events (page_view, session_start, etc.), insights on likely causes, and the date range. Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| generate_tracking_code | Generate a GA4 event tracking JavaScript snippet. Produces ready-to-paste gtag code for the specified event. Includes recommended parameters for well-known GA4 events (sign_up, purchase, etc.). Optionally checks GA4 to warn if the event already fires. Returns the javascript snippet, already_exists / existing_count from GA4, and notes (duplicates, marking it as a key event, GDPR consent). Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| estimate_budget | Forecast clicks, cost, and conversions for a set of keywords. Uses Google Ads Keyword Planner to estimate campaign performance without creating anything. Essential for budget planning before launching campaigns. Per-keyword max_cpc values are collapsed to a campaign-level manual CPC cap (the highest one) — the Ads API forecast takes no per-keyword bids. Returns estimated clicks, cost, avg CPC, conversions and avg CPA for the forecast period, daily estimates, and insights. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| discover_keywords | Discover new keyword ideas using Google Ads Keyword Planner. Mirrors the "Discover new keywords" UI in Keyword Planner: start with keywords (seed_keywords), start with a website (url), or both together for more targeted ideas. At least one of seed_keywords or url is required. Returns keyword ideas sorted by avg monthly search volume, with competition level (LOW/MEDIUM/HIGH) and top-of-page bid range, plus the seeds used and insights. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| suggest_brands | Resolve a brand name to the brands Google recognizes for it. Mirrors the brand picker in the Google Ads UI (BrandSuggestionService.SuggestBrands): takes a free-text name such as "EscapeGame München" or "NoWayOut" and returns the matching brands with their ID, display name, state, and associated URLs. The returned brand ID is the Commercial Knowledge Graph ID. Brand criteria — brand lists, brand exclusions — target that ID, not a display name, so a name is resolved here before it can go into a brand list. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| check_brand_names | Check a list of brand names against Google's brand knowledge graph. One SuggestBrands call per name, for the case where a shortlist has to be triaged instead of a single name resolved: which of these brands does Google know at all, and what is the ID of each? Returns checked / matched / no_match counts and one result per name with status "matched" (with a best-match brand plus all candidates) or "no_match" (empty candidate list — a normal answer, not an error). exact_match marks a candidate whose name matches the query apart from case and punctuation; anything else is a Google suggestion, not a guarantee. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_brand_lists | List all brand lists (SharedSets of type BRANDS) in the account. Returns each list's ID, name, status, and member count, plus the total — the basis for reusing an existing list with add_to_brand_list instead of duplicating it with propose_brand_list. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_brand_list_brands | List the brands inside a brand list. Returns the brands and their total. Each entry carries brand.entity_id (the Commercial KG MID that suggest_brands returns as id), the display name, primary URL, status and a criterion_id — the latter is what remove_from_brand_list needs. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| get_brand_list_campaigns | List which campaigns a brand list is attached to. Brand lists attach as CampaignCriterion rows of type BRAND_LIST (not as CampaignSharedSet like negative keyword lists). Returns each attachment's campaign ID, name and status, the criterion, and `role`: "excluded" when the criterion is negative, "targeted" when it restricts targeting to the list. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Lecture seule |
| propose_brand_list | Draft a brand list and optionally attach it to campaigns — returns a PREVIEW. Creates a SharedSet of type BRANDS, fills it with brands, and — when campaign_ids is given — attaches it to those campaigns. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| add_to_brand_list | Append brands to an EXISTING brand list — returns a PREVIEW. For a list that already exists and only needs more brands (propose_brand_list creates a new list instead). The shared_set_id comes from get_brand_lists; get_brand_list_brands shows the brands already in the list, which makes a brand that would be added twice visible. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| remove_from_brand_list | Remove brands from a brand list — returns a PREVIEW. SharedCriteria have no status field, so removal is the only way to take a brand out of a list — there is nothing to pause. Removing a brand does not detach the list from any campaign. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| attach_brand_list_to_campaigns | Attach an existing brand list to one or more campaigns — returns a PREVIEW. Creates a CampaignCriterion.brand_list per campaign. This is NOT the CampaignSharedSet linkage used for negative keyword lists — brand lists are criteria, and `negative` decides the role. The shared_set_id comes from get_brand_lists; get_brand_list_campaigns lists existing attachments. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
| detach_brand_list_from_campaigns | Detach a brand list from one or more campaigns — returns a PREVIEW. Removes the CampaignCriterion rows linking the list to those campaigns; the list itself and its brands are unchanged. get_brand_list_campaigns lists the existing attachments. Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply. Google Ads API: https://developers.google.com/google-ads/api/docs/start | Action |
Configuration
ADLOOP_TOOLSETS
| Nom | Description | Type |
|---|---|---|
| ADLOOP_TOOLSETS | — |
Vérifications automatisées
Exécuté le 16 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleklosk/adloop is public and reachablegithub.com/klosk/adloop ↗Réussi
- Le nom du package correspond au dépôt sourceadloop names klosk/adloop as sourcepypi.org/project/adloop/ ↗Réussi
- Provenance du build (attestation Sigstore)Sigstore attestation for adlooppypi.org/project/adloop/ ↗Réussi
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-16github.com/klosk/adloop ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from adloopRéussi
- Aucun avis critique dans le package ou ses dépendancesthe package checked; no critical advisoryosv.dev ↗Réussi
- Aucune instruction cachée destinée au modèle145 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésDestructive tools carry destructiveHintRéussi
- Le point de terminaison distant répond à la poignée de main MCPHTTPS endpoint answered 401 (sign-in required)Réussi
README
Voir sur GitHubAdLoop
The Google Ads MCP server for Claude, ChatGPT and Cursor.
Plus Reddit Ads, GA4 and your tracking code, with a preview before every change.
An MCP server that gives your AI assistant read + write access to Google Ads, Reddit Ads and GA4 — with safety guardrails that prevent accidental spend.
☁️ Skip the setup — use AdLoop Cloud (free plan, no card) · or self-host: pip install adloop
[!TIP] AdLoop Cloud is the hosted version of this project, with a free plan that needs no credit card. Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no API access application, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
📚 Documentation: docs.getadloop.com — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.
Cloud or Self-Hosted?
Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
| ☁️ AdLoop Cloud | 🛠️ Self-hosted (this repo) | |
|---|---|---|
| Setup | Connect Google in two clicks | ~5 min: own Google Cloud project + adloop init |
| Google Cloud project | Not needed | Required (free) |
| Ads API access | Not needed | Granted to your Cloud project (no developer token, no MCC since Sept 2026) |
| Works with | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
| Where your data flows | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
| Updates | Automatic | pip install -U adloop |
| Price | Free plan, no card; paid plans for more accounts and volume | Free forever (MIT) |
Not sure? Start with Cloud — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
What It Solves
AdLoop exists because managing Google Ads alongside your code is a mess. These are the specific problems it handles:
-
"My conversions dropped and I don't know why." AdLoop cross-references Ads clicks, GA4 sessions, and conversion events in one query. It detects whether the gap is from GDPR consent rejection, broken tracking, or an actual landing page problem — before you waste hours checking each dashboard separately.
-
"I'm wasting ad spend on irrelevant searches." Pull your search terms report, identify the junk, and add negative keywords — all from a single conversation in your IDE. No context-switching to the Ads UI.
-
"Is my tracking even working?" Compare the event names in your actual codebase against what GA4 is receiving. Find the mismatches: events you fire that GA4 never sees, events GA4 records that you didn't know about.
-
"I need to create ads but the Google Ads UI is hostile." Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation: in Claude, ChatGPT and VS Code the preview is an approval card, and only your click on Apply changes the account (the AI cannot press it). New ads and campaigns start paused.
-
"My landing page gets paid traffic but nobody converts." AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
-
"Are conversions even being tagged on every page?" AdLoop reads your live Google Tag Manager container, joins it against the events in your codebase and the events firing in GA4, and tells you exactly which conversions are being captured, which tags are paused, which page-scope filters are too narrow, and which codebase events have no tag at all — the kind of three-way audit GTM Preview can't give you in a single view.
-
"I don't know if my EU consent setup is causing data gaps." In Europe, 30-70% of users reject analytics cookies. AdLoop accounts for this automatically — it won't diagnose a normal GDPR consent gap as broken tracking.
Built From Real Usage
Every tool exists because of an actual problem hit while running real Google Ads campaigns. The cross-reference tools exist because we kept manually asking the AI to "get Ads data, then get GA4 data, then compare them" — so we automated the join. The Broad Match + Manual CPC safety rule exists because the AI once created that exact combination and wasted budget. The GDPR consent awareness exists because the AI kept diagnosing normal EU cookie rejection as broken tracking.
The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, open an issue describing your situation — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
All Tools
Quick start:
pip install adlooporgit clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init— or zero setup on AdLoop Cloud
Diagnostics
| Tool | What It Does |
|---|---|
health_check |
Test OAuth, GA4, and Ads connectivity in one call — actionable error messages if anything is broken. Also reports the pinned Google Ads API version and warns if a newer version is available. |
GA4 Read Tools
| Tool | What It Does |
|---|---|
get_account_summaries |
List GA4 accounts and properties |
run_ga4_report |
Custom reports: sessions, users, key events, page performance. Optional dimension and metric filters, ordering, paging, and a comparison period |
run_realtime_report |
Live data — verify tracking fires after deploys |
get_tracking_events |
All configured events and their volume |
list_key_events |
The property's key events (conversions) with counting method, create time and whether they can be deleted |
list_ga4_dimensions_and_metrics |
Every dimension and metric the property can report on, including custom ones, with search |
Google Ads Read Tools
| Tool | What It Does |
|---|---|
list_accounts |
Discover accessible Ads accounts |
get_campaign_performance |
Campaign metrics: impressions, clicks, cost, conversions, CPA, Search impression share and share lost to budget/rank |
get_ad_performance |
Ad copy analysis: headlines, descriptions, CTR, policy approval status and topics |
get_keyword_performance |
Keywords — quality scores, competitive metrics |
get_search_terms |
What users actually searched before clicking |
get_negative_keywords |
List direct campaign-level negative keywords |
get_negative_keyword_lists |
List all shared negative keyword lists (SharedSets) — names, IDs, status, keyword count |
get_negative_keyword_list_keywords |
List the keywords inside a specific shared negative keyword list |
get_negative_keyword_list_campaigns |
List which campaigns a shared negative keyword list is attached to |
get_recommendations |
Google's auto-generated recommendations with type, estimated impact, and campaign context |
get_recommendation_subscriptions |
Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on |
get_pmax_performance |
Performance Max campaign metrics with network breakdown + asset group ad strength |
get_pmax_assets |
Per-asset details for PMax — field type, serving status, content |
get_asset_group_signals |
A PMax asset group's search themes and audience signal, plus the audiences available for it |
get_detailed_asset_performance |
Top-performing asset combinations — which headline+description+image combos Google selects most |
get_audience_performance |
Audience segment performance — remarketing, in-market, affinity, demographics |
get_shopping_product_performance |
Spend, conversions, CPA and ROAS per product across Shopping and Performance Max, plus products that spent without converting |
get_change_history |
What changed before the drop: who changed what and when, through which client (UI, API, scripts, auto-applied recommendations), last 30 days |
get_demographic_targeting |
List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
get_audience_lists |
The account's remarketing and customer lists (size, eligibility, open/closed), custom and combined segments |
search_audience_segments |
Find Google's in-market and affinity segments by name |
get_audience_targeting |
Audiences and audience exclusions on a campaign or ad group, plus the audience mode (observation or targeting) |
suggest_brands |
Resolve a brand name to the brands Google recognizes — brand ID, name, state, URLs |
check_brand_names |
Check a shortlist of brand names against Google's brand knowledge graph (max 25 per call) |
get_brand_lists |
List brand lists (SharedSets of type BRANDS) — ID, name, status, member count |
get_brand_list_brands |
List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
get_brand_list_campaigns |
Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
get_ai_max_settings |
AI Max knobs per campaign and ad group — enable_ai_max, bundling_required, the full asset_automation_settings list and each ad group's disable_search_term_matching |
get_campaign_settings |
One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged |
get_custom_conversion_goals |
Custom conversion goals with their actions, plus one campaign's goal config |
run_gaql |
Arbitrary GAQL queries for anything else |
Brand lists — a list is a
SharedSetof typeBRANDS; attaching it to a campaign is aCampaignCriterion.brand_list(negative=trueexcludes,falserestricts), not aCampaignSharedSetlike negative keyword lists.remove_from_brand_listanddetach_brand_list_from_campaignsremove for real —SharedCriterionhas no status field.
Brand targeting — brand criteria (brand lists, brand exclusions) target a brand's Commercial Knowledge Graph ID, not its display name. Use
suggest_brandsfor a single name orcheck_brand_namesfor a shortlist to get the ID;exact_matchmarks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.
AI Max is the container for Search brand exclusions — Google rejects a brand list on a plain Search campaign with "For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns."
draft_prepare_brand_exclusionssets the state that makes the exclusion usable without handing Google the automations: AI Max on, search term matching off per ad group, text and final-URL automation opted out.draft_ai_max_settingsis the general form when only parts of that state should change — it refuses a plan that would leave an automation on unnoticed, and asks for a second confirmation when that automation was requested explicitly.
Custom conversion goals — a named set of conversion actions that a campaign can be pointed at.
get_custom_conversion_goalsshows the goals with their actions and a campaign's current goal config;draft_custom_conversion_goalcreates a set,draft_update_custom_conversion_goalrenames or replaces its actions,draft_assign_custom_conversion_goalpoints a campaign at it anddraft_clear_custom_conversion_goalputs the campaign back on the account-level goals. Only the goal and the campaign's goal config are touched — conversion actions, bidding and budgets stay as they are.
Compact mode —
get_campaign_performance,get_keyword_performance,get_search_terms, andget_ad_performanceacceptcompact=true: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.
Cross-Reference Tools (GA4 + Ads Combined)
These tools call both APIs internally and return unified results with auto-generated insights. They're the core of what makes AdLoop different from having separate GA4 and Ads tools.
| Tool | What It Does |
|---|---|
analyze_campaign_conversions |
Maps Ads clicks → GA4 sessions → conversions per campaign. Detects GDPR consent gaps, computes real CPA, compares paid vs organic channels. |
landing_page_analysis |
Joins ad final URLs with GA4 page data. Shows conversion rate, bounce rate, and engagement per landing page. Flags pages with paid traffic but zero conversions. |
attribution_check |
Compares Ads-reported conversions vs GA4 events. Diagnoses whether discrepancies are from GDPR consent, attribution windows, or broken tracking. |
Tracking Tools
| Tool | What It Does |
|---|---|
validate_tracking |
Compare event names found in your codebase against what GA4 actually records. Returns matched, missing, and unexpected events with diagnostics. |
generate_tracking_code |
Generate ready-to-paste GA4 gtag JavaScript for any event, with recommended parameters for well-known events (sign_up, purchase, etc.) and optional trigger wrappers. |
Google Tag Manager Tools
These tools read the live GTM container and join it with the codebase + GA4 to find tracking gaps that pure GA4 inspection can't catch — page-scoped triggers, paused tags, dynamic event names, brittle CSS selectors, and codebase events with no tag wired up at all.
| Tool | What It Does |
|---|---|
audit_event_coverage |
The flagship. Three-way join: codebase events ↔ GTM tags ↔ GA4 actual fires. For each event name in expected_events, returns one of 10 statuses (ok, no_tag_no_fire, tag_paused, tag_active_but_not_firing, gtm_only_firing, ga4_only, etc.) plus auto-generated insights for the gaps. |
list_gtm_accounts |
Discover accessible GTM accounts |
list_gtm_containers |
List containers under an account — returns numeric container_id (needed by other tools), public GTM-XXXXXXX ID, and usage context (web/iOS/Android/server) |
list_gtm_tags |
Every tag in the live container with parsed event names and resolved firing/blocking trigger names. Pass workspace_id to read a workspace's unpublished state instead, so a just-drafted tag is visible (also on get_gtm_tag, list_gtm_triggers, get_gtm_trigger, list_gtm_variables) |
get_gtm_tag |
Full raw config for a single tag — every parameter, firing/blocking triggers with filter conditions, priority, pause status, sampling |
list_gtm_triggers |
Every trigger with filter conditions parsed to readable text (e.g. {{Page Path}} contains service-promotions, {{Form ID}} NOT contains wf-form-...). Renders the negate flag explicitly. |
get_gtm_trigger |
Full trigger config + reverse lookup of every tag that uses it. Includes parsed element_visibility block (selector, on-screen ratio, firing frequency) for elementVisibility triggers and group_member_trigger_ids for triggerGroup types |
list_gtm_variables |
Custom variables (data layer, constants, JS) plus enabled built-in variables |
list_gtm_workspaces |
List drafts (workspaces) under a container — workspace IDs are needed by get_gtm_workspace_diff |
get_gtm_workspace_diff |
Drafted-but-not-published changes — common cause of "I edited a tag but nothing happened". Returns is_clean: true when nothing is pending. |
list_gtm_versions |
Version history, newest first, with version IDs and entity counts. The Tag Manager API returns no timestamps or author for versions. |
get_gtm_version |
Name, notes and tag/trigger names for a single historical container version |
get_gtm_version_diff |
What a publish changed: added, removed and changed tags, triggers and variables with the changed fields, plus built-in variables enabled or disabled. Defaults to the live version against the one before it; two or three API calls. |
GTM write tools (opt-in)
Off by default. Set gtm.write_enabled: true in ~/.adloop/config.yaml and restart; the next call asks you to re-consent with the Tag Manager edit + publish scopes, which are never part of the default grant. Everything follows the usual draft → preview → confirm_and_apply flow, and tag/trigger edits only touch a workspace until you publish it.
| Tool | What It Does |
|---|---|
draft_gtm_tag |
Create a tag, or update one by tag_id. Updates are a read-modify-write: parameters merge by key and every field you don't pass (priority, consent settings, firing options, schedule, folder, …) is preserved. Tag types are canonical GTM template IDs (googtag, gaawe, awct, sp, gclidw, …) or cvt_<id> gallery templates. |
draft_gtm_trigger |
Create a trigger, or update one by trigger_id (type is immutable). custom_event_name wires a customEvent trigger to a dataLayer event. |
draft_gtm_variable |
Create or update variables, e.g. Data Layer Variables for GA4 ecommerce values; renaming a referenced variable is refused, Custom JavaScript is gated |
draft_delete_gtm_entity |
Delete a workspace tag, trigger or variable. Triggers and variables still in use are refused up front, with the references listed. |
draft_publish_gtm_workspace |
Publish a workspace live. The preview lists every pending change, including edits other people made in the GTM UI. |
draft_rollback_gtm_version |
Republish an older container version live. The preview is the diff from the live version to the target; the plan pins the live version, so apply refuses if someone publishes in between. Workspaces are left as they are. |
Safety gates specific to GTM:
- Custom HTML runs arbitrary JavaScript on your site, so creating or editing an
htmltag — or publishing a workspace that adds or changes one — is refused unlessgtm.allow_custom_html: trueis also set. Pausing or deleting one is always allowed. - No stale writes. Updates and deletes pin the entity's fingerprint from the preview, and publish pins the workspace's pending changes; if someone edits the container in between, apply refuses and you re-draft.
- Publishing stops on merge conflicts or GTM compiler errors. The dry run runs a Tag Manager quick preview first (Tag Manager has no validate-only mode), so compiler errors surface before a version is even created. That preview is a POST and stores a preview version in the container — nothing is published and no live tag changes; the rest of the dry run only reads.
- The publish and rollback results name the version they replaced (
previous_live_version_id), so rolling back is one step:draft_rollback_gtm_versionwith that id. If the version was created but publishing it failed, the error carries both the created version id and the still-live one. - Per-operation names for
safety.blocked_operations:gtm_create_tag,gtm_update_tag,gtm_delete_tag,gtm_create_trigger,gtm_update_trigger,gtm_delete_trigger,gtm_publish_workspace,gtm_rollback_version.
The Google account also needs Edit permission on the container (and Publish to publish) under Admin → User Management.
Setup for GTM tools — Enable the Tag Manager API v2 in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a Read user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. OAuth users upgrading from an earlier AdLoop version must re-authorize once: the GTM scope is new, so delete
~/.adloop/token.jsonand run any tool to re-consent — until then GTM tools return a permissions error.
Search Console Tools
| Tool | What It Does |
|---|---|
list_gsc_sites |
List Search Console properties the connected account can access |
run_gsc_report |
Organic search analytics: clicks, impressions, CTR, position by query/page/country/device/date/searchAppearance/hour. Supports fresh data (data_state="all"), aggregation_type, and paging past 25,000 rows with start_row |
Web Performance Tools
| Tool | What It Does |
|---|---|
analyze_page_speed |
PageSpeed Insights for landing pages: Lighthouse score, Core Web Vitals, real-user CrUX data (falls back to origin-wide data, labelled as such, when the page has too little traffic), top fixes. No OAuth needed (optional API key). |
Merchant Center Tools
| Tool | What It Does |
|---|---|
list_merchant_accounts |
Discover accessible Merchant Center accounts |
get_merchant_feed_health |
Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax. |
get_merchant_product_issues |
The products behind the feed-health counts: which are disapproved, limited or pending, and each issue with its attribute and affected countries |
Setup for Merchant Center tools — Enable the Merchant API in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.
Setup for GSC tools — Enable the Search Console API in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete
~/.adloop/token.json, run any tool). The killer combo: cross-reference organic queries withget_keyword_performanceto find paid/organic cannibalization and untapped keyword opportunities.
Questions sur AdLoop MCP
Comment ajouter AdLoop MCP à Claude Code ?
Exécutez claude mcp add adloop -- uvx adloop dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter AdLoop MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils AdLoop MCP fournit-il ?
Il expose 145 outils, dont health_check, get_account_summaries, run_ga4_report, run_realtime_report, get_ga4_property.
Que puis-je faire avec le MCP server AdLoop ?
Il donne à un assistant IA un accès en lecture et en écriture à Google Ads, Reddit Ads et GA4, incluant les performances des campagnes, les termes de recherche, les audiences et les rapports.
Les modifications sont-elles appliquées sans mon approbation ?
Non. Chaque modification fait l'objet d'un aperçu préalable, et seul votre clic sur Apply modifie le compte ; l'IA ne peut pas cliquer dessus.
Les nouvelles campagnes sont-elles créées en mode pause ?
Oui, les nouvelles publicités et campagnes sont créées en mode pause afin qu'elles ne puissent pas générer de dépenses avant que vous ne les activiez.
Comment installer AdLoop ?
Installez-le depuis PyPI avec pip install adloop, ou clonez le dépôt et lancez adloop init avec uv.
AdLoop fonctionne-t-il avec GA4 et Tag Manager ?
Oui, il lit les rapports GA4, les événements clés et les événements de suivi, et audite votre conteneur Google Tag Manager en direct par rapport à votre base de code.