scrapeloop-mcp 0.7.0 → 0.8.0

package/src/index.js

@@ -1,27 +1,28 @@
 #!/usr/bin/env node
 /**
- * scrapeloop-mcp — Model Context Protocol server for Scrapeloop.
+ * scrapeloop-mcp: Model Context Protocol server for Scrapeloop.
  *
  * A thin wrapper over the Scrapeloop REST API (/api/v1). Authenticates with a
  * per-workspace API key (Settings → API access). Credit-gated actions surface
  * 402/403 bodies verbatim so the model can self-correct or prompt a top-up.
  *
- * The full setup flow (connect → choose source → configure → verify → clean →
- * enrich → campaigns) is driven by these tools. Call `get_capabilities` first to
- * learn what this workspace actually has and `get_setup_status` to know where the
- * user already is, then walk the manifest's `steps` in order.
+ * Read get_capabilities, get_setup_status and get_playbook first. Use this
+ * workspace's saved answers for setup and later tasks, following the live
+ * manifest steps and each tool's approval and retry rules.
  *
  * Env:
- *   SCRAPELOOP_API_KEY   required — sl_live_… key
- *   SCRAPELOOP_API_URL   optional — defaults to https://api.scrapeloop.com
+ *   SCRAPELOOP_API_KEY   required: sl_live_… key
+ *   SCRAPELOOP_API_URL   optional, defaults to https://api.scrapeloop.com
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { MUTATION_POLICIES, RETRY_CONTRACT_COPY } from './mutation-policies.js';
 
 const API_KEY = process.env.SCRAPELOOP_API_KEY;
 const BASE = (process.env.SCRAPELOOP_API_URL || 'https://api.scrapeloop.com').replace(/\/$/, '');
@@ -29,28 +30,57 @@ const TIMEOUT_MS = Number(process.env.SCRAPELOOP_TIMEOUT_MS) || 30000;
 const MAX_RETRIES = 3;
 const MAX_TABLE_CELL_WRITES = 500;
 const MAX_TABLE_CELL_REQUEST_BYTES = 256 * 1024;
+// Native Smart Table tool keys, mirroring apps/api/lib/native_tool_columns.json.
+// This package ships standalone, so it cannot read that file; the pairing is
+// asserted in apps/web/lib/native-tool-columns.test.ts. Drift fails SAFE: the
+// API rejects an unknown key and returns available_tools, and
+// get_table_native_tools always serves the live catalog.
+// verify_catchall is deliberately absent: its correctness needs a sibling Verify
+// email column that has already RUN and returned Catch All or Unknown, which one
+// create call cannot establish. Customers use verify_catchall (per address) or
+// the in-app add-column menu. See docs/roadmap/mcp-native-tool-columns.md.
+const NATIVE_TABLE_TOOLS = Object.freeze([
+  'verify_email',
+  'verify_phone',
+  'email_finder',
+  'business_email_finder',
+]);
 const TRACE_HEADER = 'X-Scrapeloop-Trace-Id';
 const SAFE_TRACE_ID = /^[A-Za-z0-9_-]{8,80}$/;
 const STARTUP_WARNINGS = new Set();
+const RETRY_BASE_MS = Number(process.env.SCRAPELOOP_RETRY_BASE_MS) || 500;
+const toolCallContext = new AsyncLocalStorage();
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-// One API call with a per-request timeout + retry/backoff on 429/5xx + transient
-// network errors. Never throws — always resolves to {ok, status, data|error} so a
-// single failed upstream call can't kill the server. The API key is sent in the
-// Authorization header only and is never logged.
-const uncertainMutationFailure = (status, error, reconciliation) => {
-  const base = error && typeof error === 'object' ? error : { detail: String(error) };
+const uncertainResult = ({ context, method, path, upstreamStatus, reconciliation }) => {
+  const policy = context?.policy || {};
+  const args = context?.args || {};
+  const match = Object.fromEntries(
+    (policy.match_fields || [])
+      .filter((field) => args[field] !== undefined)
+      .map((field) => [field, args[field]]),
+  );
   return {
     ok: false,
-    status,
+    status: upstreamStatus || 0,
     error: {
-      ...base,
+      type: 'uncertain_result',
       uncertain_result: true,
-      retry_guidance:
-        reconciliation.retry_guidance ||
-        'Do not repeat this mutation yet. The server may have committed it before the response was lost.',
-      reconciliation,
+      detail: `The ${method} ${path} result is unknown. The request may have committed before the response was lost.`,
+      tool: context?.toolName,
+      operation: `${method} ${path}`,
+      ...(args.idempotency_key ? { idempotency_key: args.idempotency_key } : {}),
+      inspect_with: policy.inspect_with || [],
+      match_fields: match,
+      ...(reconciliation ? { reconciliation } : {}),
+      ...(reconciliation?.retry_guidance
+        ? { retry_guidance: reconciliation.retry_guidance }
+        : {}),
+      guidance:
+        reconciliation?.guidance ||
+        reconciliation?.retry_guidance ||
+        'Inspect the listed read tools and stable fields before making any new mutation attempt.',
     },
   };
 };
@@ -69,34 +99,65 @@ async function api(method, path, body, options = {}) {
   }
   const fetcher = options.fetcher || fetch;
   const sleepFn = options.sleepFn || sleep;
-  const maxRetries = options.maxRetries ?? MAX_RETRIES;
   const shouldRetryResponse =
     options.shouldRetryResponse || ((status) => status === 429 || status >= 500);
-  const retryDelay = options.retryDelay || ((attempt) => 500 * 2 ** attempt);
+  const retryDelay = options.retryDelay || ((attempt) => RETRY_BASE_MS * 2 ** attempt);
   const traceId = safeTraceId(options.traceId);
+  const verb = method.toUpperCase();
+  const context = toolCallContext.getStore();
+  const policy = context?.policy;
+  if (verb !== 'GET' && (!policy || policy.method !== verb)) {
+    return {
+      ok: false,
+      status: 500,
+      error: {
+        detail: `MCP mutation policy missing or mismatched for ${context?.toolName || 'unknown tool'} (${verb} ${path}).`,
+      },
+    };
+  }
+  if (policy?.retry === 'idempotency_key' && !context?.args?.idempotency_key) {
+    return {
+      ok: false,
+      status: 400,
+      error: {
+        detail: `${context.toolName} requires idempotency_key. Generate one stable UUID and reuse it for every retry of this exact operation.`,
+      },
+    };
+  }
+  const canRetry = verb === 'GET'
+    || policy?.effect === 'read'
+    || policy?.retry === 'idempotent'
+    || policy?.retry === 'idempotency_key';
+  const maxRetries = canRetry ? (options.maxRetries ?? MAX_RETRIES) : 0;
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`,
+    'Content-Type': 'application/json',
+    ...(traceId ? { [TRACE_HEADER]: traceId } : {}),
+    ...(policy?.retry === 'idempotency_key'
+      ? { 'Idempotency-Key': context.args.idempotency_key }
+      : {}),
+  };
   let lastErr;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     let res;
     try {
       res = await fetcher(`${BASE}/api/v1${path}`, {
-        method,
-        headers: {
-          Authorization: `Bearer ${API_KEY}`,
-          'Content-Type': 'application/json',
-          ...(traceId ? { [TRACE_HEADER]: traceId } : {}),
-        },
+        method: verb,
+        headers,
         body: body === undefined ? undefined : JSON.stringify(body),
         signal: AbortSignal.timeout(TIMEOUT_MS),
       });
     } catch (e) {
-      // Network error / timeout — retry a few times, then surface a clean error.
       lastErr = e;
       if (attempt < maxRetries) {
         await sleepFn(retryDelay(attempt));
         continue;
       }
+      if (policy?.effect === 'mutation') {
+        return uncertainResult({ context, method: verb, path, reconciliation: options.reconciliation });
+      }
       const timedOut = e && (e.name === 'TimeoutError' || e.name === 'AbortError');
-      const failure = {
+      return {
         ok: false,
         status: 0,
         error: { detail: `Could not reach Scrapeloop (${timedOut ? `timeout after ${TIMEOUT_MS}ms` : String(e)}).` },
@@ -104,12 +165,10 @@ async function api(method, path, body, options = {}) {
           ? { trace_id: traceId, network_error: timedOut ? 'timeout' : 'transport' }
           : {}),
       };
-      return options.reconciliation
-        ? uncertainMutationFailure(0, failure.error, options.reconciliation)
-        : failure;
     }
     // Retry transient upstream failures (rate limit / server errors).
-    if (shouldRetryResponse(res.status) && attempt < maxRetries) {
+    const transient = shouldRetryResponse(res.status);
+    if (transient && attempt < maxRetries) {
       const retryAfter = Number(res.headers.get('retry-after')) * 1000;
       const delay =
         options.respectRetryAfter !== false && retryAfter > 0
@@ -126,9 +185,18 @@ async function api(method, path, body, options = {}) {
       data = { raw: text };
     }
     if (!res.ok) {
-      // Surface the API's structured error verbatim (401 auth, 402 credits, 403 scope, …).
-      if (res.status >= 500 && options.reconciliation) {
-        return uncertainMutationFailure(res.status, data, options.reconciliation);
+      if (
+        transient
+        && policy?.effect === 'mutation'
+        && !(res.status === 429 && canRetry)
+      ) {
+        return uncertainResult({
+          context,
+          method: verb,
+          path,
+          upstreamStatus: res.status,
+          reconciliation: options.reconciliation,
+        });
       }
       return {
         ok: false,
@@ -144,6 +212,9 @@ async function api(method, path, body, options = {}) {
       ...(options.captureTrace ? { trace_id: responseTraceId(res, traceId) } : {}),
     };
   }
+  if (policy?.effect === 'mutation') {
+    return uncertainResult({ context, method: verb, path, reconciliation: options.reconciliation });
+  }
   return {
     ok: false,
     status: 0,
@@ -281,13 +352,34 @@ const runScopeBody = (a) => ({
   ...(a.only_failed !== undefined ? { only_failed: !!a.only_failed } : {}),
 });
 
+// Plan choices mirror the app wizard. Explicit scope and limits prevent a
+// missing answer from silently becoming a country-wide paid plan.
+const PLAN_FIELDS = {
+  name: S, kind: S, integration_id: S, country: S,
+  granularity: { ...S, enum: ['country', 'state', 'city', 'postal_code'] },
+  locations: ARR(S), location_items: ARR(O), categories: ARR(S),
+  min_population: { type: 'integer', minimum: 0 }, scrape_config: O,
+  run_mode: { ...S, enum: ['all_now', 'over_time'] }, spread_evenly: B,
+  monthly_max_leads: { type: 'integer', minimum: 1 },
+  monthly_lead_ceiling: { type: 'integer', minimum: 1 },
+  monthly_max_usd: { ...N, exclusiveMinimum: 0 },
+  monthly_max_credits: { type: 'integer', minimum: 1 },
+  spend_buffer_usd: { ...N, minimum: 0 },
+  max_leads_per_chunk: { type: 'integer', minimum: 0 },
+  chunk_interval_minutes: { type: 'integer', minimum: 0 },
+  chunk_order: { ...S, enum: ['sequential', 'largest_first', 'balanced'] },
+  rescrape_covered: B, min_age_days: { type: 'integer', minimum: 1 },
+  rescrape_after_days: { type: 'integer', minimum: 1 },
+};
+const PLAN_REQUIRED = ['name', 'kind', 'country', 'granularity', 'locations', 'categories', 'run_mode'];
+
 // --- Tool registry: name → { def, run } -------------------------------------
 const TOOLS = {
   // ── Discovery / status ────────────────────────────────────────────────
   get_capabilities: {
     def: {
       description:
-        'Fetch the live Scrapeloop capability manifest: scrapers (+ their config schemas), enrichment primitives & presets, cleaners, strategy tags, vendors, scopes, filter enums, and the ordered 7 setup steps with guidance. CALL THIS FIRST and whenever unsure what is available — it reflects the workspace as it is right now.',
+        'Fetch the live Scrapeloop capability manifest: scrapers (+ their config schemas), enrichment primitives & presets, cleaners, strategy tags, vendors, scopes, filter enums, and the ordered Playbook setup and run steps with guidance. CALL THIS FIRST and whenever unsure what is available: it reflects the workspace as it is right now.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/manifest'),
@@ -295,7 +387,7 @@ const TOOLS = {
   get_setup_status: {
     def: {
       description:
-        'Onboarding checklist booleans (integration connected, a lead revealed, a verify run, a list created) so you know what is already done and where to resume.',
+        'Onboarding checklist booleans (Playbook saved, integration connected, a lead revealed, a verify run, a Table created) so you know what is already done and where to resume.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/setup/status'),
@@ -345,7 +437,7 @@ const TOOLS = {
   },
   list_credentials: {
     def: {
-      description: "List an integration's stored credentials (masked — keys are never returned).",
+      description: "List an integration's stored credentials (masked: keys are never returned).",
       inputSchema: obj({ integration_id: S }, ['integration_id']),
     },
     run: (a) =>
@@ -385,7 +477,7 @@ const TOOLS = {
   list_scrapers: {
     def: {
       description:
-        'List available scrapers and the JSON Schema for each config. Ask the user the schema\'s fields (query, locations, limit, …), then fill `config` for estimate_scrape / submit_scrape.',
+        'List available scrapers, whether each requires a credential, and the JSON Schema for each config. Reuse saved Playbook choices and ask only for missing fields. Read each plan capability before choosing preview_scrape_plan or a one-off estimate_scrape.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/scrapers'),
@@ -413,14 +505,16 @@ const TOOLS = {
   submit_scrape: {
     def: {
       description:
-        'Submit a scrape job. SPENDS vendor credits (BYOK) or lead credits (managed: 1 credit per NEW lead, deduped free) — confirm with the user first. billing: "auto" (default) uses the workspace key when one exists, else Scrapeloop\'s managed key; "byok"/"managed" force the mode. integration_id is required for BYOK, optional for managed. Surfaces 402 (budget/free-tier/credits) and 409 (rescrape confirmation needed) verbatim; pass confirm_rescrape:true to proceed past a coverage conflict.',
+        'Submit a scrape job. Optionally pass table_id from get_tables to add results to an existing writable static Table; omit it to keep results in All leads only. Paid scrapers spend vendor credits (BYOK) or lead credits (managed: 1 credit per NEW lead, deduped free), so confirm paid work with the user first. For every paid scraper, pass a positive hard_max_cost_usd equal to or above the estimate after the user confirms that ceiling; paid work will not start without it. A scraper with requires_credential=false is free and needs no integration_id, credential_id, or hard maximum. billing: "auto" (default) uses the workspace key when one exists, else Scrapeloop\'s managed key; "byok"/"managed" force the mode. integration_id is required for normal BYOK, optional for managed, and omitted for credential-free sources. Returns 402 for budget or credit limits and 409 when rescrape confirmation is needed; pass confirm_rescrape:true to proceed past a coverage conflict.',
       inputSchema: obj(
         {
           kind: S,
           integration_id: S,
           config: O,
+          table_id: S,
           credential_id: S,
           confirm_rescrape: B,
+          hard_max_cost_usd: { ...N, exclusiveMinimum: 0 },
           billing: { ...S, enum: ['auto', 'byok', 'managed'] },
         },
         ['kind', 'config'],
@@ -431,23 +525,62 @@ const TOOLS = {
         kind: a.kind,
         integration_id: a.integration_id ?? null,
         config: a.config || {},
+        ...(a.table_id ? { target_list_id: a.table_id } : {}),
         ...(a.credential_id ? { credential_id: a.credential_id } : {}),
         ...(a.confirm_rescrape ? { confirm_rescrape: true } : {}),
+        ...(a.hard_max_cost_usd !== undefined ? { hard_max_cost_usd: a.hard_max_cost_usd } : {}),
         ...(a.billing ? { billing: a.billing } : {}),
       }),
   },
+  get_scrape_plan_territories: {
+    def: {
+      description: 'Read places a scraper can cover before previewing a plan. Use returned values exactly. For Outscraper, pass a returned parent value to read its child cities.',
+      inputSchema: obj({ kind: S, country: S, granularity: S, min_population: N, parent: S }, ['kind', 'country']),
+    },
+    run: (a) => api('GET', `/plans/territories?${new URLSearchParams(Object.entries(a).filter(([, value]) => value !== undefined)).toString()}`),
+  },
+  preview_scrape_plan: {
+    def: {
+      description: 'Preview all-now or over-time scraping with the same limits as the app. No scrape or credential is created. Read the Playbook and scraper capabilities first. Set a lead or credit cap for credit-priced work, or a dollar cap for dollar-priced work. all_now limits apply once; over_time limits reset each month. Show costs and coverage warnings before creating.',
+      inputSchema: obj(PLAN_FIELDS, PLAN_REQUIRED),
+    },
+    run: (a) => api('POST', '/plans/preview', a),
+  },
+  create_scrape_plan: {
+    def: {
+      description: 'Create and start an approved scrape plan into an existing writable Table. This can spend credits or vendor money. Preview the exact choices first and stay within the approved limit and time period. Pass explicit territory values and matching billing limits. Reuse the same idempotency_key after a lost reply, inspect list_scrape_plans and never create a second plan to escape an uncertain result. Over-time limits reset monthly; a total one-time approval does not authorize recurring spend.',
+      inputSchema: obj({ ...PLAN_FIELDS, target_list_id: { ...S, format: 'uuid' } }, [...PLAN_REQUIRED, 'target_list_id']),
+    },
+    run: ({ idempotency_key: _key, ...body }) => api('POST', '/plans', body),
+  },
+  list_scrape_plans: {
+    def: { description: 'Read this workspace scrape plans, progress and spending. Use after an uncertain plan create.', inputSchema: obj({}) },
+    run: () => api('GET', '/plans'),
+  },
+  get_scrape_plan: {
+    def: { description: 'Read one scrape plan, its saved scope, limits, progress and spending.', inputSchema: obj({ plan_id: { ...S, format: 'uuid' } }, ['plan_id']) },
+    run: (a) => api('GET', `/plans/${enc(a.plan_id)}`),
+  },
+  pause_scrape_plan: {
+    def: { description: 'Pause new work from a scrape plan. A job already running may still finish. Inspect the plan and its jobs after pausing.', inputSchema: obj({ plan_id: { ...S, format: 'uuid' } }, ['plan_id']) },
+    run: (a) => api('POST', `/plans/${enc(a.plan_id)}/pause`),
+  },
   list_jobs: {
     def: { description: 'List recent scrape/enrich jobs in the workspace.', inputSchema: obj({}) },
     run: () => api('GET', '/jobs'),
   },
   get_job: {
-    def: { description: 'Get one job with its execution steps (poll this for scrape progress).', inputSchema: obj({ job_id: S }, ['job_id']) },
+    def: { description: 'Get one job with its execution steps (poll this for scrape progress). A scrape job carries `delivery`: how many rows were found, kept, new, already yours, and added to its Table, why rows were left out, and whether adding them to the Table worked.', inputSchema: obj({ job_id: S }, ['job_id']) },
     run: (a) => api('GET', `/jobs/${enc(a.job_id)}`),
   },
   cancel_job: {
-    def: { description: 'Cancel a queued/running job (also best-effort cancels the vendor task).', inputSchema: obj({ job_id: S }, ['job_id']) },
+    def: { description: 'Request cancellation of a queued or running job. An active external vendor task remains nonterminal while the worker aborts it and settles final partial usage, then becomes cancelled.', inputSchema: obj({ job_id: S }, ['job_id']) },
     run: (a) => api('POST', `/jobs/${enc(a.job_id)}/cancel`),
   },
+  attach_job_to_table: {
+    def: { description: 'Add a finished scrape job\'s leads to its Table again. Use it only when get_job shows `delivery.attach.state` as "failed" and the job is done, and not when `delivery.attach.code` is "table_missing" (that Table was deleted). Rows already in the Table are skipped, so repeating it never adds a row twice. Returns `added`, `in_table`, and the updated `delivery`.', inputSchema: obj({ job_id: S }, ['job_id']) },
+    run: (a) => api('POST', `/jobs/${enc(a.job_id)}/attach-to-table`),
+  },
 
   // ── Lead database ─────────────────────────────────────────────────────
   search_leads: {
@@ -472,7 +605,7 @@ const TOOLS = {
   },
   reveal_lead: {
     def: {
-      description: "Reveal a lead's email by global_person_id. SPENDS 1 lead credit (idempotent — already-revealed leads are free).",
+      description: "Reveal a lead's email by global_person_id. SPENDS 1 lead credit (idempotent: already-revealed leads are free).",
       inputSchema: obj({ global_person_id: S }, ['global_person_id']),
     },
     run: (a) => api('POST', '/leads/reveal', { global_person_id: a.global_person_id }),
@@ -617,7 +750,7 @@ const TOOLS = {
   verify_catchall: {
     def: {
       description:
-        'Resolve a mailbox on a catch-all domain with the deep verifier (5 verify credits). High ROI: deliverable catch-all/unknown contacts get fewer cold emails because most senders skip them, so they reply more.',
+        'Resolve a mailbox on a catch-all domain with Scrapeloop managed verification (5 verify credits). Optional and off unless chosen. It can resolve some unknown addresses but does not promise more replies. Estimate the eligible set and stay within the approved credit budget.',
       inputSchema: obj({ email: S }, ['email']),
     },
     run: (a) => api('POST', '/verify/catchall', { email: a.email }),
@@ -676,7 +809,7 @@ const TOOLS = {
   },
   run_enrich: {
     def: {
-      description: 'Enqueue a bulk enrichment run. SPENDS vendor credits — estimate + confirm first.',
+      description: 'Enqueue a bulk enrichment run. SPENDS vendor credits: estimate + confirm first.',
       inputSchema: obj({ preset_slug: S, preset_id: S, lead_ids: ARR(S), filter_query: O }),
     },
     run: (a) =>
@@ -707,6 +840,24 @@ const TOOLS = {
         ...(a.cache_settings ? { cache_settings: a.cache_settings } : {}),
       }),
   },
+  get_playbook: {
+    def: { description: "Read this workspace's saved Playbook and niches before setting up work.", inputSchema: obj({}) },
+    run: () => api('GET', '/playbook'),
+  },
+  update_playbook: {
+    def: {
+      description: 'Save defaults for this workspace only. Saves the sections you provide and keeps other answers. Never starts a scrape or spends credits.',
+      inputSchema: obj({ sections: { type: 'object', properties: Object.fromEntries(['channels', 'scrape', 'tables', 'checks', 'routing', 'campaigns'].map((key) => [key, { type: 'object' }])), additionalProperties: false } }, ['sections']),
+    },
+    run: (a) => api('PUT', '/playbook', a.sections),
+  },
+  set_playbook_niches: {
+    def: {
+      description: 'Save chosen niches in tiers 1, 2 or 3. A null tier removes a niche without deleting its category. Set replace to true only to replace all chosen niches.',
+      inputSchema: obj({ niches: ARR(obj({ gcid: { type: ['string', 'null'] }, name: { type: ['string', 'null'] }, tier: { type: ['integer', 'null'], enum: [1, 2, 3, null] } })), replace: B }, ['niches']),
+    },
+    run: (a) => api('PUT', '/playbook/niches', a),
+  },
   get_ai_context: {
     def: {
       description: 'Get the workspace AI context (company description, ICP, buyer personas) that seeds every AI feature.',
@@ -761,7 +912,7 @@ const TOOLS = {
   list_senders: {
     def: {
       description:
-        'List the sender vendors Scrapeloop supports (instantly, …) with each one\'s capabilities (webhooks, lead lists, async moves, bulk upload). Catalog read — use it to know what a connected sender can do before configuring feed/offload.',
+        'List the sender vendors Scrapeloop supports (instantly, …) with each one\'s capabilities (webhooks, lead lists, async moves, bulk upload). Catalog read: use it to know what a connected sender can do before configuring feed/offload.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/senders'),
@@ -769,7 +920,7 @@ const TOOLS = {
   list_sender_campaigns: {
     def: {
       description:
-        "List a sender credential's campaigns at the vendor (vendor-generic: works for any connected sender key, same shape as list_instantly_campaigns — use it to pick external_list_id).",
+        "List a sender credential's campaigns at the vendor (vendor-generic: works for any connected sender key, same shape as list_instantly_campaigns; use it to pick external_list_id).",
       inputSchema: obj({ credential_id: S }, ['credential_id']),
     },
     run: (a) => api('GET', `/senders/${enc(a.credential_id)}/campaigns`),
@@ -806,6 +957,10 @@ const TOOLS = {
     def: { description: 'List campaigns with per-campaign stats and the bound list name.', inputSchema: obj({}) },
     run: () => api('GET', '/campaigns'),
   },
+  get_campaign_setup_options: {
+    def: { description: 'Read this workspace\'s channel choices and defaults for new campaign drafts. Explicit create choices win. Reading options changes nothing and starts no campaign.', inputSchema: obj({}) },
+    run: () => api('GET', '/campaigns/options'),
+  },
   preview_add_leads_to_campaign: {
     def: {
       description:
@@ -833,21 +988,32 @@ const TOOLS = {
   create_campaign: {
     def: {
       description:
-        'Create a campaign binding a Scrapeloop list (source_list_id) OR segment to an Instantly campaign (external_list_id from list_instantly_campaigns). feed_mode: off|auto_add|drip. Set target_active_count, cooldown_days (default 180), resting_period_days (default 90). Created paused — confirm before activate_campaign.',
+        'Create a draft campaign connected to a sender and a Scrapeloop Table or segment. Read get_campaign_setup_options first. Absent choices use this workspace Playbook; explicit values win. GoHighLevel SMS needs a source Table and external_list_id set to a workflow ID or contacts-only. Nothing starts until activate_campaign. Ask the user before Start.',
       inputSchema: obj(
         {
           name: S,
+          sender_options: { ...O, description: "GoHighLevel SMS choices: workflow_id, tags, require_verified_mobile, voip_counts_as_mobile, missing_fields (ask, create, never)." },
+          icon: { type: ["string", "null"], description: "One or two emoji, or null to clear." },
           source_list_id: S,
           segment_id: S,
           sender_credential_id: S,
           external_list_id: S,
           instantly_campaign_name: S,
           feed_mode: { ...S, enum: ['off', 'auto_add', 'drip'] },
+          allow_risky_emails: B,
+          offload_enabled: B,
+          offload_no_reply_days: N,
+          offload_to_instantly: B,
+          offload_to_scrapeloop: B,
+          offload_scrapeloop_list_id: S,
           drip_strategy: { ...S, enum: ['target_active', 'fixed_daily'] },
           drip_daily_count: N,
           target_active_count: N,
           cooldown_days: N,
           resting_period_days: N,
+          recycle_mode: { ...S, enum: ['off', 'after_cooldown'] },
+          prioritize_fresh: B,
+          bounce_instantly_list_id: S,
         },
         ['name', 'sender_credential_id', 'external_list_id'],
       ),
@@ -856,7 +1022,10 @@ const TOOLS = {
       const body = { name: a.name, sender_credential_id: a.sender_credential_id, external_list_id: a.external_list_id };
       for (const k of [
         'source_list_id', 'segment_id', 'instantly_campaign_name', 'feed_mode', 'drip_strategy',
+        'allow_risky_emails', 'offload_enabled', 'offload_no_reply_days', 'offload_to_instantly',
+        'offload_to_scrapeloop', 'offload_scrapeloop_list_id',
         'drip_daily_count', 'target_active_count', 'cooldown_days', 'resting_period_days',
+        'recycle_mode', 'prioritize_fresh', 'bounce_instantly_list_id', 'sender_options', 'icon',
       ]) {
         if (a[k] !== undefined && a[k] !== null) body[k] = a[k];
       }
@@ -864,19 +1033,19 @@ const TOOLS = {
     },
   },
   update_campaign: {
-    def: { description: 'Patch a campaign (feed_mode, target_active_count, cooldown_days, external_list_id, …).', inputSchema: obj({ campaign_id: S, patch: O }, ['campaign_id', 'patch']) },
+    def: { description: 'Patch a campaign (feed_mode, target_active_count, cooldown_days, external_list_id, …). Switching feed_mode on for an already active campaign runs the same check as campaign_readiness_check: any fail answers 422 with the report under detail.readiness.', inputSchema: obj({ campaign_id: S, patch: { ...O, description: "Campaign settings to change.", properties: { sender_options: { ...O, description: "GoHighLevel SMS settings. Only supplied keys change." }, icon: { type: ["string", "null"], description: "One or two emoji, or null to clear." } }, additionalProperties: true } }, ['campaign_id', 'patch']) },
     run: (a) => api('PATCH', `/campaigns/${enc(a.campaign_id)}`, a.patch || {}),
   },
   duplicate_campaign: {
     def: {
       description:
-        'Duplicate a campaign: clones ALL configuration (list/segment binding, sender credential, Instantly binding, feed/drip/offload settings, field mapping) into a new draft named "Copy of …". Created SAFE regardless of the source — feed_mode is forced to off and require_approval to true, so the copy never feeds leads to Instantly until explicitly enabled. Leads/stats/ledger are NOT copied.',
+        'Duplicate a campaign: clones ALL configuration (list/segment binding, sender credential, Instantly binding, feed/drip/offload settings, field mapping) into a new draft named "Copy of …". Created SAFE regardless of the source: feed_mode is forced to off and require_approval to true, so the copy never feeds leads to Instantly until explicitly enabled. Leads/stats/ledger are NOT copied.',
       inputSchema: obj({ campaign_id: S }, ['campaign_id']),
     },
     run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/duplicate`),
   },
   activate_campaign: {
-    def: { description: 'Activate a campaign — STARTS the feed/send loop. Confirm with the user first.', inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
+    def: { description: 'Activate a campaign: STARTS the feed/send loop. Run campaign_readiness_check first; any fail makes this answer 422 with the report under detail.readiness. Confirm with the user first.', inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
     run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/activate`),
   },
   pause_campaign: {
@@ -891,6 +1060,53 @@ const TOOLS = {
     def: { description: "A campaign's ledger stats + best-effort live Instantly analytics.", inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
     run: (a) => api('GET', `/campaigns/${enc(a.campaign_id)}/stats`),
   },
+  get_campaign_field_mapping: {
+    def: {
+      description:
+        'What a campaign sends to the sender and what each detail is called there. Returns every name the sequence uses, every source that could fill it (with how full each one is over the first 500 rows), and the obvious matches. Read this when a merge variable comes out blank in the emails.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) => api('GET', `/campaigns/${enc(a.campaign_id)}/field-mapping`),
+  },
+  create_sender_fields: {
+    def: {
+      description: 'Create missing GoHighLevel SMS contact fields only after the user agrees. Existing fields are reused. With remember never, save the choice and create nothing. Returns requested names mapped to actual field keys; use those keys when saving the mapping.',
+      inputSchema: obj({ campaign_id: S, names: ARR(S), remember: { type: ['string', 'null'], enum: ['create', 'never', null] } }, ['campaign_id', 'names']),
+    },
+    run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/sender-fields`, { names: a.names, remember: a.remember ?? null }),
+  },
+  set_campaign_field_mapping: {
+    def: {
+      description:
+        'Set what a campaign sends. `mapping` is {name the sender receives: where it comes from}, using lead.<column>, send.<name>, col.<table column key> or custom.<key>. `identity` may override first_name, last_name and company only, never email. `only_mapped` true means the mapping is the complete list and nothing else is sent. Saving also records that a person reviewed it, which a campaign needs before its feed can be switched on.',
+      inputSchema: obj(
+        { campaign_id: S, mapping: { type: 'object' }, identity: { type: 'object' }, only_mapped: B },
+        ['campaign_id'],
+      ),
+    },
+    run: (a) =>
+      api('PUT', `/campaigns/${enc(a.campaign_id)}/field-mapping`, {
+        mapping: a.mapping || {},
+        identity: a.identity || {},
+        only_mapped: a.only_mapped !== false,
+      }),
+  },
+  campaign_delivery_coverage: {
+    def: {
+      description:
+        'What the live sequence asks for versus what the feed will actually supply. Names any merge variable that nothing fills, which goes out blank in the middle of a sentence, and any that is only filled on some leads.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) => api('GET', `/campaigns/${enc(a.campaign_id)}/delivery-coverage`),
+  },
+  campaign_readiness_check: {
+    def: {
+      description:
+        'Is this campaign ready to start? Run it before activate_campaign. Returns ready, sender_known, sampled and a list of checks, each with a stable key, a level (pass, warn, fail or info), one plain sentence and a fix. Any fail means activate_campaign will refuse with 422 and the same report under detail.readiness. A warn does not block: read it out to the user before they confirm. It judges the leads the feed sends next (not the ones already in the campaign). With feed_mode off nothing is uploaded, so the lead and mailbox checks only warn until the feed is switched on.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) => api('GET', `/campaigns/${enc(a.campaign_id)}/readiness`),
+  },
   get_sender_config: {
     def: { description: "Get an Instantly credential's sender config (daily cap, send accounts, …).", inputSchema: obj({ credential_id: S }, ['credential_id']) },
     run: (a) => api('GET', `/sender_configs/${enc(a.credential_id)}`),
@@ -943,6 +1159,35 @@ const TOOLS = {
     },
     run: () => api('GET', '/workbench/tree'),
   },
+  get_pipeline: {
+    def: {
+      description: 'Read the saved result and progress for a pipeline. Use its operation_id after an interrupted create.',
+      inputSchema: obj({ operation_id: { ...S, format: 'uuid' } }, ['operation_id']),
+    },
+    run: (a) => api('GET', `/pipelines/${enc(a.operation_id)}`),
+  },
+  preview_pipeline: {
+    def: {
+      description: 'Preview an empty pipeline from this workspace Playbook, including Tables, columns, checks, rules and future-row work. Creates nothing. Review this before create_pipeline.',
+      inputSchema: obj({}),
+    },
+    run: (a) => api('POST', '/pipelines/preview', a),
+  },
+  create_pipeline: {
+    def: {
+      description: 'Create an empty pipeline from this workspace Playbook. Raw keeps originals. Rules start on, and chosen columns run on future rows. Creation starts no scrape, sends no messages and activates no campaign. Read get_playbook first. Reuse the same operation_id and choices to resume a partial create. Campaign bindings require campaigns:write and feeds off.',
+      inputSchema: obj({
+        operation_id: { ...S, format: 'uuid' }, name: S, market: S,
+        niche_gcids: ARR(S), mode: { ...S, enum: ['auto', 'simple', 'advanced'] },
+        channels: ARR({ ...S, enum: ['email', 'sms', 'linkedin'] }),
+        checks: { ...O, description: 'Overrides for saved checks, using the Playbook checks keys.' },
+        stage_mode: { ...S, enum: ['move', 'copy'] }, carry_values: B,
+        raw_setup: { ...O, description: 'Optional Raw columns, packs and layout. Same shape as create_table table_setup.' },
+        bindings: { ...O, description: 'Optional email, sms or linkedin campaign IDs. Existing campaign feeds must be off.' },
+      }, ['operation_id', 'name']),
+    },
+    run: (a) => api('POST', '/pipelines', a),
+  },
   create_workbook: {
     def: {
       description:
@@ -955,7 +1200,7 @@ const TOOLS = {
     def: {
       description:
         'Add one tab to a workbook. Pass list_id to attach an existing standalone Table, or new_table_name to create a new empty Table and attach it. Pass exactly one.',
-      inputSchema: obj({ workbook_id: S, list_id: S, new_table_name: S }, ['workbook_id']),
+      inputSchema: obj({ workbook_id: S, list_id: S, new_table_name: S, operation_id: { ...S, format: 'uuid' }, table_setup: { ...O, description: 'New Tables only. Same saved-column, pack and layout choices as create_table.' } }, ['workbook_id']),
     },
     run: (a) => {
       if (!!a.list_id === !!a.new_table_name) {
@@ -968,6 +1213,8 @@ const TOOLS = {
       return api('POST', `/workbooks/${enc(a.workbook_id)}/tables`, {
         ...(a.list_id ? { list_id: a.list_id } : {}),
         ...(a.new_table_name ? { new_table_name: a.new_table_name } : {}),
+        ...(a.operation_id ? { operation_id: a.operation_id } : {}),
+        ...(a.table_setup !== undefined ? { table_setup: a.table_setup } : {}),
       });
     },
   },
@@ -1059,16 +1306,33 @@ const TOOLS = {
     },
     run: (a) => api('GET', `/tables${qs({ archived: a.archived })}`),
   },
+  get_table_setup_options: {
+    def: {
+      description: 'Read this workspace\'s saved Table columns, layout and available column packs. Read-only; starts no work.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/playbook/tables/options'),
+  },
   create_table: {
     def: {
       description:
-        'Create a campaign-bindable Scrapeloop Table. Static is the default for imported/manual leads and accepts only name, description, and kind. filter_expression, sort_expression, visible_columns, and is_shared are smart-Table-only fields. The create is retry-safe: one operation_id is reused across HTTP retries. You may pass a prior operation_id to recover an ambiguous call; reusing it with different inputs returns 409.',
+        'Create a Scrapeloop Table. Regular Tables start with this workspace\'s saved columns and layout. Use table_setup to change columns, choose packs or rename labels. Creation never runs columns or spends credits. Smart Tables use filter_expression, sort_expression, visible_columns and is_shared, and cannot use table_setup. Retry with the same operation_id; different inputs return 409.',
       inputSchema: obj(
         {
           name: S,
           operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
           description: S,
           kind: { ...S, enum: ['static', 'smart'] },
+          table_setup: {
+            ...O,
+            description: 'Regular Tables only. Read get_table_setup_options first. columns replaces saved columns (empty list means none); packs adds named packs; identity_column_state replaces the saved layout. All created columns start with auto-run off.',
+            properties: {
+              columns: ARR({ ...O, properties: { kind: { ...S, enum: ['native', 'preset'] }, key: S, label: S, config: O }, required: ['kind', 'key', 'label'] }),
+              packs: ARR(S),
+              identity_column_state: O,
+            },
+            additionalProperties: false,
+          },
           filter_expression: { ...O, description: 'Smart Tables only.' },
           sort_expression: { ...O, description: 'Smart Tables only.' },
           visible_columns: { ...ARR(S), description: 'Smart Tables only.' },
@@ -1096,6 +1360,7 @@ const TOOLS = {
         operation_id: a.operation_id || randomUUID(),
         ...(a.description !== undefined ? { description: a.description } : {}),
         ...(a.kind !== undefined ? { kind: a.kind } : {}),
+        ...(a.table_setup !== undefined ? { table_setup: a.table_setup } : {}),
         ...(a.filter_expression !== undefined ? { filter_expression: a.filter_expression } : {}),
         ...(a.sort_expression !== undefined ? { sort_expression: a.sort_expression } : {}),
         ...(a.visible_columns !== undefined ? { visible_columns: a.visible_columns } : {}),
@@ -1207,6 +1472,156 @@ const TOOLS = {
       });
     },
   },
+  create_table_preset_column: {
+    def: {
+      description:
+        'Attach one shipped system preset or active workspace preset as a real enrichment column. operation_id is required and must be reused for every retry. auto_run defaults false and queues nothing. If auto_run would backfill existing rows, the API returns an exact 409 estimate first; confirm that estimate with confirm_auto_run and confirmed_estimated_cost_usd before retrying. The Table master auto-run switch and budget caps remain fail-closed. Only preset-documented overrides are accepted.',
+      inputSchema: {
+        ...obj(
+          {
+            table_id: S,
+            preset_slug: S,
+            preset_id: { ...S, format: 'uuid' },
+            label: S,
+            auto_run: B,
+            confirm_auto_run: B,
+            confirmed_estimated_cost_usd: { ...N, minimum: 0 },
+            overrides: O,
+            operation_id: {
+              ...S,
+              format: 'uuid',
+              description: 'Required stable retry key for this logical preset-column create.',
+            },
+          },
+          ['table_id', 'operation_id'],
+        ),
+        oneOf: [
+          { required: ['preset_slug'], not: { required: ['preset_id'] } },
+          { required: ['preset_id'], not: { required: ['preset_slug'] } },
+        ],
+      },
+    },
+    run: async (a) => {
+      if (!a.table_id || !a.operation_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'table_id and a stable operation_id are required.' },
+        };
+      }
+      if (!!a.preset_slug === !!a.preset_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Pass exactly one of preset_slug or preset_id.' },
+        };
+      }
+      const requestBody = {
+        operation_id: a.operation_id,
+        ...(a.preset_slug !== undefined ? { preset_slug: a.preset_slug } : {}),
+        ...(a.preset_id !== undefined ? { preset_id: a.preset_id } : {}),
+        ...(a.label !== undefined ? { label: a.label } : {}),
+        ...(a.auto_run !== undefined ? { auto_run: a.auto_run } : {}),
+        ...(a.confirm_auto_run !== undefined ? { confirm_auto_run: a.confirm_auto_run } : {}),
+        ...(a.confirmed_estimated_cost_usd !== undefined
+          ? { confirmed_estimated_cost_usd: a.confirmed_estimated_cost_usd }
+          : {}),
+        ...(a.overrides !== undefined ? { overrides: a.overrides } : {}),
+      };
+      const path = `/tables/${enc(a.table_id)}/preset-columns`;
+      return api('POST', path, requestBody, {
+        reconciliation: {
+          operation_id: a.operation_id,
+          retry_with: {
+            tool: 'create_table_preset_column',
+            arguments: { ...a, operation_id: a.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table_preset_column with the same operation_id ${a.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
+    },
+  },
+  get_table_native_tools: {
+    def: {
+      description:
+        'List the first-party Scrapeloop tools a Smart Table column can be built on, with their per-row credit price, documented options, and the legacy preset slugs each one supersedes. Read this when create_table_preset_column refuses a slug as superseded, or before create_table_native_column, so the tool key and options are exact rather than guessed.',
+      inputSchema: obj({}, []),
+    },
+    run: () => api('GET', '/tables/native-tools'),
+  },
+  create_table_native_column: {
+    def: {
+      description:
+        `Attach one native Scrapeloop tool as a real Smart Table column: ${NATIVE_TABLE_TOOLS.join(', ')}. These are the first-party tools that superseded four legacy presets, so they are addressed by tool key here rather than by preset slug through create_table_preset_column (which refuses a superseded slug for a new column). Each bills MANAGED VERIFICATION CREDITS per row, never dollars and never the customer's own vendor keys: verify_email reserves 1 credit per selected row, verify_phone reserves 5, and each email finder reserves 3. Settlement charges only fresh vendor checks and returns the unused reservation; missing inputs, cached rows, and skipped rows are free. Creating a column is always free. auto_run defaults false and queues nothing; when auto_run would backfill existing rows the API returns a 409 estimate whose cost.total_credits is the real charge, and you confirm it with confirm_auto_run plus confirmed_credits (CREDITS, not dollars - estimated_cost_usd is our vendor cost and is far smaller than what the workspace is billed). An auto_run that exceeds the workspace verify-credit balance returns 402 with {credit_kind, required, available} before anything is created. The Table master auto-run switch and workspace budget caps stay fail-closed. options are per tool and only the documented names are accepted - call get_table_native_tools for the current list. Owner email finder needs an owner first name plus the company website; point options.owner_name_column at an Owner name finder column to source the name, which auto_run requires. Business email finder is a SEPARATE column - create it with its own call and set options.owner_email_column to run it behind an owner finder. The Catch-all verifier is NOT creatable here: it needs a Verify email column that has already RUN and returned Catch All or Unknown, so use verify_catchall per address, or add the column from the Table's add-column menu.`,
+      inputSchema: obj(
+        {
+          table_id: S,
+          tool: { ...S, enum: NATIVE_TABLE_TOOLS },
+          label: { ...S, description: 'Column label. Defaults to the tool name.' },
+          auto_run: B,
+          confirm_auto_run: B,
+          confirmed_credits: {
+            ...N,
+            minimum: 0,
+            description:
+              'The 409 estimate\'s cost.total_credits, echoed back exactly. Verification credits, not dollars.',
+          },
+          options: {
+            ...O,
+            description:
+              'Tool-specific options. verify_phone: phone_col, default_region. email_finder: owner_name_column. business_email_finder: owner_email_column. An undocumented name is rejected, never ignored.',
+          },
+          operation_id: {
+            ...S,
+            format: 'uuid',
+            description: 'Required stable retry key for this logical native-column create.',
+          },
+        },
+        ['table_id', 'tool', 'operation_id'],
+      ),
+    },
+    run: async (a) => {
+      if (!a.table_id || !a.tool || !a.operation_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'table_id, tool, and a stable operation_id are required.' },
+        };
+      }
+      if (!NATIVE_TABLE_TOOLS.includes(a.tool)) {
+        return {
+          ok: false,
+          status: 400,
+          error: {
+            detail: `Unknown native tool '${a.tool}'. Expected one of ${NATIVE_TABLE_TOOLS.join(', ')}. Call get_table_native_tools for the live catalog.`,
+          },
+        };
+      }
+      const requestBody = {
+        tool: a.tool,
+        operation_id: a.operation_id,
+        ...(a.label !== undefined ? { label: a.label } : {}),
+        ...(a.auto_run !== undefined ? { auto_run: a.auto_run } : {}),
+        ...(a.confirm_auto_run !== undefined ? { confirm_auto_run: a.confirm_auto_run } : {}),
+        ...(a.confirmed_credits !== undefined
+          ? { confirmed_credits: a.confirmed_credits }
+          : {}),
+        ...(a.options !== undefined ? { options: a.options } : {}),
+      };
+      return api('POST', `/tables/${enc(a.table_id)}/native-columns`, requestBody, {
+        reconciliation: {
+          operation_id: a.operation_id,
+          retry_with: {
+            tool: 'create_table_native_column',
+            arguments: { ...a, operation_id: a.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table_native_column with the same operation_id ${a.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
+    },
+  },
   set_table_cells: {
     def: {
       description:
@@ -1311,6 +1726,55 @@ const TOOLS = {
       });
     },
   },
+  list_apify_actors: {
+    def: {
+      description:
+        'List the APPROVED Apify actors you may run/import from. Arbitrary Apify actors are NOT allowed: only vetted actors (website content, contact info with add-ons off, google search with add-ons off) can be used, and LinkedIn / Facebook-group / social-graph actors are always rejected. Returns [{actor_id, add_ons_allowed}]. Use this before preview_apify_import to pick a permitted actor_id.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/apify/actors'),
+  },
+  preview_apify_import: {
+    def: {
+      description:
+        "Read-only preview of an approved Apify actor's already-produced dataset before importing it. mapping is {lead_field: dotted.source.path} where lead_field is one of name, email, phone, domain, organization_name, city, state, country, linkedin_url, title. Normalizes the whole dataset (rows with no email/phone/domain/linkedin/name are skipped), returns the first 25 rows plus record_count (the true total) and a preview_hash. Pass that preview_hash to import_apify_dataset: the import re-verifies it and refuses (409) if the dataset changed. Does NOT run the actor or spend: it reads an existing dataset_id. Returns {dataset_id, actor_id, record_count, preview, preview_truncated, preview_hash}.",
+      inputSchema: obj(
+        {
+          dataset_id: { ...S, description: 'Apify dataset id from a completed actor run.' },
+          actor_id: { ...S, description: 'Approved actor id (owner/name), e.g. apify/google-search-scraper.' },
+          mapping: { ...O, description: '{lead_field: "dotted.source.path"} onto the lead spine.' },
+        },
+        ['dataset_id', 'actor_id', 'mapping'],
+      ),
+    },
+    run: (a) => api('POST', '/apify/preview', { dataset_id: a.dataset_id, actor_id: a.actor_id, mapping: a.mapping }),
+  },
+  import_apify_dataset: {
+    def: {
+      description:
+        'Import a previewed Apify dataset (≤1000 rows) into a private Scrapeloop Table through the bring-your-own-leads funnel (dedupe + identity matching + Table attach reused; no lead credits). Call preview_apify_import first and pass its preview_hash: the import re-reads the dataset and returns 409 (preview_drift) if it changed since preview. Each row gets a stable external_id (apify:{dataset}:{row}) so re-importing updates rather than duplicates; company lands in business_name and the contact name/title ride through as custom fields. Target list_id, or omit for a new "Apify import" Table. Returns the import funnel result {inserted, updated, deduped, invalid, ...}.',
+      inputSchema: obj(
+        {
+          dataset_id: S,
+          actor_id: S,
+          mapping: O,
+          preview_hash: { ...S, description: 'The preview_hash returned by preview_apify_import.' },
+          list_id: S,
+          list_name: S,
+        },
+        ['dataset_id', 'actor_id', 'mapping', 'preview_hash'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/apify/import', {
+        dataset_id: a.dataset_id,
+        actor_id: a.actor_id,
+        mapping: a.mapping,
+        preview_hash: a.preview_hash,
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+      }),
+  },
   capture_community_intent: {
     def: {
       description:
@@ -1466,7 +1930,7 @@ const TOOLS = {
   preview_import: {
     def: {
       description:
-        'Dry-run for import_leads: report exactly what an import WOULD do — {would_insert, would_update, deduped, invalid, invalid_reasons, list_exists} — WITHOUT writing anything (no leads, no list, no tags created). Same inputs as import_leads. Call this first for a bring-your-own batch, show the user the plan (e.g. "adds 340 new, updates 12, skips 3 bad rows"), then confirm before import_leads.',
+        'Dry-run for import_leads: report exactly what an import WOULD do ({would_insert, would_update, deduped, invalid, invalid_reasons, list_exists}) WITHOUT writing anything (no leads, no list, no tags created). Same inputs as import_leads. Call this first for a bring-your-own batch, show the user the plan (e.g. "adds 340 new, updates 12, skips 3 bad rows"), then confirm before import_leads.',
       inputSchema: obj(
         {
           list_id: S,
@@ -1720,6 +2184,60 @@ const TOOLS = {
             error: { detail: 'campaign_id and rule_id are required.' },
           },
   },
+  test_flow_rule: {
+    def: {
+      description:
+        'Test one saved flow rule against one lead. Dry-run is the safe default and reports whether the row matches plus the action that would run. Set execute=true only after confirmation because the action may spend credits or change data.',
+      inputSchema: obj(
+        {
+          list_id: { ...S, description: 'Source Table id. Provide this or campaign_id, never both.' },
+          campaign_id: { ...S, description: 'Source campaign id. Provide this or list_id, never both.' },
+          rule_id: S,
+          lead_id: { ...S, description: 'Optional lead id. The newest source row is used when omitted.' },
+          execute: { ...B, description: 'False for dry-run. True executes the action once.' },
+        },
+        ['rule_id'],
+      ),
+    },
+    run: (a) => {
+      if (!!a.list_id === !!a.campaign_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Provide exactly one of list_id or campaign_id.' },
+        };
+      }
+      const source = a.list_id
+        ? `/lists/${enc(a.list_id)}`
+        : `/campaigns/${enc(a.campaign_id)}`;
+      return api('POST', `${source}/flow-rules/${enc(a.rule_id)}/test`, {
+        ...(a.lead_id ? { lead_id: a.lead_id } : {}),
+        execute: !!a.execute,
+      });
+    },
+  },
+  get_flow_rule_stats: {
+    def: {
+      description:
+        'Get the frozen 24-hour and 7-day fire, failure, last-run, and paused-state counters for every saved rule on one Table or campaign.',
+      inputSchema: obj({
+        list_id: { ...S, description: 'Source Table id. Provide this or campaign_id, never both.' },
+        campaign_id: { ...S, description: 'Source campaign id. Provide this or list_id, never both.' },
+      }),
+    },
+    run: (a) => {
+      if (!!a.list_id === !!a.campaign_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Provide exactly one of list_id or campaign_id.' },
+        };
+      }
+      return a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/flow-rules/stats`)
+        : api('GET', `/campaigns/${enc(a.campaign_id)}/flow-rules/stats`);
+    },
+  },
   preview_send_to_table: {
     def: {
       description:
@@ -1834,7 +2352,7 @@ const TOOLS = {
   list_table_rows: {
     def: {
       description:
-        "Read a table's rows the way the grid sees them — lead identity fields (name/email/phone/domain/city/state/country/status) plus every column's cell (status + value). Server-side: sort is a JSON-array string like [{\"key\":\"lead.name\",\"dir\":\"asc\"},{\"key\":\"col.company_size\",\"dir\":\"desc\"}] (keys are lead.<field> or col.<column_key>, ≤3 levels); q is a full-text search across identity fields + visible column cells; filter is a FilterExpr object (same grammar the Tables filter UI uses) — e.g. {\"and\":[{\"field\":\"lead.email_status\",\"op\":\"eq\",\"value\":\"valid\"},{\"field\":\"col.company_size\",\"op\":\"gte\",\"value\":50}]} — and adds total_filtered alongside total; pass the previous response's next_cursor back as cursor to page (null next_cursor = last page). Distinct from get_list_rows (the plain import read-back). limit ≤ 500.",
+        "Read a table's rows the way the grid sees them: lead identity fields (name/email/phone/domain/city/state/country/status) plus every column's cell (status + value). Server-side: sort is a JSON-array string like [{\"key\":\"lead.name\",\"dir\":\"asc\"},{\"key\":\"col.company_size\",\"dir\":\"desc\"}] (keys are lead.<field> or col.<column_key>, ≤3 levels); q is a full-text search across identity fields + visible column cells; filter is a FilterExpr object (same grammar the Tables filter UI uses), e.g. {\"and\":[{\"field\":\"lead.email_status\",\"op\":\"eq\",\"value\":\"valid\"},{\"field\":\"col.company_size\",\"op\":\"gte\",\"value\":50}]}, and adds total_filtered alongside total; pass the previous response's next_cursor back as cursor to page (null next_cursor = last page). Distinct from get_list_rows (the plain import read-back). limit ≤ 500.",
       inputSchema: obj(
         {
           list_id: S,
@@ -1842,7 +2360,7 @@ const TOOLS = {
           limit: N,
           sort: S,
           q: S,
-          filter: { ...O, description: 'FilterExpr JSON (object) — server-side row filter; adds total_filtered.' },
+          filter: { ...O, description: 'FilterExpr JSON (object): server-side row filter; adds total_filtered.' },
           view_id: { ...S, description: 'A saved custom view uuid or a system key (errored_rows/fully_enriched/data_only) from list_table_views. An ad-hoc filter/sort replaces the view\'s.' },
         },
         ['list_id'],
@@ -1866,7 +2384,7 @@ const TOOLS = {
   list_table_views: {
     def: {
       description:
-        "List a table's views — three always-current SYSTEM views (errored_rows / fully_enriched / data_only) plus the user's saved custom views. Pass a returned id (or a system key) as view_id to list_table_rows to read that view (a saved filter + sorts + column overlay).",
+        "List a table's views: three always-current SYSTEM views (errored_rows / fully_enriched / data_only) plus the user's saved custom views. Pass a returned id (or a system key) as view_id to list_table_rows to read that view (a saved filter + sorts + column overlay).",
       inputSchema: obj({ list_id: S }, ['list_id']),
     },
     run: (a) =>
@@ -1922,7 +2440,7 @@ const TOOLS = {
   update_table_view: {
     def: {
       description:
-        'Update a saved table view — any field (name/description/filter_expression/sorts/column_state/row_window); a field set to null clears it. System views (errored_rows/fully_enriched/data_only) are read-only.',
+        'Update a saved table view: any field (name/description/filter_expression/sorts/column_state/row_window); a field set to null clears it. System views (errored_rows/fully_enriched/data_only) are read-only.',
       inputSchema: obj(
         { list_id: S, view_id: S, name: S, description: S, filter_expression: O, sorts: ARR(O), column_state: O, row_window: O },
         ['list_id', 'view_id'],
@@ -1939,7 +2457,7 @@ const TOOLS = {
   delete_table_view: {
     def: {
       description:
-        'Delete a saved table view — rows in the table are unaffected. Confirm with the user first. System views cannot be deleted.',
+        'Delete a saved table view. Rows in the table are unaffected. Confirm with the user first. System views cannot be deleted.',
       inputSchema: obj({ list_id: S, view_id: S }, ['list_id', 'view_id']),
     },
     run: (a) =>
@@ -1950,7 +2468,7 @@ const TOOLS = {
   estimate_table_column: {
     def: {
       description:
-        "FREE cost preview for running one enrichment column, optionally scoped to a view or selection (view_id + selection{mode:'query', filter:<FilterExpr>, exclude_ids} or {mode:'explicit', ids}). cell_filter picks which cells: 'empty_or_stale' (default in the UI — skips results still fresh under the current column config), 'failed', or 'all'; n_rows/start_row window the run (1-based). Returns lead_count + estimated_cost_usd + scope_resolved. ALWAYS show this to the user before run_table_column — it spends nothing.",
+        "FREE cost preview for running one enrichment column, optionally scoped to a view or selection (view_id + selection{mode:'query', filter:<FilterExpr>, exclude_ids} or {mode:'explicit', ids}). cell_filter picks which cells: 'empty_or_stale' (default in the UI; skips results still fresh under the current column config), 'failed', or 'all'; n_rows/start_row window the run (1-based). Returns lead_count + estimated_cost_usd + scope_resolved. ALWAYS show this to the user before run_table_column; it spends nothing.",
       inputSchema: obj(
         { list_id: S, column_id: S, view_id: S, selection: O, cell_filter: S, n_rows: N, start_row: N, only_failed: B },
         ['list_id', 'column_id'],
@@ -1964,7 +2482,7 @@ const TOOLS = {
   run_table_column: {
     def: {
       description:
-        "SPENDS vendor credits — enrich one column across the scoped rows (view_id + selection + cell_filter + n_rows/start_row, same shape as estimate_table_column). cell_filter='empty_or_stale' re-runs only rows that are empty or out of date — fresh results are never re-billed. Run estimate_table_column first and confirm with the user.",
+        "SPENDS vendor credits: enrich one column across the scoped rows (view_id + selection + cell_filter + n_rows/start_row, same shape as estimate_table_column). cell_filter='empty_or_stale' re-runs only rows that are empty or out of date; fresh results are never re-billed. Run estimate_table_column first and confirm with the user.",
       inputSchema: obj(
         { list_id: S, column_id: S, view_id: S, selection: O, cell_filter: S, n_rows: N, start_row: N, only_failed: B },
         ['list_id', 'column_id'],
@@ -1978,7 +2496,7 @@ const TOOLS = {
   run_scope_summary: {
     def: {
       description:
-        'FREE counts + estimates for a column run scope — total, empty_or_stale, stale, failed rows + est_all/est_empty_or_stale/est_first_10 USD + budget. Use to decide what to run (which cell_filter) before estimate/run_table_column. Read-only.',
+        'FREE counts + estimates for a column run scope: total, empty_or_stale, stale, failed rows + est_all/est_empty_or_stale/est_first_10 USD + budget. Use to decide what to run (which cell_filter) before estimate/run_table_column. Read-only.',
       inputSchema: obj({ list_id: S, column_id: S, view_id: S, selection: O }, ['list_id', 'column_id']),
     },
     run: (a) =>
@@ -1992,7 +2510,7 @@ const TOOLS = {
   estimate_table_run_all: {
     def: {
       description:
-        'FREE per-column preview + total for running EVERY enrichment column in dependency order, optionally scoped (view_id + selection). Show before run_table_all — spends nothing.',
+        'FREE per-column preview + total for running EVERY enrichment column in dependency order, optionally scoped (view_id + selection). Show before run_table_all; spends nothing.',
       inputSchema: obj(
         { list_id: S, column_ids: ARR(S), view_id: S, selection: O, only_empty: B },
         ['list_id'],
@@ -2011,7 +2529,7 @@ const TOOLS = {
   run_table_all: {
     def: {
       description:
-        'SPENDS vendor credits — run every enrichment column in dependency order over the scoped rows (only empty cells run by default; cached results are free). Run estimate_table_run_all first and confirm with the user.',
+        'SPENDS vendor credits: run every enrichment column in dependency order over the scoped rows (only empty cells run by default; cached results are free). Run estimate_table_run_all first and confirm with the user.',
       inputSchema: obj(
         { list_id: S, column_ids: ARR(S), view_id: S, selection: O, only_empty: B },
         ['list_id'],
@@ -2041,7 +2559,7 @@ const TOOLS = {
   remove_table_rows: {
     def: {
       description:
-        'Remove rows from a Scrapeloop table (list) by lead id — the leads stay in the workspace pool; only the table membership and that table\'s enrichment cells are removed. Get ids from list_table_rows. To delete the whole table use delete_list.',
+        'Remove rows from a Scrapeloop table (list) by lead id. The leads stay in the workspace pool; only the table membership and that table\'s enrichment cells are removed. Get ids from list_table_rows. To delete the whole table use delete_list.',
       inputSchema: obj({ list_id: S, lead_ids: ARR(S) }, ['list_id', 'lead_ids']),
     },
     run: (a) =>
@@ -2130,7 +2648,7 @@ const TOOLS = {
   delete_list: {
     def: {
       description:
-        'Delete a list (the list + its membership; the underlying leads stay in the workspace). Works for any Scrapeloop list. Irreversible — confirm with the user first.',
+        'Delete a list (the list + its membership; the underlying leads stay in the workspace). Works for any Scrapeloop list. Irreversible: confirm with the user first.',
       inputSchema: obj({ list_id: S }, ['list_id']),
     },
     run: (a) =>
@@ -2141,7 +2659,7 @@ const TOOLS = {
   delete_campaign: {
     def: {
       description:
-        'Delete a campaign (the Scrapeloop campaign + its ledger; the Instantly campaign itself is not deleted). Irreversible — if you only want to stop sending, pause_campaign instead. Confirm with the user first.',
+        'Delete a campaign (the Scrapeloop campaign + its ledger; the Instantly campaign itself is not deleted). Irreversible. If you only want to stop sending, pause_campaign instead. Confirm with the user first.',
       inputSchema: obj({ campaign_id: S }, ['campaign_id']),
     },
     run: (a) =>
@@ -2154,7 +2672,7 @@ const TOOLS = {
   list_replies: {
     def: {
       description:
-        'List inbound campaign replies, newest first. Filters: sentiment (interested|not_interested|unsubscribed), handled (true = already actioned, false = needs attention), lead_id, campaign_id, status (pending|auto_classified|human_required|human_reviewed — human_required is the review queue).',
+        'List inbound campaign replies, newest first. Filters: sentiment (interested|not_interested|unsubscribed), handled (true = already actioned, false = needs attention), lead_id, campaign_id, status (pending|auto_classified|human_required|human_reviewed; human_required is the review queue).',
       inputSchema: obj({ sentiment: S, handled: B, lead_id: S, campaign_id: S, status: S, limit: N, offset: N }),
     },
     run: (a) =>
@@ -2174,7 +2692,7 @@ const TOOLS = {
   update_reply: {
     def: {
       description:
-        "Update a reply: mark it handled/unhandled and/or set its sentiment. Setting sentiment is a human classification — it propagates to the lead (reply_sentiment, replied_at, status transition, the unsubscribe guard for 'unsubscribed', and the workspace's auto-suppress feed).",
+        "Update a reply: mark it handled/unhandled and/or set its sentiment. Setting sentiment is a human classification: it propagates to the lead (reply_sentiment, replied_at, status transition, the unsubscribe guard for 'unsubscribed', and the workspace's auto-suppress feed).",
       inputSchema: obj(
         {
           reply_id: S,
@@ -2285,7 +2803,7 @@ const TOOLS = {
         {
           slug: S,
           status: { ...S, enum: ['planned', 'in_progress', 'deployed'] },
-          pr_url: { ...S, description: 'PR link — set it when marking deployed' },
+          pr_url: { ...S, description: 'PR link: set it when marking deployed' },
         },
         ['slug', 'status'],
       ),
@@ -2335,7 +2853,7 @@ const TOOLS = {
   roadmap_update_plan: {
     def: {
       description:
-        "Update a roadmap card's fields — most importantly plan_md (the execution plan). Also: title, summary, kind, track, area, effort, depends_on, files_hint, position, pr_url.",
+        "Update a roadmap card's fields, most importantly plan_md (the execution plan). Also: title, summary, kind, track, area, effort, depends_on, files_hint, position, pr_url.",
       inputSchema: obj(
         {
           slug: S,
@@ -2361,25 +2879,70 @@ const TOOLS = {
       );
       return Object.keys(body).length
         ? api('PATCH', `/roadmap/${enc(slug)}`, body)
-        : { ok: false, status: 400, error: { detail: 'nothing to update — pass at least one field' } };
+        : { ok: false, status: 400, error: { detail: 'nothing to update: pass at least one field' } };
     },
   },
 };
 
+TOOLS.preview_pipeline.def.inputSchema = TOOLS.create_pipeline.def.inputSchema;
+
+const extractHttpMethods = (run) => [
+  ...run.toString().matchAll(/api\(\s*['"](GET|POST|PUT|PATCH|DELETE)['"]/g),
+].map((match) => match[1]);
+
+export const TOOL_HTTP_OPERATIONS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(TOOLS).map(([name, tool]) => [
+      name,
+      Object.freeze([...new Set(extractHttpMethods(tool.run))]),
+    ]),
+  ),
+);
+
+for (const [name, tool] of Object.entries(TOOLS)) {
+  const originalRun = tool.run;
+  const policy = MUTATION_POLICIES[name];
+  const methods = TOOL_HTTP_OPERATIONS[name];
+  const retryCopy = policy
+    ? RETRY_CONTRACT_COPY[policy.retry]
+    : methods.every((method) => method === 'GET')
+      ? RETRY_CONTRACT_COPY.bounded
+      : 'Policy missing. This operation is blocked until its retry contract is reviewed.';
+  tool.def.description = `${tool.def.description} Retry contract: ${retryCopy}`;
+  if (policy?.retry === 'idempotency_key') {
+    const schema = tool.def.inputSchema;
+    tool.def.inputSchema = {
+      ...schema,
+      properties: {
+        ...schema.properties,
+        idempotency_key: {
+          type: 'string',
+          description: 'Stable UUID for this exact mutation. Reuse it after a timeout or lost response.',
+        },
+      },
+      required: [...new Set([...(schema.required || []), 'idempotency_key'])],
+    };
+  }
+  tool.run = (args = {}) => toolCallContext.run(
+    { toolName: name, policy, args },
+    () => originalRun(args),
+  );
+}
+
 async function serve() {
-  // Start cleanly even without a key — never crash or hang. The first tools/call
+  // Start cleanly even without a key: never crash or hang. The first tools/call
   // returns a clear, structured auth error (api() handles the missing key), and we
   // log exactly one warning to stderr here. The key itself is never logged.
   if (!API_KEY) {
     warnStartupOnce(
       'missing_api_key',
-      'scrapeloop-mcp: SCRAPELOOP_API_KEY is not set — tools will return an auth error until it is. ' +
+      'scrapeloop-mcp: SCRAPELOOP_API_KEY is not set, so tools will return an auth error until it is. ' +
         'Generate a key in Scrapeloop → Settings → API access.'
     );
   }
 
   const server = new Server(
-    { name: 'scrapeloop-mcp', version: '0.7.0' },
+    { name: 'scrapeloop-mcp', version: '0.8.0' },
     { capabilities: { tools: {} } }
   );
 
@@ -2420,9 +2983,10 @@ async function serve() {
 // Exported for the manifest/tools drift test. Tests set SCRAPELOOP_MCP_NO_SERVE
 // before importing so the stdio server (and the API-key requirement) stay dormant;
 // the CLI leaves it unset and serves. (An entrypoint-URL check is unreliable when
-// the install path contains spaces — import.meta.url percent-encodes them but
-// process.argv[1] does not — so an explicit opt-out flag is used instead.)
+// the install path contains spaces: import.meta.url percent-encodes them but
+// process.argv[1] does not, so an explicit opt-out flag is used instead.)
 export {
+  MUTATION_POLICIES,
   TOOLS,
   classifyApiKeyPreflight,
   formatApiKeyPreflightWarning,