# AdLoop [Health: Active] **Category:** 🎯 Marketing **Repository:** https://github.com/kLOsk/adloop **GitHub Stars:** 284 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/adloop ## Description Google Ads, GA4 and Tag Manager in your AI client, with a preview before every change. ## Tools Capabilities this server exposes over MCP: - **health_check** β€” Test AdLoop connectivity β€” checks OAuth token, GA4 API, Google Ads API, and (when configured) the Reddit Ads API. 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_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 - **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. Queries the GA4 Data API. Dimensions and metrics: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema - **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. Returns the dimension and metric headers and one row per dimension combination over the realtime window (the last 30 minutes). 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_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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **get_recommendations** β€” Retrieve Google's auto-generated recommendations with estimated impact. Returns each recommendation's 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. Google Ads API: https://developers.google.com/google-ads/api/docs/start - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **draft_delete_gtm_entity** β€” Draft deleting a Tag Manager tag or trigger β€” 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 is refused up front, with the referencing tags 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_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 - **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 - **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 - **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 1,000 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_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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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. 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_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 - **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). 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_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. Google caps: at most 2 headlines per pin slot, at most 1 description per pin slot. 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_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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **draft_callouts** β€” Draft campaign callout assets β€” returns a PREVIEW. Creates callout assets and links them to the 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 - **draft_structured_snippets** β€” Draft campaign structured snippet assets β€” returns a PREVIEW. Creates structured snippet assets and links them to the 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 - **draft_image_assets** β€” Draft campaign 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_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 - **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 - **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 - **draft_sitelinks** β€” Draft sitelink extensions for a campaign β€” 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_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, APPLIED, PARTIAL_UPLOAD or APPLY_IN_PROGRESS. 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. 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. 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_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:" 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/ - **list_uploads** β€” List the images the user uploaded to AdLoop that have not expired. Returns each upload's upload_id, name, type, dimensions, size and hours until it expires (uploads last a day): the ids of files the user sent through the upload link, or of earlier uploads. 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/ - **list_reddit_accounts** β€” List Reddit businesses and ad accounts the connected Reddit user can access. Returns the Reddit username, the businesses, and per ad account the ad_account_id values (plus currency, time zone and approval state) that every other Reddit tool takes. Requires the Reddit Ads connection (adloop init β†’ Reddit step, or Settings β†’ Reddit Ads in Cloud). Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **list_reddit_funding_instruments** β€” Funding instruments (billing) and posting profiles of a Reddit ad account. Returns funding_instruments (funding_instrument_id, currency, is_servable, reasons_not_servable, credit limit and billable amount in account currency) and profiles (profile_id, username). draft_reddit_campaign needs a servable funding_instrument_id; draft_reddit_ad needs the profile_id that authors the post. Both come from here. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_campaigns** β€” List Reddit campaigns with status, objective, budget mode and bids. Returns the account currency, the campaigns, and insights for campaigns blocked by account state. Each campaign carries configured_status (what was set) and effective_status (what Reddit computes: PENDING_APPROVAL, REJECTED, PENDING_BILLING_INFO, ...). Money is in account currency. Budgets live on ad groups unless is_campaign_budget_optimization is true. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_ad_groups** β€” List Reddit ad groups (budget, bid, pixel, weekly schedule, targeting summary), optionally per campaign. Returns the account currency, the ad groups, and insights. Reddit requires conversion_pixel_id on every ad group; insights flag ad groups without one and name ad groups that run on a weekly schedule. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_ads** β€” List Reddit ads with status, rejection_reason, post and click URL. Returns the ads and insights: insights flag REJECTED ads (policy review) and ads still PENDING_APPROVAL. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_performance** β€” Reddit Ads performance: spend, impressions, clicks, CTR, CPC, conversions, CPA, ROAS. Returns rows per entity for the chosen level with names joined, plus totals and insights[] (zero-conversion spenders, rejected ads, empty windows). 'conversions' is the account's key conversion event. Money is in account currency. Data lags up to 6 hours. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **run_reddit_report** β€” Run a custom Reddit Ads report for metrics get_reddit_performance omits. Returns the requested fields per breakdown row, the date range and the account currency. Microcurrency and cent fields are converted to currency amounts. Queries the Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_pixels** β€” Reddit pixels of the account and when each event (purchase, sign_up, lead, ...) last fired. Returns each pixel's pixel_id, name, last_fired_at per standard event, custom events and a never_fired flag, plus insights. Relevant before conversion-optimized campaigns: insights flag pixels that never fired and ad groups optimizing for an event their pixel has never sent. Every new ad group needs a conversion_pixel_id from here. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_audiences** β€” Reddit custom and saved audiences of the account, and which ad groups use them. Returns each custom audience's audience_id, name, type (PIXEL_RETARGETING, ENGAGEMENT_RETARGETING, CUSTOMER_LIST, LOOKALIKE, ...), status, estimated size_range, its source (pixel events or campaigns, lookback days) and the ad groups that target or exclude it; saved audiences with their targeting; and insights that flag audiences Reddit cannot use yet or that are too small to deliver. The audience_id goes into custom_audience_ids or excluded_custom_audience_ids on an ad group. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **search_reddit_targeting** β€” Look up targeting options for draft_reddit_ad_group. Returns ids/names to pass into the targeting lists, with the kind, the query and the total number of matches. Communities target by name, interests by id, geolocations by id (e.g. "DE" or "DE:2874225"), languages by code (e.g. "DE"), carriers by id (e.g. "O2_DEUTSCHLAND"). Devices come back as make/model pairs for the label_map of a device target. Keyword suggestions carry Reddit-wide monthly views, not search volume. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **get_reddit_account_history** β€” Who changed what in the Reddit ad account: field, before/after, member, time. Returns the changes, most recent first, with changed_at, by, entity type, id and name, field, and before/after values. The first thing to check when performance moves. Child entities are included when filtering by entity. Changes made through AdLoop show under the connected Reddit user, like changes made in Ads Manager. Money fields are in account currency. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **estimate_reddit_ad_group** β€” Audience size, delivery estimate and Reddit's suggested bid for a planned ad group β€” read-only. Reddit's counterpart of estimate_budget: takes the same targeting and budget as draft_reddit_ad_group, ahead of drafting. Returns the reachable and targetable audience (fixed 30-day basis), estimated impressions/clicks/reach for the schedule, the minimum/suggested bid range for bid_type in account currency, and insights (audience under 10,000 people, bid_value below the suggested minimum). Nothing is created. At least one of geolocations, communities, interests or keywords is required. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **pause_reddit_entity** β€” Draft pausing a Reddit campaign, ad group or ad β€” returns a PREVIEW. Returns a preview with a plan_id, the current and target status (PAUSED) and warnings (e.g. already paused); nothing changes until confirm_and_apply applies the plan_id. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **enable_reddit_entity** β€” Draft enabling (configured_status=ACTIVE) a Reddit campaign, ad group or ad β€” PREVIEW. Enabling a new ad sends it to Reddit policy review (PENDING_APPROVAL). Returns a preview with a plan_id, the current and target status and warnings (e.g. an effective_status of REJECTED or PENDING_BILLING_INFO that keeps it from serving); nothing changes until confirm_and_apply applies the plan_id. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **remove_reddit_entity** β€” Draft ARCHIVING a Reddit campaign, ad group or ad β€” irreversible, PREVIEW. Reddit has no hard delete for entities that ran; ARCHIVED is permanent. pause_reddit_entity is the reversible alternative when the entity does not need to be gone. Returns a preview with a plan_id that requires double confirmation; confirm_and_apply executes it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **update_reddit_campaign** β€” Draft changes to a Reddit campaign β€” name, run dates, spend cap, and (CBO only) budget/bid/schedule. daily_budget / lifetime_budget / bid_* / schedule apply only when the campaign uses campaign budget optimization; otherwise the budget lives on its ad groups (changed via update_reddit_ad_group). Budgets are in account currency and checked against max_daily_budget; bid_value against max_bid_increase_pct. Returns a preview with a plan_id showing old β†’ new per field; nothing changes until confirm_and_apply applies it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **update_reddit_ad_group** β€” Draft changes to a Reddit ad group β€” budget, bid, run dates, weekly schedule, targeting. Budget (daily_budget or lifetime_budget + end_time) is checked against max_daily_budget; bid_value against max_bid_increase_pct. Targeting lists REPLACE the current value of each key passed (each takes the full list); omitted keys are preserved. Ids/names come from search_reddit_targeting. Budget and schedule of an ad group in a campaign-budget-optimization campaign are set on the campaign (update_reddit_campaign). Returns a preview with a plan_id showing old β†’ new per field; nothing changes until confirm_and_apply applies it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **update_reddit_ad** β€” Draft changes to a Reddit ad β€” name, landing URL (click_url), comments on/off. The headline and body of a live Reddit post cannot be edited; new copy means a new ad via draft_reddit_ad, with the old ad paused. Returns a preview with a plan_id showing old β†’ new; nothing changes until confirm_and_apply executes it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **draft_reddit_custom_audience** β€” Draft a Reddit retargeting audience (website visitors or engaged people) β€” PREVIEW. Builds the audience from data Reddit already has: people the pixel saw on the website, or people who saw or engaged with the account's campaigns. No personal data is uploaded. Nothing changes until confirm_and_apply applies the plan_id; Reddit then fills the audience (status PENDING, up to a day), and an ad group uses it through update_reddit_ad_group custom_audience_ids (target) or excluded_custom_audience_ids (exclude). Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **draft_reddit_campaign** β€” Draft a new Reddit campaign (created PAUSED) β€” returns a PREVIEW. By default the budget lives on the ad groups; campaign_budget_optimization holds it on the campaign. Budgets are checked against max_daily_budget. Ad groups are added with draft_reddit_ad_group. Returns a preview with a plan_id, the payload and warnings; nothing changes until confirm_and_apply applies it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **draft_reddit_ad_group** β€” Draft a new Reddit ad group (created PAUSED) β€” returns a PREVIEW. Required: campaign_id, ad_group_name, conversion_pixel_id and at least one targeting list (geolocations, communities, interests or keywords β€” ids/names from search_reddit_targeting). For non-CBO campaigns also daily_budget (or lifetime_budget + end_time), bid_strategy and bid_type. Budgets are checked against max_daily_budget; keywords and geolocations are pre-validated with Reddit. Returns a preview with a plan_id, the payload and warnings; nothing changes until confirm_and_apply applies it. Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **draft_reddit_ad** β€” Draft a Reddit ad: creates a post on the profile, then the ad (PAUSED) β€” PREVIEW. click_url and the media URLs are checked before drafting, so ads do not point at unverified pages and Reddit gets real image and video files. Comments are public on Reddit ads. With post_id an EXISTING post is promoted instead, keeping its upvotes and comments: no post is created and the copy arguments are ignored. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it. Once enabled, the ad goes through Reddit policy review (PENDING_APPROVAL). Reddit Ads API: https://ads-api.reddit.com/docs/v3/ - **draft_key_event** β€” Draft marking a GA4 event as a key event (conversion) β€” 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. 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_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 - **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 - **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, or changing attribution. 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_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 - **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. Local file only: on the hosted server this tool refuses, because it would read a path on the server rather than the caller's machine. 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_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. 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. Local file only: on the hosted server this tool refuses, because it would read a path on the server rather than the caller's machine. 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_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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 - **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 ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "adloop": { "command": "uvx", "args": ["adloop"] } } ``` ## Documentation ## What AdLoop MCP server does The AdLoop MCP server brings advertising and measurement data into an MCP-compatible AI client. Its documented integrations include Google Ads, GA4, Google Search Console, Google Merchant Center, PageSpeed Insights, and optional Reddit Ads connectivity for diagnostics. The toolset is aimed at marketing analysis: campaign performance, ad and keyword results, search terms, audience segments, conversion gaps, landing-page behavior, organic search visibility, and product-feed issues. The AdLoop MCP server also provides discovery tools before reporting begins. You can list accessible Ads accounts, GA4 properties, Search Console sites, and Merchant Center accounts. This is useful when one authenticated identity can reach multiple properties or customer accounts. ## How it works AdLoop runs as an MCP server and calls the relevant provider APIs on behalf of the connected client. GA4 tools support custom reports, realtime reports, event volumes, key events, and property metadata. Google Ads tools return campaign, ad, keyword, search-term, recommendation, Performance Max, audience, demographic, and change-history data. Search Console reporting supports dimensions such as search queries and pages, with paging for larger result sets. Several tools combine data from more than one system. `analyze_campaign_conversions` compares Ads campaign results with GA4 sessions and key events, while `landing_page_analysis` joins ad final URLs with page-level analytics. `analyze_page_speed` adds Lighthouse and available Chrome User Experience field data to a landing-page investigation. Responses generally include headers, rows, totals, identifiers, status values, or diagnostic insights relevant to the selected report. The server can run `health_check` to test OAuth and API connectivity. It reports separate service statuses and provides guidance when a dependency is unavailable. Report validation happens before a GA4 request is sent, so invalid filters or ordering return error details rather than querying the API. ## Setup and configuration The self-hosted project requires Python 3.11 or newer. Installation can use the published package: ```text pip install adloop ``` The repository also documents a source workflow using `uv sync` followed by `uv run adloop init`. Self-hosting requires a Google Cloud project, and the project documentation distinguishes this from AdLoop Cloud, which handles the hosted setup. The self-hosted model keeps data on the machine running the server. Specific environment variable names are not provided in the supplied material, so configuration should follow the repository or linked documentation rather than assumed variables. ## Tools and capabilities The AdLoop MCP server includes these supported areas: - Discover GA4 properties, Ads accounts, Search Console sites, and Merchant Center accounts. - Run GA4 standard and realtime reports, inspect events and key events, and list valid dimensions and metrics. - Review campaign, ad, keyword, search-term, audience, demographic, recommendation, and Performance Max data. - Inspect negative keyword lists, asset combinations, account changes, and policy-related ad information. - Query Search Console performance, including clicks, impressions, CTR, and average position. - Check Merchant Center disapprovals and account-level issues. - Measure landing-page performance with PageSpeed Insights and connect paid traffic to GA4 outcomes. ## Limitations and notes GA4 realtime results cover the last 30 minutes. Search Console returns up to 25,000 rows per request and may require another call when a continuation value is returned. Merchant Center product-status information can lag by about 30 minutes. PageSpeed runs commonly take 10–30 seconds, and field data may be origin-wide when a specific page lacks enough traffic. Performance Max reporting does not provide complete channel splits: the API may group traffic under `MIXED`. Individual PMax asset performance labels are not available; detailed asset combinations are provided instead. Google Ads change history is retained for 30 days. Reddit Ads is checked by `health_check` only when configured in the supplied tool list. The project documentation states that changes use a preview and explicit confirmation, but the provided tool descriptions primarily document reporting and analysis operations. Confirm the current write-tool and client behavior in the repository documentation before relying on automated account mutations. _Full upstream README: https://allmcps.com/mcp/adloop/readme_