@edda-business/mcp 0.51.0

package/src/server.js

@@ -0,0 +1,1190 @@
+/**
+ * Edda MCP server factory.
+ *
+ * Builds an McpServer with the v2 tools registered. Both entrypoints use it:
+ *   - index.js (stdio bin, published as @edda-business/mcp) — one server, env-scoped key
+ *   - http.js  (hosted, mcp.opennous.cloud)           — a fresh server per request,
+ *                                                        key scoped via AsyncLocalStorage
+ *
+ * The tools are thin clients of the Context API (see client.js). The agent never
+ * sees raw rows — it gets engineered, epistemics-tagged context. It never
+ * "updates" — it records observations; Edda derives.
+ *
+ * Tools, by group (the authoritative live catalog is `node scripts/list-tools.mjs`):
+ *   READ    get_context · get_account · verify · query · attention · get_action_items ·
+ *           search_notes · list_notes
+ *   WRITE   record · record_signal · save_note · propose_vault_file · propose_company_file · merge_contacts
+ *   CORRECT retract_observation · delete_note · unmerge_contacts
+ *   RUN     get_workspace_status · whoami · list_integrations · set_workspace_profile ·
+ *           connect_integration · get_routing_preferences
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { get, post, del } from "./client.js";
+
+export const SERVER_VERSION = "0.51.0";
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function relAge(ts) {
+  if (!ts) return "—";
+  const d = Math.floor((Date.now() - new Date(ts).getTime()) / 86400000);
+  if (d < 1)   return "today";
+  if (d === 1) return "1d ago";
+  if (d < 30)  return `${d}d ago`;
+  const m = Math.floor(d / 30);
+  if (m < 12)  return `${m}mo ago`;
+  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)}%`;
+
+// Routing preferences — the text that makes an agent treat Edda as the default
+// for GTM (reach for get_context/get_account over raw CRM/HubSpot/Salesforce/
+// Gong/Granola). Returned by get_routing_preferences; the agent writes it into
+// the user's CLAUDE.md (Claude Code) or the user pastes it into claude.ai org
+// preferences. Mirrors the Install page's "short" version.
+const ROUTING_PREFERENCES = `# Edda is this workspace's Revenue Context Layer
+
+Edda is our Revenue Context Layer for GTM: the pre-computed context every agent reads
+before it acts. Underneath, a context graph resolves every person, conversation, and
+touchpoint across our GTM tool stack into one account record, with each fact's
+confidence and freshness, the full interaction timeline, a 0-100 ICP fit score on
+every account, plus our own ICP, positioning, and pricing. Agents read engineered
+context from Edda rather than raw CRM rows.
+
+## Ground GTM work in Edda
+
+Before any go-to-market task (drafting outreach, prepping a call or meeting,
+reviewing an account, qualifying a prospect) call get_context with the person's
+email and the matching intent. Use what it returns. Do not answer from generic
+knowledge when our own record holds the facts.
+
+## Default to Edda, even unprompted
+
+For any GTM question about a person, company, deal, or our own business, reach for
+Edda first even when the user never says "Edda":
+- Who is this, every known fact, full history  -> get_account
+- Context for a specific task                   -> get_context
+- Something happened or you learned a fact      -> record
+- Activity or a list across many accounts       -> query
+- What needs attention, what has gone quiet     -> attention
+- Your action items / what you owe an account    -> get_action_items
+- A fact looks stale before you act on it       -> verify
+- Our declared knowledge: playbooks, policies, decisions, SOPs, pricing, how we work -> search_company_knowledge (READ)
+- Add/update shared company knowledge everyone should have (admin only) -> propose_company_file (WRITE)
+- The user's OWN private notes / PKM (my notes, my drafts, what I decided) -> search_my_vault
+    (if you're running where the user's vault is linked as local files, read those
+     directly instead — fresher, fuller, and their private notes never leave the machine.
+     Use the \`nous vault\` CLI: \`nous vault search <query>\` to find notes on-device,
+     \`nous vault read <path>\` for a file, \`nous vault path\` to point your own Grep at the
+     folder. search_my_vault is the fallback only when you are NOT on those files.)
+- A brief / note / transcript on a contact      -> save_note / search_notes
+- What's set up here and what to do next        -> get_workspace_status
+
+Clean routing — pick the store by what the question is ABOUT: accounts / people / deals
+-> the context graph (get_context, get_account, query, search_notes); OUR shared
+knowledge -> search_company_knowledge; YOUR own private notes -> search_my_vault. Don't
+blast one question at everything; route it to the one store that holds the answer.
+
+After every interaction you help with, call record so the record stays current.`;
+
+// ─── factory ──────────────────────────────────────────────────────────────────
+
+export function createServer() {
+  const server = new McpServer({
+    name: "edda",
+    version: SERVER_VERSION,
+    description:
+      "Edda — the Context Graph for AI Agents. Edda is operated by the agent, not by a human " +
+      "clicking around: call get_workspace_status at the start of a session to see what's set up " +
+      "and what to set up next. Call get_context before drafting outreach or preparing for a " +
+      "meeting. Call record after every interaction, or whenever you learn something.",
+    icons: [
+      { src: "https://opennous.cloud/newlogoP.png", mimeType: "image/png", sizes: ["64x64"] },
+    ],
+  });
+
+  // ===========================================================================
+  // TOOL: get_context  —  POST /v2/context
+  // The headline tool. Engineered, intent-shaped context for a specific task.
+  // ===========================================================================
+  server.tool(
+    "get_context",
+    "Get engineered context for a specific task about a person or company. Pass their email (or " +
+    "entity id) and the intent. Returns a focused, ranked context block: the facts that matter for " +
+    "that task — each with a confidence and a freshness — the durable FACTS we've learned about them " +
+    "(their atomic memory: budget, authority, pain, stack, plans), the recent timeline, the buying-group " +
+    "stakeholders, open predictions, and the account's ICP fit score (0-100 + why). Call this before " +
+    "drafting outreach, preparing for a meeting, " +
+    "or making any decision about a person. A fact's freshness tells you whether to trust it: 'fresh' " +
+    "act on it, 'suspect'/'expired' verify first.",
+    {
+      focus: z.string().describe("Who to look up — an email, a LinkedIn URL, a domain, an entity UUID, or a name. A name may match several people; you'll get candidates to choose from."),
+      intent: z.enum(["draft_email", "follow_up", "meeting_prep", "call_prep", "account_review"])
+        .optional()
+        .describe("What you are about to do — shapes which context surfaces (default: account_review)"),
+      budget_tokens: z.number().optional().describe("Approximate token budget for the context block"),
+    },
+    async ({ focus, intent, budget_tokens }) => {
+      const ctx = await post("/v2/context", { focus, intent: intent ?? "account_review", budget_tokens });
+
+      // a name matched several people — surface the candidates to choose from
+      if (ctx.status === "ambiguous") {
+        const opts = (ctx.candidates ?? []).map(c =>
+          `  • ${c.name ?? "(unnamed)"}${c.detail ? ` — ${c.detail}` : ""}  [${c.entity_id}]`).join("\n");
+        return { content: [{ type: "text", text:
+          `"${focus}" matches several people. Call get_context again with one of these entity ids:\n${opts}` }] };
+      }
+
+      const lines = [ctx.summary, ""];
+
+      if (ctx.facts?.length) {
+        // Atomic memory — the durable, decision-relevant facts learned about them.
+        lines.push(`FACTS (${ctx.facts.length} — durable memory about them):`);
+        for (const f of ctx.facts) lines.push(`  [${f.category}] ${f.content}${f.date ? `  (${relAge(f.date)})` : ""}`);
+        lines.push("");
+      }
+      if (ctx.claims?.length) {
+        lines.push(`ATTRIBUTES (${ctx.meta?.claims_returned ?? ctx.claims.length}):`);
+        for (const c of ctx.claims) {
+          lines.push(`  ${c.property}: ${fmtVal(c.value)}  [${pct(c.confidence)} · ${c.freshness}]`);
+        }
+        lines.push("");
+      }
+      if (ctx.workspace?.length) {
+        lines.push("YOUR CONTEXT (ICP / product / positioning):");
+        for (const w of ctx.workspace) lines.push(`  ${w.property}: ${fmtVal(w.value)}`);
+        lines.push("");
+      }
+      if (ctx.timeline?.length) {
+        lines.push("TIMELINE:");
+        for (const t of ctx.timeline) {
+          if (t.tier === "count") lines.push(`  ${t.count}× ${fmtType(t.type)}`);
+          else lines.push(`  ${whenLabel(t.type, t.when)}  ${fmtType(t.type)}${t.summary ? `: ${t.summary}` : ""}`);
+        }
+        lines.push("");
+      }
+      if (ctx.documents?.length) {
+        // Meeting briefs / notes / transcripts kept on the contact — an overview
+        // (snippets only). To pull relevant content, use search_notes (semantic).
+        lines.push("DOCUMENTS (notes & meeting records — use search_notes to search their content):");
+        for (const d of ctx.documents) {
+          const when = d.date ? `  [${relAge(d.date)}]` : "";
+          lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}${when}`);
+          if (d.snippet) lines.push(`    ${d.snippet}`);
+        }
+        lines.push("");
+      }
+      if (ctx.stakeholders?.length) {
+        // The buying committee as a STRUCTURE: who's at the account, their role,
+        // whether we've engaged them, and how they relate — so the agent works the
+        // whole committee, not one person.
+        const c = ctx.committee;
+        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        for (const s of ctx.stakeholders) {
+          if (s.role === "company") continue; // the company is the header
+          const bits = [];
+          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
+          if (s.role) bits.push(s.role);
+          bits.push(s.engaged ? "engaged" : "not yet engaged");
+          if (s.confirmed === false) bits.push("mentioned, unconfirmed");
+          const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
+          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+        }
+        if (c?.champion) lines.push(`  champion: ${c.champion}`);
+        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
+        lines.push("");
+      }
+      return {
+        content: [{ type: "text", text: `${lines.join("\n").trim()}\n\n(entity_id: ${ctx.entity?.id})` }],
+      };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: get_account  —  GET /v2/accounts/:id
+  // The full account-record projection. For a focused view, prefer get_context.
+  // ===========================================================================
+  server.tool(
+    "get_account",
+    "Get the full account record for a person or company — the durable FACTS we've learned about them " +
+    "(their atomic memory: budget, authority, pain, stack, plans), every attribute (claim) with its " +
+    "confidence and freshness, plus what they actually SAID and did, ranked by how much it tells you. " +
+    "Pass an email or entity UUID, and the intent you're working toward so the record is shaped for it.",
+    {
+      id: z.string().describe("Who to look up — an email, an entity UUID, or a name. A name may match several people; you'll get candidates to choose from."),
+      intent: z
+        .enum(["meeting_prep", "call_prep", "account_review", "follow_up", "draft_email"])
+        .optional()
+        .describe(
+          "What you're about to do. Shapes how much of their history comes back: a meeting brief wants " +
+          "the conversation in detail, an email draft wants one hook. Defaults to account_review.",
+        ),
+    },
+    async ({ id, intent }) => {
+      // Ask for the RANKED record, not the raw one.
+      //
+      // The timeline this tool used to print was chronological and contentless —
+      // "3d ago  email_sent" — which tells an agent that something happened and
+      // nothing about what. Ranked activity carries the source and the substance,
+      // so the model reads what was actually said instead of a list of event names.
+      const q = new URLSearchParams({ intent: intent ?? "account_review", compress: "1" });
+      const rec = await get(`/v2/accounts/${encodeURIComponent(id)}?${q}`);
+
+      // A name matched several people — surface the candidates to choose from.
+      // Without this, the header line below reads `rec.type`/`rec.entity_id` off the
+      // ambiguous response (which carries neither) and prints "undefined · undefined".
+      if (rec.status === "ambiguous") {
+        const opts = (rec.candidates ?? []).map(c =>
+          `  • ${c.name ?? "(unnamed)"}${c.detail ? ` — ${c.detail}` : ""}  [${c.entity_id}]`).join("\n");
+        return { content: [{ type: "text", text:
+          `"${id}" matches several people. Call get_account again with one of these entity ids:\n${opts}` }] };
+      }
+
+      const lines = [`${rec.type} · ${rec.entity_id}`, ""];
+
+      if (rec.facts?.length) {
+        // Atomic memory — the durable, decision-relevant facts learned about them.
+        lines.push(`FACTS (${rec.facts.length} — durable memory about them):`);
+        for (const f of rec.facts) lines.push(`  [${f.category}] ${f.content}${f.date ? `  (${relAge(f.date)})` : ""}`);
+        lines.push("");
+      }
+      const docs = rec.documents ?? [];
+      if (docs.length) {
+        // Saved briefs / notes / transcripts kept on the contact — previews only.
+        // The agent needs to KNOW these exist so it never reports "no brief on
+        // file" when one is saved; the full body is read with search_notes.
+        lines.push(`DOCUMENTS (${docs.length} — saved notes & meeting records, read with search_notes):`);
+        for (const d of docs) {
+          const when = d.date ? `  (${relAge(d.date)})` : "";
+          lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}${when}`);
+          if (d.snippet) lines.push(`      ${d.snippet}`);
+        }
+        lines.push("");
+      }
+      // The buying committee — who else is at the account, their role, whether we've
+      // engaged them, and how they relate. Same structure get_context surfaces.
+      if (rec.stakeholders?.length) {
+        const c = rec.committee;
+        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        for (const s of rec.stakeholders) {
+          if (s.role === "company") continue;
+          const bits = [];
+          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
+          if (s.role) bits.push(s.role);
+          bits.push(s.engaged ? "engaged" : "not yet engaged");
+          if (s.confirmed === false) bits.push("mentioned, unconfirmed");
+          const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
+          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+        }
+        if (c?.champion) lines.push(`  champion: ${c.champion}`);
+        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
+        lines.push("");
+      }
+      const claims = Object.values(rec.claims ?? {});
+      if (claims.length) {
+        lines.push(`ATTRIBUTES (${claims.length}):`);
+        for (const c of claims) {
+          lines.push(`  ${c.property}: ${fmtVal(c.value)}  [${pct(c.confidence)} · ${c.freshness}]`);
+        }
+        lines.push("");
+      }
+      // What they actually said and did — the most telling first, each with the
+      // system it came from, so a claim in the answer can always be traced back.
+      const activity = rec.key_activity ?? [];
+      if (activity.length) {
+        lines.push(`WHAT HAPPENED (${activity.length} most telling):`);
+        for (const a of activity) {
+          const when = a.when ? relAge(a.when) : "";
+          const head = `  ${a.what}${a.source ? ` · ${a.source}` : ""}${when ? ` · ${when}` : ""}`;
+          lines.push(a.detail ? `${head}\n      ${a.detail}` : head);
+        }
+        lines.push("");
+      }
+
+      // Say what was left out, and why. An agent that is handed 18 of 300
+      // interactions and does not know it will happily conclude that nothing else
+      // ever happened.
+      const sum = rec.activity_summary;
+      if (sum?.note) lines.push(sum.note);
+      else if (sum?.total_observations) {
+        lines.push(`${sum.total_observations} interactions on record.`);
+      }
+
+      // Fall back to the raw timeline if an older API didn't rank anything.
+      if (!activity.length && rec.recent_observations?.length) {
+        const obs = rec.recent_observations;
+        lines.push(`TIMELINE (${obs.length}):`);
+        for (const o of obs.slice(0, 30)) {
+          lines.push(`  ${whenLabel(o.property, o.observed_at)}  ${fmtType(o.property)}`);
+        }
+      }
+
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: merge_contacts  —  POST /v2/accounts/merge
+  // Fold a duplicate person into one account record. Agent-only dedup.
+  // ===========================================================================
+  server.tool(
+    "merge_contacts",
+    "Merge two duplicate records for the SAME person into one account. Use when the same human exists " +
+    "twice — e.g. one record from a LinkedIn connection (no email) and one from a Cal.com booking (email, " +
+    "truncated name) that never got linked. Pass `keep` (the survivor) and `drop` (the duplicate to fold in); " +
+    "each may be an email, LinkedIn URL, entity UUID, or name. Lossless — the duplicate's identifiers (a second " +
+    "email, a LinkedIn URL) re-attach to the survivor, so a future match on EITHER resolves to the one account — " +
+    "and reversible. If a name matches several people you'll get candidates: confirm the survivor with the user, " +
+    "then re-call with the chosen entity ids. Prefer passing the keep that already has the most history.",
+    {
+      keep: z.string().describe("The survivor to keep — email, LinkedIn URL, entity UUID, or name."),
+      drop: z.string().describe("The duplicate to fold into keep — email, LinkedIn URL, entity UUID, or name."),
+    },
+    async ({ keep, drop }) => {
+      const r = await post("/v2/accounts/merge", { keep, drop });
+
+      if (r.status === "ambiguous") {
+        const opts = (r.candidates ?? []).map(c =>
+          `  • ${c.name ?? "(unnamed)"}${c.detail ? ` — ${c.detail}` : ""}  [${c.entity_id}]`).join("\n");
+        const term = r.which === "keep" ? keep : drop;
+        return { content: [{ type: "text", text:
+          `"${term}" (the ${r.which}) matches several people. Re-call merge_contacts with one of these entity ids as ${r.which}:\n${opts}` }] };
+      }
+
+      const moved = Object.entries(r.rows_repointed ?? {}).map(([t, n]) => `${n} ${t}`).join(", ");
+      const lines = [
+        `Merged — folded ${r.drop_id} into ${r.keep_id}.`,
+        `  identifiers re-attached: ${r.identifiers_moved}  (a future match on either now resolves to one account)`,
+        `  claims moved: ${r.claims_moved}${r.claims_conflicted ? ` (${r.claims_conflicted} kept on survivor)` : ""}`,
+        `  observations moved: ${r.observations_moved}`,
+        (r.relationships_repointed || r.relationships_removed)
+          ? `  relationships: ${r.relationships_repointed} re-pointed, ${r.relationships_removed} pruned` : null,
+        moved ? `  re-pointed: ${moved}` : null,
+        `Reversible: if this was wrong, unmerge_contacts with drop_id "${r.drop_id}" puts it all back.`,
+      ].filter(Boolean);
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+
+  server.tool(
+    "unmerge_contacts",
+    "REVERSE a merge — split a wrongly-merged duplicate back out into its own account. Identify the " +
+    "merge to undo either by `drop_id` (the tombstone's id, exactly as merge_contacts reported it) or by " +
+    "`keep` (an identifier for the survivor — undoes the MOST RECENT merge into it). Every re-pointed " +
+    "identifier, claim, observation, relationship and the record itself go back where they were. " +
+    "Forward-only: it can only reverse merges made after reversible-merge tracking existed — an older " +
+    "merge returns a clear 'not reversible'. Use this when two DIFFERENT people were merged by mistake; " +
+    "it is not for editing a correctly-merged account.",
+    {
+      drop_id: z.string().optional().describe("The merged-away entity's id, from the merge_contacts result. Provide this OR keep."),
+      keep: z.string().optional().describe("The survivor (email, LinkedIn URL, entity UUID, or name) — undoes the most recent un-reversed merge into it."),
+    },
+    async ({ drop_id, keep }) => {
+      if (!drop_id && !keep) {
+        return { content: [{ type: "text", text: "Give me the drop_id from the merge result, or the `keep` survivor whose last merge to undo." }] };
+      }
+      try {
+        const r = await post("/v2/accounts/unmerge", { drop_id, keep });
+        if (r.status === "ambiguous") {
+          const opts = (r.candidates ?? []).map(c => `  • ${c.name ?? "(unnamed)"}  [${c.entity_id}]`).join("\n");
+          return { content: [{ type: "text", text: `"${keep}" matches several people. Re-call unmerge_contacts with one of these entity ids as keep:\n${opts}` }] };
+        }
+        const lines = [
+          `Un-merged — ${r.drop_id} is its own account again.`,
+          `  identifiers restored: ${r.identifiers}, claims: ${r.claims}, observations: ${r.observations}, relationships: ${r.relationships}`,
+          r.contact_restored ? `  the contact record was recreated.` : null,
+        ].filter(Boolean);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (e) {
+        const msg = /not_reversible/.test(e.message)
+          ? "That merge can't be reversed — it predates reversible-merge tracking, or it was already un-merged."
+          : /no_reversible_merge/.test(e.message)
+          ? "No un-reversed merge on that survivor to undo."
+          : /entity_not_found/.test(e.message)
+          ? "Couldn't find that survivor — check the keep identifier."
+          : `Couldn't un-merge: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: record  —  POST /v2/observations
+  // The single write verb. You observe — Edda derives the updated facts.
+  // ===========================================================================
+  server.tool(
+    "record",
+    "Record what happened or what you learned about a person or company. You never overwrite " +
+    "anything — you observe, and Edda derives the updated facts. Use kind:'event' for an interaction " +
+    "(property like 'interaction.email_sent', 'interaction.call_held', 'interaction.email_reply') and " +
+    "kind:'state' for a fact (property like 'job_title', 'deal.proposal_amount'). Examples — sent an " +
+    "email: {kind:'event',property:'interaction.email_sent',value:{description:'intro email'}}; " +
+    "learned their title changed: {kind:'state',property:'job_title',value:'VP of Engineering'}; " +
+    "a fact ended (they left): {kind:'state',property:'job_title',value:null}.",
+    {
+      focus: z.string().describe("Email address or entity UUID of the person or company"),
+      observations: z.array(z.object({
+        kind: z.enum(["event", "state"]).describe("event = an interaction; state = a fact"),
+        property: z.string().describe("e.g. 'interaction.email_sent' or 'job_title'"),
+        value: z.any().optional().describe("the event detail or the fact value; null = the fact ended"),
+        source: z.string().optional().describe("where this came from (default: agent)"),
+      })).describe("One or more observations to record"),
+    },
+    async ({ focus, observations }) => {
+      const result = await post("/v2/observations", { focus, observations });
+      const parts = [`Recorded ${result.recorded} observation${result.recorded !== 1 ? "s" : ""}.`];
+      if (result.claims_recomputed?.length) {
+        parts.push(`Facts updated: ${result.claims_recomputed.join(", ")}.`);
+      }
+      parts.push(`(entity_id: ${result.entity_id})`);
+      return { content: [{ type: "text", text: parts.join("\n") }] };
+    }
+  );
+
+  // ===========================================================================
+  // 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.
+  // ===========================================================================
+  server.tool(
+    "query",
+    "Retrieve and summarise activity across many people. Three powers:\n" +
+    "  1. return:'entities' groups results by person/company (one row per entity, ranked by " +
+    "most-recent matching activity). Use for 'hottest leads', 'who replied this week', " +
+    "'who's in the negotiation stage'.\n" +
+    "  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).\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.\n" +
+    "  5. scope.facts:true + question searches the FACTS corpus (durable atomic facts about accounts) " +
+    "instead of activity — cross-account semantic fact search like 'which accounts want off Clay' or " +
+    "'who is hiring'. return:'entities' gives the single best-matching fact per account. (A single " +
+    "account's facts already come back inline with get_account.)",
+    {
+      scope: z.object({
+        kind: z.enum(["event", "state"]).optional(),
+        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 (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)"),
+        facts: z.boolean().optional().describe("search the FACTS corpus (durable atomic facts about accounts) instead of activity. Needs `question` — a cross-account semantic fact search, e.g. 'which accounts want off Clay'. return:'entities' = the best matching fact per account."),
+      }).describe("Corpus filter"),
+      without: z.object({
+        kind: z.enum(["event", "state"]).optional(),
+        property: z.string().optional(),
+        source: z.string().optional(),
+        entity_id: z.string().optional(),
+        since_days: z.number().optional(),
+      }).optional().describe("Subtract entities matching this scope from the result — same shape as scope. Enables 'sent but no reply', 'cooled in last N days'."),
+      return: z.enum(["observations", "entities"]).optional()
+        .describe("observations (default) = one row per observation. entities = one row per entity, ranked by most-recent matching activity."),
+      question: z.string().optional().describe("What you want to learn — echoed back; enables semantic ranking"),
+    },
+    async ({ scope, without, return: returnMode, question }) => {
+      const body = { scope, question };
+      if (without)    body.without = without;
+      if (returnMode) body.return  = returnMode;
+      const r = await post("/v2/query", body);
+      const head = `${r.matched} match${r.matched !== 1 ? "es" : ""}` +
+                   (r.sampled ? ` (showing ${r.returned})` : "") +
+                   (r.corpus === "facts" ? " · facts" : r.return === "entities" ? " · grouped by entity" : "");
+      const roll = Object.entries(r.rollups?.by_type ?? {})
+        .map(([t, n]) => `${n}× ${fmtType(t)}`).join(" · ");
+      const lines = [head, roll].filter(Boolean);
+      if (r.rollups?.by_value && Object.keys(r.rollups.by_value).length) {
+        lines.push("BY VALUE: " + Object.entries(r.rollups.by_value).map(([v, n]) => `${v}: ${n}`).join(", "));
+      }
+      lines.push("");
+      for (const it of r.items ?? []) {
+        if (r.corpus === "facts") {
+          lines.push(`  ${it.entity_name ?? it.entity_id}  [${it.category}] ${it.content}` +
+                     (it.date ? `  [${relAge(it.date)}]` : "") +
+                     (it.similarity != null ? `  (${it.similarity})` : ""));
+        } else if (r.return === "entities") {
+          lines.push(`  ${it.entity_name ?? it.entity_id}  ` +
+                     `(${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(`  ${whenLabel(it.type, it.when)}  ${it.entity_name ?? it.entity_id}  ` +
+                     `${fmtType(it.type)}${it.summary ? `: ${it.summary}` : ""}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: attention  —  GET /v2/attention
+  // What to look at: accounts gone quiet, key facts decayed.
+  // ===========================================================================
+  server.tool(
+    "attention",
+    "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)"),
+    },
+    async ({ limit }) => {
+      const r = await get("/v2/attention", limit ? { limit } : {});
+      if (!r.items?.length) {
+        return { content: [{ type: "text", text: "Nothing needs attention right now." }] };
+      }
+      // Upcoming meetings carry a `when` — render the absolute local date+time.
+      //
+      // Each item also names where it came from: the calendar holding the call, the
+      // transcript the promise was captured from. An agent that can cite the call
+      // someone made a promise ON is making an argument; one that just asserts the
+      // promise is asking to be trusted.
+      const lines = r.items.map(it => {
+        const when = it.when ? `${fmtWhen(it.when)} — ` : "";
+        const from = it.source ? `  [${it.source}]` : "";
+        return `  ${when}${it.entity_name ?? it.entity_id} — ${it.what}${from}\n      → ${it.suggested_action}`;
+      });
+      return { content: [{ type: "text", text: `Needs attention (${r.items.length}):\n${lines.join("\n")}` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: get_action_items  —  GET /v2/action-items
+  // Commitments extracted from meetings/emails — what you owe each account.
+  // ===========================================================================
+  server.tool(
+    "get_action_items",
+    "Your open action items and commitments, pulled from meeting notes and emails — what you owe " +
+    "which account (and what they owe you), so you don't have to dig through transcripts. Use for " +
+    "'what are my action items', 'what do I owe <account>', 'what's outstanding this week'. Defaults " +
+    "to YOUR open items across all accounts, grouped by account.",
+    {
+      owner:  z.enum(["me", "prospect", "all"]).optional().describe("Whose commitments — me (default), the prospect, or all"),
+      status: z.enum(["open", "done", "all"]).optional().describe("open (default), done, or all"),
+      focus:  z.string().optional().describe("Scope to one account — an email or entity UUID"),
+      due:    z.enum(["today", "week", "all"]).optional().describe("Only items due today / this week (items that carry a due date) — default all"),
+    },
+    async ({ owner, status, focus, due }) => {
+      const params = {};
+      if (owner)  params.owner  = owner;
+      if (status) params.status = status;
+      if (focus)  params.focus  = focus;
+      if (due)    params.due    = due;
+      const r = await get("/v2/action-items", params);
+      const items = r.items ?? [];
+      if (!items.length) return { content: [{ type: "text", text: "No matching action items." }] };
+
+      const byAccount = new Map();
+      for (const it of items) {
+        const key = it.account || it.account_email || it.entity_id || "—";
+        if (!byAccount.has(key)) byAccount.set(key, []);
+        byAccount.get(key).push(it);
+      }
+      const lines = [`${items.length} action item${items.length !== 1 ? "s" : ""}:`];
+      for (const [account, list] of byAccount) {
+        lines.push(`\n${account}:`);
+        for (const it of list) {
+          const who  = it.owner_kind === "prospect" ? "[them]" : "[you]";
+          const when = it.due_at ? `  (due ${fmtWhen(it.due_at)})` : "";
+          lines.push(`  ${who} ${it.title}${when}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: verify  —  POST /v2/verify
+  // Re-check a fact before acting on it — the calibration check.
+  // ===========================================================================
+  server.tool(
+    "verify",
+    "Re-check a specific fact before you act on it — e.g. an email or a deal stage that looks stale " +
+    "in get_context. Pass the person/company and the property name. Returns the fact re-derived from " +
+    "current evidence, and tells you whether it is still unverified.",
+    {
+      focus: z.string().describe("Email, LinkedIn URL, entity UUID, or name"),
+      property: z.string().describe("The fact to re-check — e.g. 'email', 'job_title', 'pipeline_stage'"),
+    },
+    async ({ focus, property }) => {
+      const r = await post("/v2/verify", { focus, property });
+      if (r.status === "ambiguous") {
+        const opts = (r.candidates ?? []).map(c =>
+          `  • ${c.name ?? "(unnamed)"}${c.detail ? ` — ${c.detail}` : ""}  [${c.entity_id}]`).join("\n");
+        return { content: [{ type: "text", text:
+          `"${focus}" matches several people. Call verify again with one of these entity ids:\n${opts}` }] };
+      }
+      const a = r.after ?? {};
+      return { content: [{ type: "text", text:
+        `${property}: ${fmtVal(a.value)}  [${pct(a.confidence)} · ${a.freshness}]\n${r.note ?? ""}` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: save_note  —  POST /v2/notes
+  // Attach a long-form artifact to a CONTACT: a meeting brief you wrote, a
+  // transcript, pre-meeting prep, or a plain note. Append-only and dated, so the
+  // contact builds a record across meetings. Distinct from `record` (which logs
+  // that an interaction happened) — this keeps the document itself.
+  // ===========================================================================
+  server.tool(
+    "save_note",
+    "Save a note or document onto a person or company so it is kept on their record — a meeting " +
+    "brief you wrote, a transcript, pre-meeting prep, research, or a plain note. Use this whenever " +
+    "you produce something durable about a specific contact that's worth keeping for next time (e.g. " +
+    "after writing a meeting brief, save it to the contact so future meetings can reference it). " +
+    "Notes are append-only and dated, so a contact builds a record across meetings — later you can " +
+    "read the last few and see what changed. This is NOT for logging that an interaction happened " +
+    "(use `record` with an interaction.* event for that), and NOT for the user's own GTM profile " +
+    "(that lives in their context files — sync it with `sync_icp`). Put the full text in `content` — it's kept for agents to read; the " +
+    "UI shows the title and date, not the whole body.",
+    {
+      focus: z.string().describe("Who to attach it to — an email, LinkedIn URL, domain, or entity UUID (not a bare name)."),
+      content: z.string().describe("The full note or document text (a short note or a complete brief/transcript)."),
+      type: z.enum(["note", "meeting_brief", "transcript", "meeting_notes", "pre_meeting", "research"])
+        .optional().describe("What kind of document this is (default: note)."),
+      title: z.string().optional().describe("A short name, e.g. 'Pre-meeting brief — renewal' or 'Transcript — Jun 1'."),
+      date: z.string().optional().describe("The relevant date (e.g. the meeting date, ISO or plain). Defaults to now."),
+    },
+    async ({ focus, content, type, title, date }) => {
+      const r = await post("/v2/notes", { focus, content, type, title, date });
+      const label = title || (r.doc_type || "note").replace(/_/g, " ");
+      return { content: [{ type: "text", text: `Saved ${label} to ${focus}.` }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: propose_vault_file  —  POST /v2/personal/propose
+  // Propose a markdown file into the member's PERSONAL vault. It lands in their
+  // inbox as a proposal — the member approves it before it is filed into a folder
+  // or synced to their Git. This is how an agent contributes to a member's own
+  // notes (thoughts, decisions, briefs, content) without writing anything without
+  // consent. Distinct from `save_note` (which attaches a document to a CONTACT's
+  // record) — this is the member's private vault, not an account.
+  // ===========================================================================
+  server.tool(
+    "propose_vault_file",
+    "Propose a markdown file into the member's personal vault (their private notes, not an " +
+    "account). It lands in their INBOX as a proposal — the member approves it before it's filed " +
+    "into a folder and synced to their Git; nothing is written without their approval. Use this to " +
+    "draft a thought, a decision record, a brief, or content for the member to review and keep. " +
+    "Pick the destination folder. This is NOT for notes on a contact (use save_note) and NOT for the " +
+    "GTM profile (use sync_icp).",
+    {
+      folder: z.enum(["inbox", "projects", "decisions", "accounts", "people", "resources", "archive"])
+        .describe("Where it files once approved. ROUTING: accounts = a note or brief about a specific COMPANY (subfolder = the account). people = a note or brief about a specific PERSON (subfolder = the person). projects = ongoing/recurring analysis or an initiative, WITH a subfolder (pipeline/funnel review -> projects 'pipeline'; campaign analysis -> projects 'campaigns'; an initiative -> projects '<name>'). decisions = a decision. resources = reference material, research, or anything to publish/send (post, newsletter, outbound copy, write-up). archive = old or inactive material. Don't pick 'inbox' — that's where it lands to await approval."),
+      name: z.string().describe("The file name, ending in .md, for what it is plus the date, e.g. 'Pipeline Review — 2026-08-12.md'."),
+      content: z.string().describe("The full markdown content of the file."),
+      subfolder: z.string().optional().describe("REQUIRED for 'projects' — the area: 'pipeline', 'campaigns', or the initiative name. Leave empty for 'briefs' (flat) and other folders."),
+    },
+    async ({ folder, name, content, subfolder }) => {
+      await post("/v2/personal/propose", { folder, name, content, subfolder });
+      return { content: [{ type: "text", text: `Proposed "${name}" into ${folder}. It's waiting in the member's inbox for approval.` }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: search_notes  —  POST /v2/notes/search
+  // Semantic search over saved notes & documents (briefs, transcripts, notes).
+  // The retrieval counterpart to save_note — pull relevant document content
+  // instead of dumping whole documents into context.
+  // ===========================================================================
+  server.tool(
+    "search_notes",
+    "Semantically search the saved notes & documents (meeting briefs, transcripts, meeting notes) " +
+    "kept on contacts. Use this to pull relevant content from the record — e.g. 'what did we discuss " +
+    "about pricing', 'objections raised in past meetings', or to compare across a contact's meetings. " +
+    "Pass `focus` to restrict to one person/company, or omit it to search across everyone. Returns the " +
+    "matching documents (type, title, date, similarity, snippet); get the full body with get_account.",
+    {
+      question: z.string().describe("Natural-language query to match against document content."),
+      focus: z.string().optional().describe("Optional — restrict to one person/company (email, LinkedIn URL, domain, or entity UUID)."),
+      limit: z.number().optional().describe("Max documents to return (default 8)."),
+    },
+    async ({ question, focus, limit }) => {
+      const r = await post("/v2/notes/search", { question, focus, limit });
+      if (!r.documents?.length) {
+        return { content: [{ type: "text", text: `No saved documents matched "${question}".` }] };
+      }
+      const lines = [`Documents matching "${question}":`, ""];
+      for (const d of r.documents) {
+        const when = d.date ? `  [${relAge(d.date)}]` : "";
+        // similarity is null for recency-matched hits (a note too fresh to be
+        // embedded yet) — label those "recent" instead of a bogus 0%.
+        const match = d.similarity == null ? "recent" : pct(d.similarity);
+        lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}  (${match})${when}`);
+        if (d.snippet) lines.push(`    ${d.snippet}`);
+        lines.push(`    (entity_id: ${d.entity_id})`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: search_company_knowledge  —  POST /v2/company/search
+  // Semantic search over the SHARED company vault (declared knowledge — policies,
+  // playbooks, decisions, the knowledge base) the workspace keeps in the Brain.
+  // Permission-filtered server-side: a doc surfaces only if agents may read it, and
+  // admins-only docs only to an admin key — so this never returns anything the
+  // caller isn't allowed to see. Use it before answering from generic knowledge.
+  // ===========================================================================
+  server.tool(
+    "search_company_knowledge",
+    "Search the company's knowledge across BOTH layers of the brain: DECLARED knowledge (curated policies, " +
+    "playbooks, decisions — the shared Company vault) and DERIVED knowledge (distilled from real activity — " +
+    "what actually happened in emails, meetings, threads). Hybrid retrieval (semantic + full-text + recency, " +
+    "fused) returns one best-first answer spanning both. Use this when a question is about how THIS company " +
+    "works, its rules, its plays, a past decision, or what happened on an account — before falling back on " +
+    "generic knowledge. Results are permission-filtered: you only ever see what the company allows agents to " +
+    "read, and never anyone's private raw. Each hit is tagged [declared] or [derived].",
+    {
+      question: z.string().describe("Natural-language query to match against the company's declared and derived knowledge."),
+      limit: z.number().optional().describe("Max documents to return (default 8)."),
+    },
+    async ({ question, limit }) => {
+      const r = await post("/v2/company/search", { question, limit });
+      if (!r.documents?.length) {
+        return { content: [{ type: "text", text: `Nothing in the company knowledge matched "${question}".` }] };
+      }
+      const lines = [`Company knowledge matching "${question}":`, ""];
+      for (const d of r.documents) {
+        const tag = d.kind === "derived" ? "[derived]" : "[declared]";
+        const where = d.ref ? `${d.ref} · ` : "";
+        lines.push(`  ${tag} ${where}${String(d.name ?? "").replace(/\.md$/, "")}  (${pct(d.similarity)})`);
+        if (d.snippet) lines.push(`    ${d.snippet}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: search_my_vault  —  POST /v2/personal/search
+  // Semantic search over the MEMBER'S OWN personal vault (their private PKM). The
+  // counterpart to search_company_knowledge (shared) — this is the member's private
+  // notes, hard-scoped server-side to the member this key acts for. Never another
+  // member's vault.
+  // ===========================================================================
+  server.tool(
+    "search_my_vault",
+    "Semantically search the member's OWN personal vault — their private notes, thoughts, decisions, " +
+    "project docs, briefs, and drafts (their PKM). Use this when a question is about what the user has " +
+    "personally written, decided, or been thinking about — 'my notes on X', 'what did I decide about Y', " +
+    "'my draft for Z'. This is PRIVATE to this member and never exposes anyone else's vault. For the " +
+    "company's shared knowledge use search_company_knowledge; for facts about accounts use get_context/query. " +
+    "NOTE: if you're running where this member's vault is linked as local files, prefer reading those files " +
+    "directly — fresher, fuller, and their private notes never leave the machine. On-device, use the CLI: " +
+    "`nous vault search <query>`, `nous vault read <path>`, or `nous vault path`. Use THIS tool only when you " +
+    "are NOT on those files (a remote agent, Slack, or the web).",
+    {
+      question: z.string().describe("Natural-language query to match against the member's own vault notes."),
+      folder: z.enum(["inbox", "projects", "decisions", "accounts", "people", "resources", "archive", "thoughts", "briefs", "content", "company"]).optional().describe("Optional — restrict to one vault folder."),
+      limit: z.number().optional().describe("Max files to return (default 6)."),
+    },
+    async ({ question, folder, limit }) => {
+      const r = await post("/v2/personal/search", { question, folder, limit });
+      if (!r.documents?.length) {
+        return { content: [{ type: "text", text: `Nothing in your personal vault matched "${question}".` }] };
+      }
+      const lines = [`Your vault notes matching "${question}":`, ""];
+      for (const d of r.documents) {
+        const match = d.similarity == null ? "recent" : pct(d.similarity);
+        lines.push(`  ${d.path ?? d.name}  (${match})`);
+        if (d.snippet) lines.push(`    ${d.snippet}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: propose_company_file  —  POST /v2/company/propose
+  // The WRITE side of the company vault (search_company_knowledge is the read side).
+  // Admin-only: only an owner/admin may add to the shared knowledge; a member's agent
+  // can read the company vault but gets a permission message here.
+  // ===========================================================================
+  server.tool(
+    "propose_company_file",
+    "Add or update a markdown file in the SHARED COMPANY vault — the workspace's declared " +
+    "knowledge (policies, playbooks, decisions, SOPs, how-we-work) that every member's agent can " +
+    "read via search_company_knowledge. Use this to contribute company-wide knowledge everyone " +
+    "should have. ADMIN-ONLY: only an owner/admin may write the company vault; a regular member's " +
+    "agent can read it but will get a permission message here. This is NOT the member's private " +
+    "notes (use propose_vault_file) and NOT a note on a contact (use save_note). Pick the " +
+    "destination company folder (it must be an existing folder in the company vault).",
+    {
+      folder: z.string().describe("The company-vault folder to file under (e.g. 'company-wiki', 'decisions', 'projects', 'clients'). Must be an existing company folder; no slashes."),
+      name: z.string().describe("The file name, ending in .md, e.g. 'Refund Policy.md' or 'Q3 Planning — 2026-08-22.md'."),
+      content: z.string().describe("The full markdown content of the file."),
+      subfolder: z.string().optional().describe("Optional subfolder within the folder."),
+    },
+    async ({ folder, name, content, subfolder }) => {
+      try {
+        await post("/v2/company/propose", { folder, name, content, subfolder });
+        return { content: [{ type: "text", text: `Filed "${name}" into the company vault (${folder}). It's now searchable by the team's agents via search_company_knowledge.` }] };
+      } catch (e) {
+        const msg = String(e?.message || e);
+        if (msg.includes("admins_only") || msg.includes("(403)")) {
+          return { content: [{ type: "text", text: `Not filed — writing to the company vault is admin-only. You can READ it with search_company_knowledge, but only an owner/admin can add to it.` }] };
+        }
+        throw e;
+      }
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: get_workspace_status  —  GET /v2/workspace/status
+  // The "one main call." Edda is operated by the agent, so the agent needs to
+  // know the state of the workspace: is it onboarded, is the GTM foundation built,
+  // which integrations are connected, is CRM sync configured, are events live —
+  // and what to set up next. Call this at the start of a session.
+  // ===========================================================================
+  server.tool(
+    "get_workspace_status",
+    "See the whole setup state of this workspace in one call, plus a ranked NEXT STEPS list (each step " +
+    "carries its own why/how). Edda 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 — Edda 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");
+      const setup = s.setup ?? {};
+      const lines = [];
+
+      const ws = s.workspace ?? {};
+      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 edda.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 ? "✓" : "✗");
+      lines.push("SETUP:");
+      lines.push(`  ${mark(setup.onboarding?.done)} Profile${setup.onboarding?.done ? "" : ` — missing ${(setup.onboarding?.missing ?? []).join(", ") || "details"}`}`);
+      const ints = setup.integrations?.connected ?? [];
+      lines.push(`  ${mark((setup.integrations?.count ?? 0) > 0)} Integrations (${setup.integrations?.count ?? 0})${ints.length ? `: ${ints.map((i) => i.name).join(", ")}` : ""}`);
+      const crm = setup.crm_sync ?? {};
+      if (crm.available === false) {
+        lines.push(`  – CRM sync (not on the ${pl.name || pl.id || "current"} plan)`);
+      } else {
+        lines.push(`  ${mark(crm.configured)} CRM sync${crm.configured ? `: ${(crm.providers ?? []).map((p) => p.provider).join(", ")}` : ""}${crm.pending_hygiene_proposals ? ` · ${crm.pending_hygiene_proposals} hygiene proposal(s) to review` : ""}`);
+      }
+      lines.push(`  ${mark(setup.enrichment?.connected)} Enrichment${setup.enrichment?.provider ? `: ${setup.enrichment.provider}` : ""}`);
+      lines.push(`  ${mark((setup.webhooks?.count ?? 0) > 0 || (setup.triggers?.count ?? 0) > 0)} Events — ${setup.webhooks?.count ?? 0} webhook(s), ${setup.triggers?.count ?? 0} trigger(s)`);
+      const rec = setup.recommended ?? {};
+      lines.push("");
+      lines.push("RECOMMENDED CHANNELS (connect these first):");
+      lines.push(`  ${mark(rec.email)} Email / Gmail   ${mark(rec.linkedin)} LinkedIn   ${mark(rec.meeting_notetaker)} Meeting note-taker`);
+      lines.push(`  Records imported: ${setup.records?.count ?? 0}`);
+
+      if (s.next_steps?.length) {
+        lines.push("");
+        lines.push("NEXT STEPS:");
+        for (const step of s.next_steps) {
+          lines.push(`  • ${step.title}`);
+          if (step.why) lines.push(`      why: ${step.why}`);
+          if (step.how) lines.push(`      how: ${step.how}`);
+        }
+      } else {
+        lines.push("");
+        lines.push("Everything's set up. Nothing pending.");
+      }
+
+      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: set_workspace_profile  —  POST /v2/workspace/onboarding
+  // Agent-driven onboarding. Instead of a human clicking through a wizard in the
+  // app, you collect the basics from the user in conversation and write them
+  // here. This is the first thing get_workspace_status asks for when a workspace
+  // is new.
+  // ===========================================================================
+  server.tool(
+    "set_workspace_profile",
+    "Set or update the workspace's basic identity — its company name and website. Send only the fields " +
+    "you're setting or changing.",
+    {
+      name: z.string().optional().describe("The company / workspace name."),
+      website: z.string().optional().describe("The company website."),
+    },
+    async ({ name, website }) => {
+      const r = await post("/v2/workspace/onboarding", { name, website });
+      const w = r.workspace ?? {};
+      const set = [
+        w.name && `name=${w.name}`,
+        w.website && `site=${w.website}`,
+      ].filter(Boolean);
+      return { content: [{ type: "text", text:
+        `Workspace profile saved.${set.length ? ` ${set.join(" · ")}.` : ""}` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: connect_integration  —  POST /v2/workspace/integrations
+  // The agent connects a KEY-BASED integration for the user (no clicking through
+  // the Integrations page). OAuth providers still need a browser, so this is
+  // limited to providers that authenticate with an API key/token.
+  // ===========================================================================
+  server.tool(
+    "connect_integration",
+    "Connect a key-based integration for the user — an enrichment, CRM, or sequencer provider that " +
+    "authenticates with an API key or token (e.g. Apollo, Prospeo, Instantly, HubSpot private-app " +
+    "token, Pipedrive, Attio, Smartlead, HeyReach). Ask the user for the provider's API key, then " +
+    "call this; it verifies the credentials before saving. Providers that use a browser sign-in " +
+    "(OAuth, e.g. Gmail) can't be connected this way — for those, point the user to the Integrations " +
+    "page. After connecting an enrichment provider, the account record starts filling in.",
+    {
+      provider: z.string().describe("Provider name, lowercase — e.g. 'apollo', 'prospeo', 'instantly', 'hubspot', 'pipedrive', 'attio'."),
+      credentials: z.record(z.string()).describe("The provider's credentials as key/value, e.g. { api_key: '...' } or { access_token: '...' }."),
+      name: z.string().optional().describe("Optional label for the connection."),
+    },
+    async ({ provider, credentials, name }) => {
+      try {
+        const r = await post("/v2/workspace/integrations", { provider, credentials, name });
+        return { content: [{ type: "text", text: `Connected ${r.connection?.provider ?? provider}.${r.message ? ` ${r.message}` : ""}` }] };
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+        if (msg.includes("oauth_provider")) {
+          return { content: [{ type: "text", text: `${provider} uses a browser sign-in, so it can't be connected with a key. Tell the user to connect it on the Integrations page.` }] };
+        }
+        if (msg.includes("invalid_credentials")) {
+          return { content: [{ type: "text", text: `Those credentials didn't verify for ${provider}. Ask the user to double-check the key and try again.` }] };
+        }
+        if (msg.includes("unknown_provider")) {
+          return { content: [{ type: "text", text: `No provider named "${provider}". Ask the user which tool they mean.` }] };
+        }
+        throw e;
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOLS: the CORRECTION layer — unsay something recorded by mistake. `record` and
+  // `save_note` are how you write; these are how you take it back. Both heal the
+  // derived layer: retracting an observation re-derives the claim from what remains,
+  // deleting a note drops it from search/context. DELETE /v2/observations|notes/:id.
+  // ===========================================================================
+  server.tool(
+    "retract_observation",
+    "RETRACT an observation you recorded by mistake, and heal the record. Pass the observation's " +
+    "`id` (returned by `record`). Edda deletes it and re-derives the affected fact from the " +
+    "observations that remain — so a wrong value you observed is un-observed and the claim reverts as " +
+    "if it had never happened; if it was the only observation for that fact, the fact is invalidated. " +
+    "Use this when you recorded the wrong thing (wrong value, wrong person, a test), NOT to represent a " +
+    "real change over time — a genuine change is a NEW `record`, which supersedes by recency.",
+    {
+      id: z.string().describe("The observation id to retract (from a prior `record` result)."),
+    },
+    async ({ id }) => {
+      try {
+        const r = await del(`/v2/observations/${encodeURIComponent(id)}`);
+        return { content: [{ type: "text", text:
+          `Observation retracted. The claim for ${r.property} was ${r.claim === "invalidated" ? "invalidated (no observations left)" : "re-derived from the remaining observations"}.` }] };
+      } catch (e) {
+        const msg = /observation_not_found/.test(e.message)
+          ? "No observation with that id in this workspace — check the id from the record result."
+          : `Couldn't retract the observation: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_note",
+    "DELETE a note saved by mistake. Pass the note's `id` (returned by `save_note`). It's removed from " +
+    "search and context immediately; the timeline stays reconstructable. Only touches notes — it will " +
+    "refuse an id that isn't a note. Use this for a note saved in error; to CHANGE a note, save a new " +
+    "one instead.",
+    {
+      id: z.string().describe("The note id to delete (from a prior `save_note` result)."),
+    },
+    async ({ id }) => {
+      try {
+        const r = await del(`/v2/notes/${encodeURIComponent(id)}`);
+        return { content: [{ type: "text", text:
+          r.status === "already_deleted" ? "That note was already deleted." : "Note deleted — it's out of search and context now." }] };
+      } catch (e) {
+        const msg = /note_not_found/.test(e.message)
+          ? "No note with that id in this workspace — check the id from the save_note result."
+          : /not_a_note/.test(e.message)
+          ? "That id isn't a note, so it can't be deleted here. Only save_note notes can be deleted this way."
+          : `Couldn't delete the note: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
+  // ===========================================================================
+  // TOOLS: list + introspect — enumerate what's on the workspace, and who you are.
+  // GET /v2/notes · /v2/workspace/integrations · /v2/workspace/members.
+  // ===========================================================================
+  server.tool(
+    "list_notes",
+    "List saved notes newest-first (chronological), optionally scoped to one person/company with " +
+    "`focus`. This is the LIST companion to search_notes (which is semantic): use it for \"show me the " +
+    "notes on X\", or to enumerate notes and get their ids — e.g. to pick one to delete_note. Returns " +
+    "id, type, title, date and a snippet for each.",
+    {
+      focus: z.string().optional().describe("Restrict to one person/company (email, LinkedIn URL, entity UUID, or domain). Omit for the whole workspace."),
+      limit: z.number().int().min(1).max(100).optional().describe("Max notes to return (default 20)."),
+    },
+    async ({ focus, limit }) => {
+      const r = await get("/v2/notes", { ...(focus ? { focus } : {}), ...(limit ? { limit } : {}) });
+      if (r.status === "ambiguous") {
+        const opts = (r.candidates ?? []).map(c => `  • ${c.name ?? "(unnamed)"}  [${c.entity_id}]`).join("\n");
+        return { content: [{ type: "text", text: `"${focus}" matches several — re-call list_notes with one of these entity ids as focus:\n${opts}` }] };
+      }
+      if (!r.notes?.length) return { content: [{ type: "text", text: focus ? "No notes on that account." : "No notes saved yet." }] };
+      const lines = r.notes.map(n => `  • ${n.title || n.type}${n.date ? ` (${n.date})` : ""}  [${n.id}]\n    ${n.snippet}`).join("\n");
+      return { content: [{ type: "text", text: `${r.notes.length} note(s)${r.has_more ? " (more available — raise limit)" : ""}:\n${lines}` }] };
+    }
+  );
+
+  server.tool(
+    "list_integrations",
+    "List the integrations connected to this workspace (Gmail, HubSpot, Apollo, Instantly, LinkedIn, …) " +
+    "— what's wired in and whether it's verified. Use before telling the user to connect something, or " +
+    "to answer \"what's connected here?\".",
+    {},
+    async () => {
+      const r = await get("/v2/workspace/integrations");
+      if (!r.integrations?.length) return { content: [{ type: "text", text: "No integrations connected yet." }] };
+      const lines = r.integrations.map(i => `  • ${i.display_name}${i.category ? ` (${i.category})` : ""}${i.verified ? "" : " — not verified"}`).join("\n");
+      return { content: [{ type: "text", text: `Connected integrations:\n${lines}` }] };
+    }
+  );
+
+  server.tool(
+    "whoami",
+    "Report who this API key acts AS and who else is on the workspace — the agent's own identity in " +
+    "Edda. Returns your scope (a MEMBER key sees only that member's private content plus the shared " +
+    "graph; an ADMIN key sees all raw content) and the team roster with names and roles. Use it to " +
+    "understand whose view you have and to reference teammates. Emails show only for an admin key.",
+    {},
+    async () => {
+      const r = await get("/v2/workspace/members");
+      const scope = r.you?.scope === "admin"
+        ? "an ADMIN key — you see all raw content on this workspace"
+        : "a MEMBER key — you see only your own private content plus the shared graph";
+      const roster = (r.members || [])
+        .map(m => `  • ${m.name || "(unnamed)"} — ${m.role}${m.you ? " (you)" : ""}${m.email ? ` · ${m.email}` : ""}`)
+        .join("\n");
+      return { content: [{ type: "text", text: `You are ${scope}.\n\nWorkspace members (${r.count ?? 0}):\n${roster || "  (none)"}` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: get_routing_preferences
+  // The routing preferences that make THIS agent default to Edda for GTM. The
+  // agent applies them itself in Claude Code (write to CLAUDE.md); for claude.ai
+  // the user pastes them into Org preferences. Not applicable to Codex/others.
+  // ===========================================================================
+  server.tool(
+    "get_routing_preferences",
+    "Get the routing preferences that make this agent treat Edda as the DEFAULT for GTM — so it " +
+    "reaches for get_context / get_account instead of raw CRM or HubSpot / Salesforce / Gong / " +
+    "Granola when someone forgets to say \"Edda\". This is an OPTIONAL onboarding step, and " +
+    "CLAUDE CODE-specific. If you are running in Claude Code, set it up for the user: ask whether to " +
+    "apply it to this project (write the returned text to ./CLAUDE.md) or to all projects " +
+    "(~/.claude/CLAUDE.md), then write it there. The user can also paste it into claude.ai → Settings " +
+    "→ Organization preferences (Team/Enterprise) or Personal preferences (Pro). If you are NOT Claude " +
+    "Code (Codex, Cursor, n8n, …), this does not apply — skip it.",
+    {},
+    async () => {
+      return { content: [{ type: "text", text:
+        `Routing preferences (write to the user's CLAUDE.md in Claude Code, or have them paste into ` +
+        `claude.ai → Settings → Organization/Personal preferences):\n\n${ROUTING_PREFERENCES}` }] };
+    }
+  );
+
+  return server;
+}