adloop 0.27.2__tar.gz → 0.28.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.27.2
+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.2 → 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.2 → adloop-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.27.2"
+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.2 → adloop-0.28.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.27.2"
+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.2 → 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.2 → 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 = "",
@@ -6475,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)