adloop 0.16.0__tar.gz → 0.17.0__tar.gz

{adloop-0.16.0 → adloop-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.16.0
+Version: 0.17.0
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -132,8 +132,12 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `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_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `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) |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Brand targeting** — brand criteria (brand lists, brand exclusions) target a brand's **Commercial Knowledge Graph ID**, not its display name. Use `suggest_brands` for a single name or `check_brand_names` for a shortlist to get the ID; `exact_match` marks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.
+
 > **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=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)

{adloop-0.16.0 → adloop-0.17.0}/README.md

@@ -105,8 +105,12 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `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_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `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) |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Brand targeting** — brand criteria (brand lists, brand exclusions) target a brand's **Commercial Knowledge Graph ID**, not its display name. Use `suggest_brands` for a single name or `check_brand_names` for a shortlist to get the ID; `exact_match` marks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.
+
 > **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=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)

{adloop-0.16.0 → adloop-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.16.0"
+version = "0.17.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.16.0 → adloop-0.17.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.16.0"
+version = "0.17.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

adloop-0.17.0/src/adloop/ads/brands.py

@@ -0,0 +1,201 @@
+"""Google Ads brand tools — resolve brand names to Google's brand entities.
+
+Backs the brand picker of the Google Ads UI: ``BrandSuggestionService``
+matches a free-text name against Google's brand knowledge graph and answers
+with the canonical brand ID, display name, state, and associated URLs.
+
+The ID is what brand targeting actually needs. Brand criteria (brand lists /
+``BRAND_HINT``) reference the Commercial Knowledge Graph ID, not the display
+name — resolving the name first is what makes "steer the account towards
+brand X" possible at all. Read-only: no account state is touched.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+# SuggestBrands resolves a single prefix per round trip, and a bulk check is
+# therefore one API call per name. The cap keeps a single tool call inside the
+# MCP host's timeout while covering the usual audit batch (a campaign's brand
+# shortlist, a competitor shortlist, ...). Longer lists are split by the caller.
+MAX_BRAND_BATCH = 25
+
+_SENTINEL_STATES = {"UNSPECIFIED", "UNKNOWN"}
+
+
+def suggest_brands(
+    config: AdLoopConfig,
+    *,
+    brand_prefix: str,
+    selected_brand_ids: list[str] | None = None,
+    customer_id: str = "",
+) -> dict:
+    """Resolve one brand name to the brands Google recognizes for it.
+
+    ``selected_brand_ids`` mirrors the API field of the same purpose: IDs the
+    caller already picked can be handed back so Google keeps them in the
+    suggestion set while the prefix narrows.
+    """
+    prefix = (brand_prefix or "").strip()
+    if not prefix:
+        return {"error": "brand_prefix is required — pass the brand name to look up."}
+
+    cid = customer_id or config.ads.customer_id
+    brands = _fetch_brand_suggestions(
+        config,
+        customer_id=cid,
+        brand_prefix=prefix,
+        selected_brand_ids=selected_brand_ids or [],
+    )
+    return {
+        "customer_id": _digits(cid),
+        "brand_prefix": prefix,
+        "brand_count": len(brands),
+        "brands": brands,
+    }
+
+
+def check_brand_names(
+    config: AdLoopConfig,
+    *,
+    brand_names: list[str],
+    customer_id: str = "",
+) -> dict:
+    """Check several brand names against Google's brand knowledge graph.
+
+    One ``SuggestBrands`` call per name. Names Google does not know come back
+    as ``status: "no_match"`` with an empty candidate list — that is a normal
+    answer, not an error. An API failure aborts the whole batch and surfaces
+    as the regular structured error, so an expired token cannot hide behind a
+    half-filled result list.
+    """
+    names = _clean_brand_names(brand_names)
+    if not names:
+        return {"error": "brand_names is required — pass the brand names to check."}
+    if len(names) > MAX_BRAND_BATCH:
+        return {
+            "error": (
+                f"Too many brand names in one call ({len(names)}). "
+                f"SuggestBrands answers one prefix per request — split into "
+                f"batches of at most {MAX_BRAND_BATCH}."
+            )
+        }
+
+    cid = customer_id or config.ads.customer_id
+    results: list[dict] = []
+    for name in names:
+        brands = _fetch_brand_suggestions(
+            config, customer_id=cid, brand_prefix=name, selected_brand_ids=[]
+        )
+        best, exact = _best_match(name, brands)
+        results.append(
+            {
+                "query": name,
+                "status": "matched" if best else "no_match",
+                "exact_match": exact,
+                "brand": best,
+                "candidates": brands,
+            }
+        )
+
+    matched = sum(1 for r in results if r["status"] == "matched")
+    return {
+        "customer_id": _digits(cid),
+        "checked": len(results),
+        "matched": matched,
+        "no_match": len(results) - matched,
+        "results": results,
+        "note": (
+            "brand.id is the Commercial Knowledge Graph ID that brand "
+            "criteria (brand lists / BRAND_HINT) target. Match exact names "
+            "first; candidates are Google's own suggestions, not guarantees."
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+def _fetch_brand_suggestions(
+    config: AdLoopConfig,
+    *,
+    customer_id: str,
+    brand_prefix: str,
+    selected_brand_ids: list[str],
+) -> list[dict[str, Any]]:
+    """One ``BrandSuggestionService.SuggestBrands`` round trip, flattened."""
+    from adloop.ads.client import call_with_retry, get_ads_client, normalize_customer_id
+
+    client = get_ads_client(config)
+    service = client.get_service("BrandSuggestionService")
+    request = client.get_type("SuggestBrandsRequest")
+    request.customer_id = normalize_customer_id(customer_id)
+    request.brand_prefix = brand_prefix
+    for brand_id in selected_brand_ids:
+        request.selected_brands.append(str(brand_id))
+
+    response = call_with_retry(service.suggest_brands, request=request)
+
+    brand_state = client.enums.BrandStateEnum
+    brands: list[dict[str, Any]] = []
+    for suggestion in response.brands:
+        state = brand_state(suggestion.state).name
+        brands.append(
+            {
+                "id": suggestion.id,
+                "name": suggestion.name,
+                "state": state,
+                "urls": list(suggestion.urls),
+            }
+        )
+    return brands
+
+
+def _clean_brand_names(brand_names: list[str] | None) -> list[str]:
+    """Trim, drop blanks, and de-duplicate while keeping the caller's order."""
+    seen: set[str] = set()
+    names: list[str] = []
+    for raw in brand_names or []:
+        name = (raw or "").strip()
+        if not name or name.casefold() in seen:
+            continue
+        seen.add(name.casefold())
+        names.append(name)
+    return names
+
+
+def _best_match(query: str, brands: list[dict[str, Any]]) -> tuple[dict | None, bool]:
+    """Pick the suggestion that best answers *query*.
+
+    Ranking is deliberately shallow: an exact name match wins, then brands in
+    a usable state, then Google's own order. Anything deeper would imply a
+    confidence the API does not provide.
+    """
+    if not brands:
+        return None, False
+
+    normalized = _normalize(query)
+    ranked = sorted(
+        brands,
+        key=lambda brand: (
+            0 if _normalize(brand["name"]) == normalized else 1,
+            0 if brand["state"] not in _SENTINEL_STATES else 1,
+        ),
+    )
+    best = ranked[0]
+    return best, _normalize(best["name"]) == normalized
+
+
+def _normalize(name: str) -> str:
+    """Case- and punctuation-insensitive form used for exact-match checks."""
+    return re.sub(r"[\W_]+", "", (name or "").casefold())
+
+
+def _digits(customer_id: str) -> str:
+    return (customer_id or "").replace("-", "")

{adloop-0.16.0 → adloop-0.17.0}/src/adloop/ads/read.py

@@ -190,6 +190,7 @@ def get_ad_performance(
                     "ad_group": r.get("ad_group.name"),
                     "headlines": headlines,
                     "descriptions": descriptions,
+                    "final_urls": r.get("ad_group_ad.ad.final_urls") or [],
                 })
 
     single_ad_groups = [
@@ -205,7 +206,6 @@ def get_ad_performance(
             if k not in (
                 "ad_group_ad.ad.responsive_search_ad.headlines",
                 "ad_group_ad.ad.responsive_search_ad.descriptions",
-                "ad_group_ad.ad.final_urls",
             )
         }
         slim["headline_count"] = _asset_count(
@@ -228,6 +228,12 @@ def get_ad_performance(
             f"Google cannot rotate or optimize with a single creative."
         )
 
+    # Landing-page work needs every ad's URL, not just the top ten rows'.
+    landing_pages: dict[str, int] = {}
+    for r in rows:
+        for url in r.get("ad_group_ad.ad.final_urls") or []:
+            landing_pages[url] = landing_pages.get(url, 0) + 1
+
     top = [_slim(r) for r in rows[:10]]
     return {
         "compact": True,
@@ -237,9 +243,14 @@ def get_ad_performance(
         "ads_top_spend": top,
         "incomplete_rsas": incomplete_rsas[:10],
         "single_ad_ad_groups": single_ad_groups[:10],
+        "landing_pages": [
+            {"final_url": url, "ads": count}
+            for url, count in sorted(landing_pages.items(), key=lambda item: -item[1])
+        ],
         "insights": insights,
         "note": _compact_note(len(top), len(rows), "get_ad_performance")
-        + " Compact rows replace full headline/description lists with counts.",
+        + " Compact rows replace full headline/description lists with counts;"
+        " landing_pages lists every final URL across all ads.",
     }
 
 
@@ -480,6 +491,7 @@ def get_negative_keywords(
                campaign_criterion.criterion_id
         FROM campaign_criterion
         WHERE campaign_criterion.negative = TRUE
+          AND campaign_criterion.type = 'KEYWORD'
           AND campaign_criterion.status != 'REMOVED'
           {campaign_filter}
         ORDER BY campaign.name

{adloop-0.16.0 → adloop-0.17.0}/src/adloop/ads/validate_only.py

@@ -10,6 +10,11 @@ Validate-only responses carry no results, so each validated call answers the
 apply code with placeholder resource names. A later call that references one
 (a plan whose second step uses what the first would have created) cannot be
 validated meaningfully; it is skipped and counted instead of sent.
+
+The wrapper fails closed: only path helpers, reads, ``mutate*`` and
+``upload*`` calls (both sent validate-only) reach the real service. Any other
+method raises, so a write path added later cannot slip past a dry run and
+change an account for real.
 """
 
 from __future__ import annotations
@@ -18,7 +23,8 @@ from types import SimpleNamespace
 
 PLACEHOLDER = "adloop-validate-only"
 
-_RESPONSE_FIELD_FOR_SERVICE = "campaign_result"
+# Methods that never change an account and may run for real in a dry run.
+_READ_METHODS = frozenset({"search", "search_stream"})
 
 
 class ValidateOnlyFailure(Exception):
@@ -52,9 +58,14 @@ class _ValidateOnlyService:
         self._service = service
 
     def __getattr__(self, attr: str) -> object:
+        if attr in _READ_METHODS or attr.endswith("_path") or attr.startswith("parse_"):
+            return getattr(self._service, attr)
+        if not (attr.startswith("mutate") or attr.startswith("upload")):
+            raise ValidateOnlyFailure(
+                f"{self._name}.{attr} has no validate-only mode, so a dry run "
+                "cannot check it without changing the account. Refusing."
+            )
         target = getattr(self._service, attr)
-        if not attr.startswith("mutate"):
-            return target
 
         def validate(request: object = None, **kwargs: object) -> object:
             if request is None:
@@ -78,35 +89,51 @@ class _ValidateOnlyService:
     def _build_request(self, method: str, kwargs: dict) -> object:
         request = self._owner._client.get_type(_request_type(self._name, method))
         for key, value in kwargs.items():
-            if key in ("operations", "mutate_operations"):
+            if key in _LIST_FIELDS:
                 getattr(request, key).extend(value)
             else:
                 setattr(request, key, value)
         return request
 
 
+_LIST_FIELDS = ("operations", "mutate_operations", "conversions")
+
+
 def _request_type(service_name: str, method: str) -> str:
-    """``mutate_ad_group_criteria`` -> ``MutateAdGroupCriteriaRequest``."""
+    """``mutate_ad_group_criteria`` -> ``MutateAdGroupCriteriaRequest``,
+    ``upload_click_conversions`` -> ``UploadClickConversionsRequest``."""
     if method == "mutate":
         return "Mutate" + service_name.removesuffix("Service") + "Request"
-    words = method.removeprefix("mutate_").split("_")
-    return "Mutate" + "".join(word.capitalize() for word in words) + "Request"
+    verb, _, rest = method.partition("_")
+    return verb.capitalize() + "".join(word.capitalize() for word in rest.split("_")) + "Request"
 
 
 def _operations_of(request: object) -> object:
-    if hasattr(request, "mutate_operations"):
-        return request.mutate_operations
-    return getattr(request, "operations", [])
+    for field in _LIST_FIELDS:
+        if hasattr(request, field):
+            return getattr(request, field)
+    return []
+
+
+class _PlaceholderResult:
+    """A MutateOperationResponse stand-in: every ``*_result`` field
+    (``asset_result``, ``campaign_asset_result``, ...) carries the placeholder,
+    whichever one the apply code reads."""
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def __getattr__(self, attr: str) -> object:
+        if attr.endswith("_result"):
+            return SimpleNamespace(resource_name=self._name)
+        raise AttributeError(attr)
 
 
 def _placeholder_response(customer_id: str, count: int, googleads_mutate: bool) -> object:
     names = [f"customers/{customer_id}/{PLACEHOLDER}/{i}" for i in range(count)]
     if googleads_mutate:
         return SimpleNamespace(
-            mutate_operation_responses=[
-                SimpleNamespace(**{_RESPONSE_FIELD_FOR_SERVICE: SimpleNamespace(resource_name=n)})
-                for n in names
-            ],
+            mutate_operation_responses=[_PlaceholderResult(n) for n in names],
             partial_failure_error=None,
         )
     return SimpleNamespace(

{adloop-0.16.0 → adloop-0.17.0}/src/adloop/ga4/reports.py

@@ -36,6 +36,27 @@ def get_account_summaries(config: AdLoopConfig) -> dict:
     }
 
 
+def first_property(summaries: dict) -> str:
+    """The first property in a get_account_summaries() result, or ""."""
+    for account in summaries.get("accounts", []):
+        for prop in account.get("properties", []):
+            if prop.get("property"):
+                return prop["property"]
+    return ""
+
+
+def probe_data_api(config: AdLoopConfig, property_name: str) -> None:
+    """Raise if the GA4 Data API cannot serve this property.
+
+    A metadata lookup is the cheapest Data API call: it touches no report
+    quota, yet fails with SERVICE_DISABLED exactly when every report would.
+    """
+    from adloop.ga4.client import get_data_client
+
+    name = property_name if property_name.startswith("properties/") else f"properties/{property_name}"
+    get_data_client(config).get_metadata(name=f"{name}/metadata")
+
+
 def run_ga4_report(
     config: AdLoopConfig,
     *,

{adloop-0.16.0 → adloop-0.17.0}/src/adloop/rules/adloop.md

@@ -14,6 +14,8 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 |------|-------------|----------------|
 | `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) |
 
+**GA4 has two surfaces in health_check:** `ga4_admin` (listing properties) and `ga4_data` (every report). `ga4_data: error` with `SERVICE_DISABLED` means the Google Analytics Data API is not enabled in the Google Cloud project — tell the user to enable it; it is not a permissions or consent problem.
+
 **If health_check reports Google auth errors:** Tell the user to delete `~/.adloop/token.json` and re-run any tool to trigger re-authorization. If tokens keep expiring weekly, the GCP consent screen needs to be published from "Testing" to "In production". **Reddit auth errors** (`REDDIT_INVALID_GRANT`, `REDDIT_NOT_CONNECTED`) are fixed by re-running the Reddit step of `adloop init` (self-hosted) or reconnecting under Settings → Reddit Ads (AdLoop Cloud); the Google token is unrelated.
 
 ### GA4 Read Tools
@@ -44,6 +46,8 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 | `get_detailed_asset_performance` | Top-performing asset combinations — which headline+description+image combos Google selects most | `campaign_id` (optional) |
 | `get_audience_performance` | Audience segment metrics — remarketing, in-market, affinity, demographics | `date_range_start`, `date_range_end`, `campaign_id` (optional) |
 | `get_demographic_targeting` | List current demographic criteria (age/gender/parental status/income) on an ad group or campaign — returns each criterion's `remove_id` for use with `remove_entity` | exactly one of `ad_group_id` or `campaign_id` |
+| `suggest_brands` | Resolve one brand name to the brands Google recognizes — brand ID, name, state, URLs. The ID is what brand criteria target, so resolve here before building any brand list | `brand_prefix` (required), `selected_brand_ids` (optional, IDs already picked) |
+| `check_brand_names` | Triage a shortlist of brand names at once: matched vs. unknown, plus each brand's ID | `brand_names` (required, max 25 per call) |
 | `run_gaql` | Custom queries not covered by other tools | `query`, `format` (table/json/csv) |
 
 **Return format notes:**
@@ -55,7 +59,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 - `get_asset_performance` returns `by_status` and `by_field_type` summaries. Note: per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. Use `get_detailed_asset_performance` for quality signals via top combinations.
 - `get_audience_performance` works for campaigns with explicit audience targeting. PMax audience targeting is automatic and may not appear in this report. When the results include SEARCH campaigns, `insights[]` reminds you that custom segments cannot be attached to them (see the compatibility matrix below) — relay that constraint instead of proposing impossible pairings.
 - `get_demographic_targeting` returns an empty list when no demographics have been excluded or narrowed — that is the DEFAULT state (Google serves to all segments). Each criterion includes a composite `remove_id` (`adGroupId~criterionId` or `campaignId~criterionId`) that can be passed straight to `remove_entity`.
-- **Compact mode for audits**: `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`, returning account totals, breakdowns, the top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword waste candidates, thin RSAs, single-ad ad groups) instead of every row — roughly 90% smaller. Use it for account audits and overviews so raw tables don't flood the context; use the default full mode when you need a specific entity's exact rows before drafting a change. In harnesses with subagents, heavy multi-tool audits can additionally be delegated to a subagent that returns only the summary.
+- **Compact mode for audits**: `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`, returning account totals, breakdowns, the top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword waste candidates, thin RSAs, single-ad ad groups) instead of every row; compact `get_ad_performance` keeps `final_urls` on its rows and adds `landing_pages` (every final URL across all ads with its ad count), so landing-page checks need no extra GAQL — roughly 90% smaller. Use it for account audits and overviews so raw tables don't flood the context; use the default full mode when you need a specific entity's exact rows before drafting a change. In harnesses with subagents, heavy multi-tool audits can additionally be delegated to a subagent that returns only the summary.
 
 ### Cross-Reference Tools (GA4 + Ads combined)
 

{adloop-0.16.0 → adloop-0.17.0}/src/adloop/server.py

@@ -421,15 +421,10 @@ def health_check() -> dict:
     except ImportError:
         pass
 
-    try:
-        from adloop.ga4.reports import get_account_summaries as _ga4_test
-
-        result = _ga4_test(current_config())
-        status["ga4"] = "ok"
-        status["ga4_properties"] = result.get("total_properties", 0)
-    except Exception as e:
+    def _ga4_failed(surface: str, e: Exception) -> None:
         parsed = _structured_error("health_check", e)
         status["ga4"] = "error"
+        status[surface] = "error"
         status["ga4_error"] = parsed["error"]
         if "hint" in parsed:
             status["ga4_hint"] = parsed["hint"]
@@ -438,6 +433,32 @@ def health_check() -> dict:
         if "details" in parsed:
             status["ga4_error_details"] = parsed["details"]
 
+    # Two surfaces: the Admin API lists properties, the Data API serves every
+    # report. A project can have one enabled and not the other, so "ok" means
+    # both answered.
+    try:
+        from adloop.ga4.reports import get_account_summaries as _ga4_test
+
+        result = _ga4_test(current_config())
+        status["ga4_admin"] = "ok"
+        status["ga4_properties"] = result.get("total_properties", 0)
+    except Exception as e:
+        _ga4_failed("ga4_admin", e)
+    else:
+        from adloop.ga4.reports import first_property, probe_data_api
+
+        prop = current_config().ga4.property_id or first_property(result)
+        if not prop:
+            status["ga4"] = "ok"
+            status["ga4_data"] = "not_checked"
+        else:
+            try:
+                probe_data_api(current_config(), prop)
+                status["ga4"] = "ok"
+                status["ga4_data"] = "ok"
+            except Exception as e:
+                _ga4_failed("ga4_data", e)
+
     try:
         from adloop.ads.gaql import execute_query
 
@@ -3291,6 +3312,72 @@ def discover_keywords(
     )
 
 
+# ---------------------------------------------------------------------------
+# Google Ads — Brand Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(title="Suggest brands", annotations=_READONLY, tags={"ads"})
+@_safe
+def suggest_brands(
+    brand_prefix: str,
+    selected_brand_ids: _StrList = [],  # noqa: B006 — mutable default required for MCP JSON schema
+    customer_id: str = "",
+) -> dict:
+    """Resolve a brand name to the brands Google recognizes for it.
+
+    Mirrors the brand picker in the Google Ads UI
+    (BrandSuggestionService.SuggestBrands): pass a free-text name such as
+    "EscapeGame München" or "NoWayOut" and get back 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 resolve the name here before building any brand list.
+
+    selected_brand_ids: IDs already picked, handed back so Google keeps them
+    in the suggestion set while the prefix narrows. Optional.
+    """
+    from adloop.ads.brands import suggest_brands as _impl
+
+    return _impl(
+        current_config(),
+        brand_prefix=brand_prefix,
+        selected_brand_ids=selected_brand_ids,
+        customer_id=customer_id or current_config().ads.customer_id,
+    )
+
+
+@mcp.tool(title="Check brand names", annotations=_READONLY, tags={"ads"})
+@_safe
+def check_brand_names(
+    brand_names: _StrList,
+    customer_id: str = "",
+) -> dict:
+    """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?
+
+    Every entry answers 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.
+
+    At most 25 names per call — the API resolves one prefix per request, so
+    split longer lists.
+    """
+    from adloop.ads.brands import check_brand_names as _impl
+
+    return _impl(
+        current_config(),
+        brand_names=brand_names,
+        customer_id=customer_id or current_config().ads.customer_id,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Optional local-only debug tools (not shipped in git).
 # ---------------------------------------------------------------------------