@opennous/mcp 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Nous MCP Server — Customer graph for GTM agents.",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/server.js

@@ -27,19 +27,21 @@
  *   record_closed_deals  — build the ICP model from real closed-won/lost deals (contrastive lift)
  *   connect_integration  — connect a key-based integration (Apollo, Prospeo, HubSpot, …)
  *   configure_crm_sync   — set CRM sync rules (auto-sync, create policy, hygiene cadence)
+ *   sync_crm_now         — run an immediate incremental/full CRM pull (don't wait for the daily cron)
  *   set_trigger          — create an outbound event trigger (webhook); list_triggers reads them
  *   list_triggers        — list the workspace's event triggers + available events
  *   get_routing_preferences — Claude Code routing prefs to default GTM to Nous (write to CLAUDE.md)
  *   lead_list_operations — the operations trail of a lead list (imports/enrich/push/replies), filterable
- *   check_leads          — pre-spend coverage check: which candidates you already own / should re-enrich
- *   lead_coverage        — attribute coverage estimate ("how many agency founders do we have, by freshness")
+ *   coverage             — pre-spend coverage: exact per-lead check (identifiers) or attribute estimate (title/keyword)
+ *   enrich_leads         — find missing emails for a lead list (two-step: dry-run cost preview, then confirm)
+ *   verify_leads         — validate email deliverability for a lead list (two-step preview, then confirm)
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post } from "./client.js";
 
-export const SERVER_VERSION = "0.27.0";
+export const SERVER_VERSION = "0.34.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -54,6 +56,28 @@ function relAge(ts) {
   return `${Math.floor(m / 12)}y ago`;
 }
 
+// Absolute calendar date + clock time, in the user's local zone (this server runs
+// on their machine over stdio, so toLocaleString is already local). For meetings,
+// "Tue, Jun 16, 3:00 PM" beats relAge's fuzzy "today" — and relAge can't represent
+// the future at all, so every scheduled call would otherwise read "today".
+function fmtWhen(ts) {
+  if (!ts) return "—";
+  return new Date(ts).toLocaleString("en-US", {
+    weekday: "short", month: "short", day: "numeric",
+    hour: "numeric", minute: "2-digit", timeZoneName: "short",
+  });
+}
+
+// When to show an absolute datetime vs a relative age. Meetings/calls always get
+// the exact time (you need to know it's 3pm, not "today"); so does anything
+// future-dated (a scheduled event), which relAge would collapse to "today".
+function whenLabel(type, ts) {
+  const t = String(type || "");
+  const isMeeting = t.includes("meeting") || t.includes("call");
+  const isFuture = ts && new Date(ts).getTime() > Date.now();
+  return (isMeeting || isFuture) ? fmtWhen(ts) : relAge(ts);
+}
+
 const fmtType = (p) => (p || "").replace(/^interaction\./, "").replace(/_/g, " ");
 const fmtVal  = (v) => (v != null && typeof v === "object") ? JSON.stringify(v) : String(v ?? "");
 const pct     = (c) => `${Math.round((c ?? 0) * 100)}%`;
@@ -166,7 +190,7 @@ export function createServer() {
         lines.push("TIMELINE:");
         for (const t of ctx.timeline) {
           if (t.tier === "count") lines.push(`  ${t.count}× ${fmtType(t.type)}`);
-          else lines.push(`  ${relAge(t.when)}  ${fmtType(t.type)}${t.summary ? `: ${t.summary}` : ""}`);
+          else lines.push(`  ${whenLabel(t.type, t.when)}  ${fmtType(t.type)}${t.summary ? `: ${t.summary}` : ""}`);
         }
         lines.push("");
       }
@@ -229,7 +253,7 @@ export function createServer() {
       if (obs.length) {
         lines.push(`TIMELINE (${obs.length}):`);
         for (const o of obs.slice(0, 30)) {
-          lines.push(`  ${relAge(o.observed_at)}  ${fmtType(o.property)}`);
+          lines.push(`  ${whenLabel(o.property, o.observed_at)}  ${fmtType(o.property)}`);
         }
       }
       return { content: [{ type: "text", text: lines.join("\n").trim() }] };
@@ -269,6 +293,50 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: record_signal  —  a buying signal, as a structured signal.<class> fact
+  // A validated wrapper over record: one canonical way to write a signal, so it
+  // both shows on the account's Signals tab AND feeds the ICP scorecard as a
+  // feature (signal.* claims flow into the feature map the scorer reads).
+  // ===========================================================================
+  server.tool(
+    "record_signal",
+    "Record a buying signal on a person or company — a concrete, current reason to reach out, " +
+    "found by research (signal-scan). Stored as a structured signal.<class> fact so it shows on the " +
+    "account's Signals tab AND feeds the ICP scoring model as a feature. One call per signal; one " +
+    "current signal per class (the strongest). class is one of stack | hiring | momentum | friction | " +
+    "intent | domain. score is 0-10 (exclusivity x intent — score honestly, a 4 is useful). Be " +
+    "specific: 'posted 3 SDR roles in 30 days', not 'they're growing'.",
+    {
+      focus: z.string().describe("Email address or entity UUID of the person/company"),
+      signal_class: z.enum(["stack", "hiring", "momentum", "friction", "intent", "domain"])
+        .describe("the signal class"),
+      detected: z.string().describe("the specific, factual finding"),
+      implies: z.string().optional().describe("what the prospect is likely experiencing because of it"),
+      score: z.number().min(0).max(10).describe("strength 0-10 (exclusivity x intent)"),
+      approach: z.enum(["pain_led", "value_led", "fallback"]).optional()
+        .describe("recommended outreach approach"),
+      angle: z.string().optional().describe("one-line outreach angle this signal enables"),
+    },
+    async ({ focus, signal_class, detected, implies, score, approach, angle }) => {
+      const result = await post("/v2/observations", {
+        focus,
+        observations: [{
+          kind: "state",
+          property: `signal.${signal_class}`,
+          value: { detected, implies: implies ?? null, score, approach: approach ?? null, angle: angle ?? null },
+          source: "signal-scan",
+        }],
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Recorded ${signal_class} signal (score ${score}/10) on ${result.entity_id || focus}.`,
+        }],
+      };
+    }
+  );
+
   // ===========================================================================
   // TOOL: query  —  POST /v2/query
   // Retrieve a corpus of activity across many people. You do the analysis.
@@ -282,14 +350,21 @@ export function createServer() {
     "  2. `without` subtracts entities — 'sent in 5d MINUS replied in 5d' = 'no-reply leads'. " +
     "'activity in 30d MINUS activity in 5d' = 'cooled leads'.\n" +
     "  3. rollups.by_value appears when scope.kind='state' — counts entities by current value " +
-    "(use scope.property='stage' for funnel reports).",
+    "(use scope.property='stage' for funnel reports).\n" +
+    "  4. Scheduled meetings/calls are events with property 'interaction.meeting_scheduled' and a " +
+    "future-dated `when`. For 'what's booked today/this week', set property:'interaction.meeting_scheduled' " +
+    "with from/to bounding the day or week (since_days only looks backward and can't reach them), and " +
+    "order:'asc' to list soonest-first. Meeting rows render the absolute date and time.",
     {
       scope: z.object({
         kind: z.enum(["event", "state"]).optional(),
-        property: z.string().optional().describe("property prefix — 'interaction.email' covers email_sent and email_replied"),
+        property: z.string().optional().describe("property prefix — 'interaction.email' covers email_sent and email_replied; 'interaction.meeting_scheduled' for booked meetings"),
         source: z.string().optional().describe("e.g. 'gmail', 'linkedin', 'slack'"),
         entity_id: z.string().optional().describe("scope to one person/company"),
-        since_days: z.number().optional().describe("only activity within the last N days"),
+        since_days: z.number().optional().describe("only activity within the last N days (backward only)"),
+        from: z.string().optional().describe("ISO timestamp — only activity at/after this (absolute lower bound; use for date windows like 'today')"),
+        to: z.string().optional().describe("ISO timestamp — only activity at/before this (absolute upper bound). Combine from+to for a window; future-dated for upcoming meetings"),
+        order: z.enum(["asc", "desc"]).optional().describe("observed_at order (default desc, newest first). Use 'asc' for an upcoming-meeting schedule (soonest first)"),
         limit: z.number().optional().describe("max items (default 50, cap 200)"),
       }).describe("Corpus filter"),
       without: z.object({
@@ -321,11 +396,11 @@ export function createServer() {
       for (const it of r.items ?? []) {
         if (r.return === "entities") {
           lines.push(`  ${it.entity_name ?? it.entity_id}  ` +
-                     `(${it.matches} match${it.matches !== 1 ? "es" : ""}, last ${relAge(it.most_recent_at)})` +
+                     `(${it.matches} match${it.matches !== 1 ? "es" : ""}, last ${whenLabel(it.most_recent_type, it.most_recent_at)})` +
                      (it.most_recent_value != null ? `  → ${fmtVal(it.most_recent_value)}` : "") +
                      (it.most_recent_summary ? `\n      ${it.most_recent_summary}` : ""));
         } else {
-          lines.push(`  ${relAge(it.when)}  ${it.entity_name ?? it.entity_id}  ` +
+          lines.push(`  ${whenLabel(it.type, it.when)}  ${it.entity_name ?? it.entity_id}  ` +
                      `${fmtType(it.type)}${it.summary ? `: ${it.summary}` : ""}`);
         }
       }
@@ -339,9 +414,12 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "attention",
-    "What needs your attention across the workspace right now — accounts that have gone quiet and " +
-    "key facts that have decayed. Returns ranked items, each with what happened and a suggested " +
-    "action. Call this to decide who to work next.",
+    "What needs your attention across the workspace right now — upcoming meetings and calls in the " +
+    "next 7 days (each with its date and time, soonest first), accounts that have gone quiet, and key " +
+    "facts that have decayed. Returns ranked items (time-critical meetings lead), each with what's " +
+    "happening and a suggested action. Call this to decide what to work next, or to answer 'what's " +
+    "coming up' / 'what's on my calendar this week'. For a precise single-day list, use query with " +
+    "property:'interaction.meeting_scheduled' and from/to.",
     {
       limit: z.number().min(1).max(100).optional().describe("Max items (default 25)"),
     },
@@ -350,8 +428,11 @@ export function createServer() {
       if (!r.items?.length) {
         return { content: [{ type: "text", text: "Nothing needs attention right now." }] };
       }
-      const lines = r.items.map(it =>
-        `  ${it.entity_name ?? it.entity_id} — ${it.what}\n      → ${it.suggested_action}`);
+      // Upcoming meetings carry a `when` — render the absolute local date+time.
+      const lines = r.items.map(it => {
+        const when = it.when ? `${fmtWhen(it.when)} — ` : "";
+        return `  ${when}${it.entity_name ?? it.entity_id} — ${it.what}\n      → ${it.suggested_action}`;
+      });
       return { content: [{ type: "text", text: `Needs attention (${r.items.length}):\n${lines.join("\n")}` }] };
     }
   );
@@ -387,7 +468,6 @@ export function createServer() {
   // TOOL: get_gtm_profile  —  GET /v2/workspace/facts
   // The user's OWN GTM profile: ICP, market, product, pricing, competitors.
   // Use this for any question about the user's business — NOT get_account.
-  // Registered also under the legacy name get_workspace_facts for back-compat.
   // ===========================================================================
   const gtmProfileDescription =
     "Get the user's OWN GTM profile — their ICP, target market, product, pricing, " +
@@ -431,8 +511,6 @@ export function createServer() {
     return { content: [{ type: "text", text: lines.join("\n").trim() }] };
   };
   server.tool("get_gtm_profile", gtmProfileDescription, gtmProfileSchema, gtmProfileHandler);
-  // Legacy alias — keeps existing integrations calling get_workspace_facts working.
-  server.tool("get_workspace_facts", gtmProfileDescription, gtmProfileSchema, gtmProfileHandler);
 
   // ===========================================================================
   // TOOL: update_gtm_profile  —  POST /v2/workspace/facts
@@ -546,21 +624,15 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "get_workspace_status",
-    "See the whole setup state of this workspace in one call, and what to do next. Nous is operated " +
-    "by you, the agent: call this at the start of a session. It returns a ranked NEXT STEPS list — " +
-    "walk the user through it top-down. The onboarding sequence, in order: " +
-    "(1) profile (set_workspace_profile); " +
-    "(2) connect core channels — Gmail/email, LinkedIn, and a meeting note-taker (Fireflies/Fathom/" +
-    "Calendly); (3) connect enrichment/outbound (Prospeo/Apollo/Instantly); (4) set up webhooks for " +
-    "the connected tools so their events flow in; (5) import first records (CSV from the CRM) on the " +
-    "Accounts page, then backfill enrichment; (6) build the GTM playbook (update_gtm_profile + " +
-    "build_scoring_model, asking for closed-won/lost domains). " +
-    "KNOW THE CONSTRAINTS: Gmail uses Google OAuth and LinkedIn has NO public API (Nous connects it " +
-    "natively via Unipile) — you CANNOT connect those yourself; tell the user to set them up on the " +
-    "Integrations page. Key-based tools (Prospeo, Apollo, Instantly, HubSpot token) you CAN connect " +
-    "with connect_integration. CSV import and CRM-page actions are done by the user in the app — guide " +
-    "them. Respect PLAN: never push a feature the plan doesn't include (e.g. CRM sync on free). " +
-    "Recommend, don't dump — surface the next 1-2 steps, not all of them at once.",
+    "See the whole setup state of this workspace in one call, plus a ranked NEXT STEPS list (each step " +
+    "carries its own why/how). Nous is operated by you, the agent — call this at the START of a session " +
+    "and walk the user top-down through the steps it returns; the server sequences them by current " +
+    "state, so trust that order. Two constraints when acting on them: (1) Gmail (Google OAuth) and " +
+    "LinkedIn (no public API — Nous uses Unipile) CANNOT be connected by you — point the user to the " +
+    "Integrations page; key-based tools (Prospeo, Apollo, Instantly, HubSpot token) you CAN connect via " +
+    "connect_integration, and CSV import is a user action in the app. (2) Respect the plan — never push " +
+    "a feature it doesn't include (e.g. CRM sync on free). Recommend the next 1-2 steps, don't dump the " +
+    "whole list.",
     {},
     async () => {
       const s = await get("/v2/workspace/status");
@@ -571,6 +643,12 @@ export function createServer() {
       lines.push(`WORKSPACE: ${ws.name || "(unnamed)"}${ws.website ? ` · ${ws.website}` : ""}${ws.business_type ? ` · ${ws.business_type}` : ""}`);
       const pl = s.plan ?? {};
       lines.push(`PLAN: ${pl.name || pl.id || "free"}${pl.crm_sync === false ? "  (CRM sync not included — do not offer it)" : ""}`);
+      if (s.self_hosted) {
+        const e = s.env_integrations ?? {};
+        const mk = (b) => (b ? "✓ set" : "✗ NOT set");
+        lines.push("SELF-HOSTED — these channels are wired via nous.env (you can't set env vars; tell the operator to set + restart):");
+        lines.push(`  LinkedIn/Unipile: ${mk(e.linkedin_unipile)}   Email/Resend: ${mk(e.email_resend)}   Gmail OAuth: ${mk(e.gmail_oauth)}`);
+      }
       lines.push("");
 
       const mark = (b) => (b ? "✓" : "✗");
@@ -786,7 +864,7 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "configure_crm_sync",
-    "Configure how Nous keeps a connected CRM in sync — the same settings as the CRM Sync page. The " +
+    "(Nous Cloud only) Configure how Nous keeps a connected CRM in sync — the same settings as the CRM Sync page. The " +
     "CRM must already be connected (HubSpot/Pipedrive/Attio). Set any of: auto-sync (daily pull), " +
     "push of touchpoints, the create policy (when a new record is auto-created and the ICP-fit " +
     "threshold), and the hygiene cadence. Only send the fields you want to change. If it reports the " +
@@ -821,6 +899,39 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: sync_crm_now  —  POST /v2/workspace/crm-sync-now
+  // Run an immediate incremental CRM pull right now, instead of waiting for the
+  // daily auto-sync cron — e.g. straight after configure_crm_sync, or whenever
+  // the user wants the latest. Same engine the scheduled sync uses.
+  // ===========================================================================
+  server.tool(
+    "sync_crm_now",
+    "(Nous Cloud only) Pull the latest from a connected CRM (HubSpot/Pipedrive/Attio) RIGHT NOW, instead of waiting for " +
+    "the daily auto-sync. Use it just after configure_crm_sync to seed the data, or whenever the user " +
+    "wants an immediate refresh. Incremental by default (only what changed since the last pull); pass " +
+    "full:true to re-fetch everything. The CRM must already be connected and sync configured — if not, " +
+    "it'll tell you to connect/configure first.",
+    {
+      provider: z.enum(["hubspot", "pipedrive", "attio"]).optional().describe("Which connected CRM to pull from (default hubspot)."),
+      full: z.boolean().optional().describe("true = re-fetch everything; default = incremental since the last sync."),
+    },
+    async ({ provider, full }) => {
+      try {
+        const r = await post("/v2/workspace/crm-sync-now", { provider: provider || "hubspot", full: full === true });
+        const errs = (r.errors && r.errors.length) ? ` · ${r.errors.length} error(s)` : "";
+        return { content: [{ type: "text", text:
+          `Pulled from ${r.provider}: ${r.fetched ?? 0} records — ${r.created ?? 0} new, ${r.updated ?? 0} updated${errs}.` }] };
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (/sync_not_configured/.test(msg)) return { content: [{ type: "text", text: `Sync isn't configured for that CRM yet — call configure_crm_sync first.` }] };
+        if (/crm_not_connected/.test(msg)) return { content: [{ type: "text", text: `That CRM isn't connected. Tell the user to connect it on the Integrations page, then try again.` }] };
+        if (/salesforce_not_yet_supported/.test(msg)) return { content: [{ type: "text", text: `Salesforce pull isn't supported yet — only HubSpot, Pipedrive, and Attio.` }] };
+        return { content: [{ type: "text", text: `Couldn't sync: ${msg}` }] };
+      }
+    }
+  );
+
   // ===========================================================================
   // TOOL: set_trigger / list_triggers  —  /v2/workspace/triggers
   // Outbound event triggers (webhooks) — wire the user's stack to fire when the
@@ -876,7 +987,7 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "lead_list_operations",
-    "Inspect the operations trail of a lead list — imports, enrichment runs, pushes to campaigns, " +
+    "(Nous Cloud only) Inspect the operations trail of a lead list — imports, enrichment runs, pushes to campaigns, " +
     "and classified replies — to report on what happened and attribute outcomes to a list's source. " +
     "Call with NO lead_list_id to list the workspace's lead lists (id, name, count, source), then " +
     "call again with an id. Filter with `event` (import | enrich | export | reply) and `days`. " +
@@ -918,97 +1029,200 @@ export function createServer() {
   );
 
   // ===========================================================================
-  // TOOL: check_leads  —  POST /v2/dedup
-  // The pre-spend coverage check. Run this BEFORE building/buying a lead list in
-  // Apollo, Sales Navigator, DeepSearch, Clay, etc. Paste the candidate emails /
-  // LinkedIn URLs / company domains (all visible for free in the tool's preview)
-  // and find out what you already own — so you never re-buy a record you have,
-  // and you re-enrich stale ones instead of paying to acquire them again.
+  // TOOL: coverage  —  POST /v2/dedup (exact) | GET /v2/people/coverage (estimate)
+  // "What do I already have?" before spending on a list elsewhere. One tool, two
+  // modes: pass identifiers for an EXACT per-lead net-new/re-enrich/reuse check
+  // (the pre-spend gate), or a title/keyword for a rough attribute ESTIMATE.
+  // (Replaces the former check_leads + lead_coverage tools.)
   // ===========================================================================
   server.tool(
-    "check_leads",
-    "Pre-spend coverage check — call this BEFORE building or buying a lead list elsewhere (Apollo, " +
-    "Sales Navigator, DeepSearch, Clay). Paste the candidate emails, LinkedIn URLs, or company " +
-    "domains (free in any tool's preview) and learn what you already have, so you don't pay twice. " +
-    "Returns counts: net_new (acquire + enrich these), needs_enrichment (you already OWN these but " +
-    "they're stale / not enriched in 90 days — re-enrich instead of re-buying), reusable (you have a " +
-    "fresh verified email — reuse, spend nothing), plus engaged/recent/bounced/unsubscribed/known to " +
-    "skip. Each result carries entity_id, email_status, enriched_at, and stale so you can act per-lead.",
+    "coverage",
+    "(Nous Cloud only) Check what you ALREADY have before spending on a list elsewhere (Apollo, Sales Navigator, Clay). " +
+    "Two modes:\n" +
+    "  • EXACT — pass candidate identifiers (emails / linkedin_urls / domains, free in any tool's " +
+    "preview). Returns per-lead buckets: net_new (acquire + enrich), needs_enrichment (you OWN these " +
+    "but stale >90d — re-enrich, don't re-buy), reusable (fresh verified email on file — reuse, spend " +
+    "nothing), plus engaged/recent/known/bounced to skip. Each result carries entity_id, email_status, " +
+    "enriched_at, stale.\n" +
+    "  • ESTIMATE — pass a title and/or keyword instead. Returns how many people you already have " +
+    "matching (e.g. title='founder', keyword='agency'), split by freshness: never-enriched, stale >90d, " +
+    "fresh-verified. Rough by design (title precise; keyword matches title/company/department).\n" +
+    "Pass identifiers for the exact pre-spend check, OR title/keyword for the planning estimate — not both.",
     {
-      emails: z.array(z.string()).optional().describe("Candidate email addresses (up to 50,000)."),
-      linkedin_urls: z.array(z.string()).optional().describe("Candidate LinkedIn profile URLs (up to 50,000)."),
-      domains: z.array(z.string()).optional().describe("Company domains — 'do I already have anyone here?' (up to 50,000)."),
+      emails: z.array(z.string()).optional().describe("EXACT mode — candidate email addresses (up to 50,000)."),
+      linkedin_urls: z.array(z.string()).optional().describe("EXACT mode — candidate LinkedIn profile URLs (up to 50,000)."),
+      domains: z.array(z.string()).optional().describe("EXACT mode — company domains, 'do I already have anyone here?' (up to 50,000)."),
+      title: z.string().optional().describe("ESTIMATE mode — role match, e.g. 'founder', 'VP Sales' (matches job_title)."),
+      keyword: z.string().optional().describe("ESTIMATE mode — extra match across title/company/department, e.g. 'agency'."),
+      stale_days: z.number().optional().describe("ESTIMATE mode — days after which enrichment counts as stale (default 90)."),
     },
-    async ({ emails, linkedin_urls, domains }) => {
-      const body = {};
-      if (emails?.length) body.emails = emails;
-      if (linkedin_urls?.length) body.linkedin_urls = linkedin_urls;
-      if (domains?.length) body.domains = domains;
-      if (!Object.keys(body).length) {
-        return { content: [{ type: "text", text: "Pass at least one of: emails, linkedin_urls, domains." }] };
+    async ({ emails, linkedin_urls, domains, title, keyword, stale_days }) => {
+      const hasIds  = !!(emails?.length || linkedin_urls?.length || domains?.length);
+      const hasAttr = !!(title || keyword);
+      if (hasIds && hasAttr) {
+        return { content: [{ type: "text", text:
+          "Pass identifiers (emails/linkedin_urls/domains) for the exact check, OR title/keyword for the estimate — not both." }] };
       }
-      const r = await post("/v2/dedup", body);
-      const s = r.summary || {};
-      const lines = [
-        `COVERAGE (${s.total ?? 0} checked)`,
-        `  net_new          ${s.net_new ?? 0}   → acquire + enrich`,
-        `  needs_enrichment ${s.needs_enrichment ?? 0}   → you OWN these but stale (>90d) → re-enrich, don't re-buy`,
-        `  reusable         ${s.reusable ?? 0}   → fresh verified email on file → reuse, spend nothing`,
-        `  engaged          ${s.engaged ?? 0}   → in an active conversation, don't cold-send`,
-        `  recent           ${s.recent ?? 0}   → contacted <30d, defer`,
-        `  known            ${s.known ?? 0}   → company already in the workspace`,
-        `  bounced/unsub    ${(s.bounced ?? 0) + (s.unsubscribed ?? 0) + (s.suppressed ?? 0)}   → skip`,
-      ];
-      // Surface a few stale entities the caller should re-enrich (with their last date).
-      const stale = (r.results || []).filter(x => x.entity_id && x.stale).slice(0, 15);
-      if (stale.length) {
-        lines.push("", "RE-ENRICH (sample):");
-        for (const x of stale) {
-          lines.push(`  ${x.value}  [${x.enriched_at ? `last enriched ${relAge(x.enriched_at)}` : "never enriched"}]  ${x.entity_id}`);
+
+      // EXACT mode — per-identifier coverage against /v2/dedup.
+      if (hasIds) {
+        const body = {};
+        if (emails?.length) body.emails = emails;
+        if (linkedin_urls?.length) body.linkedin_urls = linkedin_urls;
+        if (domains?.length) body.domains = domains;
+        const r = await post("/v2/dedup", body);
+        const s = r.summary || {};
+        const lines = [
+          `COVERAGE (${s.total ?? 0} checked)`,
+          `  net_new          ${s.net_new ?? 0}   → acquire + enrich`,
+          `  needs_enrichment ${s.needs_enrichment ?? 0}   → you OWN these but stale (>90d) → re-enrich, don't re-buy`,
+          `  reusable         ${s.reusable ?? 0}   → fresh verified email on file → reuse, spend nothing`,
+          `  engaged          ${s.engaged ?? 0}   → in an active conversation, don't cold-send`,
+          `  recent           ${s.recent ?? 0}   → contacted <30d, defer`,
+          `  known            ${s.known ?? 0}   → company already in the workspace`,
+          `  bounced/unsub    ${(s.bounced ?? 0) + (s.unsubscribed ?? 0) + (s.suppressed ?? 0)}   → skip`,
+        ];
+        // Surface a few stale entities the caller should re-enrich (with their last date).
+        const stale = (r.results || []).filter(x => x.entity_id && x.stale).slice(0, 15);
+        if (stale.length) {
+          lines.push("", "RE-ENRICH (sample):");
+          for (const x of stale) {
+            lines.push(`  ${x.value}  [${x.enriched_at ? `last enriched ${relAge(x.enriched_at)}` : "never enriched"}]  ${x.entity_id}`);
+          }
         }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+
+      // ESTIMATE mode — attribute coverage against /v2/people/coverage.
+      if (hasAttr) {
+        const r = await get("/v2/people/coverage", { title, keyword, stale_days });
+        const lines = [
+          `COVERAGE — ${[title && `title~"${title}"`, keyword && `keyword~"${keyword}"`].filter(Boolean).join(" + ")}`,
+          `  ${r.total ?? 0} already in your workspace`,
+          `    ${r.needs_enrichment ?? 0} need (re-)enrichment  (${r.never_enriched ?? 0} never enriched · ${r.stale ?? 0} stale >90d)`,
+          `    ${r.fresh_verified ?? 0} have a fresh verified email`,
+        ];
+        const sample = r.sample || [];
+        if (sample.length) {
+          lines.push("", "SAMPLE (oldest first):");
+          for (const s of sample.slice(0, 12)) {
+            lines.push(`  ${[s.job_title, s.company].filter(Boolean).join(" @ ") || s.entity_id}  [${s.enriched_at ? `enriched ${relAge(s.enriched_at)}` : "never enriched"}]`);
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      return { content: [{ type: "text", text:
+        "Pass at least one of: emails / linkedin_urls / domains (exact check), or title / keyword (estimate)." }] };
     }
   );
 
   // ===========================================================================
-  // TOOL: lead_coverage  —  GET /v2/people/coverage
-  // The attribute-based planning check: "how many <agency founders> do we already
-  // have, and how fresh?" — answered WITHOUT pasting identifiers. Use it before
-  // building a list elsewhere to see how much you already cover.
+  // TOOLS: enrich_leads / verify_leads  —  POST /api/lead-lists/:id/enrich|verify
+  // The agent OPERATES the lead list. Both are two-step: a dry-run preview that
+  // quotes the chargeable count + provider + $ estimate (report it to the user
+  // first), then a confirmed run as a background job. Target by `filter` so no
+  // ids are needed (enrich {emailStatus:'none'} = all missing an email; verify
+  // defaults to all unverified). BYOK — the $ is the user's own provider spend.
   // ===========================================================================
+  const fmtCost = (c) => {
+    if (!c) return "no chargeable records — nothing to spend";
+    const money = c.low === c.high ? `~$${c.low.toFixed(2)}` : `~$${c.low.toFixed(2)}–$${c.high.toFixed(2)}`;
+    return `${money} via ${c.label} (${(c.count ?? 0).toLocaleString()} ${c.action})`;
+  };
+  const LEAD_FILTER_SHAPE = {
+    emailStatus: z.enum(["has", "none", "unverified"]).optional().describe("none = no email yet; unverified = has an email but no verification verdict; has = has any email."),
+    domain: z.enum(["has", "none"]).optional().describe("has = a company domain is known; none = no domain."),
+    icp: z.enum(["true", "false"]).optional().describe("true = ICP-qualified leads only."),
+    status: z.string().optional().describe("Lifecycle: pending | sent | replied | bounced."),
+    source: z.string().optional().describe("Substring of where the lead came from (campaign / import name)."),
+    size: z.string().optional().describe("Substring of company size, e.g. '1 to 10'."),
+    channel: z.string().optional().describe("Last-contacted channel substring, or 'none' for not-yet-contacted."),
+  };
+
   server.tool(
-    "lead_coverage",
-    "Estimate how many people you ALREADY have matching a role/keyword, bucketed by enrichment " +
-    "freshness — the planning question before building a list (no identifiers to paste). E.g. " +
-    "title='founder', keyword='agency' → how many agency founders are already in your workspace, " +
-    "how many were never enriched or are stale (>90d, so re-enrich), and how many have a fresh " +
-    "verified email. Rough by design (title is precise; keyword matches title/company/department). " +
-    "For an exact net-new check against specific candidates, use check_leads with their identifiers.",
+    "enrich_leads",
+    "(Nous Cloud only) Find missing emails for leads in a lead list, on the workspace's own Prospeo/Apollo key. ALWAYS two " +
+    "steps: call WITHOUT confirm for a dry-run cost preview (chargeable count, provider, $ estimate) — " +
+    "report it and get the user's go-ahead — then call again with confirm:true to run as a background job. " +
+    "Pick leads with `filter` (e.g. {emailStatus:'none'} = every lead missing an email, the usual case) or " +
+    "explicit `ids`; defaults to {emailStatus:'none'}. Call lead_list_operations with no id first to get the " +
+    "list's id.",
     {
-      title: z.string().optional().describe("Role match, e.g. 'founder', 'VP Sales' (matches job_title)."),
-      keyword: z.string().optional().describe("Extra match across title/company/department, e.g. 'agency'."),
-      stale_days: z.number().optional().describe("Days after which enrichment counts as stale (default 90)."),
+      lead_list_id: z.string().describe("The lead list's UUID."),
+      filter: z.object(LEAD_FILTER_SHAPE).optional().describe("Pick leads by attribute. Omit (with no ids) to default to all leads missing an email."),
+      ids: z.array(z.string()).optional().describe("Explicit lead ids — an alternative to filter."),
+      confirm: z.boolean().optional().describe("Omit or false = dry-run cost preview only (spends nothing). true = actually run it as a background job."),
     },
-    async ({ title, keyword, stale_days }) => {
-      if (!title && !keyword) {
-        return { content: [{ type: "text", text: "Pass a title and/or keyword, e.g. title='founder', keyword='agency'." }] };
+    async ({ lead_list_id, filter, ids, confirm }) => {
+      const sel = (ids && ids.length) ? { ids } : { filter: filter || { emailStatus: "none" } };
+      const path = `/api/lead-lists/${encodeURIComponent(lead_list_id)}/enrich`;
+      try {
+        if (!confirm) {
+          const r = await post(path, { ...sel, preview: true });
+          const lines = [
+            `ENRICH PREVIEW — list ${lead_list_id}`,
+            `  ${r.total ?? 0} selected · ${r.chargeable ?? 0} chargeable · ${r.reused ?? 0} already on file (free) · ${r.no_identifier ?? 0} no identifier`,
+            `  provider: ${r.provider || "—"}`,
+            `  estimated cost: ${fmtCost(r.cost)}`,
+            "",
+            r.chargeable
+              ? "Report this to the user. To run it, call enrich_leads again with the same selection and confirm:true."
+              : "Nothing chargeable to enrich.",
+          ];
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        const r = await post(path, { ...sel, background: true });
+        return { content: [{ type: "text", text:
+          `Enrichment started — job ${r.job_id}, ${r.total} lead${r.total === 1 ? "" : "s"} queued. It runs in the background; report back to the user that it's running.` }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: `Couldn't enrich: ${e.message}` }] };
       }
-      const r = await get("/v2/people/coverage", { title, keyword, stale_days });
-      const lines = [
-        `COVERAGE — ${[title && `title~"${title}"`, keyword && `keyword~"${keyword}"`].filter(Boolean).join(" + ")}`,
-        `  ${r.total ?? 0} already in your workspace`,
-        `    ${r.needs_enrichment ?? 0} need (re-)enrichment  (${r.never_enriched ?? 0} never enriched · ${r.stale ?? 0} stale >90d)`,
-        `    ${r.fresh_verified ?? 0} have a fresh verified email`,
-      ];
-      const sample = r.sample || [];
-      if (sample.length) {
-        lines.push("", "SAMPLE (oldest first):");
-        for (const s of sample.slice(0, 12)) {
-          lines.push(`  ${[s.job_title, s.company].filter(Boolean).join(" @ ") || s.entity_id}  [${s.enriched_at ? `enriched ${relAge(s.enriched_at)}` : "never enriched"}]`);
+    }
+  );
+
+  server.tool(
+    "verify_leads",
+    "(Nous Cloud only) Validate email deliverability for leads in a lead list, on the workspace's own MillionVerifier / " +
+    "NeverBounce key. ALWAYS two steps: call WITHOUT confirm for a dry-run cost preview (chargeable count, " +
+    "connected verifiers, $ estimate) — report it to the user — then call again with confirm:true to run as " +
+    "a background job. Defaults to every UNVERIFIED email (has an address, no verdict yet); narrow with " +
+    "`filter` or pass `ids`. If no verifier is connected it says so — tell the user to add a MillionVerifier " +
+    "or NeverBounce key in Integrations.",
+    {
+      lead_list_id: z.string().describe("The lead list's UUID."),
+      filter: z.object(LEAD_FILTER_SHAPE).optional().describe("Pick leads by attribute. Omit (with no ids) to default to all unverified emails."),
+      ids: z.array(z.string()).optional().describe("Explicit lead ids — an alternative to filter."),
+      provider: z.enum(["millionverifier", "neverbounce"]).optional().describe("Which verifier to use. Defaults to MillionVerifier, then NeverBounce."),
+      confirm: z.boolean().optional().describe("Omit or false = dry-run cost preview only. true = actually run it as a background job."),
+    },
+    async ({ lead_list_id, filter, ids, provider, confirm }) => {
+      const sel = (ids && ids.length) ? { ids } : { filter: filter || { emailStatus: "unverified" } };
+      const path = `/api/lead-lists/${encodeURIComponent(lead_list_id)}/verify`;
+      try {
+        if (!confirm) {
+          const r = await post(path, { ...sel, provider, preview: true });
+          const lines = [
+            `VERIFY PREVIEW — list ${lead_list_id}`,
+            `  ${r.total ?? 0} selected · ${r.chargeable ?? 0} chargeable · ${r.reused ?? 0} recently verified (free) · ${r.no_email ?? 0} no email`,
+            `  verifier: ${r.provider || "—"}${r.connected_verifiers ? `  (connected: ${r.connected_verifiers.join(", ") || "none"})` : ""}`,
+            `  estimated cost: ${fmtCost(r.cost)}`,
+            "",
+            r.chargeable
+              ? "Report this to the user. To run it, call verify_leads again with the same selection and confirm:true."
+              : "Nothing chargeable to verify.",
+          ];
+          return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        const r = await post(path, { ...sel, provider, background: true });
+        return { content: [{ type: "text", text:
+          `Verification started — job ${r.job_id}, ${r.total} email${r.total === 1 ? "" : "s"} queued via ${r.provider}. It runs in the background; report back to the user.` }] };
+      } catch (e) {
+        const msg = /no_verifier_connected/.test(e.message)
+          ? "No email verifier is connected. Tell the user to add a MillionVerifier or NeverBounce API key in Integrations, then try again."
+          : `Couldn't verify: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );