adloop 0.30.0__tar.gz → 0.32.0__tar.gz

{adloop-0.30.0 → adloop-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.30.0
+Version: 0.32.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
@@ -206,7 +206,8 @@ Off by default. Set `gtm.write_enabled: true` in `~/.adloop/config.yaml` and res
 |------|-------------|
 | `draft_gtm_tag` | Create a tag, or update one by `tag_id`. Updates are a read-modify-write: `parameters` merge by key and every field you don't pass (priority, consent settings, firing options, schedule, folder, …) is preserved. Tag types are canonical GTM template IDs (`googtag`, `gaawe`, `awct`, `sp`, `gclidw`, …) or `cvt_<id>` gallery templates. |
 | `draft_gtm_trigger` | Create a trigger, or update one by `trigger_id` (type is immutable). `custom_event_name` wires a `customEvent` trigger to a dataLayer event. |
-| `draft_delete_gtm_entity` | Delete a workspace tag or trigger. Triggers still referenced by a tag are refused up front, with the tags listed. |
+| `draft_gtm_variable` | Create or update variables, e.g. Data Layer Variables for GA4 ecommerce values; renaming a referenced variable is refused, Custom JavaScript is gated |
+| `draft_delete_gtm_entity` | Delete a workspace tag, trigger or variable. Triggers and variables still in use are refused up front, with the references listed. |
 | `draft_publish_gtm_workspace` | Publish a workspace live. The preview lists every pending change, including edits other people made in the GTM UI. |
 | `draft_rollback_gtm_version` | Republish an older container version live. The preview is the diff from the live version to the target; the plan pins the live version, so apply refuses if someone publishes in between. Workspaces are left as they are. |
 

{adloop-0.30.0 → adloop-0.32.0}/README.md

@@ -178,7 +178,8 @@ Off by default. Set `gtm.write_enabled: true` in `~/.adloop/config.yaml` and res
 |------|-------------|
 | `draft_gtm_tag` | Create a tag, or update one by `tag_id`. Updates are a read-modify-write: `parameters` merge by key and every field you don't pass (priority, consent settings, firing options, schedule, folder, …) is preserved. Tag types are canonical GTM template IDs (`googtag`, `gaawe`, `awct`, `sp`, `gclidw`, …) or `cvt_<id>` gallery templates. |
 | `draft_gtm_trigger` | Create a trigger, or update one by `trigger_id` (type is immutable). `custom_event_name` wires a `customEvent` trigger to a dataLayer event. |
-| `draft_delete_gtm_entity` | Delete a workspace tag or trigger. Triggers still referenced by a tag are refused up front, with the tags listed. |
+| `draft_gtm_variable` | Create or update variables, e.g. Data Layer Variables for GA4 ecommerce values; renaming a referenced variable is refused, Custom JavaScript is gated |
+| `draft_delete_gtm_entity` | Delete a workspace tag, trigger or variable. Triggers and variables still in use are refused up front, with the references listed. |
 | `draft_publish_gtm_workspace` | Publish a workspace live. The preview lists every pending change, including edits other people made in the GTM UI. |
 | `draft_rollback_gtm_version` | Republish an older container version live. The preview is the diff from the live version to the target; the plan pins the live version, so apply refuses if someone publishes in between. Workspaces are left as they are. |
 

{adloop-0.30.0 → adloop-0.32.0}/pyproject.toml

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

{adloop-0.30.0 → adloop-0.32.0}/pyproject.toml.orig

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

{adloop-0.30.0 → adloop-0.32.0}/src/adloop/ads/write.py

@@ -550,9 +550,10 @@ def draft_responsive_search_ad(
         headlines:    HEADLINE_1, HEADLINE_2, HEADLINE_3
         descriptions: DESCRIPTION_1, DESCRIPTION_2
 
-    Google caps: at most 2 headlines per pin slot, at most 1 description per
-    pin slot. Mixed plain-string and dict entries are allowed within a single
-    call (e.g. brand pinned to HEADLINE_1, the rest unpinned).
+    Several assets may pin to the same position (Google rotates them there),
+    as long as every position stays fillable: by an asset pinned to it or by
+    a distinct unpinned asset. Mixed plain-string and dict entries are allowed
+    within a single call (e.g. brand pinned to HEADLINE_1, the rest unpinned).
     """
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
@@ -2055,12 +2056,19 @@ def remove_entity(
     if entity_type in ("campaign_asset", "customer_asset"):
         entity_id = entity_id.replace(",", "~")
 
+    names, not_found = _describe_target(config, customer_id, entity_type, entity_id)
+    if not_found:
+        return {"error": not_found}
+
     plan = ChangePlan(
         operation="remove_entity",
         entity_type=entity_type,
         entity_id=entity_id,
         customer_id=customer_id,
-        changes={"action": "REMOVE"},
+        changes={"action": "REMOVE", **names, **(
+            {"warnings": ["This entity is already REMOVED; applying changes nothing."]}
+            if names.get("current_status") == "REMOVED" else {}
+        )},
         # Removal is irreversible; the preview asks for a second explicit
         # confirmation, as Reddit removals already did.
         requires_double_confirm=True,
@@ -3457,7 +3465,6 @@ def _validate_rsa_assets(
         if len(descriptions) > 4:
             errors.append(f"Maximum 4 descriptions, got {len(descriptions)}")
 
-    headline_pin_counts: dict[str, int] = {}
     for i, h in enumerate(headlines):
         text = h["text"]
         pin = h["pinned_field"]
@@ -3472,13 +3479,8 @@ def _validate_rsa_assets(
                     f"Headline {i + 1} pinned_field '{pin}' invalid; "
                     f"must be one of {sorted(_VALID_HEADLINE_PINS)} or null"
                 )
-            else:
-                headline_pin_counts[pin] = headline_pin_counts.get(pin, 0) + 1
-    for pin, count in headline_pin_counts.items():
-        if count > 2:
-            errors.append(f"At most 2 headlines may pin to {pin}; got {count}")
+    errors.extend(_pin_fill_errors("headline", headlines, _VALID_HEADLINE_PINS))
 
-    description_pin_counts: dict[str, int] = {}
     for i, d in enumerate(descriptions):
         text = d["text"]
         pin = d["pinned_field"]
@@ -3493,15 +3495,37 @@ def _validate_rsa_assets(
                     f"Description {i + 1} pinned_field '{pin}' invalid; "
                     f"must be one of {sorted(_VALID_DESCRIPTION_PINS)} or null"
                 )
-            else:
-                description_pin_counts[pin] = description_pin_counts.get(pin, 0) + 1
-    for pin, count in description_pin_counts.items():
-        if count > 1:
-            errors.append(f"At most 1 description may pin to {pin}; got {count}")
+    errors.extend(_pin_fill_errors("description", descriptions, _VALID_DESCRIPTION_PINS))
 
     return errors
 
 
+def _pin_fill_errors(kind: str, assets: list[dict], positions: set[str]) -> list[str]:
+    """Google's pinning rule: every position must be fillable, either by an
+    asset pinned to it or by a distinct unpinned asset.
+
+    Google sets no cap on how many assets pin to one position (they rotate
+    there), so several headlines pinned to HEADLINE_1 are fine as long as the
+    other positions can still be filled. Breaking the rule fails at Google with
+    NOT_ENOUGH_AVAILABLE_ASSET_LINKS_FOR_VALID_COMBINATION.
+    """
+    if not assets:
+        return []
+    pinned = {a["pinned_field"] for a in assets if a.get("pinned_field") in positions}
+    if not pinned:
+        return []
+    empty = sorted(positions - pinned)
+    unpinned = sum(1 for a in assets if not a.get("pinned_field"))
+    if unpinned >= len(empty):
+        return []
+    return [
+        f"Pinning leaves {', '.join(empty)} without enough {kind}s: "
+        f"{len(empty)} position(s) have no pinned {kind} and need one distinct "
+        f"unpinned {kind} each, but only {unpinned} {kind}(s) are unpinned. "
+        f"Unpin a {kind}, add more unpinned ones, or pin one to each empty position."
+    ]
+
+
 def _validate_rsa(
     ad_group_id: str,
     headlines: list[dict],
@@ -3815,6 +3839,98 @@ def _preflight_ad_group_checks(
     return errors, warnings
 
 
+# What the preview of a pause, enable or remove names besides the IDs:
+# (query resource, id fields, name field, extra fields) per entity type. The
+# names reach the approval card and the confirmation dialog, where an ID alone
+# is hard to check, and a lookup that finds nothing exposes a mistyped ID.
+_TARGET_LOOKUPS: dict[str, tuple[str, tuple[str, ...], str, dict[str, str]]] = {
+    "campaign": ("campaign", ("campaign.id",), "campaign.name",
+                 {"current_status": "campaign.status"}),
+    "ad_group": ("ad_group", ("ad_group.id",), "ad_group.name",
+                 {"campaign_name": "campaign.name", "current_status": "ad_group.status"}),
+    "ad": ("ad_group_ad", ("ad_group_ad.ad.id",), "ad_group_ad.ad.name",
+           {"ad_group_name": "ad_group.name", "campaign_name": "campaign.name",
+            "current_status": "ad_group_ad.status"}),
+    "keyword": ("ad_group_criterion", ("ad_group.id", "ad_group_criterion.criterion_id"),
+                "ad_group_criterion.keyword.text",
+                {"match_type": "ad_group_criterion.keyword.match_type",
+                 "ad_group_name": "ad_group.name", "campaign_name": "campaign.name",
+                 "current_status": "ad_group_criterion.status"}),
+    "asset_group": ("asset_group", ("asset_group.id",), "asset_group.name",
+                    {"campaign_name": "campaign.name", "current_status": "asset_group.status"}),
+    "negative_keyword": ("campaign_criterion", ("campaign.id", "campaign_criterion.criterion_id"),
+                         "campaign_criterion.keyword.text", {"campaign_name": "campaign.name"}),
+    "campaign_criterion": ("campaign_criterion", ("campaign.id", "campaign_criterion.criterion_id"),
+                           "campaign_criterion.type", {"campaign_name": "campaign.name"}),
+    "ad_group_criterion": ("ad_group_criterion", ("ad_group.id", "ad_group_criterion.criterion_id"),
+                           "ad_group_criterion.type",
+                           {"ad_group_name": "ad_group.name", "campaign_name": "campaign.name"}),
+}
+
+
+def _format_customer(customer_id: object) -> str:
+    digits = str(customer_id or "").replace("-", "")
+    return f"{digits[:3]}-{digits[3:6]}-{digits[6:]}" if len(digits) == 10 else digits
+
+
+def _describe_target(
+    config: AdLoopConfig, customer_id: str, entity_type: str, entity_id: str
+) -> tuple[dict, str | None]:
+    """Names for a status change or removal preview: ``({names}, error)``.
+
+    One GAQL query reads the account name and, for the entity types above,
+    the entity's name, its campaign or ad group and its current status. A
+    failed lookup (API error, an ID format this does not know) returns no
+    names and no error, so the preview falls back to the IDs. A lookup that
+    succeeds but finds no such entity returns an error: the ID is wrong.
+    """
+    from adloop.ads.gaql import execute_query
+
+    spec = _TARGET_LOOKUPS.get(entity_type)
+    parts = entity_id.split("~")
+    if entity_type == "ad" and len(parts) == 2:
+        parts = parts[1:]  # adGroupId~adId: the ad id alone identifies it
+    if spec and (len(parts) != len(spec[1]) or not all(p.isdigit() for p in parts)):
+        spec = None
+    try:
+        if spec:
+            resource, id_fields, name_field, extra = spec
+            fields = ["customer.descriptive_name", "customer.id", name_field, *extra.values()]
+            where = " AND ".join(f"{f} = {v}" for f, v in zip(id_fields, parts))
+            rows = execute_query(
+                config, customer_id,
+                f"SELECT {', '.join(fields)} FROM {resource} WHERE {where} LIMIT 1",
+            )
+        else:
+            rows = execute_query(
+                config, customer_id, "SELECT customer.descriptive_name, customer.id FROM customer LIMIT 1"
+            )
+    except Exception:
+        return {}, None
+    if not rows:
+        if spec:
+            return {}, (
+                f"No {entity_type.replace('_', ' ')} with ID {entity_id} in account "
+                f"{_format_customer(customer_id) or 'the default account'}. Check the ID "
+                "with a read tool (get_campaign_performance, get_ad_performance, ...)."
+            )
+        return {}, None
+    row = rows[0]
+    names: dict = {}
+    account = row.get("customer.descriptive_name") or ""
+    cid = _format_customer(row.get("customer.id"))
+    if account or cid:
+        names["account"] = f"{account} ({cid})" if account and cid else account or cid
+    if spec:
+        name = row.get(spec[2])
+        if name:
+            names["entity_name"] = str(name)
+        for key, field_name in spec[3].items():
+            if row.get(field_name) not in (None, ""):
+                names[key] = str(row[field_name])
+    return names, None
+
+
 def _draft_status_change(
     config: AdLoopConfig,
     operation: str,
@@ -3841,12 +3957,21 @@ def _draft_status_change(
     if errors:
         return {"error": "Validation failed", "details": errors}
 
+    names, not_found = _describe_target(config, customer_id, entity_type, entity_id)
+    if not_found:
+        return {"error": not_found}
+    changes: dict = {"target_status": target_status, **names}
+    if names.get("current_status") == target_status:
+        changes["warnings"] = [
+            f"This {entity_type.replace('_', ' ')} is already {target_status}; applying changes nothing."
+        ]
+
     plan = ChangePlan(
         operation=operation,
         entity_type=entity_type,
         entity_id=entity_id,
         customer_id=customer_id,
-        changes={"target_status": target_status},
+        changes=changes,
     )
     store_plan(plan)
     return plan.to_preview()

{adloop-0.30.0 → adloop-0.32.0}/src/adloop/gtm/write.py

@@ -18,10 +18,10 @@ Three gates sit on top of that, all enforced here rather than advised:
   every page they fire on. Creating or editing one, or publishing a
   workspace (or rolling back to a version) that adds or changes one, is
   refused unless this is on. Pausing
-  or deleting one is always allowed (both reduce what runs). The gate matches
-  the tag type ``html``: a Custom JavaScript variable or a custom template
-  tag (``cvt_…``), which can inject a script, is not covered and has to be
-  reviewed in the GTM UI.
+  or deleting one is always allowed (both reduce what runs). Creating or
+  editing a Custom JavaScript variable (``jsm``) is gated the same way. A
+  custom template (``cvt_…``), which runs sandboxed code, is not covered
+  and has to be reviewed in the GTM UI.
 * Concurrency — every update/delete pins the entity fingerprint read at draft
   time, and publish pins a digest of the workspace's pending changes. A
   rollback pins the live version it replaces and the target's fingerprint. If
@@ -78,6 +78,25 @@ KNOWN_TRIGGER_TYPES = {
     "triggerGroup",
 }
 
+# GTM API variable type values the draft accepts. Custom templates use
+# ``cvt_<id>`` like tags. ``jsm`` (Custom JavaScript) runs code on the site
+# and is gated by gtm.allow_custom_html.
+KNOWN_VARIABLE_TYPES: dict[str, str] = {
+    "v": "Data Layer Variable",
+    "c": "Constant",
+    "u": "URL",
+    "k": "1st-Party Cookie",
+    "j": "JavaScript Variable (reads a global, runs no code)",
+    "aev": "Auto-Event Variable",
+    "d": "DOM Element",
+    "f": "HTTP Referrer",
+    "e": "Custom Event",
+    "smm": "Lookup Table",
+    "remm": "RegEx Table",
+    "jsm": "Custom JavaScript (gated by gtm.allow_custom_html)",
+}
+CUSTOM_JAVASCRIPT = "jsm"
+
 # Trigger request fields the draft tool can set, keyed by the tool's
 # snake_case argument name.
 _TRIGGER_FIELDS = {
@@ -314,25 +333,29 @@ def _summarize_changes(status: dict) -> list[dict]:
 
 
 def _custom_html_changes(status: dict) -> list[dict]:
-    """Custom HTML tags the publish would add or change (deletes are fine)."""
-    return [
-        {"tag_id": c["tag"].get("tagId"), "name": c["tag"].get("name"),
-         "change_status": c.get("changeStatus")}
-        for c in status.get("workspaceChange", []) or []
-        if "tag" in c
-        and c["tag"].get("type") == CUSTOM_HTML
-        and c.get("changeStatus") != "deleted"
-    ]
+    """Custom HTML tags and Custom JavaScript variables the publish would add
+    or change (deletes are fine)."""
+    out = []
+    for c in status.get("workspaceChange", []) or []:
+        if c.get("changeStatus") == "deleted":
+            continue
+        if "tag" in c and c["tag"].get("type") == CUSTOM_HTML:
+            out.append({"tag_id": c["tag"].get("tagId"), "name": c["tag"].get("name"),
+                        "change_status": c.get("changeStatus")})
+        elif "variable" in c and c["variable"].get("type") == CUSTOM_JAVASCRIPT:
+            out.append({"variable_id": c["variable"].get("variableId"), "name": c["variable"].get("name"),
+                        "change_status": c.get("changeStatus")})
+    return out
 
 
 def _custom_html_pending_changes(pending: list[dict]) -> list[dict]:
     """The same check against a stored preview's summarized pending changes."""
     return [
-        {"tag_id": c.get("entity_id"), "name": c.get("name"),
+        {"entity_kind": c.get("entity_kind"), "id": c.get("entity_id"), "name": c.get("name"),
          "change_status": c.get("change_status")}
         for c in pending
-        if c.get("entity_kind") == "tag"
-        and c.get("type") == CUSTOM_HTML
+        if ((c.get("entity_kind") == "tag" and c.get("type") == CUSTOM_HTML)
+            or (c.get("entity_kind") == "variable" and c.get("type") == CUSTOM_JAVASCRIPT))
         and c.get("change_status") != "deleted"
     ]
 
@@ -610,6 +633,152 @@ def draft_gtm_trigger(
     return _store(operation, "gtm_trigger", trigger_id, changes, warnings=warnings)
 
 
+def _variable_references(ws, ws_path: str, name: str, *, skip_variable_id: str = "") -> list[dict]:
+    """Tags, triggers and variables whose fields mention {{name}}."""
+    if not name:
+        return []
+    needle = "{{" + name + "}}"
+    found = []
+    for kind, method, id_field in (("tag", ws.tags, "tagId"), ("trigger", ws.triggers, "triggerId"),
+                                   ("variable", ws.variables, "variableId")):
+        for entity in method().list(parent=ws_path).execute().get(kind, []) or []:
+            if kind == "variable" and str(entity.get(id_field)) == skip_variable_id:
+                continue
+            if needle in json.dumps(entity):
+                found.append({"kind": kind, "id": entity.get(id_field), "name": entity.get("name")})
+    return found
+
+
+def draft_gtm_variable(
+    config: AdLoopConfig,
+    *,
+    account_id: str,
+    container_id: str,
+    variable_id: str = "",
+    workspace_id: str = "",
+    name: str = "",
+    variable_type: str = "",
+    data_layer_key: str = "",
+    default_value: str | None = None,
+    parameters: list[dict] | None = None,
+    notes: str | None = None,
+) -> dict:
+    """Create (no ``variable_id``) or update (``variable_id`` set) a variable."""
+    _require_writes(config)
+    operation = "gtm_update_variable" if variable_id else "gtm_create_variable"
+    blocked = _blocked(operation, config)
+    if blocked:
+        return blocked
+
+    errors: list[str] = _validate_parameters(parameters, "parameters")
+    if name and (len(name) > 200 or "{" in name or "}" in name):
+        errors.append("name must be 1-200 characters without curly braces")
+    if variable_id and variable_type:
+        errors.append("variable_type cannot be changed on an existing variable; delete it and create a new one")
+    if not variable_id:
+        if not name:
+            errors.append("name is required when creating a variable")
+        if variable_type not in KNOWN_VARIABLE_TYPES and not variable_type.startswith(_CUSTOM_TEMPLATE_PREFIX):
+            errors.append(
+                f"variable_type '{variable_type}' invalid; valid: "
+                + ", ".join(f"{k} ({v})" for k, v in KNOWN_VARIABLE_TYPES.items())
+                + ", or cvt_<id> for a custom template"
+            )
+        if variable_type == "v" and not data_layer_key and not any(
+            p.get("key") == "name" for p in parameters or []
+        ):
+            errors.append("data_layer_key is required for a Data Layer Variable, e.g. 'ecommerce.value'")
+    if (data_layer_key or default_value is not None) and variable_type and variable_type != "v":
+        errors.append("data_layer_key and default_value only apply to Data Layer Variables (variable_type='v')")
+    if variable_type == CUSTOM_JAVASCRIPT and not config.gtm.allow_custom_html:
+        return _custom_html_refusal("a Custom JavaScript variable")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    # Data Layer Variable fields, from the shortcut arguments.
+    shortcut: list[dict] = []
+    if data_layer_key:
+        shortcut += [
+            {"type": "INTEGER", "key": "dataLayerVersion", "value": "2"},
+            {"type": "TEMPLATE", "key": "name", "value": data_layer_key},
+        ]
+    if default_value is not None:
+        shortcut += [
+            {"type": "BOOLEAN", "key": "setDefaultValue", "value": "true"},
+            {"type": "TEMPLATE", "key": "defaultValue", "value": default_value},
+        ]
+
+    client = _client(config)
+    ws_id, ws_name = _resolve_workspace(client, account_id, container_id, workspace_id)
+    base = {
+        "account_id": account_id,
+        "container_id": container_id,
+        "workspace_id": ws_id,
+        "workspace_name": ws_name,
+    }
+    ws = _workspaces(client)
+    warnings = [
+        f"This edits workspace '{ws_name}' only. Nothing changes on the site "
+        "until the workspace is published (draft_publish_gtm_workspace)."
+    ]
+    variables = ws.variables().list(parent=_ws_path(base)).execute().get("variable", []) or []
+
+    if not variable_id:
+        if any(v.get("name") == name for v in variables):
+            return {"error": f"A variable named '{name}' already exists in workspace '{ws_name}'; update it with its variable_id instead."}
+        body: dict[str, Any] = {
+            "name": name,
+            "type": variable_type,
+            "parameter": _merge_parameters(shortcut, list(parameters or [])),
+        }
+        if notes:
+            body["notes"] = notes
+        warnings.append(f"Tags and triggers use it as {{{{{name}}}}}.")
+        return _store(operation, "gtm_variable", ws_id, {**base, "variable": body}, warnings=warnings)
+
+    var_path = f"{_ws_path(base)}/variables/{variable_id}"
+    existing = ws.variables().get(path=var_path).execute()
+    if existing.get("type") == CUSTOM_JAVASCRIPT and not config.gtm.allow_custom_html:
+        return _custom_html_refusal("editing a Custom JavaScript variable")
+    if (data_layer_key or default_value is not None) and existing.get("type") != "v":
+        return {"error": "data_layer_key and default_value only apply to Data Layer Variables"}
+    patch: dict[str, Any] = {}
+    if name and name != existing.get("name"):
+        if any(v.get("name") == name for v in variables):
+            return {"error": f"A variable named '{name}' already exists in workspace '{ws_name}'."}
+        users = _variable_references(ws, _ws_path(base), existing.get("name", ""), skip_variable_id=str(variable_id))
+        if users:
+            return {
+                "error": (
+                    f"Variable '{existing.get('name')}' is referenced by {len(users)} tag(s), "
+                    "trigger(s) or variable(s), and renaming it through the API would break those "
+                    "{{…}} references. Rename it in the GTM UI, which updates them."
+                ),
+                "referenced_by": users,
+            }
+        patch["name"] = name
+    updates = shortcut + list(parameters or [])
+    if updates:
+        patch["parameter"] = _merge_parameters(existing.get("parameter", []), updates)
+    if notes is not None:
+        patch["notes"] = notes
+    patch = {k: v for k, v in patch.items() if existing.get(k) != v}
+    if not patch:
+        return {"error": "No changes: every field passed already matches the variable."}
+
+    changes = {
+        **base,
+        "variable_id": str(variable_id),
+        "variable_name": existing.get("name"),
+        "variable_type": existing.get("type"),
+        "fingerprint": existing.get("fingerprint"),
+        "patch": patch,
+        "before": {k: existing.get(k) for k in patch},
+    }
+    warnings.append("Every tag and trigger that uses this variable picks up the new value.")
+    return _store(operation, "gtm_variable", variable_id, changes, warnings=warnings)
+
+
 def draft_delete_gtm_entity(
     config: AdLoopConfig,
     *,
@@ -619,10 +788,10 @@ def draft_delete_gtm_entity(
     entity_id: str,
     workspace_id: str = "",
 ) -> dict:
-    """Delete a workspace tag or trigger (``entity_type`` = tag | trigger)."""
+    """Delete a workspace tag, trigger or variable."""
     _require_writes(config)
-    if entity_type not in ("tag", "trigger"):
-        return {"error": "entity_type must be 'tag' or 'trigger'"}
+    if entity_type not in ("tag", "trigger", "variable"):
+        return {"error": "entity_type must be 'tag', 'trigger' or 'variable'"}
     operation = f"gtm_delete_{entity_type}"
     blocked = _blocked(operation, config)
     if blocked:
@@ -639,9 +808,22 @@ def draft_delete_gtm_entity(
         "workspace_name": ws_name,
     }
     ws = _workspaces(client)
-    api = ws.tags() if entity_type == "tag" else ws.triggers()
+    api = getattr(ws, f"{entity_type}s")()
     existing = api.get(path=f"{_ws_path(base)}/{entity_type}s/{entity_id}").execute()
 
+    if entity_type == "variable":
+        users = _variable_references(ws, _ws_path(base), existing.get("name", ""), skip_variable_id=str(entity_id))
+        if users:
+            return {
+                "error": (
+                    f"Variable '{existing.get('name')}' is referenced by {len(users)} "
+                    "tag(s), trigger(s) or variable(s); deleting it would break "
+                    "them. Remove the {{" + str(existing.get("name")) + "}} "
+                    "references first."
+                ),
+                "referenced_by": users,
+            }
+
     if entity_type == "trigger":
         # GTM refuses to delete a referenced trigger; say which tags up front
         # instead of letting apply fail with a bare 400.
@@ -754,13 +936,19 @@ def draft_publish_gtm_workspace(
 
 
 def _custom_html_in_diff(diff: dict) -> list[dict]:
-    """Custom HTML tags a version change would add or change (removals are fine)."""
-    tags = diff.get("tags", {})
+    """Custom HTML tags and Custom JavaScript variables a version change would
+    add or change (removals are fine)."""
+    tags, variables = diff.get("tags", {}), diff.get("variables", {})
     return [
         {"tag_id": t.get("id"), "name": t.get("name"), "change_status": status}
         for status in ("added", "changed")
         for t in tags.get(status, [])
         if t.get("type") == CUSTOM_HTML
+    ] + [
+        {"variable_id": v.get("id"), "name": v.get("name"), "change_status": status}
+        for status in ("added", "changed")
+        for v in variables.get(status, [])
+        if v.get("type") == CUSTOM_JAVASCRIPT
     ]
 
 
@@ -945,13 +1133,17 @@ def _check_target_unchanged(client, plan: ChangePlan) -> dict:
     return target
 
 
+def _entity_kind(plan: ChangePlan) -> str:
+    return plan.entity_type.replace("gtm_", "")
+
+
 def _entity_api(client, plan: ChangePlan):
     ws = _workspaces(client)
-    return ws.tags() if plan.entity_type == "gtm_tag" else ws.triggers()
+    return getattr(ws, f"{_entity_kind(plan)}s")()
 
 
 def _entity_path(plan: ChangePlan) -> str:
-    kind = "tag" if plan.entity_type == "gtm_tag" else "trigger"
+    kind = _entity_kind(plan)
     return f"{_ws_path(plan.changes)}/{kind}s/{plan.changes[f'{kind}_id']}"
 
 
@@ -974,6 +1166,10 @@ def _check_gates(config: AdLoopConfig, plan: ChangePlan) -> None:
     elif op == "gtm_update_tag":
         html = (changes.get("tag_type") == CUSTOM_HTML
                 and changes["patch"] != {"paused": True})
+    elif op == "gtm_create_variable":
+        html = changes["variable"].get("type") == CUSTOM_JAVASCRIPT
+    elif op == "gtm_update_variable":
+        html = changes.get("variable_type") == CUSTOM_JAVASCRIPT
     else:
         html = op == "gtm_create_tag" and changes["tag"].get("type") == CUSTOM_HTML
     if html:
@@ -997,7 +1193,7 @@ def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict:
     changes = plan.changes
     checks: dict[str, Any] = {"workspace": changes.get("workspace_name")}
     try:
-        if plan.operation in ("gtm_create_tag", "gtm_create_trigger"):
+        if plan.operation in ("gtm_create_tag", "gtm_create_trigger", "gtm_create_variable"):
             _workspaces(client).get(path=_ws_path(changes)).execute()
             checks["workspace_exists"] = True
         elif plan.operation == "gtm_publish_workspace":
@@ -1082,7 +1278,15 @@ def _apply(config: AdLoopConfig, plan: ChangePlan) -> dict:
                 "type": resp.get("type"), "workspace_id": changes["workspace_id"],
                 "published": False}
 
-    if op in ("gtm_update_tag", "gtm_update_trigger"):
+    if op == "gtm_create_variable":
+        resp = ws.variables().create(
+            parent=_ws_path(changes), body=changes["variable"]
+        ).execute()
+        return {"variable_id": resp.get("variableId"), "name": resp.get("name"),
+                "type": resp.get("type"), "workspace_id": changes["workspace_id"],
+                "published": False}
+
+    if op in ("gtm_update_tag", "gtm_update_trigger", "gtm_update_variable"):
         api = _entity_api(client, plan)
         path = _entity_path(plan)
         current = _check_fingerprint(api, path, changes.get("fingerprint"),
@@ -1094,18 +1298,18 @@ def _apply(config: AdLoopConfig, plan: ChangePlan) -> dict:
         body.update(copy.deepcopy(changes["patch"]))
         resp = api.update(path=path, body=body,
                           fingerprint=current.get("fingerprint")).execute()
-        kind = "tag" if plan.entity_type == "gtm_tag" else "trigger"
+        kind = _entity_kind(plan)
         return {f"{kind}_id": resp.get(f"{kind}Id"), "name": resp.get("name"),
                 "updated_fields": sorted(changes["patch"]),
                 "workspace_id": changes["workspace_id"], "published": False}
 
-    if op in ("gtm_delete_tag", "gtm_delete_trigger"):
+    if op in ("gtm_delete_tag", "gtm_delete_trigger", "gtm_delete_variable"):
         api = _entity_api(client, plan)
         path = _entity_path(plan)
         _check_fingerprint(api, path, changes.get("fingerprint"),
                            plan.entity_type.replace("gtm_", ""))
         api.delete(path=path).execute()
-        kind = "tag" if plan.entity_type == "gtm_tag" else "trigger"
+        kind = _entity_kind(plan)
         return {f"deleted_{kind}_id": changes[f"{kind}_id"],
                 "workspace_id": changes["workspace_id"], "published": False}
 

{adloop-0.30.0 → adloop-0.32.0}/src/adloop/rules/adloop.md

@@ -131,14 +131,16 @@ These tools call both APIs internally and return unified results with computed `
 |------|-------------|----------------|
 | `draft_gtm_tag` | Create a tag (no `tag_id`) or update one (`tag_id`) in a workspace. On update, `parameters` merge by key and every field you don't pass is preserved | `name`, `tag_type` (create only: `googtag`, `gaawe`, `awct`, `awcc`, `awud`, `sp`, `gclidw`, `flc`, `fls`, `img`, `html`, `cvt_<id>`), `parameters`, `firing_trigger_ids`, `blocking_trigger_ids`, `paused` |
 | `draft_gtm_trigger` | Create a trigger (no `trigger_id`) or update one | `name`, `trigger_type` (camelCase API values: `pageview`, `domReady`, `click`, `linkClick`, `formSubmission`, `customEvent`, `elementVisibility`, …), `custom_event_name`, `filters` |
-| `draft_delete_gtm_entity` | Delete a workspace tag or trigger. Referenced triggers are refused with the referencing tags listed | `entity_type` (`tag`/`trigger`), `entity_id` |
+| `draft_gtm_variable` | Create a variable (no `variable_id`) or update one. Data Layer Variables take `data_layer_key` (e.g. `ecommerce.value`); renaming a variable that tags or triggers use as `{{name}}` is refused | `name`, `variable_type` (`v` Data Layer, `c` Constant, `u` URL, `k` cookie, `j` JS global, `aev`, `d`, `smm`, `remm`, `jsm` gated, `cvt_<id>`), `data_layer_key`, `default_value`, `parameters` |
+| `draft_delete_gtm_entity` | Delete a workspace tag, trigger or variable. Referenced triggers and variables are refused with the references listed | `entity_type` (`tag`/`trigger`/`variable`), `entity_id` |
 | `draft_publish_gtm_workspace` | Publish a workspace LIVE. Preview lists every pending change — including other people's UI edits | `version_name`, `version_notes`, `workspace_id` |
 | `draft_rollback_gtm_version` | Republish an older container version LIVE. Preview is the diff from the live version to the target; destructive, double confirmation | `version_id` |
 
 **GTM write rules:**
 - Writes are off unless the user sets `gtm.write_enabled: true`; enabling it asks for re-consent with the Tag Manager edit + publish scopes. The Google account also needs Edit (and Publish) permission on the container.
 - Tag/trigger drafts only change a **workspace**. Nothing changes on the site until `draft_publish_gtm_workspace` is applied — say so when presenting a tag preview.
-- **Custom HTML (`html`) is gated** by `gtm.allow_custom_html`: creating/editing one, or publishing a workspace that adds/changes one, is refused while it is off. Prefer a built-in template. Pausing or deleting an HTML tag is always allowed. The gate matches the tag type `html` only — a Custom JavaScript variable or a custom template tag (`cvt_…`), which can inject a script, is not covered and has to be reviewed in the GTM UI.
+- **Custom HTML (`html`) is gated** by `gtm.allow_custom_html`: creating/editing one, or publishing a workspace that adds/changes one, is refused while it is off. Prefer a built-in template. Pausing or deleting an HTML tag is always allowed. Custom JavaScript variables (`jsm`) are gated the same way, including when a publish or rollback would add or change one. A custom template (`cvt_…`) runs sandboxed code and is not covered; review it in the GTM UI.
+- **GA4 purchase events:** read the purchase `dataLayer.push` in the codebase, create one Data Layer Variable per value the event needs (`draft_gtm_variable` with `data_layer_key` such as `ecommerce.transaction_id`, `ecommerce.value`, `ecommerce.currency`, `ecommerce.items`), a `customEvent` trigger for the `purchase` event, then a `gaawe` tag that sends them as `{{DLV - …}}` parameters. Check `list_gtm_variables` first: reuse a variable that reads the same key instead of creating a duplicate.
 - Always read before writing: `list_gtm_tags` / `list_gtm_triggers` for IDs, `get_gtm_workspace_diff` before publishing. Present the publish preview's `pending_changes` in full — the user is approving all of them, not just the ones AdLoop drafted.
 - Updates and deletes pin the entity fingerprint and publish pins the workspace state; if someone edits the container after the preview, apply refuses. Re-draft rather than retrying.
 - The dry run for a publish runs a Tag Manager quick preview, so compiler errors show up before a version exists. The apply result names the version it replaced (`previous_live_version_id`) — that is the rollback, and if publishing a created version failed, the error carries both ids.
@@ -268,7 +270,7 @@ For images that have no public URL: a file on the user's computer, or an image t
 | `draft_ad_group` | Create a new ad group within an existing campaign (does NOT publish) | `campaign_id` (REQUIRED), `ad_group_name` (REQUIRED), `keywords` (optional list of {text, match_type}), `cpc_bid_micros` (optional) |
 | `update_campaign` | Modify existing campaign settings — bid strategy, budget, geo targets, language targets, Search partners, display expansion | `campaign_id` (REQUIRED), plus any of: `bidding_strategy`, `daily_budget`, `geo_target_ids`, `language_ids`, `search_partners_enabled`, `display_network_enabled`, TARGET_SPEND `max_cpc` |
 | `update_ad_group` | Update ad group name and/or MANUAL_CPC `max_cpc` | `ad_group_id`, optional `ad_group_name`, optional `max_cpc` |
-| `draft_responsive_search_ad` | Create RSA preview (does NOT publish) | 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), final_url required, path1/path2 (≤15 chars each). Each headline/description may be a plain string (unpinned) or `{"text": "...", "pinned_field": "HEADLINE_1"}` (pinned). Valid pin slots: `HEADLINE_1/2/3`, `DESCRIPTION_1/2`. Google permits ≤2 headlines per slot, ≤1 description per slot. |
+| `draft_responsive_search_ad` | Create RSA preview (does NOT publish) | 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), final_url required, path1/path2 (≤15 chars each). Each headline/description may be a plain string (unpinned) or `{"text": "...", "pinned_field": "HEADLINE_1"}` (pinned). Valid pin slots: `HEADLINE_1/2/3`, `DESCRIPTION_1/2`. Several assets may pin to one slot (they rotate there), but every slot must stay fillable: by an asset pinned to it or by a distinct unpinned asset. |
 | `draft_callouts` | Create callout assets for a campaign (does NOT publish) | `campaign_id`, `callouts` list with 1-25 chars each |
 | `draft_structured_snippets` | Create structured snippet assets for a campaign (does NOT publish) | `campaign_id`, `snippets` list of `{header, values}` with official header values and 3-10 values |
 | `draft_image_assets` | Create image assets for a campaign from local files, public image URLs or uploads (does NOT publish) | `campaign_id`, `image_paths` (local PNG/JPEG/GIF files; not on a hosted server), `image_urls` (public http(s) image links, ≤5120 KB; re-checked at apply — if the image changed since the preview, draft again) and/or `upload_ids` (`up_...` from `upload_images` / `list_uploads`) |
@@ -425,7 +427,7 @@ Most websites (especially in the EU) use a GDPR cookie consent banner. This has
 7. **Pinning (use sparingly).** By default, pass headlines and descriptions as plain strings — Google rotates them for you and ad strength benefits from the diversity. Only switch to the dict shape `{"text": "...", "pinned_field": "HEADLINE_1"}` when the user has a concrete brand-safety, compliance, or messaging requirement (e.g. "the brand name must always appear", "the disclaimer must always show"). Trade-offs to flag before pinning:
    - Each pin reduces Google's ability to optimize headline order, which usually drops ad strength one notch.
    - Phone numbers should generally use a **call asset at the campaign level** (separate tool/manual setup) rather than a pinned headline — call assets are clickable on mobile and don't burn a headline slot. If the user asks to pin a phone number, suggest the call-asset path first.
-   - Valid pin slots: `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3` for headlines; `DESCRIPTION_1`, `DESCRIPTION_2` for descriptions. Google permits at most 2 headlines per slot and 1 description per slot — the draft tool enforces these caps.
+   - Valid pin slots: `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3` for headlines; `DESCRIPTION_1`, `DESCRIPTION_2` for descriptions. Several assets may pin to the same slot and rotate there (Google suggests 2 or 3 unique ones per pinned slot), but every slot must stay fillable: by an asset pinned to it or by a distinct unpinned asset. Pinning 3 keyword headlines to `HEADLINE_1` with 10 unpinned headlines is fine; pinning all 3 headlines of a 3-headline ad to `HEADLINE_1` is refused.
    - You can mix pinned dict entries with plain-string entries in a single call (e.g. brand pinned to `HEADLINE_1`, the rest unpinned).
 8. **Always set display paths** (`path1`, `path2`, max 15 chars each). These appear in the display URL (e.g. `example.com/Products/Pricing`) and significantly improve ad relevance. Derive them from the landing page URL structure or the ad's value proposition.
 9. Present the complete preview to the user — include any warnings from the pre-write checks, and explicitly call out which assets (if any) are pinned and the trade-off.
@@ -574,7 +576,7 @@ Reddit's structure is campaign → ad group (budget, bid, pixel, targeting) →
 
 1. Call the appropriate read tool to confirm the entity exists and get its current status
 2. Call `pause_entity` or `enable_entity` (Google) or `pause_reddit_entity` / `enable_reddit_entity` (Reddit) with the entity type and ID
-3. Present the preview with a clear warning about impact (e.g. "This will stop all ads in this campaign")
+3. Present the preview with a clear warning about impact (e.g. "This will stop all ads in this campaign"). Google Ads previews of pause, enable and remove name the target: `entity_name`, `account`, the parent `campaign_name` / `ad_group_name` and `current_status`. Repeat the names to the user, because a wrong account is the costly mistake; an ID that matches nothing is refused at draft time
 4. Wait for confirmation
 
 ### When user asks about landing page performance

{adloop-0.30.0 → adloop-0.32.0}/src/adloop/safety/approval_card.html

@@ -203,15 +203,25 @@
     const p = plan.preview;
     $("platform").textContent = PLATFORMS[platformOf(p)];
     $("title").textContent = humanize(p.operation);
+    // Names resolved at draft time (pause, enable, remove) sit in changes;
+    // the IDs stay visible next to them, and the card falls back to IDs.
+    const ch = p.changes || {};
     const sub = [];
-    if (p.entity_type) sub.push(String(p.entity_type).replace(/_/g, " ") + (p.entity_id ? " " + p.entity_id : ""));
-    if (p.customer_id) sub.push(String(p.customer_id));
+    if (p.entity_type) {
+      let target = String(p.entity_type).replace(/_/g, " ");
+      if (ch.entity_name) target += " \u201c" + ch.entity_name + "\u201d" + (p.entity_id ? " (" + p.entity_id + ")" : "");
+      else if (p.entity_id) target += " " + p.entity_id;
+      sub.push(target);
+    }
+    if (ch.account) sub.push(String(ch.account));
+    else if (p.customer_id) sub.push(String(p.customer_id));
     sub.push("plan " + plan.planId);
     $("subtitle").textContent = sub.join(" · ");
 
     const dl = $("changes");
     dl.replaceChildren();
-    const entries = Object.entries(p.changes || {});
+    const SHOWN_ELSEWHERE = new Set(["account", "entity_name", "warnings"]);
+    const entries = Object.entries(ch).filter(([k]) => !SHOWN_ELSEWHERE.has(k));
     entries.slice(0, MAX_ROWS).forEach(([k, v]) => row(dl, k, v));
     if (entries.length > MAX_ROWS) {
       const more = document.createElement("div");

{adloop-0.30.0 → adloop-0.32.0}/src/adloop/server.py

@@ -2547,7 +2547,79 @@ def draft_gtm_trigger(
     )
 
 
-@_tool(title="Draft deleting a Tag Manager tag or trigger", annotations=_DESTRUCTIVE, tags={"gtm"})
+@_tool(title="Draft a Tag Manager variable", annotations=_WRITE, tags={"gtm"})
+@_safe
+def draft_gtm_variable(
+    name: str = "",
+    variable_type: str = "",
+    data_layer_key: str = "",
+    default_value: str | None = None,
+    parameters: _DictListOpt = None,
+    notes: str | None = None,
+    variable_id: str = "",
+    workspace_id: str = "",
+    gtm_account_id: str = "",
+    gtm_container_id: str = "",
+) -> dict:
+    """Draft creating or updating a Tag Manager variable: returns a PREVIEW.
+
+    Without variable_id this creates a variable in a workspace; with
+    variable_id it updates the existing one. Data Layer Variables, the usual
+    source for GA4 ecommerce values, take data_layer_key (e.g.
+    "ecommerce.value") instead of raw parameters. Tags and triggers use a
+    variable as {{name}}; renaming one they reference is refused, because
+    the references would break (the GTM UI renames safely). Custom
+    JavaScript variables run code on the site and are refused unless
+    gtm.allow_custom_html is set. The edit lands in the workspace and
+    changes nothing on the site until the workspace is published. Refused
+    unless gtm.write_enabled is set.
+
+    Args:
+        name: Variable name, 1-200 characters without curly braces.
+            Required when creating a variable.
+        variable_type: Required when creating, fixed afterwards: v (Data
+            Layer Variable), c (Constant), u (URL), k (1st-party cookie), j
+            (JavaScript Variable, reads a global), aev (Auto-Event
+            Variable), d (DOM element), f (HTTP referrer), e (Custom event),
+            smm (Lookup table), remm (RegEx table), jsm (Custom JavaScript,
+            gated) or cvt_<id> for a custom template.
+        data_layer_key: For Data Layer Variables: the dataLayer key to read,
+            dot notation for nested values, e.g. "ecommerce.transaction_id".
+        default_value: For Data Layer Variables: the value when the key is
+            missing. None sets no default.
+        parameters: GTM parameter dicts with at least "type" and "key" for
+            the other types, e.g. a Constant's [{"type": "TEMPLATE", "key":
+            "value", "value": "G-ABC123"}]. On update they merge by key.
+        notes: Free-form note stored on the variable. None keeps the current
+            note.
+        variable_id: Existing variable ID to update (see list_gtm_variables).
+            Empty creates a new variable.
+        workspace_id: Workspace to edit (see list_gtm_workspaces). Empty uses
+            the Default Workspace, or the only workspace there is.
+        gtm_account_id: Numeric GTM account ID (see list_gtm_accounts). Empty
+            uses gtm.account_id from the config.
+        gtm_container_id: Numeric GTM container ID (see list_gtm_containers).
+            Empty uses gtm.container_id from the config.
+    """
+    from adloop.gtm.write import draft_gtm_variable as _impl
+
+    gtm_account_id, gtm_container_id = _gtm_defaults(gtm_account_id, gtm_container_id)
+    return _impl(
+        current_config(),
+        account_id=gtm_account_id,
+        container_id=gtm_container_id,
+        variable_id=variable_id,
+        workspace_id=workspace_id,
+        name=name,
+        variable_type=variable_type,
+        data_layer_key=data_layer_key,
+        default_value=default_value,
+        parameters=parameters,
+        notes=notes,
+    )
+
+
+@_tool(title="Draft deleting a Tag Manager tag, trigger or variable", annotations=_DESTRUCTIVE, tags={"gtm"})
 @_safe
 def draft_delete_gtm_entity(
     entity_type: str,
@@ -2556,18 +2628,19 @@ def draft_delete_gtm_entity(
     gtm_account_id: str = "",
     gtm_container_id: str = "",
 ) -> dict:
-    """Draft deleting a Tag Manager tag or trigger — returns a PREVIEW.
+    """Draft deleting a Tag Manager tag, trigger or variable — returns a PREVIEW.
 
     The entity is removed from a workspace and stays on the site until the
-    workspace is published. A trigger that any tag still references is
-    refused up front, with the referencing tags named. Refused unless
+    workspace is published. A trigger that any tag still references, or a
+    variable that a tag, trigger or other variable uses as {{name}}, is
+    refused up front, with the references named. Refused unless
     gtm.write_enabled is set. Returns the entity that would be deleted, the
     resolved workspace and a plan_id.
 
     Args:
-        entity_type: "tag" or "trigger".
-        entity_id: Numeric ID of the entity (see list_gtm_tags and
-            list_gtm_triggers).
+        entity_type: "tag", "trigger" or "variable".
+        entity_id: Numeric ID of the entity (see list_gtm_tags,
+            list_gtm_triggers and list_gtm_variables).
         workspace_id: Workspace to edit (see list_gtm_workspaces). Empty uses
             the Default Workspace, or the only workspace there is.
         gtm_account_id: Numeric GTM account ID (see list_gtm_accounts). Empty
@@ -3333,10 +3406,11 @@ def draft_responsive_search_ad(
 
     The preview shows exactly what will be created; confirm_and_apply executes
     the returned plan_id. The ad is created PAUSED. final_url is checked for
-    reachability first and an unreachable URL is refused. Google caps: at most
-    2 headlines per pin slot, at most 1 description per pin slot. Mixed
-    plain-string and dict entries are allowed within a single call (e.g. brand
-    pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8
+    reachability first and an unreachable URL is refused. Several headlines
+    may pin to the same position (Google rotates them there) as long as every
+    position stays fillable, by an asset pinned to it or by a distinct
+    unpinned one. Mixed plain-string and dict entries are allowed within a
+    single call (e.g. brand pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8
     headlines or 3 descriptions.
 
     Args:
@@ -3410,15 +3484,15 @@ def update_responsive_search_ad(
             uses the configured default account.
         headlines: LIST-REPLACE: None or [] means no change; a non-empty list
             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.
+            apply: 3-15 headlines, max 30 chars each, every pin position fillable.
             Each entry is a plain string (unpinned) or {"text": "...",
             "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 and
-            insertion-tag counting as headlines.
+            fully swaps in. 2-4 descriptions, max 90 chars each, pins to
+            DESCRIPTION_1 or DESCRIPTION_2 with every position fillable. 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