adloop 0.13.2__tar.gz → 0.13.3__tar.gz

{adloop-0.13.2 → adloop-0.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.13.2
+Version: 0.13.3
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -24,6 +24,8 @@ Project-URL: Changelog, https://github.com/kLOsk/adloop/releases
 Provides-Extra: dev
 Description-Content-Type: text/markdown
 
+<!-- mcp-name: com.getadloop/adloop -->
+
 <div align="center">
 
 # AdLoop
@@ -40,12 +42,12 @@ Description-Content-Type: text/markdown
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project, with a free plan that needs no credit card.** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 > 📚 **Documentation: [docs.getadloop.com](https://docs.getadloop.com)** — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.
 
@@ -63,7 +65,7 @@ Both versions run the same tools with the same safety model. The difference is w
 | **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
 | **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
 | **Updates** | Automatic | `pip install -U adloop` |
-| **Price** | Free during beta | Free forever (MIT) |
+| **Price** | Free plan, no card; [paid plans](https://getadloop.com/preise) for more accounts and volume | Free forever (MIT) |
 
 **Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
 
@@ -517,7 +519,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires

{adloop-0.13.2 → adloop-0.13.3}/README.md

@@ -1,3 +1,5 @@
+<!-- mcp-name: com.getadloop/adloop -->
+
 <div align="center">
 
 # AdLoop
@@ -14,12 +16,12 @@
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project, with a free plan that needs no credit card.** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 > 📚 **Documentation: [docs.getadloop.com](https://docs.getadloop.com)** — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.
 
@@ -37,7 +39,7 @@ Both versions run the same tools with the same safety model. The difference is w
 | **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
 | **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
 | **Updates** | Automatic | `pip install -U adloop` |
-| **Price** | Free during beta | Free forever (MIT) |
+| **Price** | Free plan, no card; [paid plans](https://getadloop.com/preise) for more accounts and volume | Free forever (MIT) |
 
 **Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
 
@@ -491,7 +493,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires

{adloop-0.13.2 → adloop-0.13.3}/pyproject.toml

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

{adloop-0.13.2 → adloop-0.13.3}/pyproject.toml.orig

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

{adloop-0.13.2 → adloop-0.13.3}/src/adloop/ads/read.py

@@ -278,10 +278,24 @@ def get_keyword_performance(
         return {"keywords": rows, "total_keywords": len(rows)}
 
     qs_field = "ad_group_criterion.quality_info.quality_score"
+
+    def _rated_score(r: dict) -> int | None:
+        """The Quality Score, or None when Google has not assigned one.
+
+        Google never issues a real score of 0: both null and 0 mean "not
+        enough impressions to rate". Counting those as "< 5" reports an
+        ordinary unrated long tail as an account-wide relevance problem and
+        sends the assistant off fixing ads and landing pages that are fine.
+        """
+        score = r.get(qs_field)
+
+        return score if isinstance(score, int) and score > 0 else None
+
     low_quality = [
         r for r in rows
-        if r.get(qs_field) is not None and (r.get(qs_field) or 0) < 5
+        if (score := _rated_score(r)) is not None and score < 5
     ]
+    unrated_count = sum(1 for r in rows if _rated_score(r) is None)
     zero_conv_spenders = [
         r for r in rows
         if (r.get("metrics.cost_micros") or 0) > 0
@@ -304,6 +318,11 @@ def get_keyword_performance(
             f"{len(low_quality)} keyword(s) have quality score < 5 — fix ad "
             f"relevance and landing pages before adding keywords or budget."
         )
+    if unrated_count:
+        insights.append(
+            f"{unrated_count} keyword(s) have no quality score yet (too few "
+            f"impressions to rate). They are excluded from the count above."
+        )
     if zero_conv_spenders:
         wasted = round(
             sum((r.get("metrics.cost_micros") or 0) for r in zero_conv_spenders)
@@ -325,6 +344,7 @@ def get_keyword_performance(
         ),
         "keywords_top_spend": top,
         "low_quality_score": [_kw(r) for r in low_quality[:10]],
+        "unrated_quality_score": unrated_count,
         "zero_conversion_spenders": [_kw(r) for r in zero_conv_spenders[:10]],
         "insights": insights,
         "note": _compact_note(len(top), len(rows), "get_keyword_performance"),
@@ -430,7 +450,7 @@ def get_search_terms(
     return {
         "compact": True,
         "total_search_terms": len(rows),
-        "totals": _compact_totals(rows, currency_code),
+        "totals": _compact_totals(rows, currency_code, row_limit=200),
         "search_terms_top_clicks": top,
         "waste_candidates": [_term(r) for r in waste[:10]],
         "top_converters": [_term(r) for r in converters[:5]],
@@ -923,8 +943,15 @@ def _date_clause(start: str, end: str) -> str:
     return "AND segments.date DURING LAST_30_DAYS"
 
 
-def _compact_totals(rows: list[dict], currency_code: str) -> dict:
-    """Deterministic account-level aggregates over enriched metric rows."""
+def _compact_totals(
+    rows: list[dict], currency_code: str, *, row_limit: int | None = None
+) -> dict:
+    """Deterministic aggregates over the rows given.
+
+    Not account-level whenever the query behind them carries a LIMIT: pass
+    ``row_limit`` for those reports so a truncated total is marked partial
+    instead of being read as the account's real cost and conversions.
+    """
     cost = sum((r.get("metrics.cost_micros") or 0) for r in rows) / 1_000_000
     clicks = sum((r.get("metrics.clicks") or 0) for r in rows)
     impressions = sum((r.get("metrics.impressions") or 0) for r in rows)
@@ -940,6 +967,21 @@ def _compact_totals(rows: list[dict], currency_code: str) -> dict:
         totals["cpa"] = round(cost / conversions, 2)
     if impressions > 0:
         totals["ctr_pct"] = round(clicks / impressions * 100, 2)
+
+    # Hitting the ceiling exactly is indistinguishable from stopping there, so
+    # this errs toward declaring partial. Silently under-reporting cost is the
+    # worse failure: these numbers are labelled "totals" and get compared
+    # against campaign-level truth.
+    if row_limit is not None and len(rows) >= row_limit:
+        totals["partial"] = True
+        totals["rows_counted"] = len(rows)
+        totals["partial_reason"] = (
+            f"The underlying query returns at most {row_limit} rows, ranked by "
+            f"the report's sort metric, and this account reached that ceiling. "
+            f"These totals cover those rows only, not the whole account. Use "
+            f"get_campaign_performance for account-level figures."
+        )
+
     return totals
 
 

{adloop-0.13.2 → adloop-0.13.3}/src/adloop/config.py

@@ -82,6 +82,26 @@ def _resolve_path(path_str: str) -> Path:
     return Path(os.path.expandvars(os.path.expanduser(path_str)))
 
 
+def _text(raw: dict, key: str, default: str = "") -> str:
+    """Read a string setting, treating blank as absent.
+
+    ``raw.get(key, default)`` only falls back when the key is *missing*, so an
+    explicit ``token_path: ""`` — easy to produce from a template with blank
+    placeholders — passed straight through. ``Path("")`` is ``Path(".")``, the
+    working directory always exists, and adloop then tried to read the cwd as
+    a token file and died with ``[Errno 1] Operation not permitted: '.'``,
+    which points nowhere near the config that caused it.
+
+    Also coerces non-strings, so ``customer_id: 1234567890`` in YAML arrives
+    as text rather than an int.
+    """
+    value = raw.get(key, default)
+
+    if value is None:
+        return default
+
+    return str(value).strip() or default
+
 def load_config(config_path: str | None = None) -> AdLoopConfig:
     """Load configuration from YAML file.
 
@@ -112,34 +132,34 @@ def load_config(config_path: str | None = None) -> AdLoopConfig:
 
     return AdLoopConfig(
         google=GoogleConfig(
-            project_id=google_raw.get("project_id", ""),
-            credentials_path=google_raw.get("credentials_path", ""),
-            token_path=google_raw.get("token_path", "~/.adloop/token.json"),
+            project_id=_text(google_raw, "project_id"),
+            credentials_path=_text(google_raw, "credentials_path"),
+            token_path=_text(google_raw, "token_path", "~/.adloop/token.json"),
         ),
         ga4=GA4Config(
-            property_id=ga4_raw.get("property_id", ""),
+            property_id=_text(ga4_raw, "property_id"),
         ),
         ads=AdsConfig(
-            developer_token=ads_raw.get("developer_token", ""),
-            customer_id=ads_raw.get("customer_id", ""),
-            login_customer_id=ads_raw.get("login_customer_id", ""),
+            developer_token=_text(ads_raw, "developer_token"),
+            customer_id=_text(ads_raw, "customer_id"),
+            login_customer_id=_text(ads_raw, "login_customer_id"),
         ),
         gsc=GscConfig(
-            site_url=gsc_raw.get("site_url", ""),
+            site_url=_text(gsc_raw, "site_url"),
         ),
         gtm=GtmConfig(
-            account_id=str(gtm_raw.get("account_id", "")),
-            container_id=str(gtm_raw.get("container_id", "")),
+            account_id=_text(gtm_raw, "account_id"),
+            container_id=_text(gtm_raw, "container_id"),
         ),
         pagespeed=PageSpeedConfig(
-            api_key=str(pagespeed_raw.get("api_key", "")),
+            api_key=_text(pagespeed_raw, "api_key"),
         ),
         safety=SafetyConfig(
             max_daily_budget=safety_raw.get("max_daily_budget", 50.0),
             max_bid_increase_pct=safety_raw.get("max_bid_increase_pct", 100),
             require_dry_run=safety_raw.get("require_dry_run", True),
             two_phase_apply=safety_raw.get("two_phase_apply", False),
-            log_file=safety_raw.get("log_file", "~/.adloop/audit.log"),
+            log_file=_text(safety_raw, "log_file", "~/.adloop/audit.log"),
             blocked_operations=safety_raw.get("blocked_operations", []),
         ),
         source_path=resolved,

{adloop-0.13.2 → adloop-0.13.3}/src/adloop/rules/adloop.md

@@ -655,16 +655,29 @@ For cities/regions, use `run_gaql` with `geo_target_constant` resource or look u
 
 ### Common Language IDs (languageConstants)
 
-| ID | Language |
-|----|----------|
-| 1000 | English |
-| 1001 | German |
-| 1002 | French |
-| 1003 | Italian |
-| 1004 | Spanish |
-| 1005 | Dutch |
-| 1009 | Portuguese |
-| 1014 | Polish |
+Verified against the `language_constant` resource. Google accepts a wrong
+language ID silently, so confirm anything not listed here with:
+`SELECT language_constant.id, language_constant.code, language_constant.name FROM language_constant`
+
+| ID | Code | Language |
+|----|------|----------|
+| 1000 | en | English |
+| 1001 | de | German |
+| 1002 | fr | French |
+| 1003 | es | Spanish |
+| 1004 | it | Italian |
+| 1005 | ja | Japanese |
+| 1009 | da | Danish |
+| 1010 | nl | Dutch |
+| 1011 | fi | Finnish |
+| 1014 | pt | Portuguese |
+| 1015 | sv | Swedish |
+| 1017 | zh_CN | Chinese (simplified) |
+| 1019 | ar | Arabic |
+| 1021 | cs | Czech |
+| 1030 | pl | Polish |
+| 1031 | ru | Russian |
+| 1037 | tr | Turkish |
 
 ## Marketing Best Practices
 

{adloop-0.13.2 → adloop-0.13.3}/src/adloop/server.py

@@ -285,7 +285,7 @@ def _safe(fn: Callable) -> Callable:
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"core"})
+@mcp.tool(title="Connection health check", annotations=_READONLY, tags={"core"})
 @_safe
 def health_check() -> dict:
     """Test AdLoop connectivity — checks OAuth token, GA4 API, and Google Ads API.
@@ -372,7 +372,7 @@ def health_check() -> dict:
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"ga4"})
+@mcp.tool(title="List Analytics properties", annotations=_READONLY, tags={"ga4"})
 @_safe
 def get_account_summaries() -> dict:
     """List all GA4 accounts and properties accessible by the authenticated user.
@@ -385,7 +385,7 @@ def get_account_summaries() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(annotations=_READONLY, tags={"ga4"})
+@mcp.tool(title="Analytics report", annotations=_READONLY, tags={"ga4"})
 @_safe
 def run_ga4_report(
     dimensions: _StrListOpt = None,
@@ -416,7 +416,7 @@ def run_ga4_report(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ga4"})
+@mcp.tool(title="Analytics realtime report", annotations=_READONLY, tags={"ga4"})
 @_safe
 def run_realtime_report(
     dimensions: _StrListOpt = None,
@@ -439,7 +439,7 @@ def run_realtime_report(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ga4"})
+@mcp.tool(title="List Analytics events", annotations=_READONLY, tags={"ga4"})
 @_safe
 def get_tracking_events(
     date_range_start: str = "28daysAgo",
@@ -466,7 +466,7 @@ def get_tracking_events(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"gsc"})
+@mcp.tool(title="List Search Console properties", annotations=_READONLY, tags={"gsc"})
 @_safe
 def list_gsc_sites() -> dict:
     """List all Google Search Console properties the authenticated user can access.
@@ -480,7 +480,7 @@ def list_gsc_sites() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(annotations=_READONLY, tags={"gsc"})
+@mcp.tool(title="Search Console report", annotations=_READONLY, tags={"gsc"})
 @_safe
 def run_gsc_report(
     site_url: str = "",
@@ -530,7 +530,7 @@ def run_gsc_report(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"web"})
+@mcp.tool(title="PageSpeed analysis", annotations=_READONLY, tags={"web"})
 @_safe
 def analyze_page_speed(url: str, strategy: str = "mobile") -> dict:
     """Run PageSpeed Insights for a landing page — Lighthouse + real-user data.
@@ -549,7 +549,11 @@ def analyze_page_speed(url: str, strategy: str = "mobile") -> dict:
     return _impl(current_config(), url=url, strategy=strategy)
 
 
-@mcp.tool(annotations=_READONLY, tags={"merchant"})
+@mcp.tool(
+    title="List Merchant Center accounts",
+    annotations=_READONLY,
+    tags={"merchant"},
+)
 @_safe
 def list_merchant_accounts() -> dict:
     """List Google Merchant Center accounts the connected user can access.
@@ -562,7 +566,7 @@ def list_merchant_accounts() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(annotations=_READONLY, tags={"merchant"})
+@mcp.tool(title="Merchant Center feed health", annotations=_READONLY, tags={"merchant"})
 @_safe
 def get_merchant_feed_health(account_id: str) -> dict:
     """Merchant Center feed health — disapproved products + account issues.
@@ -581,7 +585,7 @@ def get_merchant_feed_health(account_id: str) -> dict:
     return _impl(current_config(), account_id=account_id)
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="List Google Ads accounts", annotations=_READONLY, tags={"ads"})
 @_safe
 def list_accounts(limit: int = 200) -> dict:
     """List accessible Google Ads accounts.
@@ -600,7 +604,7 @@ def list_accounts(limit: int = 200) -> dict:
     return _impl(current_config(), limit=limit)
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Campaign performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_campaign_performance(
     customer_id: str = "",
@@ -629,7 +633,7 @@ def get_campaign_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Ad performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_ad_performance(
     customer_id: str = "",
@@ -657,7 +661,7 @@ def get_ad_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Keyword performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_keyword_performance(
     customer_id: str = "",
@@ -685,7 +689,7 @@ def get_keyword_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Search terms report", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_search_terms(
     customer_id: str = "",
@@ -713,7 +717,7 @@ def get_search_terms(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="List negative keywords", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_negative_keywords(
     customer_id: str = "",
@@ -733,7 +737,11 @@ def get_negative_keywords(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(
+    title="List shared negative keyword lists",
+    annotations=_READONLY,
+    tags={"ads"},
+)
 @_safe
 def get_negative_keyword_lists(
     customer_id: str = "",
@@ -749,7 +757,11 @@ def get_negative_keyword_lists(
     return _impl(current_config(), customer_id=customer_id or current_config().ads.customer_id)
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(
+    title="Keywords in a negative keyword list",
+    annotations=_READONLY,
+    tags={"ads"},
+)
 @_safe
 def get_negative_keyword_list_keywords(
     shared_set_id: str,
@@ -768,7 +780,11 @@ def get_negative_keyword_list_keywords(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(
+    title="Campaigns using a negative keyword list",
+    annotations=_READONLY,
+    tags={"ads"},
+)
 @_safe
 def get_negative_keyword_list_campaigns(
     shared_set_id: str = "",
@@ -793,7 +809,7 @@ def get_negative_keyword_list_campaigns(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Google Ads recommendations", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_recommendations(
     customer_id: str = "",
@@ -822,7 +838,7 @@ def get_recommendations(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Performance Max performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_pmax_performance(
     customer_id: str = "",
@@ -853,7 +869,11 @@ def get_pmax_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(
+    title="Performance Max asset performance",
+    annotations=_READONLY,
+    tags={"ads"},
+)
 @_safe
 def get_asset_performance(
     customer_id: str = "",
@@ -882,7 +902,11 @@ def get_asset_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(
+    title="Performance Max asset combinations",
+    annotations=_READONLY,
+    tags={"ads"},
+)
 @_safe
 def get_detailed_asset_performance(
     customer_id: str = "",
@@ -905,7 +929,7 @@ def get_detailed_asset_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Audience performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_audience_performance(
     customer_id: str = "",
@@ -936,7 +960,7 @@ def get_audience_performance(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Demographic targeting", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_demographic_targeting(
     ad_group_id: str = "",
@@ -969,7 +993,11 @@ def get_demographic_targeting(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"tracking"})
+@mcp.tool(
+    title="Campaign conversions against Analytics",
+    annotations=_READONLY,
+    tags={"tracking"},
+)
 @_safe
 def analyze_campaign_conversions(
     date_range_start: str = "",
@@ -999,7 +1027,7 @@ def analyze_campaign_conversions(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"tracking"})
+@mcp.tool(title="Landing page analysis", annotations=_READONLY, tags={"tracking"})
 @_safe
 def landing_page_analysis(
     date_range_start: str = "",
@@ -1025,7 +1053,7 @@ def landing_page_analysis(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"tracking"})
+@mcp.tool(title="Attribution check", annotations=_READONLY, tags={"tracking"})
 @_safe
 def attribution_check(
     date_range_start: str = "",
@@ -1056,7 +1084,7 @@ def attribution_check(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tracking coverage audit", annotations=_READONLY, tags={"gtm"})
 @_safe
 def audit_event_coverage(
     expected_events: list[str],
@@ -1109,7 +1137,7 @@ def audit_event_coverage(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager accounts", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_accounts() -> dict:
     """List all GTM accounts the AdLoop service account / OAuth user can read.
@@ -1124,7 +1152,7 @@ def list_gtm_accounts() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager containers", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_containers(gtm_account_id: str = "") -> dict:
     """List all containers under a GTM account.
@@ -1144,7 +1172,7 @@ def list_gtm_containers(gtm_account_id: str = "") -> dict:
     return _impl(current_config(), account_id=gtm_account_id)
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager tags", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_tags(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     """List every tag in the LIVE GTM container.
@@ -1164,7 +1192,7 @@ def list_gtm_tags(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tag Manager tag details", annotations=_READONLY, tags={"gtm"})
 @_safe
 def get_gtm_tag(
     tag_id: str, gtm_account_id: str = "", gtm_container_id: str = ""
@@ -1189,7 +1217,7 @@ def get_gtm_tag(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager triggers", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_triggers(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     """List every trigger in the LIVE GTM container.
@@ -1209,7 +1237,7 @@ def list_gtm_triggers(gtm_account_id: str = "", gtm_container_id: str = "") -> d
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tag Manager trigger details", annotations=_READONLY, tags={"gtm"})
 @_safe
 def get_gtm_trigger(
     trigger_id: str, gtm_account_id: str = "", gtm_container_id: str = ""
@@ -1234,7 +1262,7 @@ def get_gtm_trigger(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager variables", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_variables(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     """List GTM variables — both custom and enabled built-in.
@@ -1256,7 +1284,7 @@ def list_gtm_variables(gtm_account_id: str = "", gtm_container_id: str = "") ->
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="List Tag Manager workspaces", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_workspaces(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     """List workspaces (drafts) under a GTM container.
@@ -1276,7 +1304,7 @@ def list_gtm_workspaces(gtm_account_id: str = "", gtm_container_id: str = "") ->
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tag Manager workspace changes", annotations=_READONLY, tags={"gtm"})
 @_safe
 def get_gtm_workspace_diff(
     workspace_id: str, gtm_account_id: str = "", gtm_container_id: str = ""
@@ -1303,7 +1331,7 @@ def get_gtm_workspace_diff(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tag Manager version history", annotations=_READONLY, tags={"gtm"})
 @_safe
 def list_gtm_versions(
     gtm_account_id: str = "", gtm_container_id: str = "", page_size: int = 50
@@ -1329,7 +1357,7 @@ def list_gtm_versions(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"gtm"})
+@mcp.tool(title="Tag Manager version details", annotations=_READONLY, tags={"gtm"})
 @_safe
 def get_gtm_version(
     container_version_id: str, gtm_account_id: str = "", gtm_container_id: str = ""
@@ -1354,7 +1382,7 @@ def get_gtm_version(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Custom Google Ads query", annotations=_READONLY, tags={"ads"})
 @_safe
 def run_gaql(
     query: str,
@@ -1383,7 +1411,7 @@ def run_gaql(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft a campaign", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_campaign(
     campaign_name: str,
@@ -1450,7 +1478,7 @@ def draft_campaign(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft an ad group", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_ad_group(
     campaign_id: str,
@@ -1483,7 +1511,7 @@ def draft_ad_group(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft campaign changes", annotations=_WRITE, tags={"ads"})
 @_safe
 def update_campaign(
     campaign_id: str,
@@ -1540,7 +1568,7 @@ def update_campaign(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft a responsive search ad", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_responsive_search_ad(
     ad_group_id: str,
@@ -1583,7 +1611,7 @@ def draft_responsive_search_ad(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft keywords", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_keywords(
     ad_group_id: str,
@@ -1605,7 +1633,7 @@ def draft_keywords(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft negative keywords", annotations=_WRITE, tags={"ads"})
 @_safe
 def add_negative_keywords(
     campaign_id: str,
@@ -1630,7 +1658,7 @@ def add_negative_keywords(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft negative locations", annotations=_WRITE, tags={"ads"})
 @_safe
 def add_negative_locations(
     campaign_id: str,
@@ -1654,7 +1682,11 @@ def add_negative_locations(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(
+    title="Draft a shared negative keyword list",
+    annotations=_WRITE,
+    tags={"ads"},
+)
 @_safe
 def propose_negative_keyword_list(
     campaign_id: str,
@@ -1682,7 +1714,11 @@ def propose_negative_keyword_list(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(
+    title="Draft additions to a negative keyword list",
+    annotations=_WRITE,
+    tags={"ads"},
+)
 @_safe
 def add_to_negative_keyword_list(
     shared_set_id: str,
@@ -1715,7 +1751,7 @@ def add_to_negative_keyword_list(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft attaching a shared set", annotations=_WRITE, tags={"ads"})
 @_safe
 def attach_shared_set_to_campaigns(
     shared_set_id: str,
@@ -1746,7 +1782,7 @@ def attach_shared_set_to_campaigns(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft detaching a shared set", annotations=_WRITE, tags={"ads"})
 @_safe
 def detach_shared_set_from_campaigns(
     shared_set_id: str,
@@ -1777,7 +1813,7 @@ def detach_shared_set_from_campaigns(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft demographic targeting", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_demographic_targeting(
     customer_id: str = "",
@@ -1829,7 +1865,7 @@ def draft_demographic_targeting(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft ad group changes", annotations=_WRITE, tags={"ads"})
 @_safe
 def update_ad_group(
     ad_group_id: str,
@@ -1849,7 +1885,7 @@ def update_ad_group(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft callouts", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_callouts(
     campaign_id: str,
@@ -1867,7 +1903,7 @@ def draft_callouts(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft structured snippets", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_structured_snippets(
     campaign_id: str,
@@ -1885,7 +1921,7 @@ def draft_structured_snippets(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft image assets", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_image_assets(
     campaign_id: str,
@@ -1903,7 +1939,7 @@ def draft_image_assets(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft pausing an entity", annotations=_WRITE, tags={"ads"})
 @_safe
 def pause_entity(
     entity_type: str,
@@ -1931,7 +1967,7 @@ def pause_entity(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft enabling an entity", annotations=_WRITE, tags={"ads"})
 @_safe
 def enable_entity(
     entity_type: str,
@@ -1959,7 +1995,7 @@ def enable_entity(
     )
 
 
-@mcp.tool(annotations=_DESTRUCTIVE, tags={"ads"})
+@mcp.tool(title="Draft removing an entity", annotations=_DESTRUCTIVE, tags={"ads"})
 @_safe
 def remove_entity(
     entity_type: str,
@@ -1995,7 +2031,7 @@ def remove_entity(
     )
 
 
-@mcp.tool(annotations=_WRITE, tags={"ads"})
+@mcp.tool(title="Draft sitelinks", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_sitelinks(
     campaign_id: str,
@@ -2028,7 +2064,7 @@ def draft_sitelinks(
     )
 
 
-@mcp.tool(annotations=_DESTRUCTIVE, tags={"core"})
+@mcp.tool(title="Apply a previewed change", annotations=_DESTRUCTIVE, tags={"core"})
 @_safe
 def confirm_and_apply(
     plan_id: str,
@@ -2065,7 +2101,7 @@ def confirm_and_apply(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_WRITE, tags={"ga4"})
+@mcp.tool(title="Draft an Analytics key event", annotations=_WRITE, tags={"ga4"})
 @_safe
 def draft_key_event(
     event_name: str,
@@ -2090,7 +2126,7 @@ def draft_key_event(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"tracking"})
+@mcp.tool(title="Validate tracking", annotations=_READONLY, tags={"tracking"})
 @_safe
 def validate_tracking(
     expected_events: _StrList,
@@ -2118,7 +2154,7 @@ def validate_tracking(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"tracking"})
+@mcp.tool(title="Generate tracking code", annotations=_READONLY, tags={"tracking"})
 @_safe
 def generate_tracking_code(
     event_name: str,
@@ -2153,7 +2189,7 @@ def generate_tracking_code(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Budget forecast", annotations=_READONLY, tags={"ads"})
 @_safe
 def estimate_budget(
     keywords: _DictList,
@@ -2190,7 +2226,7 @@ def estimate_budget(
     )
 
 
-@mcp.tool(annotations=_READONLY, tags={"ads"})
+@mcp.tool(title="Keyword ideas", annotations=_READONLY, tags={"ads"})
 @_safe
 def discover_keywords(
     seed_keywords: _StrList = [],  # noqa: B006 — mutable default required for MCP JSON schema