adloop 0.27.1__tar.gz → 0.28.0__tar.gz

{adloop-0.27.1 → adloop-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.27.1
+Version: 0.28.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
@@ -557,7 +557,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 
 ### Toolsets — trim the context footprint
 
-Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. With AdLoop's full catalog that's a noticeable share of the context window, paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
 
 ```json
 "env": { "ADLOOP_TOOLSETS": "ads,ga4" }
@@ -574,7 +574,15 @@ Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into
 | `merchant` | Merchant Center feed health |
 | `reddit` | Reddit Ads reads, writes, and planning |
 
-`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+Google Ads can be narrowed further. Use one of these instead of `ads`:
+
+| Subset | Covers |
+|---|---|
+| `ads:read` | Ads reports, GAQL, and the Ads/Analytics cross-checks (`attribution_check`, `analyze_campaign_conversions`, `landing_page_analysis`) |
+| `ads:write` | Ads drafts and changes; turns on `ads:read` too, because a draft needs the reads first (IDs, bidding strategy) |
+| `ads:plan` | Keyword ideas and budget forecasts (`discover_keywords`, `estimate_budget`) |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads:read,ga4` costs about 40% of `ads,ga4` for audits and diagnosis, and an `ads:plan`-only client for keyword research pays about 5% of the full catalog. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
 
 On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
 

{adloop-0.27.1 → adloop-0.28.0}/README.md

@@ -529,7 +529,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 
 ### Toolsets — trim the context footprint
 
-Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. With AdLoop's full catalog that's a noticeable share of the context window, paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
 
 ```json
 "env": { "ADLOOP_TOOLSETS": "ads,ga4" }
@@ -546,7 +546,15 @@ Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into
 | `merchant` | Merchant Center feed health |
 | `reddit` | Reddit Ads reads, writes, and planning |
 
-`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+Google Ads can be narrowed further. Use one of these instead of `ads`:
+
+| Subset | Covers |
+|---|---|
+| `ads:read` | Ads reports, GAQL, and the Ads/Analytics cross-checks (`attribution_check`, `analyze_campaign_conversions`, `landing_page_analysis`) |
+| `ads:write` | Ads drafts and changes; turns on `ads:read` too, because a draft needs the reads first (IDs, bidding strategy) |
+| `ads:plan` | Keyword ideas and budget forecasts (`discover_keywords`, `estimate_budget`) |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads:read,ga4` costs about 40% of `ads,ga4` for audits and diagnosis, and an `ads:plan`-only client for keyword research pays about 5% of the full catalog. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
 
 On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
 

{adloop-0.27.1 → adloop-0.28.0}/pyproject.toml

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

{adloop-0.27.1 → adloop-0.28.0}/pyproject.toml.orig

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

{adloop-0.27.1 → adloop-0.28.0}/src/adloop/ads/write.py

@@ -7,6 +7,7 @@ Every write tool returns a preview/plan. Nothing executes until
 from __future__ import annotations
 
 import hashlib
+import re
 import struct
 from pathlib import Path, PurePath, PurePosixPath
 from typing import TYPE_CHECKING
@@ -40,6 +41,31 @@ _VALID_IMAGE_MIME_TYPES = {
 _VALID_HEADLINE_PINS = {"HEADLINE_1", "HEADLINE_2", "HEADLINE_3"}
 _VALID_DESCRIPTION_PINS = {"DESCRIPTION_1", "DESCRIPTION_2"}
 
+# Insertion tags Google expands at serve time. Only the default text after
+# the colon counts toward the 30/90 character caps, e.g.
+# "{KeyWord:Clogged Drain Service}" is 21 characters, not 31. Written with
+# spaces ("{ KeyWord : x }") it is not a tag and counts as plain text.
+_INSERTION_TAG_RE = re.compile(r"\{(keyword|location\([a-z]+\)):([^{}]*)\}", re.IGNORECASE)
+_BARE_INSERTION_TAG_RE = re.compile(r"\{(keyword|location\([a-z]+\))\}", re.IGNORECASE)
+
+
+def _counted_length(text: str) -> int:
+    """Length Google checks against the cap: insertion tags count as their default text."""
+    return len(_INSERTION_TAG_RE.sub(lambda m: m.group(2), text))
+
+
+def _insertion_tag_errors(label: str, text: str) -> list[str]:
+    """RSA keyword/location insertion needs default text, e.g. {KeyWord:Drain Cleaning}."""
+    missing = _BARE_INSERTION_TAG_RE.search(text) or any(
+        not m.group(2).strip() for m in _INSERTION_TAG_RE.finditer(text)
+    )
+    if missing:
+        return [
+            f"{label} uses an insertion tag without default text: '{text}'. "
+            "Default text after a colon is required, e.g. {KeyWord:Drain Cleaning}"
+        ]
+    return []
+
 
 def _normalize_rsa_assets(items: list) -> list[dict]:
     """Accept str or {text, pinned_field?} dict entries; return list of dicts.
@@ -3435,9 +3461,10 @@ def _validate_rsa_assets(
     for i, h in enumerate(headlines):
         text = h["text"]
         pin = h["pinned_field"]
-        if len(text) > 30:
+        errors.extend(_insertion_tag_errors(f"Headline {i + 1}", text))
+        if _counted_length(text) > 30:
             errors.append(
-                f"Headline {i + 1} exceeds 30 chars ({len(text)}): '{text}'"
+                f"Headline {i + 1} exceeds 30 chars ({_counted_length(text)}): '{text}'"
             )
         if pin is not None:
             if pin not in _VALID_HEADLINE_PINS:
@@ -3455,9 +3482,10 @@ def _validate_rsa_assets(
     for i, d in enumerate(descriptions):
         text = d["text"]
         pin = d["pinned_field"]
-        if len(text) > 90:
+        errors.extend(_insertion_tag_errors(f"Description {i + 1}", text))
+        if _counted_length(text) > 90:
             errors.append(
-                f"Description {i + 1} exceeds 90 chars ({len(text)}): '{text}'"
+                f"Description {i + 1} exceeds 90 chars ({_counted_length(text)}): '{text}'"
             )
         if pin is not None:
             if pin not in _VALID_DESCRIPTION_PINS:

{adloop-0.27.1 → adloop-0.28.0}/src/adloop/cli.py

@@ -281,13 +281,16 @@ def _prompt_toolsets() -> str:
     Client-side (env), not config.yaml: the same machine can run one
     full-catalog client and one trimmed client off one AdLoop config.
     """
-    from adloop.server import TOOLSETS
+    from adloop.server import ADS_SUBSETS, TOOLSETS
 
     _print("  AdLoop can expose only some toolsets to your AI client —")
     _print("  a smaller tool list costs less context per conversation.")
     _print()
     for slug, description in TOOLSETS.items():
         _print(f"    {slug:<9} {description}")
+    _print("  Or only part of Google Ads instead of ads:")
+    for slug, description in ADS_SUBSETS.items():
+        _print(f"    {slug:<9} {description}")
     _print()
     _print("  (health_check and confirm_and_apply are always included.)")
     if _prompt_bool("Expose the full toolset?", default=True):
@@ -295,12 +298,12 @@ def _prompt_toolsets() -> str:
     while True:
         raw = _prompt("Toolsets (comma-separated, e.g. ads,ga4)")
         chosen = [part.strip().lower() for part in raw.split(",") if part.strip()]
-        unknown = [slug for slug in chosen if slug not in TOOLSETS]
+        unknown = [slug for slug in chosen if slug not in TOOLSETS and slug not in ADS_SUBSETS]
         if chosen and not unknown:
             return ",".join(dict.fromkeys(chosen))
         _print(
             f"    ⚠  Unknown toolset(s): {', '.join(unknown) or '(none given)'}."
-            f" Valid: {', '.join(TOOLSETS)}"
+            f" Valid: {', '.join([*TOOLSETS, *ADS_SUBSETS])}"
         )
 
 

{adloop-0.27.1 → adloop-0.28.0}/src/adloop/server.py

@@ -48,6 +48,18 @@ TOOLSETS: dict[str, str] = {
     "reddit": "Reddit Ads reads, writes, and planning",
 }
 
+# Finer selections inside "ads" (issue #56): every ads tool also carries
+# exactly one of these, derived in _tool() from its annotations, so "ads"
+# keeps its meaning and a smaller session can ask for just the part it
+# needs. The cross-reference tools that query Ads carry "ads:read" next to
+# their "tracking" tag. Not part of the Cloud contract above.
+ADS_SUBSETS: dict[str, str] = {
+    "ads:read": "Google Ads reports, GAQL and the Ads/Analytics cross-checks",
+    "ads:write": "Google Ads drafts and changes (turns on ads:read too)",
+    "ads:plan": "Keyword ideas and budget forecasts",
+}
+_ADS_PLAN_TOOLS = frozenset({"discover_keywords", "estimate_budget"})
+
 
 def _coerce_json_string_to_list(value):
     """Decode a JSON-array-shaped string into a native list.
@@ -387,17 +399,25 @@ def _tool(*, title: str, annotations: ToolAnnotations, tags: set[str], **kwargs)
             description = f"{description}\n\n{docs}"
         name = kwargs.get("name") or fn.__name__
         options = dict(kwargs)
+        tool_tags = set(tags)
+        if "ads" in tool_tags and not tool_tags & set(ADS_SUBSETS):
+            if name in _ADS_PLAN_TOOLS:
+                tool_tags.add("ads:plan")
+            elif annotations.read_only_hint:
+                tool_tags.add("ads:read")
+            else:
+                tool_tags.add("ads:write")
         if not annotations.read_only_hint and name not in _NO_CARD_TOOLS:
             # Write tools return a preview; apps with MCP Apps support
             # render it as the approval card.
             options["meta"] = {**(options.get("meta") or {}), "ui": {"resourceUri": CARD_URI}}
             fn = _with_approval_card(fn)
         if not is_app_only(options.get("meta")):
-            _TOOL_TAGS[name] = frozenset(tags)
+            _TOOL_TAGS[name] = frozenset(tool_tags)
         return mcp.tool(
             title=title,
             annotations=annotations,
-            tags=tags,
+            tags=tool_tags,
             description=description,
             **options,
         )(fn)
@@ -1739,7 +1759,7 @@ def get_change_history(
 @_tool(
     title="Campaign conversions against Analytics",
     annotations=_READONLY,
-    tags={"tracking"},
+    tags={"tracking", "ads:read"},
 )
 @_safe
 def analyze_campaign_conversions(
@@ -1780,7 +1800,7 @@ def analyze_campaign_conversions(
     )
 
 
-@_tool(title="Landing page analysis", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Landing page analysis", annotations=_READONLY, tags={"tracking", "ads:read"})
 @_safe
 def landing_page_analysis(
     date_range_start: str = "",
@@ -1815,7 +1835,7 @@ def landing_page_analysis(
     )
 
 
-@_tool(title="Attribution check", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Attribution check", annotations=_READONLY, tags={"tracking", "ads:read"})
 @_safe
 def attribution_check(
     date_range_start: str = "",
@@ -3117,10 +3137,13 @@ def draft_responsive_search_ad(
         ad_group_id: Numeric ID of the ad group that gets the ad.
         headlines: 3-15 headlines, max 30 chars each. Each entry is a plain
             string (unpinned) or {"text": "...", "pinned_field": "HEADLINE_1"};
-            valid pins are HEADLINE_1, HEADLINE_2, HEADLINE_3.
+            valid pins are HEADLINE_1, HEADLINE_2, HEADLINE_3. Keyword or
+            location insertion such as {KeyWord:Drain Cleaning} counts as its
+            default text, which is required.
         descriptions: 2-4 descriptions, max 90 chars each. Each entry is a plain
             string (unpinned) or {"text": "...", "pinned_field": "DESCRIPTION_1"};
-            valid pins are DESCRIPTION_1, DESCRIPTION_2.
+            valid pins are DESCRIPTION_1, DESCRIPTION_2. Insertion tags count
+            as their default text, as for headlines.
         final_url: Landing page URL the ad links to; must be reachable.
         customer_id: Google Ads customer ID (digits, e.g. "1234567890"). Empty
             uses the configured default account.
@@ -3183,11 +3206,13 @@ def update_responsive_search_ad(
             fully swaps in for the existing headlines. Google's RSA constraints
             apply: 3-15 headlines, max 30 chars each, at most 2 per pin slot.
             Each entry is a plain string (unpinned) or {"text": "...",
-            "pinned_field": "HEADLINE_1"} (HEADLINE_1-3).
+            "pinned_field": "HEADLINE_1"} (HEADLINE_1-3). Insertion tags such as
+            {KeyWord:Clogged Drain Service} count as their default text, which
+            is required.
         descriptions: LIST-REPLACE: None or [] means no change; a non-empty list
             fully swaps in. 2-4 descriptions, max 90 chars each, at most 1 per
-            pin slot (DESCRIPTION_1, DESCRIPTION_2). Same entry format as
-            headlines.
+            pin slot (DESCRIPTION_1, DESCRIPTION_2). Same entry format and
+            insertion-tag counting as headlines.
         final_url: Empty means no change; non-empty replaces the final URL and
             is checked for reachability.
         path1: Empty means no change; non-empty sets the first display path
@@ -6470,18 +6495,24 @@ def _apply_toolsets_env() -> None:
 
     Unset/empty = the full catalog. Core tools (health_check,
     confirm_and_apply) survive every selection. A smaller tools/list costs
-    less context in MCP clients that load all tool schemas upfront.
+    less context in MCP clients that load all tool schemas upfront. Besides
+    the toolsets, the ads subsets (ads:read, ads:write, ads:plan) narrow
+    Google Ads further; ads:write brings ads:read along, because a draft
+    needs the reads first (IDs, bidding strategy).
     """
     raw = _os.getenv("ADLOOP_TOOLSETS", "").strip()
     if not raw:
         return
     requested = {part.strip().lower() for part in raw.split(",") if part.strip()}
-    unknown = sorted(requested - set(TOOLSETS))
+    unknown = sorted(requested - set(TOOLSETS) - set(ADS_SUBSETS))
     if unknown:
         raise ValueError(
             f"ADLOOP_TOOLSETS names unknown toolset(s): {', '.join(unknown)}. "
-            f"Valid toolsets: {', '.join(TOOLSETS)}. Example: ADLOOP_TOOLSETS=ads,ga4"
+            f"Valid toolsets: {', '.join([*TOOLSETS, *ADS_SUBSETS])}. "
+            "Example: ADLOOP_TOOLSETS=ads,ga4 or ADLOOP_TOOLSETS=ads:read,ga4"
         )
+    if "ads:write" in requested:
+        requested.add("ads:read")
     global _ENABLED_TAGS
     _ENABLED_TAGS = requested | {"core"}
     mcp.enable(tags=_ENABLED_TAGS, only=True)