scrapeloop-mcp 0.6.0 → 0.7.1

package/src/index.js

@@ -17,23 +17,61 @@
  */
 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(/\/$/, '');
 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;
+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.
-async function api(method, path, body) {
+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: upstreamStatus || 0,
+    error: {
+      type: 'uncertain_result',
+      uncertain_result: true,
+      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.',
+    },
+  };
+};
+
+async function api(method, path, body, options = {}) {
   if (!API_KEY) {
     return {
       ok: false,
@@ -45,34 +83,84 @@ async function api(method, path, body) {
       },
     };
   }
+  const fetcher = options.fetcher || fetch;
+  const sleepFn = options.sleepFn || sleep;
+  const shouldRetryResponse =
+    options.shouldRetryResponse || ((status) => status === 429 || status >= 500);
+  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 <= MAX_RETRIES; attempt++) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
     let res;
     try {
-      res = await fetch(`${BASE}/api/v1${path}`, {
-        method,
-        headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+      res = await fetcher(`${BASE}/api/v1${path}`, {
+        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 < MAX_RETRIES) {
-        await sleep(500 * 2 ** attempt);
+      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');
       return {
         ok: false,
         status: 0,
         error: { detail: `Could not reach Scrapeloop (${timedOut ? `timeout after ${TIMEOUT_MS}ms` : String(e)}).` },
+        ...(options.captureTrace
+          ? { trace_id: traceId, network_error: timedOut ? 'timeout' : 'transport' }
+          : {}),
       };
     }
     // Retry transient upstream failures (rate limit / server errors).
-    if ((res.status === 429 || res.status >= 500) && attempt < MAX_RETRIES) {
+    const transient = shouldRetryResponse(res.status);
+    if (transient && attempt < maxRetries) {
       const retryAfter = Number(res.headers.get('retry-after')) * 1000;
-      await sleep(retryAfter > 0 ? retryAfter : 500 * 2 ** attempt);
+      const delay =
+        options.respectRetryAfter !== false && retryAfter > 0
+          ? retryAfter
+          : retryDelay(attempt);
+      await sleepFn(delay);
       continue;
     }
     const text = await res.text();
@@ -83,12 +171,136 @@ async function api(method, path, body) {
       data = { raw: text };
     }
     if (!res.ok) {
-      // Surface the API's structured error verbatim (401 auth, 402 credits, 403 scope, …).
-      return { ok: false, status: res.status, error: data };
+      if (
+        transient
+        && policy?.effect === 'mutation'
+        && !(res.status === 429 && canRetry)
+      ) {
+        return uncertainResult({
+          context,
+          method: verb,
+          path,
+          upstreamStatus: res.status,
+          reconciliation: options.reconciliation,
+        });
+      }
+      return {
+        ok: false,
+        status: res.status,
+        error: data,
+        ...(options.captureTrace ? { trace_id: responseTraceId(res, traceId) } : {}),
+      };
     }
-    return { ok: true, status: res.status, data };
+    return {
+      ok: true,
+      status: res.status,
+      data,
+      ...(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,
+    error: { detail: `Request failed: ${String(lastErr)}` },
+    ...(options.captureTrace ? { trace_id: traceId } : {}),
+  };
+}
+
+const safeTraceId = (value) =>
+  typeof value === 'string' && SAFE_TRACE_ID.test(value) ? value : undefined;
+
+const responseTraceId = (response, fallback) =>
+  safeTraceId(response.headers.get(TRACE_HEADER)) || fallback;
+
+const createPreflightTraceId = () => `mcp_${randomUUID()}`;
+
+const preflightRetryDelay = (random) =>
+  150 + Math.floor(Math.max(0, Math.min(1, random())) * 150);
+
+function classifyApiKeyPreflight(response) {
+  const traceId = safeTraceId(response.trace_id);
+  if (response.ok) {
+    return { state: 'authenticated', conclusive: true, status: response.status, traceId };
   }
-  return { ok: false, status: 0, error: { detail: `Request failed: ${String(lastErr)}` } };
+  if (response.status === 401) {
+    return { state: 'invalid_key', conclusive: true, status: 401, traceId };
+  }
+  if (response.status === 403) {
+    return { state: 'forbidden', conclusive: true, status: 403, traceId };
+  }
+  if (response.status === 429) {
+    return { state: 'rate_limited', conclusive: false, status: 429, traceId };
+  }
+  if (response.status >= 500) {
+    return { state: 'server_error', conclusive: false, status: response.status, traceId };
+  }
+  if (response.status === 0) {
+    return {
+      state: 'network_unreachable',
+      conclusive: false,
+      status: 0,
+      traceId,
+      networkError: response.network_error === 'timeout' ? 'timeout' : 'transport',
+    };
+  }
+  return { state: 'inconclusive', conclusive: false, status: response.status, traceId };
+}
+
+async function runApiKeyPreflight(options = {}) {
+  const random = options.random || Math.random;
+  const traceId = safeTraceId(options.traceId) || createPreflightTraceId();
+  let response;
+  try {
+    response = await api('GET', '/me', undefined, {
+      captureTrace: true,
+      fetcher: options.fetcher,
+      maxRetries: 1,
+      respectRetryAfter: false,
+      retryDelay: () => preflightRetryDelay(random),
+      shouldRetryResponse: (status) => status >= 500,
+      sleepFn: options.sleepFn,
+      traceId,
+    });
+  } catch {
+    response = {
+      ok: false,
+      status: 0,
+      trace_id: traceId,
+      network_error: 'transport',
+    };
+  }
+  return classifyApiKeyPreflight(response);
+}
+
+function formatApiKeyPreflightWarning(response) {
+  const trace = response.traceId ? ` Trace ID: ${response.traceId}.` : '';
+  if (response.state === 'invalid_key') {
+    return `scrapeloop-mcp: API key preflight failed: the key is invalid or revoked. Tools may return authentication errors.${trace}`;
+  }
+  if (response.state === 'forbidden') {
+    return `scrapeloop-mcp: API key preflight failed: the identity check is forbidden. Tool calls remain independent.${trace}`;
+  }
+  if (response.state === 'rate_limited') {
+    return `scrapeloop-mcp: API key preflight inconclusive: the identity check was rate limited. Tool calls remain available.${trace}`;
+  }
+  if (response.state === 'server_error') {
+    return `scrapeloop-mcp: API key preflight inconclusive: the identity check returned server status ${response.status}. Tool calls remain available.${trace}`;
+  }
+  if (response.state === 'network_unreachable') {
+    const kind = response.networkError === 'timeout' ? 'timed out' : 'hit a network error';
+    return `scrapeloop-mcp: API key preflight inconclusive: the identity check ${kind}. This does not prove the API is unreachable. Tool calls remain available.${trace}`;
+  }
+  return `scrapeloop-mcp: API key preflight inconclusive (status ${response.status}). Tool calls remain available.${trace}`;
+}
+
+function warnStartupOnce(key, message, logger = console.error) {
+  if (STARTUP_WARNINGS.has(key)) return false;
+  STARTUP_WARNINGS.add(key);
+  logger(message);
+  return true;
 }
 
 const result = (payload) => ({
@@ -116,6 +328,16 @@ const B = { type: 'boolean' };
 const O = { type: 'object' };
 const ARR = (items) => ({ type: 'array', items });
 
+// card run-scope-menu: build the run/estimate body from the scope args
+// (view/selection + cell_filter + n_rows/start_row window).
+const runScopeBody = (a) => ({
+  ...(a.view_id ? { view_id: a.view_id } : {}),
+  ...(a.selection ? { selection: a.selection } : {}),
+  ...(a.cell_filter ? { cell_filter: a.cell_filter } : {}),
+  ...(a.n_rows ? { row_window: { n: a.n_rows, start: a.start_row || 1 } } : {}),
+  ...(a.only_failed !== undefined ? { only_failed: !!a.only_failed } : {}),
+});
+
 // --- Tool registry: name → { def, run } -------------------------------------
 const TOOLS = {
   // ── Discovery / status ────────────────────────────────────────────────
@@ -145,7 +367,7 @@ const TOOLS = {
   get_meta: {
     def: {
       description:
-        'List the canonical values for a lead-database filter (seniorities, functions, email_quality_labels, employee_ranges) so search inputs are valid. Use "_all" for everything.',
+        'List the canonical values for a lead-database filter (seniorities, functions, email_quality_labels, industries) so search inputs are valid. Use "_all" for everything.',
       inputSchema: obj({ filter: { ...S, description: 'filter name or "_all"' } }, ['filter']),
     },
     run: (a) => api('GET', `/meta/${enc(a.filter)}`),
@@ -220,7 +442,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. Ask the user the schema\'s fields (query, state, locations, limit, …), then fill `config` for estimate_scrape / submit_scrape.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/scrapers'),
@@ -248,14 +470,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. Surfaces 402 (budget/free-tier/credits) and 409 (rescrape confirmation needed) verbatim; 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'],
@@ -266,8 +490,10 @@ 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 } : {}),
       }),
   },
@@ -280,7 +506,7 @@ const TOOLS = {
     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`),
   },
 
@@ -288,15 +514,23 @@ const TOOLS = {
   search_leads: {
     def: {
       description:
-        'Search the Scrapeloop B2B lead database. Emails are masked until revealed. Pass a filters object (titles, seniorities, functions, industries, countries, states, cities, company_keywords_include, employee_ranges, decision_maker, …). Free — costs no credits.',
+        'Search the Scrapeloop B2B lead database (people-level). Emails are masked until revealed. Pass a filters object (job_titles_include, job_titles_mode: "contains" (default) | "exact" | "similar", seniorities, functions, countries, states, cities, company_keywords_include, company_names, domains_include, industries, decision_maker, email_quality_labels, ...). Industries are coarse inferred sector buckets from the company name, not verified firmographics. Company size and revenue filters (employee_ranges, revenue_ranges, and related fields) are deprecated no-ops; fold size hints into company_keywords_include. Get valid slugs from get_meta("industries"). Free, costs no credits.',
       inputSchema: obj({ filters: O, limit: { ...N, description: '1-100 (default 25)' }, offset: N }),
     },
     run: (a) => api('POST', '/leads/search', { filters: a.filters || {}, limit: a.limit || 25, offset: a.offset || 0 }),
   },
   estimate_leads: {
-    def: { description: 'Count how many leads match a filters object (free).', inputSchema: obj({ filters: O }) },
+    def: { description: 'Count how many leads match a filters object (free). Supports job_titles_mode: "contains" (default) | "exact" | "similar".', inputSchema: obj({ filters: O }) },
     run: (a) => api('POST', '/leads/estimate', { filters: a.filters || {} }),
   },
+  expand_job_titles: {
+    def: {
+      description:
+        'Preview what "is similar to" title matching will expand to (curated synonym map). Free.',
+      inputSchema: obj({ titles: ARR(S) }, ['titles']),
+    },
+    run: (a) => api('POST', '/leads/title-expansion', { titles: a.titles }),
+  },
   reveal_lead: {
     def: {
       description: "Reveal a lead's email by global_person_id. SPENDS 1 lead credit (idempotent — already-revealed leads are free).",
@@ -311,6 +545,74 @@ const TOOLS = {
     },
     run: (a) => api('POST', '/leads/save', { global_person_ids: a.global_person_ids }),
   },
+  estimate_lead_import: {
+    def: {
+      description:
+        'Preview a Lead Database to table import: how many match, how many are new reveals, and the lead-credit cost. Free.',
+      inputSchema: obj(
+        {
+          filters: O,
+          total_limit: N,
+          per_company_limit: N,
+        },
+        ['filters'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/import-estimate', {
+        filters: a.filters || {},
+        ...(a.total_limit ? { total_limit: a.total_limit } : {}),
+        ...(a.per_company_limit ? { per_company_limit: a.per_company_limit } : {}),
+      }),
+  },
+  import_leads_to_table: {
+    def: {
+      description:
+        'Import Lead Database people into a table by filters. SPENDS lead credits for newly revealed people. Exactly one of list_id or new_list_name is required.',
+      inputSchema: obj(
+        {
+          filters: O,
+          total_limit: N,
+          per_company_limit: N,
+          list_id: S,
+          new_list_name: S,
+        },
+        ['filters'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/import-to-table', {
+        filters: a.filters || {},
+        ...(a.total_limit ? { total_limit: a.total_limit } : {}),
+        ...(a.per_company_limit ? { per_company_limit: a.per_company_limit } : {}),
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.new_list_name ? { new_list_name: a.new_list_name } : {}),
+      }),
+  },
+  list_saved_searches: {
+    def: {
+      description:
+        'List saved + recent Lead Database searches (name, filters object, result count, last used). Reuse a search by passing its filters to search_leads / estimate_leads (free).',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/leads/saved-searches'),
+  },
+  save_search: {
+    def: {
+      description:
+        'Save a Lead Database filters object as a named search for the workspace (free). Upserts by name.',
+      inputSchema: obj(
+        { name: S, filters: O, result_count_at_save: N },
+        ['name', 'filters'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/saved-searches', {
+        name: a.name,
+        filters: a.filters || {},
+        result_count_at_save: a.result_count_at_save,
+      }),
+  },
   bulk_verify_leads: {
     def: {
       description: 'Enqueue a background verification pass over saved/DB leads (by lead_ids or global_person_ids).',
@@ -324,6 +626,50 @@ const TOOLS = {
       }),
   },
 
+  // ── Local Leads: browse first, spend only on reveal or coverage fill ──
+  search_local_leads: {
+    def: {
+      description:
+        'Search existing local-business coverage for free. Results keep email and owner fields masked until reveal. Filter keys include search_query, gcids, niche_text, countries, states, cities, postal_codes, rating_min/max, reviews_min/max, has_website, has_phone, has_email, email_status, has_owner_name, platforms, tech_tools, domain_age_max_years, page_count_min/max, site_signals, has_gbp_description, and sort.',
+      inputSchema: obj(
+        { filters: O, limit: { ...N, description: '1-100 (default 25)' }, offset: N },
+      ),
+    },
+    run: (a) => api('POST', '/local-leads/search', {
+      filters: a.filters || {},
+      limit: a.limit || 25,
+      offset: a.offset || 0,
+    }),
+  },
+  estimate_local_leads: {
+    def: {
+      description: 'Count matching local businesses in existing coverage for free. Uses the same filters as search_local_leads.',
+      inputSchema: obj({ filters: O }),
+    },
+    run: (a) => api('POST', '/local-leads/estimate', { filters: a.filters || {} }),
+  },
+  reveal_local_lead: {
+    def: {
+      description: 'Reveal one local business by place_id. SPENDS 1 lead credit and is idempotent, so an already revealed record is free.',
+      inputSchema: obj({ place_id: S }, ['place_id']),
+    },
+    run: (a) => api('POST', '/local-leads/reveal', { place_id: a.place_id }),
+  },
+  fill_coverage_gap: {
+    def: {
+      description: 'Request a live local scrape when existing coverage is thin or stale. MAY SPEND vendor dollars or lead credits. Search and estimate first, show the expected cost, and confirm with the user before calling.',
+      inputSchema: obj({ filters: O }, ['filters']),
+    },
+    run: (a) => api('POST', '/local-leads/fill-gap', { filters: a.filters || {} }),
+  },
+  list_local_categories: {
+    def: {
+      description: 'Resolve a local-business category or synonym to ranked Google category IDs. Use this before search_local_leads when the user gives a plain-language niche.',
+      inputSchema: obj({ q: S, country: S }, ['q']),
+    },
+    run: (a) => api('GET', `/geo/categories${qs({ q: a.q, country: a.country })}`),
+  },
+
   // ── Step 4: verification ──────────────────────────────────────────────
   verify_email: {
     def: { description: 'Verify an email address (1 verify credit).', inputSchema: obj({ email: S }, ['email']) },
@@ -332,7 +678,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). High ROI: deliverable catch-all/unknown contacts get fewer cold emails because most senders skip them, so they reply more.',
       inputSchema: obj({ email: S }, ['email']),
     },
     run: (a) => api('POST', '/verify/catchall', { email: a.email }),
@@ -422,6 +768,33 @@ const TOOLS = {
         ...(a.cache_settings ? { cache_settings: a.cache_settings } : {}),
       }),
   },
+  get_ai_context: {
+    def: {
+      description: 'Get the workspace AI context (company description, ICP, buyer personas) that seeds every AI feature.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/ai-context'),
+  },
+  update_ai_context: {
+    def: {
+      description: 'Update the workspace AI context. The personas field replaces the whole array.',
+      inputSchema: obj({ company_description: S, icp: S, personas: ARR(S), source_domain: S }),
+    },
+    run: (a) =>
+      api('PUT', '/ai-context', {
+        ...(a.company_description !== undefined ? { company_description: a.company_description } : {}),
+        ...(a.icp !== undefined ? { icp: a.icp } : {}),
+        ...(a.personas !== undefined ? { personas: a.personas } : {}),
+        ...(a.source_domain !== undefined ? { source_domain: a.source_domain } : {}),
+      }),
+  },
+  generate_ai_context: {
+    def: {
+      description: 'Draft the AI context from a website domain (fetch + AI summarize). Returns a draft, call update_ai_context to save it. Free, no credits.',
+      inputSchema: obj({ domain: S }, ['domain']),
+    },
+    run: (a) => api('POST', '/ai-context/generate', { domain: a.domain }),
+  },
   list_strategies: {
     def: { description: 'List the workspace strategy tags (routing tags campaigns filter on).', inputSchema: obj({}) },
     run: () => api('GET', '/strategies'),
@@ -494,6 +867,30 @@ const TOOLS = {
     def: { description: 'List campaigns with per-campaign stats and the bound list name.', inputSchema: obj({}) },
     run: () => api('GET', '/campaigns'),
   },
+  preview_add_leads_to_campaign: {
+    def: {
+      description:
+        'FREE preview for pushing a table view or selection into an existing campaign. ALWAYS show the valid, risky, invalid, suppressed, and already-added breakdown before add_leads_to_campaign. scope accepts view_id plus selection {mode: query, q, filter, exclude_ids} or {mode: explicit, ids}.',
+      inputSchema: obj({ campaign_id: S, list_id: S, scope: O }, ['campaign_id', 'list_id']),
+    },
+    run: (a) =>
+      api('POST', `/campaigns/${enc(a.campaign_id)}/add-leads/preview`, {
+        list_id: a.list_id,
+        ...(a.scope ? { scope: a.scope } : {}),
+      }),
+  },
+  add_leads_to_campaign: {
+    def: {
+      description:
+        'Push scoped table rows into a live sender campaign, where they may start receiving email. Run preview_add_leads_to_campaign and confirm with the user first. Invalid emails are never added, and risky emails are added only when the campaign allows them.',
+      inputSchema: obj({ campaign_id: S, list_id: S, scope: O }, ['campaign_id', 'list_id']),
+    },
+    run: (a) =>
+      api('POST', `/campaigns/${enc(a.campaign_id)}/add-leads`, {
+        list_id: a.list_id,
+        ...(a.scope ? { scope: a.scope } : {}),
+      }),
+  },
   create_campaign: {
     def: {
       description:
@@ -576,131 +973,1419 @@ const TOOLS = {
       }),
   },
 
-  // ── Lists ─────────────────────────────────────────────────────────────
+  // ── Legacy Lead Database saved lists ─────────────────────────────────
   get_lists: {
-    def: { description: 'List the saved lead lists in the workspace.', inputSchema: obj({}) },
+    def: {
+      description:
+        'List saved B2B Lead Database collections. These are NOT campaign-bindable Tables; use get_tables when you need a source_list_id, enrichment columns, or table cells.',
+      inputSchema: obj({}),
+    },
     run: () => api('GET', '/lists'),
   },
   create_list: {
-    def: { description: 'Create a saved lead list.', inputSchema: obj({ name: S, description: S, color: S }, ['name']) },
+    def: {
+      description:
+        'Create a saved B2B Lead Database collection for add_list_members. This is NOT a campaign-bindable Table; use create_table for imports, enrichment columns, or campaigns.',
+      inputSchema: obj({ name: S, description: S, color: S }, ['name']),
+    },
     run: (a) => api('POST', '/lists', { name: a.name, description: a.description, color: a.color }),
   },
   add_list_members: {
     def: { description: 'Add lead-database people to a list by global_person_id (acquires them, dedup-aware).', inputSchema: obj({ list_id: S, global_person_ids: ARR(S) }, ['list_id', 'global_person_ids']) },
     run: (a) => api('POST', `/lists/${enc(a.list_id)}/members`, { global_person_ids: a.global_person_ids }),
   },
-  import_leads: {
+
+  // ── Workbench organization ───────────────────────────────────────────
+  list_workbooks: {
     def: {
       description:
-        'Bring your own leads: import externally-sourced lead records into a campaign-bindable Scrapeloop list. For leads you already have (a CSV/export with emails — optionally pre-verified, with a generated first line) — no scraping, no lead credits, and NO re-verification (your verification_status is preserved). Idempotent: dedupe within the workspace by email (default) or external_id — re-running the same batch UPDATES existing leads (merges custom_fields, unions strategy tags), never duplicates. custom_fields flow through to Instantly as custom variables (usable as {{first_line}} etc.). Target an existing list_id OR a list_name (create-or-get). Batch up to 1000 records. Each record: {email (required), first_name, last_name, business_name, phone, website, address, city, state_region, country, niche, rating, reviews_count, verification_status ("verified"|"catchall_verified"|"unverified"|"risky"|"invalid"), strategy_tags:[], custom_fields:{}, external_id}. Returns {list_id, inserted, updated, deduped, invalid, invalid_reasons}. Then bind list_id with create_campaign(source_list_id=...).',
-      inputSchema: obj(
-        {
-          list_id: S,
-          list_name: S,
-          records: ARR(O),
-          dedupe_by: { ...S, description: '"email" (default) or "external_id"' },
-          default_verification_status: S,
-        },
-        ['records'],
-      ),
+        'Read the complete Workbench tree: folders, workbooks in each folder, workbook table order, standalone Tables, and All leads. Use this before organizing or cloning a client workspace.',
+      inputSchema: obj({}),
     },
-    run: (a) =>
-      api('POST', '/leads/import', {
+    run: () => api('GET', '/workbench/tree'),
+  },
+  create_workbook: {
+    def: {
+      description:
+        'Create a workbook to group related Tables as ordered tabs. Pass existing list_ids in the order they should appear, or add tabs later with add_table_to_workbook.',
+      inputSchema: obj({ name: S, list_ids: ARR(S) }, ['name']),
+    },
+    run: (a) => api('POST', '/workbooks', { name: a.name, list_ids: a.list_ids || [] }),
+  },
+  add_table_to_workbook: {
+    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']),
+    },
+    run: (a) => {
+      if (!!a.list_id === !!a.new_table_name) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Pass exactly one of list_id or new_table_name.' },
+        };
+      }
+      return api('POST', `/workbooks/${enc(a.workbook_id)}/tables`, {
         ...(a.list_id ? { list_id: a.list_id } : {}),
-        ...(a.list_name ? { list_name: a.list_name } : {}),
-        records: a.records || [],
-        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
-        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
-      }),
+        ...(a.new_table_name ? { new_table_name: a.new_table_name } : {}),
+      });
+    },
   },
-  import_leads_csv: {
+  remove_table_from_workbook: {
     def: {
       description:
-        "Bring your own leads from a CSV/TSV: paste the raw file text and it's parsed server-side — the delimiter is auto-detected, headers are fuzzy-mapped to fields (email, first_name, business_name, phone, website, city, country, rating, reviews_count, verification_status, external_id, strategy tags…), any UNMAPPED columns become custom_fields (so a 'first_line' or 'review_snippet' column flows to Instantly automatically), and verifier verdicts (valid/catch-all/invalid…) are normalized. No scraping, no lead credits, no re-verification. Set dry_run:true to PREVIEW (shows would_insert/would_update + how each column mapped, writes nothing) — do that first, show the user the column_mapping, then run again with dry_run:false. Target list_id or list_name (create-or-get). ≤1000 rows/call. Returns the import result plus column_mapping + unmapped_columns + rows_parsed.",
+        'Remove a Table tab from its workbook without deleting the Table or any rows. The Table becomes standalone in the Workbench root.',
+      inputSchema: obj({ workbook_id: S, list_id: S }, ['workbook_id', 'list_id']),
+    },
+    run: (a) => api('DELETE', `/workbooks/${enc(a.workbook_id)}/tables/${enc(a.list_id)}`),
+  },
+  reorder_workbook_table: {
+    def: {
+      description:
+        'Change one workbook tab position. Read list_workbooks first, then choose a numeric position between neighboring tabs.',
+      inputSchema: obj({ workbook_id: S, list_id: S, position: N }, ['workbook_id', 'list_id', 'position']),
+    },
+    run: (a) => api('PATCH', `/workbooks/${enc(a.workbook_id)}/tables/${enc(a.list_id)}`, { position: a.position }),
+  },
+  duplicate_workbook: {
+    def: {
+      description:
+        'Clone a template pipeline for a new client. Copies table structure, settings, and views without rows or cell history. Internal routing rules are rewired to the copied Tables; external, campaign, and webhook rules are disabled with review warnings.',
       inputSchema: obj(
         {
-          csv: S,
-          list_id: S,
-          list_name: S,
-          dedupe_by: { ...S, description: '"email" (default) or "external_id"' },
-          default_verification_status: S,
-          column_map: { ...O, description: 'optional explicit header→field overrides, e.g. {"Owner":"first_name"}' },
-          dry_run: B,
+          workbook_id: S,
+          name: S,
+          folder_id: S,
+          include_rules: B,
         },
-        ['csv'],
+        ['workbook_id', 'name'],
       ),
     },
-    run: (a) =>
-      api('POST', '/leads/import/csv', {
-        csv: a.csv,
-        ...(a.list_id ? { list_id: a.list_id } : {}),
-        ...(a.list_name ? { list_name: a.list_name } : {}),
-        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
-        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
-        ...(a.column_map ? { column_map: a.column_map } : {}),
-        ...(a.dry_run ? { dry_run: true } : {}),
-      }),
+    run: (a) => api('POST', `/workbooks/${enc(a.workbook_id)}/duplicate`, {
+      name: a.name,
+      ...(a.folder_id !== undefined ? { folder_id: a.folder_id } : {}),
+      ...(a.include_rules !== undefined ? { include_rules: a.include_rules } : {}),
+    }),
   },
-  preview_import: {
+  create_folder: {
     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.',
+        'Create a Workbench folder for client, team, or pipeline organization. Then use move_to_folder for workbooks or standalone Tables.',
+      inputSchema: obj({ name: S }, ['name']),
+    },
+    run: (a) => api('POST', '/folders', { name: a.name }),
+  },
+  move_to_folder: {
+    def: {
+      description:
+        'Move exactly one workbook or standalone Table into a folder. Pass folder_id null to move it back to the Workbench root. Tables inside a workbook move with the workbook, not individually.',
       inputSchema: obj(
         {
+          folder_id: { anyOf: [S, { type: 'null' }] },
+          workbook_id: S,
           list_id: S,
-          list_name: S,
-          records: ARR(O),
-          dedupe_by: { ...S, description: '"email" (default) or "external_id"' },
-          default_verification_status: S,
         },
-        ['records'],
+        ['folder_id'],
       ),
     },
-    run: (a) =>
-      api('POST', '/leads/import/preview', {
-        ...(a.list_id ? { list_id: a.list_id } : {}),
-        ...(a.list_name ? { list_name: a.list_name } : {}),
-        records: a.records || [],
-        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
-        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
-      }),
+    run: (a) => {
+      if (!!a.workbook_id === !!a.list_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Pass exactly one of workbook_id or list_id.' },
+        };
+      }
+      return a.workbook_id
+        ? api('PATCH', `/workbooks/${enc(a.workbook_id)}`, { folder_id: a.folder_id })
+        : api('PATCH', `/lists-placement/${enc(a.list_id)}`, { folder_id: a.folder_id });
+    },
   },
-  get_list_rows: {
+  delete_folder: {
     def: {
       description:
-        "Read a list's leads with their fields (email, name, status, verification_status, custom_fields, strategy tags, position). The read-back for a list built by import_leads (custom_fields + verification_status live on the lead's attributes). Paginated (limit ≤ 500, offset).",
-      inputSchema: obj({ list_id: S, limit: N, offset: N }, ['list_id']),
+        'Delete an empty or organizational Workbench folder. Its workbooks and standalone Tables move to the root; their data is not deleted.',
+      inputSchema: obj({ folder_id: S }, ['folder_id']),
     },
-    run: (a) =>
-      a.list_id
-        ? api('GET', `/lists/${enc(a.list_id)}/leads${qs({ limit: a.limit, offset: a.offset })}`)
-        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+    run: (a) => api('DELETE', `/folders/${enc(a.folder_id)}`),
   },
-  delete_list: {
+
+  // ── Campaign-bindable Tables ─────────────────────────────────────────
+  get_tables: {
     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.',
-      inputSchema: obj({ list_id: S }, ['list_id']),
+        'List campaign-bindable Scrapeloop Tables in this workspace. Returns Clay-style Tables used by imports, enrichment columns, table cells, and create_campaign(source_list_id). Distinct from legacy get_lists.',
+      inputSchema: obj({ archived: B }),
     },
-    run: (a) =>
-      a.list_id
-        ? api('DELETE', `/lists/${enc(a.list_id)}`)
-        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+    run: (a) => api('GET', `/tables${qs({ archived: a.archived })}`),
   },
-  delete_campaign: {
+  create_table: {
     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.',
-      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+        '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.',
+      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'] },
+          filter_expression: { ...O, description: 'Smart Tables only.' },
+          sort_expression: { ...O, description: 'Smart Tables only.' },
+          visible_columns: { ...ARR(S), description: 'Smart Tables only.' },
+          is_shared: { ...B, description: 'Smart Tables only.' },
+        },
+        ['name'],
+      ),
+    },
+    run: async (a) => {
+      if (!a.name) return { ok: false, status: 400, error: { detail: 'name is required.' } };
+      const kind = a.kind || 'static';
+      const smartOnly = ['filter_expression', 'sort_expression', 'visible_columns', 'is_shared'];
+      const suppliedSmartOnly = smartOnly.filter((key) => a[key] !== undefined);
+      if (kind === 'static' && suppliedSmartOnly.length) {
+        return {
+          ok: false,
+          status: 400,
+          error: {
+            detail: `static Tables do not accept smart-only fields: ${suppliedSmartOnly.join(', ')}`,
+          },
+        };
+      }
+      const requestBody = {
+        name: a.name,
+        operation_id: a.operation_id || randomUUID(),
+        ...(a.description !== undefined ? { description: a.description } : {}),
+        ...(a.kind !== undefined ? { kind: a.kind } : {}),
+        ...(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 } : {}),
+        ...(a.is_shared !== undefined ? { is_shared: a.is_shared } : {}),
+      };
+      return api('POST', '/tables', requestBody, {
+        reconciliation: {
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'create_table',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
     },
-    run: (a) =>
-      a.campaign_id
-        ? api('DELETE', `/campaigns/${enc(a.campaign_id)}`)
-        : { ok: false, status: 400, error: { detail: 'campaign_id is required.' } },
   },
-
-  // ── Replies + suppression ─────────────────────────────────────────────
-  list_replies: {
+  get_table_columns: {
+    def: {
+      description:
+        'List a campaign-bindable Table\'s dynamic columns in display order. Use each returned id with set_table_cells and each key with list_table_rows filters/sorts.',
+      inputSchema: obj({ table_id: S }, ['table_id']),
+    },
+    run: (a) =>
+      a.table_id
+        ? api('GET', `/tables/${enc(a.table_id)}/columns`)
+        : { ok: false, status: 400, error: { detail: 'table_id is required.' } },
+  },
+  create_table_column: {
+    def: {
+      description:
+        'Create a FREE manual data column on an active campaign-bindable Table. Archived Tables must be unarchived first. Select and multi_select require 1-100 render-safe options shaped as {label,value,color?}; values are lowercase tokens and colors are gray, blue, teal, amber, or red. This tool cannot create enrichment/formula columns, auto-run work, or spend credits. 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.',
+      inputSchema: obj(
+        {
+          table_id: S,
+          label: S,
+          operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
+          type: {
+            ...S,
+            enum: ['text', 'number', 'currency', 'select', 'multi_select', 'url', 'email', 'date', 'checkbox'],
+          },
+          width: { ...N, minimum: 60, maximum: 1200 },
+          position_after: {
+            anyOf: [S, { type: 'null' }],
+            description: 'Omit to append, pass null for leftmost, or pass a column id.',
+          },
+          options: {
+            type: 'array',
+            minItems: 1,
+            maxItems: 100,
+            items: obj(
+              {
+                label: { ...S, minLength: 1, maxLength: 80 },
+                value: {
+                  ...S,
+                  minLength: 1,
+                  maxLength: 64,
+                  pattern: '^[a-z0-9][a-z0-9_-]*$',
+                },
+                color: { ...S, enum: ['gray', 'blue', 'teal', 'amber', 'red'] },
+              },
+              ['label', 'value'],
+            ),
+          },
+        },
+        ['table_id', 'label'],
+      ),
+    },
+    run: async (a) => {
+      if (!a.table_id || !a.label) {
+        return { ok: false, status: 400, error: { detail: 'table_id and label are required.' } };
+      }
+      const type = a.type || 'text';
+      const isSelect = type === 'select' || type === 'multi_select';
+      if (isSelect && (!Array.isArray(a.options) || !a.options.length)) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'select and multi_select columns require options.' },
+        };
+      }
+      if (!isSelect && a.options !== undefined) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'options are allowed only for select and multi_select columns.' },
+        };
+      }
+      const requestBody = {
+        label: a.label,
+        operation_id: a.operation_id || randomUUID(),
+        ...(a.type !== undefined ? { type: a.type } : {}),
+        ...(a.width !== undefined ? { width: a.width } : {}),
+        ...(a.position_after !== undefined ? { position_after: a.position_after } : {}),
+        ...(a.options !== undefined ? { options: a.options } : {}),
+      };
+      const columnsPath = `/tables/${enc(a.table_id)}/columns`;
+      return api('POST', columnsPath, requestBody, {
+        reconciliation: {
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'create_table_column',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table_column with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
+    },
+  },
+  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.`,
+        },
+      });
+    },
+  },
+  set_table_cells: {
+    def: {
+      description:
+        'Write up to 500 FREE manual values into an active static Table in one atomic upsert (maximum 256 KiB JSON). Archived Tables must be unarchived first. Every cell must include value; explicit null clears it. Formats: text is at most 10,000 characters, number/currency is a finite number, checkbox is boolean, date is YYYY-MM-DD, email is valid and at most 320 characters, URL is absolute HTTP(S) and at most 2,048 characters, select is one configured token, and multi_select is a unique token array of at most 100 values. The whole request is validated before writing. Returns updated and skipped counts, and triggers configured row_updated rules once per changed lead. The write itself does not run enrichment or charge Scrapeloop credits.',
+      inputSchema: obj(
+        {
+          table_id: S,
+          cells: {
+            type: 'array',
+            minItems: 1,
+            maxItems: MAX_TABLE_CELL_WRITES,
+            items: obj(
+              {
+                lead_id: S,
+                column_id: S,
+                value: { description: 'Required. Pass null explicitly to clear the cell.' },
+              },
+              ['lead_id', 'column_id', 'value'],
+            ),
+          },
+        },
+        ['table_id', 'cells'],
+      ),
+    },
+    run: (a) => {
+      if (!a.table_id || !Array.isArray(a.cells) || !a.cells.length) {
+        return { ok: false, status: 400, error: { detail: 'table_id and non-empty cells are required.' } };
+      }
+      if (a.cells.length > MAX_TABLE_CELL_WRITES) {
+        return { ok: false, status: 400, error: { detail: 'cells accepts at most 500 items.' } };
+      }
+      if (a.cells.some((cell) => !Object.prototype.hasOwnProperty.call(cell, 'value'))) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'every cell must include value; pass null explicitly to clear.' },
+        };
+      }
+      const requestBytes = new TextEncoder().encode(
+        JSON.stringify({ cells: a.cells }),
+      ).length;
+      if (requestBytes > MAX_TABLE_CELL_REQUEST_BYTES) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'cells request exceeds 256 KiB; split it into smaller batches.' },
+        };
+      }
+      return api('POST', `/tables/${enc(a.table_id)}/cells`, { cells: a.cells });
+    },
+  },
+  import_leads: {
+    def: {
+      description:
+        'Bring your own leads: atomically import externally-sourced records into a campaign-bindable Scrapeloop Table without scraping or lead credits. A generic record needs at least one stable identity: email, linkedin_url, external_id, or an absolute source_url. Email may be null. Canonical sourcing rows may opt into sourcing_contract and must include controlled source, source_state, niche, and a valid phone or email; phone-only local businesses receive a stable source-scoped fallback identity. Source and niche tags are generated automatically. Matching is workspace-scoped and deterministic: normalized email first, then local-business phone, canonical LinkedIn, and external/source identity. The legacy dedupe_by="external_id" mode keeps external identity authoritative. A later record with a real email merges into the earlier LinkedIn/source-only lead instead of duplicating it. No placeholder emails are created. verification_status and custom_fields are preserved, and custom_fields flow to Instantly as custom variables. Target list_id or pass list_name to create-or-get a Table. Batch up to 1000 records. One operation_id is reused across HTTP retries, so an uncertain response can be recovered without duplicating leads. You may pass a prior operation_id; reusing it with different inputs returns 409. Each record: {source?, source_state?, email?, linkedin_url?, source_url?, external_id?, first_name, last_name, business_name, phone, website, address, city, state_region, country, niche, rating, reviews_count, gbp_link?, facebook?, instagram?, verification_status ("verified"|"catchall_verified"|"unverified"|"risky"|"invalid"), strategy_tags:[], custom_fields:{}}. Returns {operation_id, list_id, inserted, updated, deduped, invalid, invalid_reasons}.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          list_name: S,
+          operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
+          records: ARR(O),
+          dedupe_by: { ...S, description: '"email" (default, with LinkedIn/source fallbacks) or legacy "external_id" priority' },
+          lead_type: { ...S, enum: ['local_business', 'b2b_person'] },
+          sourcing_contract: B,
+          default_verification_status: S,
+        },
+        ['records'],
+      ),
+    },
+    run: (a) => {
+      const records = a.records || [];
+      const requestBody = {
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        operation_id: a.operation_id || randomUUID(),
+        records,
+        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
+        ...(a.lead_type ? { lead_type: a.lead_type } : {}),
+        ...(a.sourcing_contract ? { sourcing_contract: true } : {}),
+        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
+      };
+      return api('POST', '/leads/import', requestBody, {
+        reconciliation: {
+          inspect_with: a.list_id
+            ? { tool: 'get_list_rows', arguments: { list_id: a.list_id, limit: 500, offset: 0 } }
+            : { tool: 'get_tables', arguments: { archived: false } },
+          expected: {
+            record_count: records.length,
+            ...(a.list_id ? { list_id: a.list_id } : {}),
+            ...(a.list_name ? { list_name: a.list_name } : {}),
+          },
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'import_leads',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry import_leads with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical import.`,
+          guidance:
+            'The original tool arguments remain the reconciliation source of truth; do not infer success from row count alone.',
+        },
+      });
+    },
+  },
+  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:
+        'Manually record one reviewed, high-intent public community signal or admin-approved opt-in. This is not a social scraper. Private content, group member lists, membership-only evidence, reactions, follows, automated messages, cookies, and platform-control bypasses are prohibited. Required evidence is minimized to policy basis, visibility, consent mode, source and public-profile URLs, observed timestamp, evidence class, company, and reviewer note. Pending signals default to outreach_ready=false and legal_review_required=true. A business email is accepted only after approval and only when it was published for business contact or explicitly opted in. Set dry_run=true first. The mutation is idempotent through operation_id and writes reviewer lineage before any Table import.',
+      inputSchema: obj(
+        {
+          policy_basis: {
+            ...S,
+            enum: ['public_product_signal', 'admin_partnership', 'approved_form', 'webinar', 'poll', 'lead_magnet'],
+          },
+          visibility: { ...S, enum: ['public', 'admin_approved_opt_in', 'private', 'member_list'] },
+          consent_mode: { ...S, enum: ['none', 'public_business_contact', 'explicit_opt_in'] },
+          source_url: { ...S, format: 'uri' },
+          public_profile_url: { ...S, format: 'uri' },
+          observed_at: { ...S, format: 'date-time' },
+          evidence_class: {
+            ...S,
+            enum: ['product_named', 'product_problem', 'admin_approved_opt_in', 'membership_only'],
+          },
+          company: S,
+          reviewer_note: {
+            ...S,
+            description: 'Short reviewer rationale only. Do not paste the post or comment body.',
+          },
+          reviewer_decision: { ...S, enum: ['pending', 'approved', 'rejected'] },
+          first_name: S,
+          last_name: S,
+          business_email: { ...S, format: 'email' },
+          email_published_for_business: B,
+          list_id: S,
+          list_name: S,
+          operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
+          dry_run: B,
+        },
+        [
+          'policy_basis',
+          'visibility',
+          'consent_mode',
+          'source_url',
+          'public_profile_url',
+          'observed_at',
+          'evidence_class',
+          'company',
+          'reviewer_note',
+        ],
+      ),
+    },
+    run: (a) => {
+      const signal = {
+        policy_basis: a.policy_basis,
+        visibility: a.visibility,
+        consent_mode: a.consent_mode,
+        source_url: a.source_url,
+        public_profile_url: a.public_profile_url,
+        observed_at: a.observed_at,
+        evidence_class: a.evidence_class,
+        company: a.company,
+        reviewer_note: a.reviewer_note,
+        reviewer_decision: a.reviewer_decision || 'pending',
+        ...(a.first_name ? { first_name: a.first_name } : {}),
+        ...(a.last_name ? { last_name: a.last_name } : {}),
+        ...(a.business_email ? { business_email: a.business_email } : {}),
+        ...(a.email_published_for_business ? { email_published_for_business: true } : {}),
+      };
+      const requestBody = {
+        signal,
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        ...(!a.dry_run ? { operation_id: a.operation_id || randomUUID() } : {}),
+      };
+      if (a.dry_run) {
+        return api('POST', '/leads/community-intent/preview', requestBody);
+      }
+      return api('POST', '/leads/community-intent', requestBody, {
+        reconciliation: {
+          inspect_with: a.list_id
+            ? { tool: 'get_list_rows', arguments: { list_id: a.list_id, limit: 100, offset: 0 } }
+            : { tool: 'get_tables', arguments: { archived: false } },
+          expected: {
+            company: a.company,
+            public_profile_url: a.public_profile_url,
+            reviewer_decision: signal.reviewer_decision,
+          },
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'capture_community_intent',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry capture_community_intent with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical review.`,
+          guidance:
+            'The reviewer decision and operation_id are the receipt source of truth. Never infer approval from a Table row alone.',
+        },
+      });
+    },
+  },
+  import_leads_csv: {
+    def: {
+      description:
+        "Bring your own leads from CSV/TSV into a campaign-bindable Table. Rows may identify a lead by email, LinkedIn URL, external ID, or absolute source URL, so raw identities do not need placeholder emails. The parser auto-detects the delimiter, maps common headers (including linkedin_url and source_url), preserves unmapped columns as custom_fields, and normalizes verifier verdicts. A CSV containing source, source_state, and niche automatically enables the sourcing contract: every loaded row must also have a valid phone or email, source IDs are namespaced, phone-only local businesses get a stable fallback identity, and source/niche tags are generated. Matching is workspace-scoped: email first, then local-business phone, LinkedIn, and external/source identity. Set dry_run:true first to preview writes and column mapping. Mutating CSV imports are atomic and reuse one operation_id across HTTP retries. You may pass a prior operation_id; reusing it with changed CSV inputs returns 409. No scraping, lead credits, or re-verification. Target list_id or pass list_name. Up to 1000 rows per call.",
+      inputSchema: obj(
+        {
+          csv: S,
+          list_id: S,
+          list_name: S,
+          operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
+          dedupe_by: { ...S, description: '"email" (default, with LinkedIn/source fallbacks) or legacy "external_id" priority' },
+          lead_type: { ...S, enum: ['local_business', 'b2b_person'] },
+          sourcing_contract: B,
+          default_verification_status: S,
+          column_map: { ...O, description: 'optional explicit header→field overrides, e.g. {"Owner":"first_name"}' },
+          dry_run: B,
+        },
+        ['csv'],
+      ),
+    },
+    run: (a) => {
+      const requestBody = {
+        csv: a.csv,
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        ...(!a.dry_run ? { operation_id: a.operation_id || randomUUID() } : {}),
+        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
+        ...(a.lead_type ? { lead_type: a.lead_type } : {}),
+        ...(a.sourcing_contract ? { sourcing_contract: true } : {}),
+        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
+        ...(a.column_map ? { column_map: a.column_map } : {}),
+        ...(a.dry_run ? { dry_run: true } : {}),
+      };
+      if (a.dry_run) return api('POST', '/leads/import/csv', requestBody);
+      return api('POST', '/leads/import/csv', requestBody, {
+        reconciliation: {
+          inspect_with: a.list_id
+            ? { tool: 'get_list_rows', arguments: { list_id: a.list_id, limit: 500, offset: 0 } }
+            : { tool: 'get_tables', arguments: { archived: false } },
+          expected: {
+            ...(a.list_id ? { list_id: a.list_id } : {}),
+            ...(a.list_name ? { list_name: a.list_name } : {}),
+          },
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'import_leads_csv',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry import_leads_csv with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical import.`,
+          guidance:
+            'Do not infer success from row count alone because the Table may already contain unrelated rows.',
+        },
+      });
+    },
+  },
+  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.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          list_name: S,
+          records: ARR(O),
+          dedupe_by: { ...S, description: '"email" (default, with LinkedIn/source fallbacks) or legacy "external_id" priority' },
+          lead_type: { ...S, enum: ['local_business', 'b2b_person'] },
+          sourcing_contract: B,
+          default_verification_status: S,
+        },
+        ['records'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/import/preview', {
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        records: a.records || [],
+        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
+        ...(a.lead_type ? { lead_type: a.lead_type } : {}),
+        ...(a.sourcing_contract ? { sourcing_contract: true } : {}),
+        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
+      }),
+  },
+  get_list_rows: {
+    def: {
+      description:
+        "Read a Table's imported leads with canonical identity fields (email, phone, LinkedIn, external_id, source_url, place_id), name/company/location, lead type, source platform, verification status, custom fields, tags, and position. Email remains null for raw identities until enrichment finds one. Paginated (limit up to 500, offset).",
+      inputSchema: obj({ list_id: S, limit: N, offset: N }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/leads${qs({ limit: a.limit, offset: a.offset })}`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  get_list_history: {
+    def: {
+      description:
+        "A table's history: log='runs' (default, who ran which enrichment column, scope, rows, cost, and outcome) or log='changes' (column and settings edits with actor). Kept 90 days. Paginated (limit at most 200).",
+      inputSchema: obj(
+        {
+          list_id: S,
+          log: { ...S, description: '"runs" (default) or "changes"' },
+          limit: N,
+          before: S,
+        },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      a.list_id
+        ? api(
+            'GET',
+            `/lists/${enc(a.list_id)}/history/${a.log === 'changes' ? 'changes' : 'runs'}${qs({ limit: a.limit, before: a.before })}`,
+          )
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  get_flow_graph: {
+    def: {
+      description:
+        'Get the real-object Flows graph for the workspace, one workbook, or one Table ego graph. Includes rule identity and activity, campaign feed/offload relationships, and saved node positions. scope is workspace, workbook:<uuid>, or list:<uuid>.',
+      inputSchema: obj({ scope: { ...S, description: 'workspace, workbook:<uuid>, or list:<uuid>' } }),
+    },
+    run: (a) => api('GET', `/workspaces/flow-graph${qs({ scope: a.scope })}`),
+  },
+  save_flow_layout: {
+    def: {
+      description:
+        'Save presentation-only node positions for a Flows scope. This never creates or changes rules or relationships. layout maps node ids to {x,y} coordinates and is limited to 500 nodes.',
+      inputSchema: obj(
+        {
+          scope_key: { ...S, description: 'workspace, workbook:<uuid>, or list:<uuid>' },
+          layout: { ...O, description: 'Map of node id to {x:number,y:number}' },
+        },
+        ['scope_key', 'layout'],
+      ),
+    },
+    run: (a) => api('PUT', '/workspaces/flow-layout', { scope_key: a.scope_key, layout: a.layout }),
+  },
+  get_flows_catalog: {
+    def: {
+      description:
+        'Get the live flow trigger, action, operator, config-schema, availability, and safety-limit catalog. Call this before creating a rule so unavailable epic capabilities are not selected.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/flows/catalog'),
+  },
+  list_table_flow_rules: {
+    def: {
+      description:
+        "List a Table's saved automation rules, including triggers, conditions, actions, enabled state, and fire counts.",
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/flow-rules`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  create_table_flow_rule: {
+    def: {
+      description:
+        'Create a Table automation rule. Conditions use FilterExpr. Actions route one matching row to another Table, a campaign, or a public webhook.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          name: S,
+          trigger: {
+            ...S,
+            enum: [
+              'row_created',
+              'row_updated',
+              'column_completed',
+              'verification_completed',
+              'schedule',
+            ],
+          },
+          trigger_column_id: S,
+          condition: O,
+          action: {
+            ...S,
+            enum: [
+              'send_to_table',
+              'send_to_campaign',
+              'send_to_webhook',
+              'set_field',
+              'run_columns',
+              'suppress',
+              'notify_email',
+              'remove_from_campaign',
+              'approval_gate',
+              'send_to_crm',
+            ],
+          },
+          action_config: O,
+          daily_fire_cap: N,
+          delay_seconds: N,
+          schedule_interval: { ...S, enum: ['hourly', 'daily', 'weekly', 'monthly'] },
+        },
+        ['list_id', 'name', 'trigger', 'condition', 'action', 'action_config'],
+      ),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('POST', `/lists/${enc(a.list_id)}/flow-rules`, {
+            name: a.name,
+            trigger: a.trigger,
+            ...(a.trigger_column_id ? { trigger_column_id: a.trigger_column_id } : {}),
+            condition: a.condition || {},
+            action: a.action,
+            action_config: a.action_config || {},
+            ...(a.daily_fire_cap != null ? { daily_fire_cap: a.daily_fire_cap } : {}),
+            ...(a.delay_seconds != null ? { delay_seconds: a.delay_seconds } : {}),
+            ...(a.schedule_interval ? { schedule_interval: a.schedule_interval } : {}),
+          })
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  toggle_table_flow_rule: {
+    def: {
+      description: 'Enable or disable one saved Table automation rule.',
+      inputSchema: obj({ list_id: S, rule_id: S, enabled: B }, ['list_id', 'rule_id', 'enabled']),
+    },
+    run: (a) =>
+      a.list_id && a.rule_id
+        ? api('PATCH', `/lists/${enc(a.list_id)}/flow-rules/${enc(a.rule_id)}`, {
+            enabled: !!a.enabled,
+          })
+        : { ok: false, status: 400, error: { detail: 'list_id and rule_id are required.' } },
+  },
+  list_campaign_flow_rules: {
+    def: {
+      description:
+        "List a campaign's saved automation rules. Campaign triggers remain unavailable until the catalog marks their event emitters live.",
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) =>
+      a.campaign_id
+        ? api('GET', `/campaigns/${enc(a.campaign_id)}/flow-rules`)
+        : { ok: false, status: 400, error: { detail: 'campaign_id is required.' } },
+  },
+  create_campaign_flow_rule: {
+    def: {
+      description:
+        'Create a campaign-scoped automation rule after get_flows_catalog reports its trigger and action available.',
+      inputSchema: obj(
+        {
+          campaign_id: S,
+          name: S,
+          trigger: {
+            ...S,
+            enum: [
+              'campaign_replied',
+              'campaign_bounced',
+              'campaign_unsubscribed',
+              'campaign_sequence_done',
+            ],
+          },
+          condition: O,
+          action: {
+            ...S,
+            enum: [
+              'send_to_table',
+              'send_to_campaign',
+              'send_to_webhook',
+              'set_field',
+              'run_columns',
+              'suppress',
+              'notify_email',
+              'remove_from_campaign',
+              'approval_gate',
+              'send_to_crm',
+            ],
+          },
+          action_config: O,
+          daily_fire_cap: N,
+          delay_seconds: N,
+        },
+        ['campaign_id', 'name', 'trigger', 'condition', 'action', 'action_config'],
+      ),
+    },
+    run: (a) =>
+      a.campaign_id
+        ? api('POST', `/campaigns/${enc(a.campaign_id)}/flow-rules`, {
+            name: a.name,
+            trigger: a.trigger,
+            condition: a.condition || {},
+            action: a.action,
+            action_config: a.action_config || {},
+            ...(a.daily_fire_cap != null ? { daily_fire_cap: a.daily_fire_cap } : {}),
+            ...(a.delay_seconds != null ? { delay_seconds: a.delay_seconds } : {}),
+          })
+        : { ok: false, status: 400, error: { detail: 'campaign_id is required.' } },
+  },
+  toggle_campaign_flow_rule: {
+    def: {
+      description: 'Enable or disable one saved campaign automation rule.',
+      inputSchema: obj(
+        { campaign_id: S, rule_id: S, enabled: B },
+        ['campaign_id', 'rule_id', 'enabled'],
+      ),
+    },
+    run: (a) =>
+      a.campaign_id && a.rule_id
+        ? api(
+            'PATCH',
+            `/campaigns/${enc(a.campaign_id)}/flow-rules/${enc(a.rule_id)}`,
+            { enabled: !!a.enabled },
+          )
+        : {
+            ok: false,
+            status: 400,
+            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:
+        'FREE preview for sending a table view or selection into another table. ALWAYS show the new-row, already-present, and cell-copy counts before send_to_table. Finished mapped values arrive as plain data; enrichment provenance stays in the source table.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          destination_list_id: S,
+          new_table_name: S,
+          scope: O,
+          include_enrichment_values: B,
+          column_mapping: ARR(O),
+        },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/send-to-list/preview`, {
+        ...(a.destination_list_id ? { destination_list_id: a.destination_list_id } : {}),
+        ...(a.new_table_name ? { new_table_name: a.new_table_name } : {}),
+        ...(a.scope ? { scope: a.scope } : {}),
+        include_enrichment_values: !!a.include_enrichment_values,
+        column_mapping: a.column_mapping || [],
+      }),
+  },
+  send_to_table: {
+    def: {
+      description:
+        'Send scoped rows into another table, optionally copying finished mapped cells as plain data. Never copies enrichment cost, status, cache, errors, or vendor provenance. Run preview_send_to_table and confirm with the user first.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          destination_list_id: S,
+          new_table_name: S,
+          scope: O,
+          include_enrichment_values: B,
+          column_mapping: ARR(O),
+        },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/send-to-list`, {
+        ...(a.destination_list_id ? { destination_list_id: a.destination_list_id } : {}),
+        ...(a.new_table_name ? { new_table_name: a.new_table_name } : {}),
+        ...(a.scope ? { scope: a.scope } : {}),
+        include_enrichment_values: !!a.include_enrichment_values,
+        column_mapping: a.column_mapping || [],
+      }),
+  },
+  preview_table_write_back: {
+    def: {
+      description:
+        "FREE dry-run of writing a column's settled values onto the leads' real field (one of: email, phone, domain, name, city, state, country, postal_code, address_line1). Returns fill-empty / conflicts / duplicates / invalid counts. ALWAYS run this and show the counts before apply_table_write_back. A verify column is refused (it already writes email_status).",
+      inputSchema: obj(
+        { list_id: S, column_id: S, field: S, lead_ids: ARR(S) },
+        ['list_id', 'column_id', 'field'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/columns/${enc(a.column_id)}/write-back/preview`, {
+        field: a.field,
+        ...(a.lead_ids ? { lead_ids: a.lead_ids } : {}),
+      }),
+  },
+  apply_table_write_back: {
+    def: {
+      description:
+        "Write a column's settled cell values onto the leads' real field. Fill-empty by default; set overwrite=true to replace a DIFFERENT existing value. FREE (writes lead fields, spends nothing). A changed email resets email_status to 'unverified' unless the cell proves that exact address was verified; a known-invalid email is never written even with overwrite. Run preview_table_write_back and confirm with the user first.",
+      inputSchema: obj(
+        { list_id: S, column_id: S, field: S, overwrite: B, lead_ids: ARR(S) },
+        ['list_id', 'column_id', 'field'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/columns/${enc(a.column_id)}/write-back`, {
+        field: a.field,
+        overwrite: !!a.overwrite,
+        ...(a.lead_ids ? { lead_ids: a.lead_ids } : {}),
+      }),
+  },
+  export_table_csv: {
+    def: {
+      description:
+        "Export a table to CSV as a background job. scope is the same view/filter/selection object used by table runs; fields are ordered lead.<field>/col.<column_key> keys and default to what the view shows. Returns job_id; poll get_table_export for a download link valid for 7 days.",
+      inputSchema: obj(
+        { list_id: S, scope: O, fields: ARR(S), filename: S },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/export`, {
+        ...(a.scope ? { scope: a.scope } : {}),
+        ...(a.fields ? { fields: a.fields } : {}),
+        ...(a.filename ? { filename: a.filename } : {}),
+      }),
+  },
+  get_table_export: {
+    def: {
+      description:
+        'Get one table export and its signed download URL, or omit job_id to list recent background exports.',
+      inputSchema: obj({ list_id: S, job_id: S }, ['list_id']),
+    },
+    run: (a) =>
+      api(
+        'GET',
+        a.job_id
+          ? `/lists/${enc(a.list_id)}/exports/${enc(a.job_id)}`
+          : `/lists/${enc(a.list_id)}/exports`,
+      ),
+  },
+  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.",
+      inputSchema: obj(
+        {
+          list_id: S,
+          cursor: S,
+          limit: N,
+          sort: S,
+          q: S,
+          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'],
+      ),
+    },
+    run: (a) =>
+      a.list_id
+        ? api(
+            'GET',
+            `/lists/${enc(a.list_id)}/rows${qs({
+              cursor: a.cursor,
+              limit: a.limit,
+              sort: a.sort,
+              q: a.q,
+              filter: a.filter ? JSON.stringify(a.filter) : undefined,
+              view_id: a.view_id,
+            })}`,
+          )
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  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).",
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/views`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  create_table_view: {
+    def: {
+      description:
+        'Save a custom view of an active table: a named filter (FilterExpr) + sorts + column overlay + row window (all optional beyond name). filter_expression uses the same grammar as list_table_rows; sorts is [{key,dir}]. 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.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          name: S,
+          operation_id: { ...S, format: 'uuid', description: 'Optional retry key from a prior ambiguous call.' },
+          description: S,
+          filter_expression: O,
+          sorts: ARR(O),
+          column_state: O,
+          row_window: O,
+        },
+        ['list_id', 'name'],
+      ),
+    },
+    run: async (a) => {
+      if (!a.list_id || !a.name) {
+        return { ok: false, status: 400, error: { detail: 'list_id and name are required.' } };
+      }
+      const viewsPath = `/lists/${enc(a.list_id)}/views`;
+      const requestBody = {
+        name: a.name,
+        operation_id: a.operation_id || randomUUID(),
+        ...(a.description !== undefined ? { description: a.description } : {}),
+        ...(a.filter_expression !== undefined ? { filter_expression: a.filter_expression } : {}),
+        ...(a.sorts !== undefined ? { sorts: a.sorts } : {}),
+        ...(a.column_state !== undefined ? { column_state: a.column_state } : {}),
+        ...(a.row_window !== undefined ? { row_window: a.row_window } : {}),
+      };
+      return api('POST', viewsPath, requestBody, {
+        reconciliation: {
+          operation_id: requestBody.operation_id,
+          retry_with: {
+            tool: 'create_table_view',
+            arguments: { ...a, operation_id: requestBody.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table_view with the same operation_id ${requestBody.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
+    },
+  },
+  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.',
+      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'],
+      ),
+    },
+    run: (a) => {
+      if (!a.list_id || !a.view_id) return { ok: false, status: 400, error: { detail: 'list_id and view_id are required.' } };
+      const body = {};
+      for (const k of ['name', 'description', 'filter_expression', 'sorts', 'column_state', 'row_window'])
+        if (a[k] !== undefined) body[k] = a[k];
+      return api('PATCH', `/lists/${enc(a.list_id)}/views/${enc(a.view_id)}`, body);
+    },
+  },
+  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.',
+      inputSchema: obj({ list_id: S, view_id: S }, ['list_id', 'view_id']),
+    },
+    run: (a) =>
+      a.list_id && a.view_id
+        ? api('DELETE', `/lists/${enc(a.list_id)}/views/${enc(a.view_id)}`)
+        : { ok: false, status: 400, error: { detail: 'list_id and view_id are required.' } },
+  },
+  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.",
+      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'],
+      ),
+    },
+    run: (a) =>
+      a.list_id && a.column_id
+        ? api('POST', `/lists/${enc(a.list_id)}/columns/${enc(a.column_id)}/estimate`, runScopeBody(a))
+        : { ok: false, status: 400, error: { detail: 'list_id and column_id are required.' } },
+  },
+  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.",
+      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'],
+      ),
+    },
+    run: (a) =>
+      a.list_id && a.column_id
+        ? api('POST', `/lists/${enc(a.list_id)}/run-column`, { column_id: a.column_id, ...runScopeBody(a) })
+        : { ok: false, status: 400, error: { detail: 'list_id and column_id are required.' } },
+  },
+  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.',
+      inputSchema: obj({ list_id: S, column_id: S, view_id: S, selection: O }, ['list_id', 'column_id']),
+    },
+    run: (a) =>
+      a.list_id && a.column_id
+        ? api('POST', `/lists/${enc(a.list_id)}/columns/${enc(a.column_id)}/run-scope-summary`, {
+            ...(a.view_id ? { view_id: a.view_id } : {}),
+            ...(a.selection ? { selection: a.selection } : {}),
+          })
+        : { ok: false, status: 400, error: { detail: 'list_id and column_id are required.' } },
+  },
+  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.',
+      inputSchema: obj(
+        { list_id: S, column_ids: ARR(S), view_id: S, selection: O, only_empty: B },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('POST', `/lists/${enc(a.list_id)}/run-all/estimate`, {
+            ...(a.column_ids ? { column_ids: a.column_ids } : {}),
+            ...(a.view_id ? { view_id: a.view_id } : {}),
+            ...(a.selection ? { selection: a.selection } : {}),
+            only_empty: a.only_empty !== false,
+          })
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  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.',
+      inputSchema: obj(
+        { list_id: S, column_ids: ARR(S), view_id: S, selection: O, only_empty: B },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('POST', `/lists/${enc(a.list_id)}/run-all`, {
+            ...(a.column_ids ? { column_ids: a.column_ids } : {}),
+            ...(a.view_id ? { view_id: a.view_id } : {}),
+            ...(a.selection ? { selection: a.selection } : {}),
+            only_empty: a.only_empty !== false,
+          })
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  get_table_cell: {
+    def: {
+      description:
+        "Read one table cell's FULL enrichment payload plus provenance (status/cost/provider/ran-at/error). Use when list_table_rows returns a cell with truncated: true because the rows endpoint trims payloads over 64KB. Get lead_id from list_table_rows and column_id from get_table_columns.",
+      inputSchema: obj({ list_id: S, lead_id: S, column_id: S }, ['list_id', 'lead_id', 'column_id']),
+    },
+    run: (a) =>
+      a.list_id && a.lead_id && a.column_id
+        ? api('GET', `/lists/${enc(a.list_id)}/cells/${enc(a.lead_id)}/${enc(a.column_id)}`)
+        : { ok: false, status: 400, error: { detail: 'list_id, lead_id and column_id are required.' } },
+  },
+  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.',
+      inputSchema: obj({ list_id: S, lead_ids: ARR(S) }, ['list_id', 'lead_ids']),
+    },
+    run: (a) =>
+      a.list_id && Array.isArray(a.lead_ids)
+        ? api('DELETE', `/lists/${enc(a.list_id)}/rows`, { lead_ids: a.lead_ids })
+        : { ok: false, status: 400, error: { detail: 'list_id and lead_ids are required.' } },
+  },
+  get_list_webhook: {
+    def: {
+      description:
+        "Read a table's inbound webhook state (masked URL, rows received, 50k lifetime cap, field mapping). Returns configured:false if none exists.",
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) => api('GET', `/lists/${enc(a.list_id)}/webhook`),
+  },
+  create_list_webhook: {
+    def: {
+      description:
+        'Create or rotate a static table inbound webhook. Returns the full URL and token ONCE, so show it to the user immediately. Calling again rotates the token and the old URL stops working. Smart and system tables are not supported.',
+      inputSchema: obj(
+        { list_id: S, field_map: O, default_verification_status: S },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/lists/${enc(a.list_id)}/webhook`, {
+        ...(a.field_map ? { field_map: a.field_map } : {}),
+        ...(a.default_verification_status
+          ? { default_verification_status: a.default_verification_status }
+          : {}),
+      }),
+  },
+  update_list_webhook: {
+    def: {
+      description: "Update a table inbound webhook's field mapping or default verification status.",
+      inputSchema: obj(
+        { list_id: S, field_map: O, default_verification_status: S },
+        ['list_id'],
+      ),
+    },
+    run: (a) =>
+      api('PATCH', `/lists/${enc(a.list_id)}/webhook`, {
+        ...(a.field_map !== undefined ? { field_map: a.field_map } : {}),
+        ...(a.default_verification_status !== undefined
+          ? { default_verification_status: a.default_verification_status }
+          : {}),
+      }),
+  },
+  revoke_list_webhook: {
+    def: {
+      description:
+        "Revoke a table's inbound webhook. The current URL stops working immediately and this cannot be undone. Confirm with the user first.",
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) => api('DELETE', `/lists/${enc(a.list_id)}/webhook`),
+  },
+  export_list_to_webhook: {
+    def: {
+      description:
+        "Push a table's rows to a webhook URL as JSON batches of 100 (Zapier/Make/n8n/custom). Optional bearer_token is stored encrypted and reusable via credential_id. Returns a job_id, poll it with get_job. Sends lead data to an external URL: confirm the destination with the user first.",
+      inputSchema: obj(
+        {
+          list_id: S,
+          url: S,
+          bearer_token: S,
+          credential_id: S,
+          lead_ids: ARR(S),
+        },
+        ['list_id', 'url'],
+      ),
+    },
+    run: (a) =>
+      a.list_id && a.url
+        ? api('POST', `/lists/${enc(a.list_id)}/export/webhook`, {
+            url: a.url,
+            bearer_token: a.bearer_token,
+            credential_id: a.credential_id,
+            lead_ids: a.lead_ids,
+          })
+        : {
+            ok: false,
+            status: 400,
+            error: { detail: 'list_id and url are required.' },
+          },
+  },
+  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.',
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('DELETE', `/lists/${enc(a.list_id)}`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  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.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) =>
+      a.campaign_id
+        ? api('DELETE', `/campaigns/${enc(a.campaign_id)}`)
+        : { ok: false, status: 400, error: { detail: 'campaign_id is required.' } },
+  },
+
+  // ── Replies + suppression ─────────────────────────────────────────────
+  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).',
@@ -800,21 +2485,178 @@ const TOOLS = {
           : {}),
       }),
   },
+
+  // ── Roadmap (agency build kanban) ─────────────────────────────────────
+  roadmap_list: {
+    def: {
+      description:
+        'List every card on the agency build roadmap (planned / in_progress / deployed). Each card is a feature/bug/improvement with slug, track (claude|codex|either), priority position, deps, and has_plan. Use roadmap_get_item for the full execution plan.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/roadmap'),
+  },
+  roadmap_next_planned: {
+    def: {
+      description:
+        'Fetch the next eligible planned roadmap card (highest priority whose dependencies are all deployed), INCLUDING its full execution plan (plan_md). This is what "launch the next planned thing on the roadmap" resolves to. Optionally filter by track.',
+      inputSchema: obj({ track: { ...S, enum: ['claude', 'codex', 'either'] } }),
+    },
+    run: (a) => api('GET', `/roadmap/next${qs({ track: a.track })}`),
+  },
+  roadmap_get_item: {
+    def: {
+      description:
+        'Fetch one roadmap card by slug, including its full execution plan (plan_md, markdown). Follow that plan exactly when building the card.',
+      inputSchema: obj({ slug: S }, ['slug']),
+    },
+    run: (a) => api('GET', `/roadmap/${enc(a.slug)}`),
+  },
+  roadmap_update_status: {
+    def: {
+      description:
+        'Move a roadmap card across the board: planned | in_progress | deployed. Set in_progress when you start building it; set deployed (with pr_url) once merged + live.',
+      inputSchema: obj(
+        {
+          slug: S,
+          status: { ...S, enum: ['planned', 'in_progress', 'deployed'] },
+          pr_url: { ...S, description: 'PR link — set it when marking deployed' },
+        },
+        ['slug', 'status'],
+      ),
+    },
+    run: (a) =>
+      api('PATCH', `/roadmap/${enc(a.slug)}`, {
+        status: a.status,
+        ...(a.pr_url ? { pr_url: a.pr_url } : {}),
+      }),
+  },
+  roadmap_create_item: {
+    def: {
+      description:
+        'Add a card to the build roadmap. slug is a stable lowercase-hyphen id; plan_md is the self-contained execution plan (markdown) an agent will follow; depends_on lists slugs that must be deployed first.',
+      inputSchema: obj(
+        {
+          slug: S,
+          title: S,
+          kind: { ...S, enum: ['feature', 'bug', 'improvement'] },
+          track: { ...S, enum: ['claude', 'codex', 'either'] },
+          area: S,
+          effort: { ...S, enum: ['S', 'M', 'L'] },
+          summary: S,
+          plan_md: S,
+          depends_on: ARR(S),
+          files_hint: ARR(S),
+          position: N,
+        },
+        ['slug', 'title'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/roadmap', {
+        slug: a.slug,
+        title: a.title,
+        ...(a.kind ? { kind: a.kind } : {}),
+        ...(a.track ? { track: a.track } : {}),
+        ...(a.area ? { area: a.area } : {}),
+        ...(a.effort ? { effort: a.effort } : {}),
+        ...(a.summary ? { summary: a.summary } : {}),
+        ...(a.plan_md ? { plan_md: a.plan_md } : {}),
+        ...(a.depends_on ? { depends_on: a.depends_on } : {}),
+        ...(a.files_hint ? { files_hint: a.files_hint } : {}),
+        ...(a.position != null ? { position: a.position } : {}),
+      }),
+  },
+  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.",
+      inputSchema: obj(
+        {
+          slug: S,
+          plan_md: S,
+          title: S,
+          summary: S,
+          kind: { ...S, enum: ['feature', 'bug', 'improvement'] },
+          track: { ...S, enum: ['claude', 'codex', 'either'] },
+          area: S,
+          effort: { ...S, enum: ['S', 'M', 'L'] },
+          depends_on: ARR(S),
+          files_hint: ARR(S),
+          position: N,
+          pr_url: S,
+        },
+        ['slug'],
+      ),
+    },
+    run: (a) => {
+      const { slug, ...rest } = a;
+      const body = Object.fromEntries(
+        Object.entries(rest).filter(([, v]) => v !== undefined && v !== null),
+      );
+      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' } };
+    },
+  },
 };
 
+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
   // 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) {
-    console.error(
+    warnStartupOnce(
+      'missing_api_key',
       'scrapeloop-mcp: SCRAPELOOP_API_KEY is not set — 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.6.0' },
+    { name: 'scrapeloop-mcp', version: '0.7.1' },
     { capabilities: { tools: {} } }
   );
 
@@ -841,10 +2683,12 @@ async function serve() {
   // user sees the problem at startup instead of only on first use. Never blocks
   // serving and never logs the key.
   if (API_KEY) {
-    api('GET', '/me').then((r) => {
-      if (!r.ok) {
-        const why = r.status === 401 ? 'invalid or revoked' : `unreachable (status ${r.status})`;
-        console.error(`scrapeloop-mcp: API key check failed — ${why}. Tools may return auth errors.`);
+    runApiKeyPreflight().then((preflight) => {
+      if (preflight.state !== 'authenticated') {
+        warnStartupOnce(
+          `api_key_preflight:${preflight.state}`,
+          formatApiKeyPreflightWarning(preflight),
+        );
       }
     });
   }
@@ -855,7 +2699,15 @@ async function serve() {
 // 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.)
-export { TOOLS, serve };
+export {
+  MUTATION_POLICIES,
+  TOOLS,
+  classifyApiKeyPreflight,
+  formatApiKeyPreflightWarning,
+  runApiKeyPreflight,
+  serve,
+  warnStartupOnce,
+};
 
 if (!process.env.SCRAPELOOP_MCP_NO_SERVE) {
   await serve();