adloop 0.19.1__tar.gz → 0.19.3__tar.gz

{adloop-0.19.1 → adloop-0.19.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.19.1
+Version: 0.19.3
 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

{adloop-0.19.1 → adloop-0.19.3}/pyproject.toml

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

{adloop-0.19.1 → adloop-0.19.3}/pyproject.toml.orig

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

{adloop-0.19.1 → adloop-0.19.3}/src/adloop/ads/write.py

@@ -2780,7 +2780,27 @@ def confirm_and_apply(
                     "objects an earlier step would create, so Google could "
                     "only validate the step(s) before them."
                 )
-        if forced_by_config:
+        from adloop.runtime import deployment_mode as _deployment_mode
+
+        if forced_by_config and _deployment_mode() == "server":
+            # Hosted: the flag is the workspace's live-changes setting,
+            # switched in the dashboard. There is no config file to edit
+            # and no server for the user to restart.
+            response["dry_run_forced_by"] = "config.safety.require_dry_run"
+            response["remediation"] = (
+                "Live changes are switched off for this workspace (or for "
+                "this client). The workspace owner can switch them on in "
+                "the AdLoop Cloud dashboard under Settings → Safety. Passing "
+                "dry_run=false on this tool will keep being overridden until "
+                "then."
+            )
+            response["message"] = (
+                "dry_run=false was IGNORED because live changes are switched "
+                "off for this workspace. No changes were made. Retrying this "
+                "tool with dry_run=false will not succeed until live changes "
+                "are switched on in the dashboard."
+            )
+        elif forced_by_config:
             # The caller passed dry_run=false but safety.require_dry_run
             # forced it back on. Tell them exactly why and how to unlock
             # real writes — without this, agents (e.g. Claude Code) retry

{adloop-0.19.1 → adloop-0.19.3}/src/adloop/server.py

@@ -166,6 +166,20 @@ mcp = FastMCP(
 )
 
 
+def _tool(*, title: str, annotations: ToolAnnotations, **kwargs):
+    """Register a tool with its title in both places MCP defines one.
+
+    The tool's own ``title`` is what clients display; ``annotations.title``
+    is what directory reviews (Claude's connector portal) check. One title,
+    copied into the shared annotation preset, keeps them from drifting.
+    """
+    return mcp.tool(
+        title=title,
+        annotations=annotations.model_copy(update={"title": title}),
+        **kwargs,
+    )
+
+
 def _reddit_structured_error(exc: Exception) -> dict | None:
     """Reddit-specific translations; keyed on exception type so Reddit's
     ``invalid_grant`` never gets the "Reconnect Google" hint below."""
@@ -310,13 +324,20 @@ def _structured_error(fn_name: str, exc: Exception) -> dict:
         }
 
     if "deleted_client" in err_lower or "invalid_client" in err_lower:
+        from adloop.runtime import deployment_mode
+
         return {
             "error": (
                 "Authentication failed — the OAuth client behind your stored "
                 "credentials no longer exists or is invalid."
             ),
+            # On a hosted server the user never sees an OAuth client: the
+            # fix is reconnecting, and pointing at a product would be an ad.
             "hint": (
-                "If you set up AdLoop before v0.10 with its bundled "
+                "Reconnect Google in your AdLoop Cloud dashboard "
+                "(Settings → Google), then retry."
+                if deployment_mode() == "server"
+                else "If you set up AdLoop before v0.10 with its bundled "
                 "credentials: that shared Google Cloud project has been "
                 "retired. Fastest fix: AdLoop Cloud (https://getadloop.com) — "
                 "connect Google in two clicks, no Google Cloud project "
@@ -393,7 +414,7 @@ def _safe(fn: Callable) -> Callable:
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Connection health check", annotations=_READONLY, tags={"core"})
+@_tool(title="Connection health check", annotations=_READONLY, tags={"core"})
 @_safe
 def health_check() -> dict:
     """Test AdLoop connectivity — checks OAuth token, GA4 API, Google Ads API,
@@ -524,7 +545,7 @@ def health_check() -> dict:
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="List Analytics properties", annotations=_READONLY, tags={"ga4"})
+@_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.
@@ -537,7 +558,7 @@ def get_account_summaries() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(title="Analytics report", annotations=_READONLY, tags={"ga4"})
+@_tool(title="Analytics report", annotations=_READONLY, tags={"ga4"})
 @_safe
 def run_ga4_report(
     dimensions: _StrListOpt = None,
@@ -570,7 +591,7 @@ def run_ga4_report(
     )
 
 
-@mcp.tool(title="Analytics realtime report", annotations=_READONLY, tags={"ga4"})
+@_tool(title="Analytics realtime report", annotations=_READONLY, tags={"ga4"})
 @_safe
 def run_realtime_report(
     dimensions: _StrListOpt = None,
@@ -593,7 +614,7 @@ def run_realtime_report(
     )
 
 
-@mcp.tool(title="List Analytics events", annotations=_READONLY, tags={"ga4"})
+@_tool(title="List Analytics events", annotations=_READONLY, tags={"ga4"})
 @_safe
 def get_tracking_events(
     date_range_start: str = "28daysAgo",
@@ -620,7 +641,7 @@ def get_tracking_events(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="List Search Console properties", annotations=_READONLY, tags={"gsc"})
+@_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.
@@ -634,7 +655,7 @@ def list_gsc_sites() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(title="Search Console report", annotations=_READONLY, tags={"gsc"})
+@_tool(title="Search Console report", annotations=_READONLY, tags={"gsc"})
 @_safe
 def run_gsc_report(
     site_url: str = "",
@@ -652,7 +673,7 @@ def run_gsc_report(
     finding keyword opportunities, and cross-referencing with GA4 and Ads data.
 
     site_url: the GSC property URL (e.g. "https://example.com/" or
-        "sc-domain:example.com"). Defaults to gsc.site_url in config.yaml.
+        "sc-domain:example.com"). Defaults to the configured Search Console site.
     dimensions: one or more of ["query", "page", "country", "device", "date"].
         Defaults to ["query"].
     date_range_start / date_range_end: ISO dates (YYYY-MM-DD) or relative
@@ -686,7 +707,7 @@ def run_gsc_report(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="PageSpeed analysis", annotations=_READONLY, tags={"web"})
+@_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.
@@ -705,7 +726,7 @@ def analyze_page_speed(url: str, strategy: str = "mobile") -> dict:
     return _impl(current_config(), url=url, strategy=strategy)
 
 
-@mcp.tool(
+@_tool(
     title="List Merchant Center accounts",
     annotations=_READONLY,
     tags={"merchant"},
@@ -723,7 +744,7 @@ def list_merchant_accounts() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(title="Merchant Center feed health", annotations=_READONLY, tags={"merchant"})
+@_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.
@@ -743,7 +764,7 @@ def get_merchant_feed_health(account_id: str = "") -> dict:
     return _impl(current_config(), account_id=account_id)
 
 
-@mcp.tool(title="List Google Ads accounts", annotations=_READONLY, tags={"ads"})
+@_tool(title="List Google Ads accounts", annotations=_READONLY, tags={"ads"})
 @_safe
 def list_accounts(limit: int = 200) -> dict:
     """List accessible Google Ads accounts.
@@ -762,7 +783,7 @@ def list_accounts(limit: int = 200) -> dict:
     return _impl(current_config(), limit=limit)
 
 
-@mcp.tool(title="Campaign performance", annotations=_READONLY, tags={"ads"})
+@_tool(title="Campaign performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_campaign_performance(
     customer_id: str = "",
@@ -791,7 +812,7 @@ def get_campaign_performance(
     )
 
 
-@mcp.tool(title="Ad performance", annotations=_READONLY, tags={"ads"})
+@_tool(title="Ad performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_ad_performance(
     customer_id: str = "",
@@ -819,7 +840,7 @@ def get_ad_performance(
     )
 
 
-@mcp.tool(title="Keyword performance", annotations=_READONLY, tags={"ads"})
+@_tool(title="Keyword performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_keyword_performance(
     customer_id: str = "",
@@ -847,7 +868,7 @@ def get_keyword_performance(
     )
 
 
-@mcp.tool(title="Search terms report", annotations=_READONLY, tags={"ads"})
+@_tool(title="Search terms report", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_search_terms(
     customer_id: str = "",
@@ -875,7 +896,7 @@ def get_search_terms(
     )
 
 
-@mcp.tool(title="List negative keywords", annotations=_READONLY, tags={"ads"})
+@_tool(title="List negative keywords", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_negative_keywords(
     customer_id: str = "",
@@ -895,7 +916,7 @@ def get_negative_keywords(
     )
 
 
-@mcp.tool(
+@_tool(
     title="List shared negative keyword lists",
     annotations=_READONLY,
     tags={"ads"},
@@ -915,7 +936,7 @@ def get_negative_keyword_lists(
     return _impl(current_config(), customer_id=customer_id or current_config().ads.customer_id)
 
 
-@mcp.tool(
+@_tool(
     title="Keywords in a negative keyword list",
     annotations=_READONLY,
     tags={"ads"},
@@ -938,7 +959,7 @@ def get_negative_keyword_list_keywords(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Campaigns using a negative keyword list",
     annotations=_READONLY,
     tags={"ads"},
@@ -967,7 +988,7 @@ def get_negative_keyword_list_campaigns(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Google Ads recommendations", annotations=_READONLY, tags={"ads"})
+@_tool(title="Google Ads recommendations", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_recommendations(
     customer_id: str = "",
@@ -996,7 +1017,7 @@ def get_recommendations(
     )
 
 
-@mcp.tool(title="Performance Max performance", annotations=_READONLY, tags={"ads"})
+@_tool(title="Performance Max performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_pmax_performance(
     customer_id: str = "",
@@ -1027,7 +1048,7 @@ def get_pmax_performance(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Performance Max asset performance",
     annotations=_READONLY,
     tags={"ads"},
@@ -1060,7 +1081,7 @@ def get_asset_performance(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Performance Max asset combinations",
     annotations=_READONLY,
     tags={"ads"},
@@ -1087,7 +1108,7 @@ def get_detailed_asset_performance(
     )
 
 
-@mcp.tool(title="Audience performance", annotations=_READONLY, tags={"ads"})
+@_tool(title="Audience performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_audience_performance(
     customer_id: str = "",
@@ -1118,7 +1139,7 @@ def get_audience_performance(
     )
 
 
-@mcp.tool(title="Demographic targeting", annotations=_READONLY, tags={"ads"})
+@_tool(title="Demographic targeting", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_demographic_targeting(
     ad_group_id: str = "",
@@ -1151,7 +1172,7 @@ def get_demographic_targeting(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(
+@_tool(
     title="Campaign conversions against Analytics",
     annotations=_READONLY,
     tags={"tracking"},
@@ -1185,7 +1206,7 @@ def analyze_campaign_conversions(
     )
 
 
-@mcp.tool(title="Landing page analysis", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Landing page analysis", annotations=_READONLY, tags={"tracking"})
 @_safe
 def landing_page_analysis(
     date_range_start: str = "",
@@ -1211,7 +1232,7 @@ def landing_page_analysis(
     )
 
 
-@mcp.tool(title="Attribution check", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Attribution check", annotations=_READONLY, tags={"tracking"})
 @_safe
 def attribution_check(
     date_range_start: str = "",
@@ -1242,7 +1263,7 @@ def attribution_check(
     )
 
 
-@mcp.tool(title="Tracking coverage audit", annotations=_READONLY, tags={"gtm"})
+@_tool(title="Tracking coverage audit", annotations=_READONLY, tags={"gtm"})
 @_safe
 def audit_event_coverage(
     expected_events: list[str],
@@ -1295,7 +1316,7 @@ def audit_event_coverage(
     )
 
 
-@mcp.tool(title="List Tag Manager accounts", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1310,7 +1331,7 @@ def list_gtm_accounts() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(title="List Tag Manager containers", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1330,7 +1351,7 @@ def list_gtm_containers(gtm_account_id: str = "") -> dict:
     return _impl(current_config(), account_id=gtm_account_id)
 
 
-@mcp.tool(title="List Tag Manager tags", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1350,7 +1371,7 @@ def list_gtm_tags(gtm_account_id: str = "", gtm_container_id: str = "") -> dict:
     )
 
 
-@mcp.tool(title="Tag Manager tag details", annotations=_READONLY, tags={"gtm"})
+@_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 = ""
@@ -1375,7 +1396,7 @@ def get_gtm_tag(
     )
 
 
-@mcp.tool(title="List Tag Manager triggers", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1395,7 +1416,7 @@ def list_gtm_triggers(gtm_account_id: str = "", gtm_container_id: str = "") -> d
     )
 
 
-@mcp.tool(title="Tag Manager trigger details", annotations=_READONLY, tags={"gtm"})
+@_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 = ""
@@ -1420,7 +1441,7 @@ def get_gtm_trigger(
     )
 
 
-@mcp.tool(title="List Tag Manager variables", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1442,7 +1463,7 @@ def list_gtm_variables(gtm_account_id: str = "", gtm_container_id: str = "") ->
     )
 
 
-@mcp.tool(title="List Tag Manager workspaces", annotations=_READONLY, tags={"gtm"})
+@_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.
@@ -1462,7 +1483,7 @@ def list_gtm_workspaces(gtm_account_id: str = "", gtm_container_id: str = "") ->
     )
 
 
-@mcp.tool(title="Tag Manager workspace changes", annotations=_READONLY, tags={"gtm"})
+@_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 = ""
@@ -1489,7 +1510,7 @@ def get_gtm_workspace_diff(
     )
 
 
-@mcp.tool(title="Tag Manager version history", annotations=_READONLY, tags={"gtm"})
+@_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
@@ -1515,7 +1536,7 @@ def list_gtm_versions(
     )
 
 
-@mcp.tool(title="Tag Manager version details", annotations=_READONLY, tags={"gtm"})
+@_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 = ""
@@ -1540,7 +1561,7 @@ def get_gtm_version(
     )
 
 
-@mcp.tool(title="Custom Google Ads query", annotations=_READONLY, tags={"ads"})
+@_tool(title="Custom Google Ads query", annotations=_READONLY, tags={"ads"})
 @_safe
 def run_gaql(
     query: str,
@@ -1570,7 +1591,7 @@ def run_gaql(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Draft a campaign", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft a campaign", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_campaign(
     campaign_name: str,
@@ -1637,7 +1658,7 @@ def draft_campaign(
     )
 
 
-@mcp.tool(title="Draft an ad group", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft an ad group", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_ad_group(
     campaign_id: str,
@@ -1670,7 +1691,7 @@ def draft_ad_group(
     )
 
 
-@mcp.tool(title="Draft campaign changes", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft campaign changes", annotations=_WRITE, tags={"ads"})
 @_safe
 def update_campaign(
     campaign_id: str,
@@ -1727,7 +1748,7 @@ def update_campaign(
     )
 
 
-@mcp.tool(title="Draft a responsive search ad", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft a responsive search ad", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_responsive_search_ad(
     ad_group_id: str,
@@ -1770,7 +1791,7 @@ def draft_responsive_search_ad(
     )
 
 
-@mcp.tool(title="Update a responsive search ad", annotations=_WRITE, tags={"ads"})
+@_tool(title="Update a responsive search ad", annotations=_WRITE, tags={"ads"})
 @_safe
 def update_responsive_search_ad(
     ad_id: str,
@@ -1829,7 +1850,7 @@ def update_responsive_search_ad(
     )
 
 
-@mcp.tool(title="Draft keywords", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft keywords", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_keywords(
     ad_group_id: str,
@@ -1851,7 +1872,7 @@ def draft_keywords(
     )
 
 
-@mcp.tool(title="Custom conversion goals", annotations=_READONLY, tags={"ads"})
+@_tool(title="Custom conversion goals", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_custom_conversion_goals(
     campaign_id: str = "",
@@ -1880,7 +1901,7 @@ def get_custom_conversion_goals(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft a custom conversion goal",
     annotations=_WRITE,
     tags={"ads"},
@@ -1924,7 +1945,7 @@ def draft_custom_conversion_goal(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft changes to a custom conversion goal",
     annotations=_WRITE,
     tags={"ads"},
@@ -1962,7 +1983,7 @@ def draft_update_custom_conversion_goal(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft assigning a custom conversion goal",
     annotations=_WRITE,
     tags={"ads"},
@@ -2005,7 +2026,7 @@ def draft_assign_custom_conversion_goal(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft clearing a custom conversion goal",
     annotations=_WRITE,
     tags={"ads"},
@@ -2036,7 +2057,7 @@ def draft_clear_custom_conversion_goal(
     )
 
 
-@mcp.tool(title="Draft negative keywords", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft negative keywords", annotations=_WRITE, tags={"ads"})
 @_safe
 def add_negative_keywords(
     campaign_id: str,
@@ -2061,7 +2082,7 @@ def add_negative_keywords(
     )
 
 
-@mcp.tool(title="Draft negative locations", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft negative locations", annotations=_WRITE, tags={"ads"})
 @_safe
 def add_negative_locations(
     campaign_id: str,
@@ -2085,7 +2106,7 @@ def add_negative_locations(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft a shared negative keyword list",
     annotations=_WRITE,
     tags={"ads"},
@@ -2117,7 +2138,7 @@ def propose_negative_keyword_list(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Draft additions to a negative keyword list",
     annotations=_WRITE,
     tags={"ads"},
@@ -2154,7 +2175,7 @@ def add_to_negative_keyword_list(
     )
 
 
-@mcp.tool(title="Draft attaching a shared set", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft attaching a shared set", annotations=_WRITE, tags={"ads"})
 @_safe
 def attach_shared_set_to_campaigns(
     shared_set_id: str,
@@ -2185,7 +2206,7 @@ def attach_shared_set_to_campaigns(
     )
 
 
-@mcp.tool(title="Draft detaching a shared set", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft detaching a shared set", annotations=_WRITE, tags={"ads"})
 @_safe
 def detach_shared_set_from_campaigns(
     shared_set_id: str,
@@ -2216,7 +2237,7 @@ def detach_shared_set_from_campaigns(
     )
 
 
-@mcp.tool(title="AI Max settings", annotations=_READONLY, tags={"ads"})
+@_tool(title="AI Max settings", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_ai_max_settings(
     campaign_id: str = "",
@@ -2246,7 +2267,7 @@ def get_ai_max_settings(
         campaign_id=campaign_id,
     )
 
-@mcp.tool(title="Draft AI Max settings", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft AI Max settings", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_ai_max_settings(
     campaign_id: str,
@@ -2311,7 +2332,7 @@ def draft_ai_max_settings(
     )
 
 
-@mcp.tool(
+@_tool(
     title="Prepare a campaign for brand exclusions",
     annotations=_WRITE,
     tags={"ads"},
@@ -2354,7 +2375,7 @@ def draft_prepare_brand_exclusions(
         include_paused_ad_groups=include_paused_ad_groups,
     )
 
-@mcp.tool(title="Draft demographic targeting", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft demographic targeting", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_demographic_targeting(
     customer_id: str = "",
@@ -2406,7 +2427,7 @@ def draft_demographic_targeting(
     )
 
 
-@mcp.tool(title="Draft ad group changes", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft ad group changes", annotations=_WRITE, tags={"ads"})
 @_safe
 def update_ad_group(
     ad_group_id: str,
@@ -2426,7 +2447,7 @@ def update_ad_group(
     )
 
 
-@mcp.tool(title="Draft callouts", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft callouts", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_callouts(
     campaign_id: str,
@@ -2444,7 +2465,7 @@ def draft_callouts(
     )
 
 
-@mcp.tool(title="Draft structured snippets", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft structured snippets", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_structured_snippets(
     campaign_id: str,
@@ -2462,7 +2483,7 @@ def draft_structured_snippets(
     )
 
 
-@mcp.tool(title="Draft image assets", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft image assets", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_image_assets(
     campaign_id: str,
@@ -2496,7 +2517,7 @@ def draft_image_assets(
     )
 
 
-@mcp.tool(title="Draft pausing an entity", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft pausing an entity", annotations=_WRITE, tags={"ads"})
 @_safe
 def pause_entity(
     entity_type: str,
@@ -2524,7 +2545,7 @@ def pause_entity(
     )
 
 
-@mcp.tool(title="Draft enabling an entity", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft enabling an entity", annotations=_WRITE, tags={"ads"})
 @_safe
 def enable_entity(
     entity_type: str,
@@ -2552,7 +2573,7 @@ def enable_entity(
     )
 
 
-@mcp.tool(title="Draft removing an entity", annotations=_DESTRUCTIVE, tags={"ads"})
+@_tool(title="Draft removing an entity", annotations=_DESTRUCTIVE, tags={"ads"})
 @_safe
 def remove_entity(
     entity_type: str,
@@ -2588,7 +2609,7 @@ def remove_entity(
     )
 
 
-@mcp.tool(title="Draft sitelinks", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft sitelinks", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_sitelinks(
     campaign_id: str,
@@ -2621,7 +2642,7 @@ def draft_sitelinks(
     )
 
 
-@mcp.tool(title="Apply a previewed change", annotations=_DESTRUCTIVE, tags={"core"})
+@_tool(title="Apply a previewed change", annotations=_DESTRUCTIVE, tags={"core"})
 @_safe
 def confirm_and_apply(
     plan_id: str,
@@ -2633,14 +2654,12 @@ def confirm_and_apply(
     to make real changes to the ad account (Google Ads or Reddit Ads — the
     plan knows which platform it targets).
 
-    Config override: if 'safety.require_dry_run: true' is set in the user's
-    config file (default ~/.adloop/config.yaml), dry_run=false is IGNORED
-    and this tool will keep returning DRY_RUN_SUCCESS. When that happens the
-    response includes 'dry_run_forced_by', 'config_path', and 'remediation'
-    fields — surface those to the user verbatim and STOP retrying. Calling
-    this tool again with dry_run=false will not change anything until the
-    user edits the config file, sets 'require_dry_run: false', and restarts
-    the AdLoop MCP server.
+    Forced dry runs: when real changes are switched off (live changes off
+    for the workspace in AdLoop Cloud, or safety.require_dry_run in a
+    self-hosted config), dry_run=false is IGNORED and the result is still
+    DRY_RUN_SUCCESS, with 'dry_run_forced_by' and 'remediation' fields.
+    Pass the remediation on to the user and stop retrying: calling again
+    with dry_run=false changes nothing until that setting is changed.
 
     Two-phase apply: if 'safety.two_phase_apply: true' is set (always on
     for AdLoop Cloud tenants), dry_run=false is REFUSED with status
@@ -2676,7 +2695,7 @@ def _reddit_account(ad_account_id: str) -> str:
     return ad_account_id or current_config().reddit.ad_account_id
 
 
-@mcp.tool(title="List Reddit ad accounts", annotations=_READONLY, tags={"reddit"})
+@_tool(title="List Reddit ad accounts", annotations=_READONLY, tags={"reddit"})
 @_safe
 def list_reddit_accounts() -> dict:
     """List Reddit businesses and ad accounts the connected Reddit user can access.
@@ -2690,7 +2709,7 @@ def list_reddit_accounts() -> dict:
     return _impl(current_config())
 
 
-@mcp.tool(
+@_tool(
     title="Reddit billing + posting profiles", annotations=_READONLY, tags={"reddit"}
 )
 @_safe
@@ -2705,7 +2724,7 @@ def list_reddit_funding_instruments(ad_account_id: str = "") -> dict:
     return _impl(current_config(), ad_account_id=_reddit_account(ad_account_id))
 
 
-@mcp.tool(title="Reddit campaigns", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit campaigns", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_campaigns(ad_account_id: str = "", include_archived: bool = False) -> dict:
     """List Reddit campaigns with status, objective, budget mode and bids.
@@ -2724,7 +2743,7 @@ def get_reddit_campaigns(ad_account_id: str = "", include_archived: bool = False
     )
 
 
-@mcp.tool(title="Reddit ad groups", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit ad groups", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_ad_groups(ad_account_id: str = "", campaign_id: str = "") -> dict:
     """List Reddit ad groups (budget, bid, pixel, weekly schedule, targeting summary), optionally per campaign.
@@ -2741,7 +2760,7 @@ def get_reddit_ad_groups(ad_account_id: str = "", campaign_id: str = "") -> dict
     )
 
 
-@mcp.tool(title="Reddit ads", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit ads", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_ads(
     ad_account_id: str = "",
@@ -2767,7 +2786,7 @@ def get_reddit_ads(
     )
 
 
-@mcp.tool(title="Reddit performance", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit performance", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_performance(
     ad_account_id: str = "",
@@ -2803,7 +2822,7 @@ def get_reddit_performance(
     )
 
 
-@mcp.tool(title="Raw Reddit report", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Raw Reddit report", annotations=_READONLY, tags={"reddit"})
 @_safe
 def run_reddit_report(
     fields: _StrList,
@@ -2839,7 +2858,7 @@ def run_reddit_report(
     )
 
 
-@mcp.tool(title="Reddit pixels", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit pixels", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_pixels(ad_account_id: str = "") -> dict:
     """Reddit pixels of the account and when each event (purchase, sign_up, lead, ...) last fired.
@@ -2853,7 +2872,7 @@ def get_reddit_pixels(ad_account_id: str = "") -> dict:
     return _impl(current_config(), ad_account_id=_reddit_account(ad_account_id))
 
 
-@mcp.tool(title="Search Reddit targeting", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Search Reddit targeting", annotations=_READONLY, tags={"reddit"})
 @_safe
 def search_reddit_targeting(
     kind: str, query: str = "", country: str = "", website_url: str = "", limit: int = 25
@@ -2875,7 +2894,7 @@ def search_reddit_targeting(
     )
 
 
-@mcp.tool(title="Reddit account change history", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Reddit account change history", annotations=_READONLY, tags={"reddit"})
 @_safe
 def get_reddit_account_history(
     ad_account_id: str = "",
@@ -2906,7 +2925,7 @@ def get_reddit_account_history(
     )
 
 
-@mcp.tool(title="Estimate a Reddit ad group", annotations=_READONLY, tags={"reddit"})
+@_tool(title="Estimate a Reddit ad group", annotations=_READONLY, tags={"reddit"})
 @_safe
 def estimate_reddit_ad_group(
     daily_budget: float | None = None,
@@ -2966,7 +2985,7 @@ def estimate_reddit_ad_group(
     )
 
 
-@mcp.tool(title="Draft pausing a Reddit entity", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft pausing a Reddit entity", annotations=_WRITE, tags={"reddit"})
 @_safe
 def pause_reddit_entity(
     entity_type: str, entity_id: str, ad_account_id: str = ""
@@ -2986,7 +3005,7 @@ def pause_reddit_entity(
     )
 
 
-@mcp.tool(title="Draft enabling a Reddit entity", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft enabling a Reddit entity", annotations=_WRITE, tags={"reddit"})
 @_safe
 def enable_reddit_entity(
     entity_type: str, entity_id: str, ad_account_id: str = ""
@@ -3006,7 +3025,7 @@ def enable_reddit_entity(
     )
 
 
-@mcp.tool(title="Draft archiving a Reddit entity", annotations=_DESTRUCTIVE, tags={"reddit"})
+@_tool(title="Draft archiving a Reddit entity", annotations=_DESTRUCTIVE, tags={"reddit"})
 @_safe
 def remove_reddit_entity(
     entity_type: str, entity_id: str, ad_account_id: str = ""
@@ -3027,7 +3046,7 @@ def remove_reddit_entity(
     )
 
 
-@mcp.tool(title="Draft Reddit campaign changes", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft Reddit campaign changes", annotations=_WRITE, tags={"reddit"})
 @_safe
 def update_reddit_campaign(
     campaign_id: str,
@@ -3075,7 +3094,7 @@ def update_reddit_campaign(
     )
 
 
-@mcp.tool(title="Draft Reddit ad group changes", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft Reddit ad group changes", annotations=_WRITE, tags={"reddit"})
 @_safe
 def update_reddit_ad_group(
     ad_group_id: str,
@@ -3146,7 +3165,7 @@ def update_reddit_ad_group(
     )
 
 
-@mcp.tool(title="Draft Reddit ad changes", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft Reddit ad changes", annotations=_WRITE, tags={"reddit"})
 @_safe
 def update_reddit_ad(
     ad_id: str,
@@ -3173,7 +3192,7 @@ def update_reddit_ad(
     )
 
 
-@mcp.tool(title="Draft a Reddit campaign", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft a Reddit campaign", annotations=_WRITE, tags={"reddit"})
 @_safe
 def draft_reddit_campaign(
     campaign_name: str,
@@ -3232,7 +3251,7 @@ def draft_reddit_campaign(
     )
 
 
-@mcp.tool(title="Draft a Reddit ad group", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft a Reddit ad group", annotations=_WRITE, tags={"reddit"})
 @_safe
 def draft_reddit_ad_group(
     campaign_id: str,
@@ -3313,7 +3332,7 @@ def draft_reddit_ad_group(
     )
 
 
-@mcp.tool(title="Draft a Reddit ad", annotations=_WRITE, tags={"reddit"})
+@_tool(title="Draft a Reddit ad", annotations=_WRITE, tags={"reddit"})
 @_safe
 def draft_reddit_ad(
     ad_group_id: str,
@@ -3369,7 +3388,7 @@ def draft_reddit_ad(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Draft an Analytics key event", annotations=_WRITE, tags={"ga4"})
+@_tool(title="Draft an Analytics key event", annotations=_WRITE, tags={"ga4"})
 @_safe
 def draft_key_event(
     event_name: str,
@@ -3394,7 +3413,7 @@ def draft_key_event(
     )
 
 
-@mcp.tool(title="Draft a conversion action", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft a conversion action", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_create_conversion_action(
     name: str,
@@ -3447,7 +3466,7 @@ def draft_create_conversion_action(
     )
 
 
-@mcp.tool(title="Draft conversion action changes", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft conversion action changes", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_update_conversion_action(
     conversion_action_id: str,
@@ -3494,7 +3513,7 @@ def draft_update_conversion_action(
     )
 
 
-@mcp.tool(title="Draft removing a conversion action", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft removing a conversion action", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_remove_conversion_action(
     conversion_action_id: str,
@@ -3518,7 +3537,7 @@ def draft_remove_conversion_action(
     )
 
 
-@mcp.tool(title="Validate tracking", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Validate tracking", annotations=_READONLY, tags={"tracking"})
 @_safe
 def validate_tracking(
     expected_events: _StrList,
@@ -3546,7 +3565,7 @@ def validate_tracking(
     )
 
 
-@mcp.tool(title="Generate tracking code", annotations=_READONLY, tags={"tracking"})
+@_tool(title="Generate tracking code", annotations=_READONLY, tags={"tracking"})
 @_safe
 def generate_tracking_code(
     event_name: str,
@@ -3581,7 +3600,7 @@ def generate_tracking_code(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Budget forecast", annotations=_READONLY, tags={"ads"})
+@_tool(title="Budget forecast", annotations=_READONLY, tags={"ads"})
 @_safe
 def estimate_budget(
     keywords: _DictList,
@@ -3618,7 +3637,7 @@ def estimate_budget(
     )
 
 
-@mcp.tool(title="Keyword ideas", annotations=_READONLY, tags={"ads"})
+@_tool(title="Keyword ideas", annotations=_READONLY, tags={"ads"})
 @_safe
 def discover_keywords(
     seed_keywords: _StrList = [],  # noqa: B006 — mutable default required for MCP JSON schema
@@ -3666,7 +3685,7 @@ def discover_keywords(
 # ---------------------------------------------------------------------------
 
 
-@mcp.tool(title="Suggest brands", annotations=_READONLY, tags={"ads"})
+@_tool(title="Suggest brands", annotations=_READONLY, tags={"ads"})
 @_safe
 def suggest_brands(
     brand_prefix: str,
@@ -3703,7 +3722,7 @@ def suggest_brands(
     )
 
 
-@mcp.tool(title="Check brand names", annotations=_READONLY, tags={"ads"})
+@_tool(title="Check brand names", annotations=_READONLY, tags={"ads"})
 @_safe
 def check_brand_names(
     brand_names: _StrList,
@@ -3736,7 +3755,7 @@ def check_brand_names(
         customer_id=customer_id or current_config().ads.customer_id,
     )
 
-@mcp.tool(title="List brand lists", annotations=_READONLY, tags={"ads"})
+@_tool(title="List brand lists", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_brand_lists(
     customer_id: str = "",
@@ -3756,7 +3775,7 @@ def get_brand_lists(
         customer_id=customer_id or current_config().ads.customer_id,
     )
 
-@mcp.tool(title="Brands in a brand list", annotations=_READONLY, tags={"ads"})
+@_tool(title="Brands in a brand list", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_brand_list_brands(
     shared_set_id: str,
@@ -3780,7 +3799,7 @@ def get_brand_list_brands(
         shared_set_id=shared_set_id,
     )
 
-@mcp.tool(title="Campaigns using a brand list", annotations=_READONLY, tags={"ads"})
+@_tool(title="Campaigns using a brand list", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_brand_list_campaigns(
     shared_set_id: str = "",
@@ -3806,7 +3825,7 @@ def get_brand_list_campaigns(
         shared_set_id=shared_set_id,
     )
 
-@mcp.tool(title="Draft a brand list", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft a brand list", annotations=_WRITE, tags={"ads"})
 @_safe
 def propose_brand_list(
     list_name: str,
@@ -3844,7 +3863,7 @@ def propose_brand_list(
         negative=negative,
     )
 
-@mcp.tool(title="Draft additions to a brand list", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft additions to a brand list", annotations=_WRITE, tags={"ads"})
 @_safe
 def add_to_brand_list(
     shared_set_id: str,
@@ -3874,7 +3893,7 @@ def add_to_brand_list(
         brand_ids=brand_ids,
     )
 
-@mcp.tool(title="Draft removing brands from a list", annotations=_DESTRUCTIVE, tags={"ads"})
+@_tool(title="Draft removing brands from a list", annotations=_DESTRUCTIVE, tags={"ads"})
 @_safe
 def remove_from_brand_list(
     shared_set_id: str,
@@ -3904,7 +3923,7 @@ def remove_from_brand_list(
         criterion_ids=criterion_ids,
     )
 
-@mcp.tool(title="Draft attaching a brand list", annotations=_WRITE, tags={"ads"})
+@_tool(title="Draft attaching a brand list", annotations=_WRITE, tags={"ads"})
 @_safe
 def attach_brand_list_to_campaigns(
     shared_set_id: str,
@@ -3941,7 +3960,7 @@ def attach_brand_list_to_campaigns(
         negative=negative,
     )
 
-@mcp.tool(title="Draft detaching a brand list", annotations=_DESTRUCTIVE, tags={"ads"})
+@_tool(title="Draft detaching a brand list", annotations=_DESTRUCTIVE, tags={"ads"})
 @_safe
 def detach_brand_list_from_campaigns(
     shared_set_id: str,