@trylighthouse/mcp-server 0.2.3 → 0.2.10

package/README.md

@@ -86,7 +86,7 @@ Records support built-in types (`company`, `person`, `deal`) and custom object t
 
 | Tool | Description |
 |------|-------------|
-| `lighthouse_crm_list_lists` | Get all CRM lists |
+| `lighthouse_crm_list_lists` | Get the CRM lists in your workspace, or find one by its name |
 | `lighthouse_crm_create_list` | Create a new list |
 | `lighthouse_crm_get_list` | Get a single list |
 | `lighthouse_crm_update_list` | Update a list |
@@ -164,6 +164,10 @@ Files and folders live in the workspace, not on a record. Linking one to a recor
 | `lighthouse_workspace_get_user` | Get a workspace user |
 | `lighthouse_workspace_list_teams` | List workspace teams |
 | `lighthouse_workspace_get_team` | Get a workspace team |
+| `lighthouse_workspace_list_webhook_subscriptions` | List your webhook subscriptions (read only) |
+| `lighthouse_workspace_get_webhook_subscription` | Get one of your webhook subscriptions (read only) |
+
+Webhook subscriptions are created and deleted with the REST API or the SDKs, with an API key.
 
 ### Discovery
 
@@ -201,6 +205,10 @@ Files and folders live in the workspace, not on a record. Linking one to a recor
 | `lighthouse_reports_share_dashboard_with_teams` | Share a dashboard with teams |
 | `lighthouse_reports_revoke_dashboard_from_teams` | Revoke team access to a dashboard |
 
+## Rate limits
+
+A `429` with the code `rate_limit_exceeded` is retried for you, up to 4 times, before the tool reports the `429` exactly as the API sent it. Before each retry the server waits at least the seconds in the `Retry-After` header (1 second if there is none, at most 30). Each retry also draws a random wait that can grow with every attempt: up to 2 seconds before the first retry, then up to 4, 8 and 16 (never more than 30), and the server waits the longer of the two. Calls refused at the same moment therefore spread out instead of all coming back together and being refused again. It never starts a retry more than 40 seconds after the first attempt, so the API still has time to answer within the 60 seconds many MCP clients allow for a tool call. When the next wait would end past those 40 seconds, the tool reports the `429` straight away. A tool call your client cancels stops waiting and is not sent again. The API refuses such a request before running it, so a refused attempt changes nothing and only the attempt it accepts is applied. No other error is retried, `credit_limit_exceeded` included, and neither is a limit set by a connected email or LinkedIn account (`rate_limited`).
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/build/api.d.ts

@@ -1,9 +1,34 @@
+export declare const RATE_LIMIT_RETRY: Readonly<{
+    retriesMax: 4;
+    fallbackWaitMs: 1000;
+    waitMaxMs: 30000;
+    backoffBaseMs: 1000;
+    retryWindowMs: 40000;
+}>;
+export declare const RATE_LIMIT_CODE = "rate_limit_exceeded";
+export interface RateLimitRetryOptions {
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+    signal?: AbortSignal;
+}
+export declare function withCallSignal<T>(signal: AbortSignal | undefined, run: () => T): T;
+export declare function callSignalOf(args: unknown[]): AbortSignal | undefined;
+export declare function retryAfterMs(header: string | null | undefined, now?: number): number;
+export declare function backoffCeilingMs(retry: number): number;
+export declare function rateLimitWaitMs(header: string | null | undefined, retry: number, random?: () => number, now?: number): number;
+export declare function isRateLimitRefusal(res: Response): Promise<boolean>;
+export declare function fetchWithRateLimitRetry(send: () => Promise<Response>, options?: RateLimitRetryOptions): Promise<Response>;
 export declare class LighthouseAPI {
     private baseUrl;
     private apiKey;
     private currentTool;
     constructor(apiKey?: string);
     setCurrentTool(toolName: string | null): void;
+    private url;
+    private headers;
+    private query;
+    private send;
     private request;
     get(path: string, params?: Record<string, unknown>): Promise<{
         status: number;
@@ -11,6 +36,15 @@ export declare class LighthouseAPI {
         error: unknown;
         meta?: unknown;
     }>;
+    download(path: string, params: Record<string, unknown> | undefined, maxBytes: number): Promise<{
+        bytes: Buffer<ArrayBuffer>;
+        contentType: string;
+    } | null>;
+    downloadSigned(url: string, maxBytes: number): Promise<{
+        bytes: Buffer<ArrayBuffer>;
+        contentType: string;
+    } | null>;
+    private fetchBytes;
     post(path: string, body?: Record<string, unknown>): Promise<{
         status: number;
         data: unknown;

package/build/api.js

@@ -1,4 +1,103 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 const DEFAULT_BASE_URL = "https://api.trylighthouse.vc";
+export const RATE_LIMIT_RETRY = Object.freeze({
+    retriesMax: 4,
+    fallbackWaitMs: 1_000,
+    waitMaxMs: 30_000,
+    backoffBaseMs: 1_000,
+    retryWindowMs: 40_000,
+});
+export const RATE_LIMIT_CODE = "rate_limit_exceeded";
+const toolCall = new AsyncLocalStorage();
+export function withCallSignal(signal, run) {
+    return toolCall.run({ signal }, run);
+}
+export function callSignalOf(args) {
+    for (let i = args.length - 1; i >= 0; i -= 1) {
+        const arg = args[i];
+        const signal = arg != null && typeof arg === "object" ? arg.signal : undefined;
+        if (signal instanceof AbortSignal)
+            return signal;
+    }
+    return undefined;
+}
+const pause = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
+function cancelled(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    const error = new Error("The tool call was cancelled.");
+    error.name = "AbortError";
+    return error;
+}
+export function retryAfterMs(header, now = Date.now()) {
+    const value = typeof header === "string" ? header.trim() : "";
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value) * 1000;
+    if (/[a-z]/i.test(value)) {
+        const at = Date.parse(value);
+        if (Number.isFinite(at))
+            return Math.max(0, at - now);
+    }
+    return RATE_LIMIT_RETRY.fallbackWaitMs;
+}
+export function backoffCeilingMs(retry) {
+    return Math.min(RATE_LIMIT_RETRY.waitMaxMs, RATE_LIMIT_RETRY.backoffBaseMs * 2 ** retry);
+}
+export function rateLimitWaitMs(header, retry, random = Math.random, now = Date.now()) {
+    const floor = Math.min(retryAfterMs(header, now), RATE_LIMIT_RETRY.waitMaxMs);
+    const draw = Number(random());
+    const spread = Number.isFinite(draw) ? Math.min(Math.max(draw, 0), 1) : 0;
+    return Math.ceil(Math.max(floor, spread * backoffCeilingMs(retry)));
+}
+export async function isRateLimitRefusal(res) {
+    if (res.status !== 429)
+        return false;
+    try {
+        const body = (await res.clone().json());
+        if (body == null || typeof body !== "object")
+            return false;
+        const error = body.error;
+        const code = error != null && typeof error === "object" ? error.code : undefined;
+        return (typeof code === "string" ? code : body.error_code) === RATE_LIMIT_CODE;
+    }
+    catch {
+        return false;
+    }
+}
+export async function fetchWithRateLimitRetry(send, options = {}) {
+    const sleep = options.sleep ?? pause;
+    const random = options.random ?? Math.random;
+    const now = options.now ?? Date.now;
+    const signal = options.signal;
+    const startedAt = now();
+    let res = await send();
+    for (let retry = 1; retry <= RATE_LIMIT_RETRY.retriesMax; retry += 1) {
+        if (signal?.aborted)
+            return res;
+        if (!(await isRateLimitRefusal(res)))
+            return res;
+        const wait = rateLimitWaitMs(res.headers.get("retry-after"), retry, random, now());
+        if (now() - startedAt + wait > RATE_LIMIT_RETRY.retryWindowMs)
+            return res;
+        await res.body?.cancel().catch(() => undefined);
+        await sleep(wait, signal);
+        if (signal?.aborted)
+            throw cancelled(signal);
+        res = await send();
+    }
+    return res;
+}
 export class LighthouseAPI {
     baseUrl;
     apiKey;
@@ -15,9 +114,11 @@ export class LighthouseAPI {
     setCurrentTool(toolName) {
         this.currentTool = toolName;
     }
-    async request(method, path, body) {
+    url(path) {
         const versioned = (/^\/v\d+\//.test(path) || path.startsWith("/mcp/")) ? path : `/v1${path}`;
-        const url = `${this.baseUrl}${versioned}`;
+        return `${this.baseUrl}${versioned}`;
+    }
+    headers() {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
@@ -26,23 +127,56 @@ export class LighthouseAPI {
         if (this.currentTool) {
             headers["X-Lighthouse-MCP-Tool"] = this.currentTool;
         }
-        const res = await fetch(url, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        const json = await res.json();
-        return json;
+        return headers;
     }
-    async get(path, params) {
-        const qs = params
+    query(params) {
+        return params
             ? "?" +
                 Object.entries(params)
                     .filter(([, v]) => v !== undefined && v !== null)
                     .map(([k, v]) => `${k}=${encodeURIComponent(typeof v === "object" ? JSON.stringify(v) : String(v))}`)
                     .join("&")
             : "";
-        return this.request("GET", path + qs);
+    }
+    send(url, init) {
+        const signal = toolCall.getStore()?.signal;
+        const request = signal ? { ...init, signal } : init;
+        return fetchWithRateLimitRetry(() => fetch(url, request), { signal });
+    }
+    async request(method, path, body) {
+        const res = await this.send(this.url(path), {
+            method,
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const json = await res.json();
+        return json;
+    }
+    async get(path, params) {
+        return this.request("GET", path + this.query(params));
+    }
+    async download(path, params, maxBytes) {
+        return this.fetchBytes(this.url(path) + this.query(params), this.headers(), maxBytes);
+    }
+    async downloadSigned(url, maxBytes) {
+        return this.fetchBytes(url, {}, maxBytes);
+    }
+    async fetchBytes(url, headers, maxBytes) {
+        try {
+            const res = await this.send(url, { headers });
+            if (!res.ok)
+                return null;
+            const declared = Number(res.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > maxBytes)
+                return null;
+            const bytes = Buffer.from(await res.arrayBuffer());
+            if (bytes.length > maxBytes)
+                return null;
+            return { bytes, contentType: (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase() };
+        }
+        catch {
+            return null;
+        }
     }
     async post(path, body) {
         return this.request("POST", path, body);

package/build/server.d.ts

@@ -1,2 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function createServer(apiKey?: string): McpServer;
+export interface CreateServerOptions {
+    privateEquity?: boolean;
+}
+export declare function createServer(apiKey?: string, options?: CreateServerOptions): McpServer;

package/build/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { LighthouseAPI } from "./api.js";
+import { LighthouseAPI, callSignalOf, withCallSignal } from "./api.js";
 import { leanDiscovery } from "./leanDiscovery.js";
 function text(data) {
     const failed = data != null && typeof data === "object" && data.error != null;
@@ -29,6 +29,44 @@ function profileSection(res, keys) {
     return { ...envelope, data: section };
 }
 const TRANSCRIPT_WINDOW_CHARS = 40_000;
+const FILE_CONTENT_WINDOW_CHARS = TRANSCRIPT_WINDOW_CHARS;
+const IMAGE_BYTES_MAX = 5 * 1024 * 1024;
+const IMAGE_CONTENT_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+const IMAGE_LIMIT_WORDS = `${IMAGE_BYTES_MAX / (1024 * 1024)} MB`;
+function viewableImageType(res, pick) {
+    if (res == null || typeof res !== "object")
+        return null;
+    const envelope = res;
+    if (envelope.error != null || envelope.data == null || typeof envelope.data !== "object")
+        return null;
+    const data = envelope.data;
+    if (data.kind !== "image")
+        return null;
+    const { contentType, size } = pick(data);
+    const type = typeof contentType === "string" ? contentType.toLowerCase() : "";
+    if (!IMAGE_CONTENT_TYPES.has(type))
+        return null;
+    if (typeof size === "number" && size > IMAGE_BYTES_MAX)
+        return null;
+    return type;
+}
+function textWithImage(res, image, declaredType) {
+    const base = text(res);
+    if (!image)
+        return base;
+    const mimeType = IMAGE_CONTENT_TYPES.has(image.contentType) ? image.contentType : declaredType;
+    return { ...base, content: [...base.content, { type: "image", data: image.bytes.toString("base64"), mimeType }] };
+}
+const FILE_CONTENT_RULES = "kind is pdf, document, spreadsheet, presentation, html, csv, markdown, text or image (null for a kind that cannot be read); pages_total is a PDF's pages or a presentation's slides. " +
+    "A spreadsheet reads as one \"Sheet: <name>\" block per sheet, a row per line with its cells tab separated (a date shows as its stored serial number); a presentation as one \"Slide <n>\" block per slide. " +
+    `A long file comes back in windows of max_chars (default ${FILE_CONTENT_WINDOW_CHARS}): meta.has_more true means the file continues, so pass meta.next_offset_chars as offset_chars to read on, and never treat a window with has_more as the end of the file. ` +
+    "meta.complete false means the file is longer than can be read here and the text stops before its end. " +
+    "When text is null, reason says why (unsupported_type, image, too_large, no_text for a scan or an empty file, unreadable for a damaged or password protected one, timed_out) and note says it in words: relay the note, never guess the content. " +
+    `An image (PNG, JPEG, GIF or WebP up to ${IMAGE_LIMIT_WORDS}) comes back as the image itself after the JSON, so you can look at it. ` +
+    "Older .doc, .xls and .ppt files, archives, audio and video cannot be read.";
+const MEETING_ACCESS_RULE = "The API key's user may read a recorded meeting (its notes and transcript) when they recorded it, were invited to it (as a guest, declined included, or as its organizer), or a teammate who recorded it shares their meeting notes with them; each occurrence of a recurring meeting is judged on its own.";
+const MEETING_KEY_SOURCES = "from a lighthouse_inbox_calendar_meetings row, or from the meeting object of a meeting note read with lighthouse_crm_get_note, lighthouse_crm_list_notes or lighthouse_crm_search_notes";
+const NOTE_MEETING_KEY_RULE = "meeting.meeting_key is the recorded meeting's handle, the same one a lighthouse_inbox_calendar_meetings row carries: when meeting.has_transcript is true, pass it to lighthouse_inbox_calendar_meeting_transcript for what was actually said. meeting.has_transcript and meeting.has_recording are answered for the API key's user: each is true only when that transcript or recording belongs to this note's occurrence and they may read it, which needs no access to the recorder's calendar (their role permitting). A recurring meeting shares one key and keeps only the transcript of its latest recorded occurrence, so the note of an earlier occurrence says false. lighthouse_inbox_calendar_meeting describes that same latest occurrence, so it answers for the key when either flag is true; lighthouse_inbox_calendar_meeting_notes returns the newest notes of that meeting the user may read. The API returns no recording, only whether one exists.";
 const THREAD_MESSAGES_PAGE_DEFAULT = 15;
 const RETIRED_INPUTS = {
     email: "email is no longer a parameter. Use emails, a comma separated list of email addresses.",
@@ -43,18 +81,18 @@ const ADDRESS_INPUT = z.union([
     }),
 ]);
 const RECIPIENTS = z.union([ADDRESS_INPUT, z.array(ADDRESS_INPUT)]);
-export function createServer(apiKey) {
+export function createServer(apiKey, options = {}) {
     const api = new LighthouseAPI(apiKey);
     const server = new McpServer({
         name: "lighthouse",
-        version: "0.2.3",
+        version: "0.2.10",
     });
     const originalRegister = server.registerTool.bind(server);
     server.registerTool = (name, schemaOrConfig, handler) => {
         const wrappedHandler = async (...args) => {
             api.setCurrentTool(name);
             try {
-                return await handler(...args);
+                return await withCallSignal(callSignalOf(args), () => handler(...args));
             }
             finally {
                 api.setCurrentTool(null);
@@ -78,7 +116,8 @@ export function createServer(apiKey) {
         "investors (a company's investors, a read-only multi_record of the GLOBAL DATABASE's companies and people): contains_any, not_contains_any, contains_all, empty, not_empty; the value is a list of investor ids from lighthouse_discovery_search_entities with record_type 'investor', never CRM record ids; " +
         "experience / education (a person's work history and schools, read-only multi_records of the GLOBAL DATABASE's companies and schools): contains_any, not_contains_any, contains_all, empty, not_empty; the value is a list of ids from lighthouse_discovery_search_entities with record_type 'company' (record_type 'school' for education), never CRM record ids; " +
         "domain/email/phone: contains_any, not_contains_any, contains_all, empty, not_empty; " +
-        "list_entries (the record's list memberships; the value is an array of list ids from lighthouse_crm_list_lists, and the list's record_type must be this record type): contains_any, not_contains_any, contains_all, empty, not_empty (empty = in no list, not_empty = in at least one list; both take no value). A custom field can belong to ONE list: lighthouse_crm_list_attributes leaves it out unless you pass that list's list_id, its value sits inside that list's entry under the record's list_entries rather than at the top level, and naming it in a condition or a sort answers 'List not found' when you cannot open the list. A question about the records IN a list with further conditions or an order (\"companies in list X created this month, newest first\") is ONE call: either lighthouse_crm_list_list_records with the same filters and sort, or this search with a list_entries contains_any condition on that list's id beside the other conditions; never read the whole list and narrow it by hand; " +
+        "list_entries (the record's list memberships; the value is an array of list ids from lighthouse_crm_list_lists, and the list's record_type must be the type of the record the condition is on: this record type, or the linked record's type on a dotted path): contains_any, not_contains_any, contains_all, empty, not_empty (empty = in no list, not_empty = in at least one list; both take no value). On a dotted path it filters by the linked records' lists, quantified like every dotted field: associated_people.list_entries contains_any [<people list id>] on a company = the companies with at least one person in that list, associated_people.list_entries empty = the companies none of whose people is in a list, companies with no people included; a custom record-link field works the same way (<link field>.list_entries, the lists of the record type it links to). A custom field can belong to ONE list: lighthouse_crm_list_attributes gives it that list's list_id, it can be set only on a record already in that list, its value sits inside that list's entry under the record's list_entries rather than at the top level, and naming it in a condition or a sort answers 'List not found' when you cannot open the list. A question about the records IN a list with further conditions or an order (\"companies in list X created this month, newest first\") is ONE call: either lighthouse_crm_list_list_records with the same filters and sort, or this search with a list_entries contains_any condition on that list's id beside the other conditions; never read the whole list and narrow it by hand; " +
+        "sequences (people only: the outbound sequences a person is in, a read-only multi_select whose options are the sequences you can open; the value is an array of sequence ids, from that field's options (lighthouse_crm_list_options) or the id of an entry of a person's sequences): contains_any, not_contains_any, contains_all, empty, not_empty (empty = in none of the sequences you can open, not_empty = in at least one of them; both take no value). The id of a sequence you cannot open, or an id that names no sequence, matches no one, so it adds no one to contains_any, makes contains_all match no one and removes no one with not_contains_any. A value that is not a sequence id is refused. On a company or a deal, associated_people.sequences filters by the sequences of its people, quantified like every dotted field (associated_people.sequences contains_any [<sequence id>] = the records with at least one person in that sequence); " +
         "checkbox: eq (value is true or false); " +
         "interaction (first/last email & linkedin interaction, overall interaction-with): eq, neq, empty, not_empty; " +
         "interaction-type (first/last interaction type): contains_any, not_contains_any, empty, not_empty. " +
@@ -100,16 +139,32 @@ export function createServer(apiKey) {
         "Dates have NO range operator, express a window as two conditions (after <start> AND before <end>) in an AND group, computing the bounds from today's date. " +
         "Use the EXACT field keys and option values returned by lighthouse_crm_list_attributes / lighthouse_crm_list_options, never abbreviate or invent them, the chosen values for a select/multi_select condition MUST be a subset of that field's options. If a requested concept has no matching field or option (e.g. a 'competitor'/'portfolio' status that no field actually holds), TELL THE USER rather than dropping the clause or mapping it onto an unrelated field. " +
         "Do NOT use discovery field keys here, CRM fields come from lighthouse_crm_list_attributes. " +
-        "RESPONSE VALIDATION META: this search NEVER fails on a bad filter; instead the response carries, alongside `records`/`total`, three arrays you MUST inspect (collected recursively across nested groups): " +
-        "`ignored_filter_fields` (field keys not recognized; that condition was dropped), " +
+        "RESPONSE VALIDATION META (searching records, and reading a list's records): an unknown field, an operator the field does not take (list_entries included; on a dotted path, the leaf field's) or a group join other than AND/OR does not fail the read; instead the response carries, alongside `records`/`total`, three arrays you MUST inspect (collected recursively across nested groups): " +
+        "`ignored_filter_fields` (field keys not recognised; that condition was dropped), " +
         "`invalid_operators` ([{field, operator}] where the operator is not valid for that field's type; that condition was dropped), and " +
         "`invalid_logical_operators` ([{operator}] where a group's join was not AND/OR; treated as AND). " +
-        "If ANY are non-empty, part of your filter did NOT apply (results are broader/narrower than intended): fix the offending field/operator and retry, or tell the user which clauses could not be applied. A `warnings` array summarizes the same in plain text.";
+        "If ANY are non-empty, part of your filter did NOT apply (results are broader/narrower than intended): fix the offending field/operator and retry, or tell the user which clauses could not be applied. A `warnings` array summarises the same in plain text. " +
+        "A dotted path is judged by its leaf, and only for its operator: a relation, or a linked record's field, that does not exist is in none of these arrays, and that condition matches no record, so take every key of a dotted path from lighthouse_crm_list_attributes of the record type it is on. " +
+        "The saved filters of a view_id are checked the same way, as if you had sent them. " +
+        "A VALUE the field cannot take is never dropped: a date that is neither YYYY-MM-DD nor a rolling period, and every value the field types above say is refused, refuses the whole call with a message that says what is wrong with it.";
+    const SAVED_FILTER_REFUSAL = "A filter the record search would not run as written is refused here with a 400 and nothing is saved: an unknown field, an operator the field does not take (list_entries included; on a dotted path, the leaf field's), a group join other than AND/OR, or a value in the wrong shape, such as a sequence name where sequence ids go.";
+    const DOTTED_PATH_NAMES_UNCHECKED = "On a dotted path only the operator is checked: a relation, or a linked record's field, that does not exist is neither refused nor reported, and that condition matches no record, so take every dotted path's fields from lighthouse_crm_list_attributes of the linked record type.";
+    const LINK_NOT_VIEWABLE_RULE = "A record of a type you cannot view, or of a custom object you cannot open, answers 404 not_found, exactly like an id that does not exist.";
+    const NOTE_CREATE_LINK_RULE = "A record of a type you cannot view answers 404 not_found, exactly like an id that does not exist, and a record of a custom object you cannot open answers 400 invalid_input, exactly like a record type that does not exist.";
+    const TASK_LINKS_PER_TYPE = "Each type you send with at least one id replaces that type's links, and a type you leave out, or send with no ids, keeps them.";
+    const TASK_UNVIEWABLE_LINKS_KEPT = "Links of such a type already on the task are kept as they are.";
+    const UNLINK_NOT_VIEWABLE_KEPT = "A link to a record of a type you cannot view, or of a custom object you cannot open, is left as it is, exactly like an id that is not linked to the note: the call still answers 200 with the note.";
+    const LINKED_RECORDS_LEFT_OUT = "A record of a type you cannot view, or of a custom object you cannot open, is left out.";
+    const ACTIVITY_RELATED_RECORDS_LEFT_OUT = "A record of a type you cannot view, or of a custom object you cannot open, is left out, as if the activity had not touched it.";
+    const REPORT_ROLE_SOURCES = "notes, tasks or a meeting transcript their role does not let them read";
+    const BOARD_GROUPING_RULE = "Kanban views only: the field the board's columns come from. It must be a status or select field stored on the view's records (lighthouse_crm_list_attributes gives each field's data_type), and a list's own field works only on that list's views. A field Lighthouse computes, such as tags, sequences or the first and last interaction type, cannot group a board, and neither can a text, number, date or user field. Any other key is refused with a 400 and nothing is saved, with the message: \"<field>\" cannot group this kanban view. Use a status or select field stored on its records (a list's own field works on that list's views only). Sending the view's current grouped_by back, or leaving it out, is never checked. A table view ignores it.";
+    const SHARE_ALONG_RULE = "Pass share_along: true ONLY when the user asked to share the lists and sequences it filters on as well; a list is shared along only when the user's role can share lists, and a sequence only when it can share sequences. The response always carries shared_along ([{ type, id, name }]) and audience_cannot_open ([{ type, id, name, is_owner, is_parent }]), lists first, then sequences (type list or sequence): for the people it is now shared with, a filter on a list they cannot open is not applied, and a filter on a sequence they cannot open counts it as a sequence nobody is in.";
+    const shareAlongInput = (where) => `Also share the lists and sequences you own that ${where} with the same people. Nothing is shared along unless you pass true.`;
     const CRM_SORT_DESCRIPTION = 'CRM sort array. Format: [{"field":"<key>","direction":"asc"|"desc"}]. ' +
         "Multiple entries sort by the first, then tie-break by the next. " +
         "NOT every field is sortable. A field is sortable ONLY when its type (the `data_type` returned by lighthouse_crm_list_attributes) is one of: " +
         "text, url, number, currency, percentage, rating, date, datetime, datetimez, select, status, user, checkbox, " +
-        "record, record_company_name, record_person_name, record_deal_name, growth, note, duration. " +
+        "record, record_company_name, record_person_name, record_deal_name, record_custom_object_name, growth, note, duration. " +
         "growth (headcount_growth) sorts by ONE window: add \"timeframe\":\"1m\"|\"3m\"|\"6m\"|\"1y\" to the sort item ({\"field\":\"headcount_growth\",\"direction\":\"desc\",\"timeframe\":\"6m\"}; 3m when omitted; an unknown window comes back in invalid_sort_fields). " +
         "note (the notes field) orders by the newest note's date, records without notes last. " +
         "duration (time_in_stage, time_in_status, every time_in_<status field> twin) orders by the time in the current status: asc = fewest days first, records whose status is empty last; the sort item is the plain {\"field\",\"direction\"} with no extra key. " +
@@ -137,7 +192,7 @@ export function createServer(apiKey) {
         "investor_multi_select: contains_any, not_contains_any, contains_all, empty, not_empty " +
         "(value is array of investor UUIDs or objects [{\"id\":\"uuid\",\"label\":\"Name\"}]. Call lighthouse_discovery_search_entities with record_type 'investor' to find investor IDs by name); " +
         "work_experience_multi_select: contains_any, not_contains_any, contains_all, empty, not_empty " +
-        "(value is array of organization UUIDs or objects [{\"id\":\"uuid\",\"label\":\"Name\"}]. Call lighthouse_discovery_search_entities with record_type 'company' to find organization IDs by name); " +
+        "(value is array of organisation UUIDs or objects [{\"id\":\"uuid\",\"label\":\"Name\"}]. Call lighthouse_discovery_search_entities with record_type 'company' to find organisation IDs by name); " +
         "education_multi_select: contains_any, not_contains_any, contains_all, empty, not_empty " +
         "(value is array of institution UUIDs or objects [{\"id\":\"uuid\",\"label\":\"Name\"}]. Call lighthouse_discovery_search_entities with record_type 'school' to find school IDs by name); " +
         "funding_type_multi_select: contains_any, not_contains_any, empty, not_empty; " +
@@ -147,7 +202,7 @@ export function createServer(apiKey) {
         "SPECIAL COMPOUND TYPES, " +
         "signal_select (company_signals): operators contains_any/not_contains_any/contains_all, value is array of signal strings e.g. [\"new_funding_round\",\"growth_headcount\"]; " +
         "signal_select (person_signals): operators contains_any/not_contains_any/contains_all, value is {\"signals\":[\"company_registration\",...],\"registration_countries\":[\"DE\",\"GB\",...],\"signal_dates\":{\"stealth\":\"2024-03-01\"},\"stealth_predicted_areas\":[\"fintech\",...]} " +
-        "(every key besides signals is optional: registration_countries only filters the company_registration signal by country, as UPPERCASE ISO codes, and the country is where the company was registered, and registrations exist only for the countries whose company registers we read (AT, BE, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, LU, PL, PT, SE, SK), so any other country returns no people; " +
+        "(every key besides signals is optional: registration_countries only filters the company_registration signal by country, as UPPERCASE ISO codes, and the country is where the company was registered, and registrations exist only for the countries whose company registers we read, which lighthouse_discovery_list_locations returns as `registration_countries`, so any other country returns no people; " +
         "signal_dates maps a signal to a 'started on/after' ISO date and applies to stealth / out_of_stealth / founded_new_company; " +
         "stealth_predicted_areas refines the stealth signal by predicted category group, same values as person_stealth_predicted_area); " +
         "language_select: operators contains_any/not_contains_any/contains_all, value is {\"languages\":[<ISO 639-1 two-letter codes, e.g. \"en\",\"de\",\"fr\">],\"proficiency\":[<one or more of exactly \"NATIVE_BILINGUAL\",\"EXPERT\",\"ADVANCED\",\"INTERMEDIATE\",\"BASIC\">]} " +
@@ -157,14 +212,14 @@ export function createServer(apiKey) {
         "date ops → ISO date string \"YYYY-MM-DD\". " +
         "The `operator` of a block (the top level OR any group) is \"AND\" or \"OR\" and joins that block's conditions AND its nested groups: \"AND\" = every one must match, \"OR\" = at least one matches. Set the top-level operator to \"OR\" to OR the top-level conditions, or nest a group to mix logic, e.g. (A OR B) AND C = {\"operator\":\"AND\",\"conditions\":[C],\"groups\":[{\"operator\":\"OR\",\"conditions\":[A,B],\"groups\":[]}]}. A worked example with real keys is in the field-key list below. " +
         "company_signals value is a plain array of strings; person_signals value is an object {\"signals\":[...],\"registration_countries\"?:[...],\"signal_dates\"?:{...},\"stealth_predicted_areas\"?:[...]}, these are the only contains_any fields whose value is not a bare array. " +
-        "Use the company_*/person_* keys listed below VERBATIM, do not invent variants (no _usd suffix, no abbreviation like hq for headquarter) and do not use the bare permalinks returned by lighthouse_discovery_list_attributes; any unrecognized key is dropped (the search runs as if that condition were absent) and echoed in the response's `ignored_filter_fields`, so ALWAYS check that array, otherwise a mistyped key returns a result that looks fine but is unfiltered. " +
+        "Use the company_*/person_* keys listed below VERBATIM, do not invent variants (no _usd suffix, no abbreviation like hq for headquarter) and do not use the bare permalinks returned by lighthouse_discovery_list_attributes; any unrecognised key is dropped (the search runs as if that condition were absent) and echoed in the response's `ignored_filter_fields`, so ALWAYS check that array, otherwise a mistyped key returns a result that looks fine but is unfiltered. " +
         "NOT EXPRESSIBLE on this surface (it searches the global database, NOT your CRM): CRM list membership, CRM record owner / unassigned, CRM custom fields, deal stage, role-change dates, and geography finer than country (no US state). If a request needs one of these, apply what you CAN and TELL THE USER which clauses you could not express, do NOT silently drop them or map them onto an unrelated field. " +
         "Do NOT use CRM attribute keys here. The complete set of valid discovery filter keys for this entity is listed at the end of this description. " +
         "RESPONSE VALIDATION META: this search NEVER fails on a bad filter; instead the response carries, alongside `items`/`total`, three arrays you MUST inspect (collected recursively across nested groups): " +
-        "`ignored_filter_fields` (keys not recognized; that condition was dropped), " +
+        "`ignored_filter_fields` (keys not recognised; that condition was dropped), " +
         "`invalid_operators` ([{field, operator}] where the operator is not valid for that field's type; that condition was dropped), and " +
         "`invalid_logical_operators` ([{operator}] where a group's join was not AND/OR; treated as AND). " +
-        "If ANY are non-empty, part of your filter did NOT apply (results are broader than intended): fix the offending field/operator and retry, or tell the user which clauses could not be applied. A `warnings` array summarizes the same in plain text.";
+        "If ANY are non-empty, part of your filter did NOT apply (results are broader than intended): fix the offending field/operator and retry, or tell the user which clauses could not be applied. A `warnings` array summarises the same in plain text.";
     const COMPANY_DISCOVERY_SORT_DESCRIPTION = 'Discovery company sort. Format: {"by":"<field>","dir":"asc"|"desc"}. ' +
         "ONLY two fields are sortable: founded_on (founding date) and total_funding_amount_usd (total funding raised, in USD). " +
         "Omit sort to use the default: relevance score, descending. " +
@@ -182,7 +237,7 @@ export function createServer(apiKey) {
         "Socials: company_linkedin, company_twitter, company_facebook, company_github, company_producthunt (url; matches the profile handle/permalink with text operators). " +
         "Investors (who invested IN this company): company_investor (investor_multi_select; ids from lighthouse_discovery_search_entities record_type 'investor'), company_investor_country (multi_select; list_locations countries), company_investor_region (multi_select; list_locations regions). " +
         "Investments (the company AS an investor; the investments_top_* keys match the investor's TOP-RANKED preference only, e.g. their #1 country, not every investment they ever made): company_is_investor (checkbox; eq true = the company is itself an investor such as a fund or CVC, eq false = exclude investors), company_num_investments (number; total recorded investments), company_investments_top_category (multi_select; list_industries categories), company_investments_top_sdg (multi_select; list_industries sdg_categories), company_investments_top_country (multi_select; list_locations countries), company_investments_top_region (multi_select; list_locations regions), company_investments_top_stage (funding_type_multi_select; lighthouse_discovery_list_funding_types `value`, no_funding not applicable). " +
-        "Team: company_team_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), company_team_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), company_team_experience (multi_select; same values as company_tags), company_team_language (language_select), company_team_language_proficiency (multi_select; use with company_team_language to require a proficiency level), company_team_name_origin (multi_select; list_locations countries), company_team_location_country, company_team_location_region, company_team_work_country, company_team_work_region, company_team_edu_country, company_team_edu_region (multi_select; list_locations). " +
+        "Team: company_team_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), company_team_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), company_team_tags (multi_select; same values as person_tags; matches a company whose current founders or executives carry the tags, and contains_all may be met by different members), company_team_language (language_select), company_team_language_proficiency (multi_select; use with company_team_language to require a proficiency level), company_team_name_origin (multi_select; list_locations countries), company_team_location_country, company_team_location_region, company_team_work_country, company_team_work_region, company_team_edu_country, company_team_edu_region (multi_select; list_locations). " +
         "CRM (filter the global database by YOUR workspace CRM): company_internal_crm_status (checkbox; eq true = already in your CRM, false = not), company_crm_list_entries (multi_select; companies that are in specific CRM company lists, list ids from lighthouse_crm_list_lists), company_crm_deals_list_entries (multi_select; companies whose deals are in specific deal lists), company_crm_team_network (multi_user; companies whose team members are connected to specific workspace users, ids from lighthouse_workspace_list_users), company_crm_team_list_entries (multi_select; companies whose team members are in specific people lists), company_external_crm_status (checkbox; needs a connected external CRM), company_external_crm_lists (multi_select; needs a connected external CRM). " +
         'NESTED-GROUP EXAMPLE for "headcount 10-50 AND (HQ in US or UK) AND raised Series A": ' +
         '{"operator":"AND","conditions":[{"field":"company_headcount","operator":"between","value":{"min":10,"max":50}},{"field":"company_last_funding_type","operator":"contains_any","value":["series_a"]}],"groups":[{"operator":"OR","conditions":[{"field":"company_hq_country","operator":"contains_any","value":["US","GB"]}],"groups":[]}]} ' +
@@ -191,8 +246,8 @@ export function createServer(apiKey) {
         "Basics: person_name (short_text), person_created_at (date). " +
         "Investments (the person AS an investor, e.g. an angel; the investments_top_* keys match the investor's TOP-RANKED preference only, e.g. their #1 country, not every investment they ever made): person_is_investor (checkbox; eq true = only investors, eq false = exclude investors), person_num_investments (number; total recorded investments), person_investments_top_category (multi_select; list_industries categories), person_investments_top_sdg (multi_select; list_industries sdg_categories), person_investments_top_country (multi_select; list_locations countries), person_investments_top_region (multi_select; list_locations regions), person_investments_top_stage (funding_type_multi_select; lighthouse_discovery_list_funding_types `value`, no_funding not applicable). " +
         "Industry: person_current_categories, person_past_categories (multi_select; values from lighthouse_discovery_list_industries → categories), person_current_sdg_impact, person_past_sdg_impact (multi_select; list_industries → sdg_categories). " +
-        "Signals: person_signals (signal_select; value {\"signals\":[...],\"registration_countries\"?:[...],\"signal_dates\"?:{<signal>:\"YYYY-MM-DD\"},\"stealth_predicted_areas\"?:[...]}), person_registration_country (multi_select; filters company_registration signals by country, list_locations countries; the country is where the company was registered, and registrations exist only for the countries whose company registers we read (AT, BE, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, LU, PL, PT, SE, SK), so any other country returns no people). " +
-        "Tags: person_tags (multi_select; values: phd_doctorate, 2nd_time_founder, serial_founder, has_exit, raised_funding, sales_exp, co_exp, eng_exp, ai_and_data_exp, product_exp, hr_exp). " +
+        "Signals: person_signals (signal_select; value {\"signals\":[...],\"registration_countries\"?:[...],\"signal_dates\"?:{<signal>:\"YYYY-MM-DD\"},\"stealth_predicted_areas\"?:[...]}), person_registration_country (multi_select; filters company_registration signals by country, values from lighthouse_discovery_list_locations → registration_countries, the countries whose company registers we read; the country is where the company was registered, so any other country returns no people). " +
+        "Tags: person_tags (multi_select; values: phd_doctorate, master, bachelor, technical, 2nd_time_founder, serial_founder, has_exit, raised_funding, sales_exp, co_exp, eng_exp, ai_and_data_exp, product_exp, hr_exp). " +
         "Language & origin: person_language (language_select), person_language_proficiency (multi_select; use with person_language to require a proficiency level), person_name_origin (multi_select; list_locations countries). " +
         "Current location: person_country (multi_select; UPPERCASE ISO alpha-2 codes e.g. \"US\", \"GB\" from lighthouse_discovery_list_locations → countries), person_region (multi_select; list_locations → regions), person_german_state (multi_select; German federal states). " +
         "Experience: person_past_companies (work_experience_multi_select; ids from lighthouse_discovery_search_entities record_type 'company'), person_education (education_multi_select; ids from lighthouse_discovery_search_entities record_type 'school'), person_experience_start_date, person_experience_end_date (date; matches people with at least one work experience whose start/end date passes the bound, independent of the other experience conditions), person_work_country, person_work_region, person_edu_country, person_edu_region (multi_select; list_locations). " +
@@ -204,13 +259,13 @@ export function createServer(apiKey) {
         "(an outer AND of two OR groups; country codes from list_locations).";
     server.registerTool("lighthouse_crm_list_attributes", {
         title: "List CRM Attributes",
-        description: "Get a lightweight catalog of the fields for a CRM record type: each field's permalink, label, data_type, links_to, read_only, is_custom, has_options, and source_field. " +
+        description: "Get a lightweight catalog of the fields for a CRM record type: each field's permalink, label, data_type, links_to, read_only, is_custom, has_options, source_field and list_id. " +
             "`source_field` names the status attribute a `duration` attribute is derived from (null on every other attribute); such attributes (time_in_stage on deals, time_in_status on tasks, time_in_<status> beside a custom status field) are read-only and computed, never written. " +
             "ALWAYS call this before building filters for search_records / list_records or creating/updating views. Use the exact permalinks it returns. " +
             "To keep the response small it does NOT include select/multi_select option values: when a field has has_options=true, call lighthouse_crm_list_options with that permalink to get its allowed values before filtering or setting it. " +
             "Supports built-in types (company, person, deal, task) and custom objects (use the object's permalink, e.g. 'lp', 'project'). " +
             "When called without record_type, returns all types including custom objects as top-level keys. " +
-            "A custom field that belongs to a single list is left out unless you pass that list's list_id, and a list you cannot open answers 'List not found'. Filtering or sorting on such a field without access to its list answers the same way.",
+            "A custom field that belongs to a single list carries that list's list_id: it can be set only on a record already in that list (add the record with lighthouse_crm_add_to_list first), and its value sits in that list's entry under the record's list_entries. Without list_id every list's fields are listed; passing list_id keeps the fields of every record plus that list's own. A list you cannot open answers 'List not found', and so does filtering or sorting on a field of such a list.",
         inputSchema: {
             record_type: z
                 .string()
@@ -425,7 +480,8 @@ export function createServer(apiKey) {
             "A search by MEANING over people or company records is a semantic_search condition in filters; it needs the ready vector of a saved view (lighthouse_crm_get_view) or of a condition copied from the app, never text and never a vector you wrote (the filters description has the rule). " +
             "NEVER guess field keys, ALWAYS call lighthouse_crm_list_attributes first to get the exact field keys " +
             "for the record_type, then use those keys in your filter conditions. " +
-            "The response's `meta` includes `total` (an integer match count) and `ignored_filter_fields` (any filter key that is not a valid attribute for this record_type, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
+            "The response's `meta` includes `total` (an integer match count), `ignored_filter_fields` (any filter key that is not a valid attribute for this record_type, each with a did_you_mean suggestion when a close match can be computed), `invalid_operators` (a condition whose operator its field does not take, left out), `invalid_logical_operators` (a group joined by something other than AND/OR, read as AND) and `invalid_sort_fields`. Check every array to confirm the whole filter and the sort were applied. " +
+            DOTTED_PATH_NAMES_UNCHECKED + " " +
             "A list_entries condition naming a list you cannot open answers 'List not found', and so does a condition or a sort on a custom field that belongs to such a list: the field is the membership. " +
             "NOT for discovering new companies/people, use lighthouse_discovery_* tools for that.",
         inputSchema: {
@@ -471,7 +527,8 @@ export function createServer(apiKey) {
             "Filter these fields by the signal VALUES (strings). Search results carry the same shape. " +
             "Two more read-only keys on a company: investors ({ company: [{ database_id, crm_id, name, avatar_url, is_lead }], person: [{ database_id, crm_id, first_name, last_name, avatar_url, is_lead }] }: the global database's investors of the company, both keys always present; database_id = the investor's id in the database tools and the value the investors filter takes, crm_id = the workspace's CRM record linked to that investor or null when it is not in the CRM, is_lead = led one of its rounds) and headcount_growth ({ \"1m\", \"3m\", \"6m\", \"1y\" }: the headcount's percent change per window, null when unknown, plus value = the headcount on measured_on; null when the record has no linked profile or no data). " +
             "Two read-only keys on a person: experience and education ([{ database_id, crm_id, name, avatar_url }]: the companies the linked global profile worked at and the schools it studied at, always present, [] without a linked profile; database_id = the id in the database tools and the value the experience / education filters take, crm_id = the workspace's CRM company linked to that company or school, null when it is not in the CRM). " +
-            "A third read-only key on every company, person, deal and custom object record: notes ({ count, last_note_at, notes: [ { id, title, type, created_at, created_by, tags, records, meeting } ] }: the notes linked to the record, the newest five with the author, the kind, the tags, the records they link to (the record itself included) and the meeting details of a meeting note; never the body, which lighthouse_crm_get_note reads; count is every note the caller may see). " +
+            "A third read-only key on every company, person, deal and custom object record: notes ({ count, last_note_at, notes: [ { id, title, type, created_at, created_by, tags, records, meeting } ] }: the notes linked to the record, the newest five with the author, the kind, the tags, the records they link to that you can view (the record itself included) and the meeting details of a meeting note; never the body, which lighthouse_crm_get_note reads; count is every note the caller may see). " +
+            "One more read-only key on a person: sequences ([{ id, name, status, end_reason, current_step, step_count, added_at, started_at, ended_at }]: the outbound sequences the person is in that the API key's user can open, runs still going first, then the most recently added; always present, [] when there are none, or when the user's role cannot view both sequences and people; id = the sequence's id, the value the sequences filter takes; status = the person's own status in that sequence (in_review, ready, active, paused, account_disconnected, completed, stopped, failed, bounced or unsubscribed), never the sequence's; end_reason = why the run ended, a short key such as finished, replied or unsubscribed, null while the run is going; current_step = { number (the step's place, from 1), type (email, linkedin_connection_request or linkedin_message) }, null before the first step or once that step no longer exists; step_count = how many steps the sequence has; added_at, started_at and ended_at are ISO 8601 timestamps, null when unset). " +
             "A read-only duration twin sits beside every status field (time_in_stage on a deal, time_in_status on a task, time_in_<status field> beside a custom status field; lighthouse_crm_list_attributes lists each with its source_field): { days, since } (the whole days the record has held its current status and the ISO timestamp since when), null while the status is empty. " +
             "(Discovery profiles keep their own signals list: one row per feed window with type, created_at, timeframe, percentage_change.)",
         inputSchema: {
@@ -494,6 +551,7 @@ export function createServer(apiKey) {
             "source always has { type, label }: type is app / mobile / api / mcp / workflow / ai_assistant / notetaker / email_sync / calendar_sync / linkedin_sync / inbound_email / inbound_whatsapp / lp_portal / sync, and label names the exact origin. The four trace keys are always present and null when the origin did not record them: workflow is { id, name, run_id, node_id } when a workflow made the change (tracing an entry back to the exact run and step), api_key_id / mcp_tool identify the key or AI tool behind an API change, and trigger is automatic or manual where the origin recorded whether a person asked for the change (meeting notes written on their own and notes a member asked for both log that member as the actor, so trigger is what tells them apart). " +
             "changes[] holds the field edits: { field, label, data_type, is_custom, list, previous, current }, where previous and current are each { value, display }: value is what is stored (an option value, a uuid, a number) and display is the same thing resolved for humans (an option's label, a linked record or user object). Consecutive edits to the same field by the same person on the same day are collapsed into one entry, so previous is the value before the burst and current the value after it. " +
             "Every entry has id, activity_id, action, occurred_at, summary, actor, source, target and changes. One save that changed several fields is reported as one entry per field: id stays unique per entry, activity_id is shared by the entries from that same save.  The five detail keys are on every entry and null on the entries they do not describe: note and task carry that note's / task's body inline (no follow-up call needed), merge carries { merged_record, kept_record }, document carries { type, id, name } for an attached file or folder, and related_records (an empty array when there are none) lists the OTHER records when one activity spanned several (never the entry's own target, which is already under target, and never the record whose feed this is). " +
+            ACTIVITY_RELATED_RECORDS_LEFT_OUT + " " +
             "record_type is company, person, deal, or a custom object permalink; pass task or note to read a task's or note's own history. " +
             "SCOPE: the feed covers records, notes and tasks being created, updated, deleted and merged, plus files and folders being attached. It does NOT record list membership changes or detaching a document, so do not present it to the user as a complete audit trail.",
         inputSchema: {
@@ -518,7 +576,7 @@ export function createServer(apiKey) {
         description: "The AI reports generated on one CRM record (any record type: company, person, deal, or a custom object permalink), newest first: the memos, SWOTs, teardowns, pass memos and briefs a member generated from the record's AI Reports tab in Lighthouse. " +
             "WHEN TO USE: the user asks whether a memo or report already exists on a record, what the last one said, wants to compare or build on an earlier report, or asks about a company's \"memo\" / \"analysis\" / \"write-up\" (check here before writing one from scratch). Not for dashboards or charts (those are lighthouse_reports_*), and nothing here generates a report: that happens in the app. " +
             "Each row: id, name, status (processing / success / error), depth (short / standard / extensive), template, partial (true when the run hit a cap), summary (one paragraph of the report's own prose), created_by ({ id, first_name, last_name, full_name, avatar_url, email }, the same member object every other row carries), created_at, completed_at. Only a success report has a document: read it with lighthouse_crm_get_ai_report. " +
-            "A report quoting a mailbox, calendar, LinkedIn account or file the API key's user cannot read is left out of the list (its author always sees it).",
+            "A report quoting a mailbox, calendar, meeting notes, LinkedIn account or file the API key's user cannot read, or " + REPORT_ROLE_SOURCES + ", is left out of the list (its author always sees it).",
         inputSchema: {
             record_type: z.string().describe("Record type: company, person, deal, or a custom object permalink"),
             record_id: z.string().uuid().optional().describe("Record ID whose reports to list"),
@@ -540,7 +598,7 @@ export function createServer(apiKey) {
         title: "Get AI Report",
         description: "One AI report by id (from lighthouse_crm_list_ai_reports): the same metadata plus record_type / record_id and content, the full document as Markdown with its section headings (citation markers removed). " +
             "WHEN TO USE: the user wants what an earlier memo or report actually says (a section, a number, a recommendation), or a comparison with it. A report can be long: quote or summarise the part the question is about rather than echoing it whole. " +
-            "content is null while the report is still processing or failed. Answers 403 naming the channel when the report draws on a shared mailbox, calendar, LinkedIn account or document the API key's user cannot read, and 404 for an unknown id.",
+            "content is null while the report is still processing or failed. Answers 403 naming the channel when the report draws on a shared mailbox, calendar, meeting notes, LinkedIn account or document the API key's user cannot read, or on " + REPORT_ROLE_SOURCES + " (its author is never refused for its sources), and 404 for an unknown id.",
         inputSchema: {
             id: z.string().uuid().describe("Report ID from lighthouse_crm_list_ai_reports"),
         },
@@ -790,14 +848,17 @@ export function createServer(apiKey) {
     server.registerTool("lighthouse_crm_list_lists", {
         title: "List CRM Lists",
         description: "Get all CRM lists in your workspace. Each list's record_type is 'company', 'person', 'deal', or a custom object permalink (e.g. 'lp', 'project'), and that is the record type of everything in it. " +
-            "Each row carries owner (the member who created it) and is_owner (true when that member is the API key's user), so 'my lists' and 'lists shared with me' can be told apart without a second call.",
+            "Each row carries owner (the member who created it) and is_owner (true when that member is the API key's user), so 'my lists' and 'lists shared with me' can be told apart without a second call. " +
+            "WHEN TO USE: to find a list someone names (\"the Deals Reviewed list\"), pass search with the words of its name and read the id off the matching row, instead of paging through every list; leave search out to page through all of them. meta.total counts the lists that matched.",
         inputSchema: {
+            search: z.string().optional().describe("Only lists whose name contains every one of these words, in any case. A list with a similar name is a different list."),
+            query: z.string().optional().describe("Same as search. Either name works; search wins when both are sent."),
             limit: z.number().min(1).max(100).default(25),
             offset: z.number().min(0).default(0),
         },
     }, async (params) => {
         try {
-            const res = await api.get("/lists", params);
+            const res = await api.post("/lists/search", params);
             return text(res);
         }
         catch (e) {
@@ -860,8 +921,9 @@ export function createServer(apiKey) {
     server.registerTool("lighthouse_crm_list_list_records", {
         title: "List Records in a List",
         description: "Get records in a CRM list with optional filtering, sorting, and view support. " +
-            "Same filter format as search_records. To get valid filter keys, call lighthouse_crm_list_attributes with this list's record_type, which is 'company', 'person', 'deal', or a custom object permalink. " +
-            "The response's `meta` includes `total` (an integer match count), `ignored_filter_fields` (any filter key that is not a valid attribute for this list's record type, each with a did_you_mean suggestion when a close match can be computed) and `invalid_sort_fields` (a sort this list cannot apply, reported rather than refused, so the records come back in their default order). Check both arrays to confirm every filter and sort was actually applied. " +
+            "Same filter format as lighthouse_crm_search_records. To get valid filter keys, call lighthouse_crm_list_attributes with this list's record_type, which is 'company', 'person', 'deal', or a custom object permalink. " +
+            "The response's `meta` includes `total` (an integer match count), `ignored_filter_fields` (any filter key that is not a valid attribute for this list's record type, each with a did_you_mean suggestion when a close match can be computed), `invalid_operators` (a condition whose operator its field does not take, left out of the results), `invalid_logical_operators` (a group joined by something other than AND/OR, read as AND) and `invalid_sort_fields` (a sort this list cannot apply, reported rather than refused, so the records come back in their default order). The saved filters of a view_id are reported on the same way. Check every array to confirm the whole filter and the sort were applied; a value in the wrong shape is refused instead, with a 400. " +
+            DOTTED_PATH_NAMES_UNCHECKED + " " +
             "A list you cannot open answers 'List not found', the same as one that does not exist, and so does a condition or a sort on a custom field that belongs to such a list.",
         inputSchema: {
             list_id: z.string().uuid().optional().describe("List ID"),
@@ -1014,9 +1076,10 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_crm_list_notes", {
         title: "List Notes",
-        description: "Get notes for a CRM record. Each note in the response includes a `records` map, every record (company/person/deal/custom object) the note is currently linked to, plus a `tags` array of any workspace tags attached to the note (each with id, label, color). " +
+        description: "Get notes for a CRM record. Each note in the response includes a `records` map, every record (company/person/deal/custom object) the note is currently linked to that you can view, plus a `tags` array of any workspace tags attached to the note (each with id, label, color). " +
+            LINKED_RECORDS_LEFT_OUT + " " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "Every note also carries `type` ('standard' for a note a member wrote, 'meeting' for meeting notes written from a recorded meeting) and `meeting` (null on a standard note; on a meeting note { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }, where attendees is [{ email, name }] with name possibly null, call_type is a short category from a fixed list such as 'First founder call' or 'Internal discussion', and duration_seconds / ical_uid / attendees are omitted when unknown). Meeting notes are included only when the API key's user can open the meeting's recording.",
+            "Every note also carries `type` ('standard' for a note a member wrote, 'meeting' for meeting notes written from a recorded meeting) and `meeting` (null on a standard note; on a meeting note { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }, where attendees is [{ email, name }] with name possibly null, call_type is a short category from a fixed list such as 'First founder call' or 'Internal discussion', duration_seconds and ical_uid are null when unknown and attendees is [] when there are none). " + NOTE_MEETING_KEY_RULE + " Meeting notes are included only when the API key's user may read the meeting. " + MEETING_ACCESS_RULE,
         inputSchema: {
             record_id: z.string().uuid().describe("Record ID to list notes for"),
             limit: z.number().min(1).max(100).default(25),
@@ -1043,7 +1106,7 @@ export function createServer(apiKey) {
             "type (select: contains_any / not_contains_any ONLY, with an array of \"standard\" and / or \"meeting\"; [\"meeting\"] selects meeting notes written from a recorded meeting, [\"standard\"] the notes members wrote; any other value is rejected). " +
             "An unknown field or invalid operator is rejected with a clear error naming it. " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "Every returned note carries `type` ('standard' | 'meeting') and `meeting` (null on a standard note; on a meeting note { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }; attendees is [{ email, name }] with name possibly null; duration_seconds, ical_uid and attendees are omitted when unknown). Meeting notes are included only when the API key's user can open the meeting's recording.",
+            "Every returned note carries `type` ('standard' | 'meeting') and `meeting` (null on a standard note; on a meeting note { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording }; attendees is [{ email, name }] with name possibly null; duration_seconds and ical_uid are null when unknown and attendees is [] when there are none). " + NOTE_MEETING_KEY_RULE + " Meeting notes are included only when the API key's user may read the meeting. " + MEETING_ACCESS_RULE,
         inputSchema: {
             search: z.string().optional().describe("Free-text search on the note title"),
             filters: z.record(z.any()).optional().describe("CRM-style filter object for notes (see tool description for fields + operators)"),
@@ -1078,7 +1141,7 @@ export function createServer(apiKey) {
             records: z
                 .record(z.array(z.string().uuid()))
                 .optional()
-                .describe("Records to link, keyed by record type. Optional: omit for a standalone note. Any record ids you pass must exist or the call returns a not-found error."),
+                .describe("Records to link, keyed by record type. Optional: omit for a standalone note. Any record ids you pass must exist, or the call answers 404 not_found. " + NOTE_CREATE_LINK_RULE),
             title: z.string().describe("Note title"),
             content: z.string().describe("Note content (plain text or HTML). Use <p> tags for paragraphs. For @mentions, include mention spans (see description)."),
             tagged_users: z
@@ -1101,9 +1164,10 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_crm_get_note", {
         title: "Get Note",
-        description: "Get a single note by ID. Response includes a `records` object keyed by record type (or custom object permalink) with every linked record, plus a `tags` array of any workspace tags attached to the note (each with permalink, label, color). " +
+        description: "Get a single note by ID. Response includes a `records` object keyed by record type (or custom object permalink) with every linked record you can view, plus a `tags` array of any workspace tags attached to the note (each with permalink, label, color). " +
+            LINKED_RECORDS_LEFT_OUT + " " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
-            "`type` is 'standard' for a note a member wrote and 'meeting' for meeting notes written from a recorded meeting; `meeting` is null on a standard note and { title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording } on a meeting note: title and occurred_at come from the meeting itself, attendees is [{ email, name }] with name possibly null, call_type is one of 'First founder call', 'Follow-up founder call', 'Diligence call', 'Re-engagement', 'Portfolio check-in', 'Board meeting', 'Investment committee', 'LP meeting', 'Fundraising call', 'Co-investor or syndication call', 'Internal discussion', 'Hiring or reference call', 'Partnership or vendor call' or 'Other', and duration_seconds / ical_uid / attendees are omitted when unknown. A meeting note is returned only when the API key's user can open the meeting's recording; otherwise it is reported as not found.",
+            "`type` is 'standard' for a note a member wrote and 'meeting' for meeting notes written from a recorded meeting; `meeting` is null on a standard note and { meeting_key, title, occurred_at, duration_seconds, call_type, ical_uid, attendees, has_transcript, has_recording } on a meeting note: title and occurred_at come from the meeting itself, attendees is [{ email, name }] with name possibly null, call_type is one of 'First founder call', 'Follow-up founder call', 'Diligence call', 'Re-engagement', 'Portfolio check-in', 'Board meeting', 'Investment committee', 'LP meeting', 'Fundraising call', 'Co-investor or syndication call', 'Internal discussion', 'Hiring or reference call', 'Partnership or vendor call' or 'Other', duration_seconds and ical_uid are null when unknown, and attendees is [] when there are none. " + NOTE_MEETING_KEY_RULE + " A meeting note is returned only when the API key's user may read the meeting; otherwise it is reported as not found. " + MEETING_ACCESS_RULE,
         inputSchema: {
             note_id: z.string().uuid().optional().describe("Note ID"),
             id: z.string().uuid().optional().describe("Same as note_id, the name this tool has always taken. Send either one."),
@@ -1165,7 +1229,8 @@ export function createServer(apiKey) {
         title: "Link Record to Note",
         description: "Attach a record to an existing note. Call once per record. " +
             "The company/person/deal record_id MUST be an EXISTING CRM record id (an id returned by lighthouse_crm_* tools), NOT a discovery id from lighthouse_discovery_* search results. To link a discovery result, first add it to your CRM and use the resulting CRM record id. " +
-            "Use lighthouse_crm_get_note to see the current set of linked records.",
+            LINK_NOT_VIEWABLE_RULE + " " +
+            "Use lighthouse_crm_get_note to see the current set of linked records (the ones you can view).",
         inputSchema: {
             note_id: z.string().uuid().describe("Note ID"),
             record_type: z.string().describe("Record type: company, person, deal, or a custom object permalink"),
@@ -1183,7 +1248,8 @@ export function createServer(apiKey) {
     server.registerTool("lighthouse_crm_unlink_note_record", {
         title: "Unlink Record from Note",
         description: "Remove a record link from a note. Call once per record. " +
-            "Removing the last linked record is allowed and leaves a standalone note (it stays in the workspace Notes section).",
+            "Removing the last linked record is allowed and leaves a standalone note (it stays in the workspace Notes section). " +
+            UNLINK_NOT_VIEWABLE_KEPT,
         inputSchema: {
             note_id: z.string().uuid().describe("Note ID"),
             record_type: z.string().describe("Record type: company, person, deal, or a custom object permalink"),
@@ -1345,7 +1411,7 @@ export function createServer(apiKey) {
             records: z
                 .record(z.array(z.string().uuid()))
                 .optional()
-                .describe("Records to link, keyed by type: {company: [ids], person: [ids], deal: [ids]}; a custom object's records go under its permalink (e.g. lp: [ids])"),
+                .describe("Records to link, keyed by type: {company: [ids], person: [ids], deal: [ids]}; a custom object's records go under its permalink (e.g. lp: [ids]). " + LINK_NOT_VIEWABLE_RULE),
         },
     }, async (params) => {
         try {
@@ -1359,7 +1425,7 @@ export function createServer(apiKey) {
     server.registerTool("lighthouse_crm_update_task", {
         title: "Update Task",
         description: "Update a CRM task. Provide only fields you want to change. " +
-            "assigned_to replaces all current assignees. records replaces all linked records. " +
+            "assigned_to replaces all current assignees. In records, " + TASK_LINKS_PER_TYPE.charAt(0).toLowerCase() + TASK_LINKS_PER_TYPE.slice(1) + " " +
             "Status values are configured per workspace and are NOT fixed: call lighthouse_crm_list_options with record_type 'task' and permalink 'status' to get the allowed values, then pass the option's value (not its label) in `status`. " +
             "status and priority answer the stored VALUE and nothing else. The words your workspace puts on those values come from lighthouse_crm_list_options(record_type:'task', permalink:'status' | 'priority'), one call that covers every task you will ever read.",
         inputSchema: {
@@ -1376,7 +1442,7 @@ export function createServer(apiKey) {
             records: z
                 .record(z.array(z.string().uuid()))
                 .optional()
-                .describe("Records to link (replaces current), keyed by type: {company: [ids], person: [ids], deal: [ids]}; a custom object's records go under its permalink (e.g. lp: [ids])"),
+                .describe("Records to link, keyed by type: {company: [ids], person: [ids], deal: [ids]}; a custom object's records go under its permalink (e.g. lp: [ids]). " + TASK_LINKS_PER_TYPE + " " + LINK_NOT_VIEWABLE_RULE + " " + TASK_UNVIEWABLE_LINKS_KEPT),
         },
     }, async (params) => {
         try {
@@ -1575,7 +1641,7 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_documents_get_file", {
         title: "Get File",
-        description: "Get file metadata. Response includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_records[] and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). Pass download_url=true to also receive a short-lived signed read URL (expires in 15 minutes).",
+        description: "Get file metadata. Response includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_records[] and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). Pass download_url=true to also receive a short-lived signed read URL (expires in 15 minutes). To read what the file SAYS, use lighthouse_documents_get_file_content.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
             download_url: z.boolean().optional().describe("Include a short-lived signed download URL"),
@@ -1590,6 +1656,39 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    server.registerTool("lighthouse_documents_get_file_content", {
+        title: "Read File",
+        description: "What one stored file SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
+            "WHEN TO USE: the answer is inside a document the workspace keeps (\"what are the conditions in the term sheet\", \"summarise the memo on this deal\", \"what does the deck say about revenue\"). " +
+            "Take the file id from lighthouse_documents_list or lighthouse_documents_list_for_record. " +
+            "Returns the file's row (the one lighthouse_documents_get_file returns: id, name, folder_id, size_bytes, content_type, sharing, owner, ...) followed by kind, pages_total, text, reason and note. " +
+            FILE_CONTENT_RULES +
+            " A file the user may not open answers forbidden, one that does not exist not found.",
+        inputSchema: {
+            file_id: z.string().uuid().optional().describe("File UUID. The name every other file tool takes."),
+            id: z.string().uuid().optional().describe("Same as file_id. Send either one."),
+            offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
+            max_chars: z.number().min(1).default(FILE_CONTENT_WINDOW_CHARS).describe("Characters per window"),
+        },
+    }, async (params) => {
+        try {
+            const fileId = requireId(params.file_id, params.id, "file_id");
+            const res = await api.get(`/v1/documents/files/${fileId}/content`, {
+                offset_chars: params.offset_chars,
+                max_chars: params.max_chars,
+            });
+            const imageType = viewableImageType(res, (data) => ({ contentType: data.content_type, size: data.size_bytes }));
+            if (!imageType)
+                return text(res);
+            const signed = await api.get(`/v1/documents/files/${fileId}`, { download_url: "1" });
+            const url = signed?.data?.download_url;
+            const image = typeof url === "string" ? await api.downloadSigned(url, IMAGE_BYTES_MAX) : null;
+            return textWithImage(res, image, imageType);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     server.registerTool("lighthouse_documents_update_file", {
         title: "Update File",
         description: "Rename, move, or change sharing on a file. Editors can rename/move-between-folders and delete; only the owner can move to root, change sharing, or grant team access. " +
@@ -1721,14 +1820,15 @@ export function createServer(apiKey) {
             "To change sharing settings, use lighthouse_crm_update_view_sharing instead. " +
             "Uses CRM filter format, call lighthouse_crm_list_attributes first if modifying filters. " +
             "A semantic_search condition in the new filters must carry its vector (keep the one the view already has, from lighthouse_crm_get_view, or one copied from the app): this API never builds an embedding from text. " +
-            "Every key is optional and a key you leave out keeps the value the view already has, the board settings included, so changing a filter never reopens the columns someone collapsed.",
+            "Every key is optional and a key you leave out keeps the value the view already has, the board settings included, so changing a filter never reopens the columns someone collapsed. " +
+            SAVED_FILTER_REFUSAL + " " + DOTTED_PATH_NAMES_UNCHECKED,
         inputSchema: {
             id: z.string().uuid().describe("View ID"),
             name: z.string().optional(),
             filters: z.record(z.unknown()).optional().describe(CRM_FILTER_DESCRIPTION),
             sort: z.array(z.record(z.unknown())).optional().describe(CRM_SORT_DESCRIPTION),
             view_type: z.enum(["table", "kanban"]).optional(),
-            grouped_by: z.string().optional().describe("Field key to group by (required for kanban views)"),
+            grouped_by: z.string().optional().describe(BOARD_GROUPING_RULE),
             hidden_kanban_groups: z
                 .array(z.unknown())
                 .nullable()
@@ -1860,6 +1960,47 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    const WEBHOOK_SUBSCRIPTION_SHAPE = "Each subscription: id, url, record_type, events ('record.created' and/or 'record.updated'), header_names (the names of the custom headers sent with every delivery, never their values), description, " +
+        "status ('active' or 'disabled'), disabled_reason (null, 'endpoint_gone' when the address answered 410 Gone, 'failing' after many failed tries in a row, 'access_lost' when the owner lost developer access or access to the record type), disabled_at, " +
+        "last_delivery (null before the first try, else { attempted_at, status: 'delivered' or 'failed', response_status }), owner (the member it belongs to), created_at and updated_at. The signing secret is never returned.";
+    const WEBHOOK_SUBSCRIPTION_WRITES = "This tool only reads: creating and deleting webhook subscriptions is done with the REST API (POST /v1/webhook-subscriptions and DELETE /v1/webhook-subscriptions/{id}) or the SDKs, with an API key, and a subscription can also be deleted in the app, under Settings > Developer > Webhook Subscriptions. A turned-off subscription is not turned back on: delete it and create a new one.";
+    server.registerTool("lighthouse_workspace_list_webhook_subscriptions", {
+        title: "List Webhook Subscriptions",
+        description: "List the webhook subscriptions of the user this key acts as (only their own), newest first, active and turned off alike: each one sends a signed POST to its url whenever a record of its record_type is created or updated. " +
+            WEBHOOK_SUBSCRIPTION_SHAPE + " " +
+            "WHEN TO USE: \"which webhooks do I have\", \"where are our company updates being sent\", \"why did our integration stop receiving changes\" (read status, disabled_reason and last_delivery). " +
+            "Needs a role with developer access. " + WEBHOOK_SUBSCRIPTION_WRITES,
+        inputSchema: {
+            limit: z.number().min(1).max(100).default(25),
+            offset: z.number().min(0).default(0),
+        },
+    }, async (params) => {
+        try {
+            const res = await api.get("/webhook-subscriptions", params);
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("lighthouse_workspace_get_webhook_subscription", {
+        title: "Get Webhook Subscription",
+        description: "Get one of the webhook subscriptions of the user this key acts as, by id. " +
+            WEBHOOK_SUBSCRIPTION_SHAPE + " " +
+            "WHEN TO USE: \"is that webhook still on\", \"when did it last deliver\", for one subscription whose id you already have (from lighthouse_workspace_list_webhook_subscriptions). " +
+            "Another member's subscription is not found, the same as an id that does not exist. Needs a role with developer access. " + WEBHOOK_SUBSCRIPTION_WRITES,
+        inputSchema: {
+            id: z.string().uuid().describe("Webhook subscription ID"),
+        },
+    }, async (params) => {
+        try {
+            const res = await api.get(`/webhook-subscriptions/${params.id}`);
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     server.registerTool("lighthouse_discovery_list_attributes", {
         title: "List Discovery Data Fields",
         description: "Get a lightweight catalog of the DATA FIELDS discovery results carry for companies or people: each field's permalink, label, data_type, links_to, read_only, and has_options. " +
@@ -1919,7 +2060,7 @@ export function createServer(apiKey) {
             "3) For location filters (company_hq_country, company_hq_region, and any other *_country/*_region key), call lighthouse_discovery_list_locations to get country/region codes. " +
             "4) For investor/past-company/education filters, call lighthouse_discovery_search_entities (record_type 'investor', 'company', or 'school') to resolve names to ids. " +
             "The COMPLETE, authoritative list of company_* filter keys (every field with its data type and where its values come from) is at the END of the `filters` parameter description below. Read it and use those keys exactly; do not anchor on a subset, invent variants (no _usd suffix), or abbreviate (hq vs headquarter). " +
-            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognized, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied." +
+            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognised, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied." +
             DISCOVERY_CRM_ID_NOTE,
         inputSchema: {
             filters: z
@@ -1949,7 +2090,7 @@ export function createServer(apiKey) {
             "3) For location filters (person_country, person_region, and any other *_country/*_region key), call lighthouse_discovery_list_locations to get country/region codes. " +
             "4) For past-company/education filters, call lighthouse_discovery_search_entities (record_type 'company' or 'school') to resolve names to ids. " +
             "The COMPLETE, authoritative list of person_* filter keys (every field with its data type and where its values come from) is at the END of the `filters` parameter description below. Read it and use those keys exactly; do not anchor on a subset, invent variants, or abbreviate. " +
-            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognized, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
+            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognised, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
             "People results are returned by founder relevance; custom sorting is NOT supported for people, so there is no sort parameter." +
             DISCOVERY_CRM_ID_NOTE,
         inputSchema: {
@@ -1976,7 +2117,7 @@ export function createServer(apiKey) {
             "You CAN combine it with structured filters: pass `filters` using the same company_* keys as lighthouse_discovery_search_companies and they apply together (semantic match AND your filters), e.g. semantically-similar companies that are ALSO headquartered in Germany. " +
             "PREFER lighthouse_discovery_search_companies (no `query`) when the user only needs exact attribute filters (a specific country, funding stage, headcount range) with no conceptual component. " +
             "If the user asks for something this cannot satisfy (an exact field the database does not expose, a guarantee of completeness, or ordering by a specific metric), tell them that plainly and fall back to lighthouse_discovery_search_companies with filters rather than guessing. " +
-            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognized, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
+            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognised, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
             "`query` is required; everything else is optional." +
             DISCOVERY_CRM_ID_NOTE,
         inputSchema: {
@@ -2010,7 +2151,7 @@ export function createServer(apiKey) {
             "You CAN combine it with structured filters: pass `filters` using the same person_* keys as lighthouse_discovery_search_people and they apply together (semantic match AND your filters), e.g. semantically-similar people who are ALSO based in the UK. " +
             "PREFER lighthouse_discovery_search_people (no `query`) when the user only needs exact attribute filters with no conceptual component. " +
             "If the user asks for something this cannot satisfy (an exact field the database does not expose, a guarantee of completeness, or ordering by a specific metric), tell them that plainly and fall back to lighthouse_discovery_search_people with filters rather than guessing. " +
-            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognized, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
+            "The response's `meta` includes `total` (the match count, e.g. \"247\", or \"1k+\" when there are 1000+) and `ignored_filter_fields` (any filter key that was NOT recognised, each with a did_you_mean suggestion when a close match can be computed). Check `ignored_filter_fields` to confirm every filter was actually applied. " +
             "`query` is required; everything else is optional." +
             DISCOVERY_CRM_ID_NOTE,
         inputSchema: {
@@ -2150,9 +2291,11 @@ export function createServer(apiKey) {
         description: "Get available location options (countries and regions) for discovery filters. " +
             "ALWAYS call this to get valid country/region values before filtering by location fields " +
             "(company_hq_country, company_hq_region, person_country, person_region, company_investor_country, etc.). " +
-            "Returns {countries: [{name, value, flag}], regions: [{name, value, flag}]}. " +
+            "Returns {countries: [{name, value, flag}], regions: [{name, value, flag}], registration_countries: [{name, value, flag}]}. " +
             "Use 'value' (alpha-2 codes for countries e.g. 'DE' for Germany, IDs for regions) " +
-            "in filter conditions with contains_any/not_contains_any operators.",
+            "in filter conditions with contains_any/not_contains_any operators. " +
+            "registration_countries are the countries whose company registers we read: the only values that can match person_registration_country " +
+            "and the registration_countries of the company_registration person signal, so any other country returns no people.",
         inputSchema: {},
     }, async () => {
         try {
@@ -2520,8 +2663,7 @@ export function createServer(apiKey) {
         title: "Update Dashboard",
         description: "Update a dashboard's name, description, or sharing. Only the dashboard owner can update. " +
             "Returns the full dashboard object (same format as get dashboard), plus shared_along and audience_cannot_open. " +
-            "Pass share_along: true ONLY when the user asked to share the lists as well; a list is shared along only when " +
-            "the user's role can share lists. The response always carries shared_along and audience_cannot_open.",
+            SHARE_ALONG_RULE,
         inputSchema: {
             id: z.string().uuid().describe("Dashboard ID"),
             name: z.string().optional().describe("New dashboard name"),
@@ -2530,7 +2672,7 @@ export function createServer(apiKey) {
             share_along: z
                 .boolean()
                 .optional()
-                .describe("Also share the lists you own that this dashboard's widgets filter on with the same people. Nothing is shared along unless you pass true."),
+                .describe(shareAlongInput("this dashboard's widgets filter on")),
         },
     }, async (params) => {
         try {
@@ -2581,6 +2723,8 @@ export function createServer(apiKey) {
             "2) Build a config object using those keys, 3) Create the widget. " +
             "Widget types: bar, line, pie, table, kpi, funnel, area. " +
             "Report types: standard (aggregate by field), funnel (pipeline conversion), stage_changes (historical transitions). " +
+            "The config's filter (and the older flat filters) uses the CRM filter format of lighthouse_crm_search_records, on the widget's record type. " +
+            SAVED_FILTER_REFUSAL + " " + DOTTED_PATH_NAMES_UNCHECKED + " " +
             "Returns: {id, name, widget_type, config, created_at, updated_at}.",
         inputSchema: {
             dashboard_id: z.string().uuid().describe("Dashboard ID to add widget to"),
@@ -2663,15 +2807,14 @@ export function createServer(apiKey) {
         description: "Grant team-level access to a dashboard. Only the dashboard owner can share. " +
             "Use lighthouse_workspace_list_teams to find team IDs first. " +
             "Requires reports.edit permission. " +
-            "Pass share_along: true ONLY when the user asked to share the lists as well; a list is shared along only when " +
-            "the user's role can share lists. The response always carries shared_along and audience_cannot_open.",
+            SHARE_ALONG_RULE,
         inputSchema: {
             id: z.string().uuid().describe("Dashboard ID"),
             team_ids: z.array(z.string().uuid()).describe("Array of team UUIDs to grant access to"),
             share_along: z
                 .boolean()
                 .optional()
-                .describe("Also share the lists you own that this dashboard's widgets filter on with the same people. Nothing is shared along unless you pass true."),
+                .describe(shareAlongInput("this dashboard's widgets filter on")),
         },
     }, async (params) => {
         try {
@@ -2707,15 +2850,14 @@ export function createServer(apiKey) {
             "Use lighthouse_workspace_list_teams to find team IDs first. " +
             "Requires views.share permission. " +
             "Returns formatted view: {id, name, record_type, list_id, view_type, filters, sort, grouped_by, sharing, owner, is_owner, shared_with_teams, created_at, shared_along, audience_cannot_open}, where is_owner says whether the API key's user owns the view. " +
-            "Pass share_along: true ONLY when the user asked to share the lists as well; a list is shared along only when " +
-            "the user's role can share lists. The response always carries shared_along and audience_cannot_open.",
+            SHARE_ALONG_RULE,
         inputSchema: {
             id: z.string().uuid().describe("View ID"),
             team_ids: z.array(z.string().uuid()).describe("Array of team UUIDs to grant access to"),
             share_along: z
                 .boolean()
                 .optional()
-                .describe("Also share the lists you own that this view filters on with the same people. Nothing is shared along unless you pass true."),
+                .describe(shareAlongInput("this view filters on")),
         },
     }, async (params) => {
         try {
@@ -2751,15 +2893,14 @@ export function createServer(apiKey) {
         description: "Change a CRM view or list view's sharing visibility. Setting to 'private' also removes all team permissions. " +
             "Automatically detects view type. Only the view owner can change sharing. Requires views.share permission. " +
             "Returns formatted view: {id, name, record_type, list_id, view_type, filters, sort, grouped_by, sharing, owner, is_owner, shared_with_teams, created_at, shared_along, audience_cannot_open}, where is_owner says whether the API key's user owns the view. " +
-            "Pass share_along: true ONLY when the user asked to share the lists as well; a list is shared along only when " +
-            "the user's role can share lists. The response always carries shared_along and audience_cannot_open.",
+            SHARE_ALONG_RULE,
         inputSchema: {
             id: z.string().uuid().describe("View ID"),
             sharing: z.enum(["private", "workspace"]).describe("New sharing visibility"),
             share_along: z
                 .boolean()
                 .optional()
-                .describe("Also share the lists you own that this view filters on with the same people. Nothing is shared along unless you pass true."),
+                .describe(shareAlongInput("this view filters on")),
         },
     }, async (params) => {
         try {
@@ -2868,7 +3009,7 @@ export function createServer(apiKey) {
             "body (the full HTML, null when there is none), reply_to_message_id (the message this one answers, when the mailbox states it), " +
             "is_read, is_starred, attachments [{ id, message_id, type (image | video | audio | file | other), filename, content_type, size }], " +
             "inline_images (the files embedded in the body: the same keys plus cid), account { id, name, email, is_owner } }. Every key is always present. " +
-            "Read text when you need what was said and body only when the markup matters. " +
+            "Read text when you need what was said and body only when the markup matters. To read what an attached file SAYS, pass its id, its message_id and the message's account.id to lighthouse_inbox_email_attachment. " +
             "When the user can see only the metadata of that account, text and body are null, both file lists are empty and data.has_limited_access is true (false otherwise). Thread ids are " +
             "account-specific: BOTH thread_id AND account_id (the thread row's account.id from " +
             "lighthouse_inbox_email_threads) are required. " +
@@ -2899,6 +3040,38 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    server.registerTool("lighthouse_inbox_email_attachment", {
+        title: "Read Email Attachment",
+        description: "What one email attachment SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
+            "WHEN TO USE: the user asks what an attached file contains (\"summarise the report Jane sent\", \"what are the numbers in the attached model\", \"check the attachment on that email\"). " +
+            "Find the message first: lighthouse_inbox_email_threads (a subject, a sender, a date), then lighthouse_inbox_email_thread, whose messages carry attachments [{ id, message_id, filename, ... }] and account { id }. Pass that attachment's id as attachment_id, its message_id, and the message's account.id as account_id. " +
+            "Returns { attachment { id, message_id, type, filename, content_type, size }, message { id, thread_id, subject }, account { id, name, email, is_owner }, kind, pages_total, text, reason, note }. " +
+            FILE_CONTENT_RULES +
+            " An attachment in an account the user may see only the metadata of answers not found.",
+        inputSchema: {
+            message_id: z.string().describe("The message_id on the attachment (the message that carries it)"),
+            attachment_id: z.string().describe("The attachment's id, from a message's attachments (or inline_images) in lighthouse_inbox_email_thread"),
+            account_id: z.string().uuid().describe("Required: the account.id of that message (attachment ids belong to one account)"),
+            offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
+            max_chars: z.number().min(1).default(FILE_CONTENT_WINDOW_CHARS).describe("Characters per window"),
+        },
+    }, async ({ message_id, attachment_id, account_id, offset_chars, max_chars }) => {
+        try {
+            const path = `/inbox/email/messages/${encodeURIComponent(message_id)}/attachments/${encodeURIComponent(attachment_id)}`;
+            const res = await api.get(`${path}/content`, { account_id, offset_chars, max_chars });
+            const imageType = viewableImageType(res, (data) => {
+                const attachment = (data.attachment ?? {});
+                return { contentType: attachment.content_type, size: attachment.size };
+            });
+            if (!imageType)
+                return text(res);
+            const image = await api.download(path, { account_id }, IMAGE_BYTES_MAX);
+            return textWithImage(res, image, imageType);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     server.registerTool("lighthouse_inbox_email_create_draft", {
         title: "Create Email Draft",
         description: "Save an email draft in one of the user's mailboxes. The draft is NOT sent: it lands in the mailbox for the " +
@@ -3022,8 +3195,8 @@ export function createServer(apiKey) {
         description: "Calendars the API key's user can read: their own connected calendar (is_owner true) and colleagues' calendars shared with them. " +
             "The same account object the email and LinkedIn channels return: { id, name, email, is_owner, provider (google | microsoft | other), " +
             "status (connected | pending | disconnected), status_reason (credentials | error | stopped | other; null unless disconnected), " +
-            "owner, permissions { calendar_view }, created_at }. " +
-            "A calendar is the same connected account as a mailbox, behind its own sharing switch, so a mailbox shared for mail only is NOT listed here. " +
+            "owner, permissions { calendar_view, meeting_notes_view }, created_at }: calendar_view reads the calendar's meetings, meeting_notes_view reads the notes and transcripts of the meetings its owner recorded, including meetings the user was not invited to. " +
+            "A calendar is the same connected account as a mailbox, behind its own sharing switch, so a mailbox shared for mail only is NOT listed here, and neither is a calendar shared for meeting notes only: those notes come through the note tools, and each one's meeting.meeting_key opens its transcript. " +
             "Use scope 'me' to get only the user's own calendar: the SAME object, or null. " +
             "Use it to know whose meetings lighthouse_inbox_calendar_meetings can see, or to get an account_id to narrow that tool to one calendar. Returns [] when no calendar is connected.",
         inputSchema: {
@@ -3044,7 +3217,7 @@ export function createServer(apiKey) {
         description: "Calendar meetings across every calendar the API key's user can read (their own, plus colleagues' calendars shared with them), read live from the calendar. PAST meetings newest first by default (the last 6 months; pass months up to 36, or after / before, to move the window), or the SCHEDULED ones soonest first with upcoming=true (90 days ahead by default; an explicit before reaches further). " +
             "Narrow by CRM record (record_id + record_type, company or person: the record's addresses and domains are matched), by emails / domains lists (comma separated), by words in the meeting TITLE (query; never the notes), or by one calendar (account_id from lighthouse_inbox_calendar_accounts). No filter lists the user's whole calendar over the window. " +
             "WHEN TO USE: \"when did we last meet X\", \"what meetings do I have next week\", \"have we talked to anyone at acme.com\", \"which calls with this company were recorded\". To find what was DISCUSSED about a topic, list the meetings and read the notes of the likely ones. " +
-            "Each row: { id, meeting_key (only when the meeting was recorded), ical_uid, title, description, location, start, end, is_all_day, is_recurring (a recurring meeting appears once per occurrence), status (confirmed | tentative | cancelled | null), meeting_url (the video link), organizer { name, email }, attendees [{ name, email, response_status }] (everyone invited, the calendar's own account included; response_status is accepted | declined | tentative | needs_action, where needs_action means that attendee has not answered yet; a missing title, description, location, name or email is null, never an empty string), account { id, name, email, is_owner } (the calendar it was read from), recording: null when not recorded, else { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by }, the same object lighthouse_inbox_calendar_meeting returns (recorded_by is the recorder as a workspace member { id, first_name, last_name, full_name, avatar_url, email }, or null; has_notes is true only when notes are ready and the user may view notes) }. " +
+            "Each row: { id, meeting_key (only when the meeting was recorded), ical_uid, title, description, location, start, end, is_all_day, is_recurring (a recurring meeting appears once per occurrence), status (confirmed | tentative | cancelled | null), meeting_url (the video link), organizer { name, email }, attendees [{ name, email, response_status }] (everyone invited, the calendar's own account included; response_status is accepted | declined | tentative | needs_action, where needs_action means that attendee has not answered yet; a missing title, description, location, name or email is null, never an empty string), account { id, name, email, is_owner } (the calendar it was read from), recording: null when not recorded, else { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by }, the same object lighthouse_inbox_calendar_meeting returns (recorded_by is the recorder as a workspace member { id, first_name, last_name, full_name, avatar_url, email }, or null; has_notes is true only when notes are ready and the user may read them) }. " +
             "A row with meeting_key is a recorded meeting: pass it to lighthouse_inbox_calendar_meeting_notes for what was discussed and decided, or lighthouse_inbox_calendar_meeting_transcript for what was said. " +
             "Paged with a CURSOR: pass meta.next_cursor as cursor (same filters) while meta.has_more is true; the window is walked from its near end in 30-day steps, so the first page always holds the newest (or soonest) meetings. A date-only before includes that whole day. meta.window { after, before } is the window that was read. meta.accounts lists every calendar the user can see, one entry of { id, name, email, is_owner, ok, error, count } (a calendar that could not be read is ok false with its error code while the others are still read). meta.complete false means a step could not be fully scanned in time or a calendar failed: filter by record, emails or domains, or narrow the window. meta.note explains an empty or partial result (no calendar connected, a record with no addresses, a calendar that could not be read).",
         inputSchema: {
@@ -3074,10 +3247,10 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting", {
         title: "Get Recorded Meeting",
-        description: "One recorded meeting's metadata by meeting_key (from a row of lighthouse_inbox_calendar_meetings; a meeting note's meeting object carries no meeting_key): { meeting_key, ical_uid, title, occurred_at, meeting_url (the video link), recording { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by } (the same object the meetings list carries; recorded_by is the recorder as a workspace member, or null), notes { id, status, created_at }: the note lighthouse_inbox_calendar_meeting_notes returns, or null when there is none the user may read }. The title and the time are the same here as on the meetings list and inside the notes. " +
-            "WHEN TO USE: to check whether a transcript or notes exist before reading them, or to answer how long a call lasted. It never returns the transcript or the notes themselves. Not found when the meeting was not recorded or the API key's user cannot open its recording.",
+        description: "One recorded meeting's metadata by meeting_key (" + MEETING_KEY_SOURCES + "): { meeting_key, ical_uid, title, occurred_at, meeting_url (the video link), recording { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by } (the same object the meetings list carries; recorded_by is the recorder as a workspace member, or null), notes { id, status, created_at }: the note lighthouse_inbox_calendar_meeting_notes returns, or null when there is none the user may read }. The title and the time are the same here as on the meetings list and inside the notes. " +
+            "WHEN TO USE: to check whether a transcript or notes exist before reading them, or to answer how long a call lasted. It never returns the transcript or the notes themselves, and the API never returns the recording itself. Not found when the meeting was not recorded or the API key's user may not read it. A recurring meeting keeps the recording of its most recently recorded occurrence. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
         },
     }, async (params) => {
         try {
@@ -3090,11 +3263,11 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_notes", {
         title: "Get Meeting Notes",
-        description: "The meeting notes written from one recorded meeting, by meeting_key: the note in the same shape as lighthouse_crm_get_note (type 'meeting', with the meeting object and the records it is linked to), plus content_markdown (what was generated: Meeting Context first, then the sections) and is_edited (true when a member changed the note since, in which case content is the version to trust). " +
+        description: "The meeting notes written from one recorded meeting, by meeting_key (" + MEETING_KEY_SOURCES + "): the note in the same shape as lighthouse_crm_get_note (type 'meeting', with the meeting object and the records it is linked to that you can view), plus content_markdown (what was generated: Meeting Context first, then the sections) and is_edited (true when a member changed the note since, in which case content is the version to trust). " +
             "WHEN TO USE: the user asks what was discussed, decided or agreed in a specific meeting, the next steps from a call, or who attended. Lighter than the transcript: prefer it unless the answer depends on exactly what was said. " +
-            "Not found when the meeting has no notes yet (see has_notes on the meeting) or the API key's user cannot open its recording.",
+            "Not found when the meeting has no notes yet (see has_notes on the meeting) or the API key's user may not read them; for a recurring meeting the newest occurrence the user may read is returned. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
         },
     }, async (params) => {
         try {
@@ -3107,12 +3280,12 @@ export function createServer(apiKey) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_transcript", {
         title: "Get Meeting Transcript",
-        description: "The transcript of one recorded meeting by meeting_key, as text: one \"Speaker: text\" line per utterance, in order. " +
+        description: "The transcript of one recorded meeting by meeting_key (" + MEETING_KEY_SOURCES + "), as text: one \"Speaker: text\" line per utterance, in order. A note's meeting_key opens this transcript when that note's meeting.has_transcript is true. " +
             "WHEN TO USE: only when the answer depends on what was actually SAID (an exact quote, a number, who said what, a nuance the notes would flatten). For what was discussed or decided, lighthouse_inbox_calendar_meeting_notes is enough and far smaller. " +
             `A long meeting comes back in windows of max_chars (default ${TRANSCRIPT_WINDOW_CHARS}): meta.has_more true means the meeting continues past this window, so pass meta.next_offset_chars as offset_chars to read on, and never treat a window with has_more as the end of the meeting. ` +
-            "Not found when the meeting has no transcript or the API key's user cannot open its recording.",
+            "Not found when the meeting has no transcript or the API key's user may not read it. " + MEETING_ACCESS_RULE,
         inputSchema: {
-            meeting_key: z.string().describe("The meeting_key of a recorded meeting"),
+            meeting_key: z.string().describe("The meeting_key of a recorded meeting, " + MEETING_KEY_SOURCES),
             offset_chars: z.number().min(0).default(0).describe("Character offset to start from (meta.next_offset_chars of the previous window)"),
             max_chars: z.number().min(1).default(TRANSCRIPT_WINDOW_CHARS).describe("Characters per window"),
         },
@@ -3125,5 +3298,68 @@ export function createServer(apiKey) {
             return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     });
+    if (options.privateEquity !== true)
+        return server;
+    server.registerTool("lighthouse_private_equity_list_saved_searches", {
+        title: "List Private Equity Saved Searches",
+        description: "List the Private Equity saved searches the user can see in this workspace (their own, the ones shared with the workspace, and the ones shared with one of their teams), ordered by name. " +
+            "Each search carries id, name, sharing (private | workspace), shared_with_teams, is_owner, owner, created_at, updated_at, last_run_at and last_run: the stored run its results come from ({ id, created_at, last_fetched_at, result_count, match_count, created_by }, where result_count is how many companies are stored and match_count how many the search matched in the company database, or null), or null when it never ran. The search's filters are not returned. " +
+            "READ ONLY: this reads what the workspace already stored. It never runs a search, never fetches new companies and never spends credits; a Private Equity search is run, and paid for, only in the Lighthouse app. " +
+            "WHEN TO USE: the user asks which Private Equity searches exist, or names one whose results they want; pass its id to lighthouse_private_equity_list_saved_search_results. " +
+            "These are separate from the Discovery saved searches (lighthouse_discovery_list_saved_searches), which search a different database.",
+        inputSchema: {
+            offset: z.number().int().min(0).optional().describe("Number of saved searches to skip (default 0)"),
+            limit: z.number().int().min(1).max(100).optional().describe("Saved searches per page, 1 to 100 (default 25)"),
+        },
+    }, async ({ offset, limit }) => {
+        try {
+            const res = await api.get("/private-equity/saved-searches", { offset, limit });
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("lighthouse_private_equity_list_saved_search_results", {
+        title: "List Private Equity Saved Search Results",
+        description: "Read one page of the companies a Private Equity saved search's LAST run stored, in the order that run returned them. " +
+            "Each row is a stored company: id, name, domain, website_url, linkedin_url, short_description, avatar_url, hq ({ country, country_code, region, city }) and hq_label, industry, category, sector, naics ({ code, label }), business_models, employees and revenue_usd ({ value, estimated }), founded_year, company_type, num_locations, crm_id (the id of this workspace's CRM company for it, or null), lighthouse_company (the matching company in Lighthouse's own data, or null), from_lighthouse (the keys whose value was filled from Lighthouse's own data), fetched_at, profile_updated_at, and match ({ snippets, headline }: why a keyword or product search matched it, or null). " +
+            "meta carries total, limit, offset, has_more, has_results and run (the stored run the page is read from). A search that never ran, or whose last run is no longer stored, answers an empty page with meta.has_results false. " +
+            "READ ONLY: the rows are exactly what the search stored when someone last ran it in the app, even if its filters were edited since. This never runs the search again, never fetches more companies and never spends credits; for newer results, ask the user to run the search in the Lighthouse app. " +
+            "WHEN TO USE: the user asks what a Private Equity search found. Page with offset while meta.has_more is true. For one company's full stored profile use lighthouse_private_equity_get_company; when crm_id is set, lighthouse_crm_get_record (record_type 'company') opens the CRM company. " +
+            "Not found when the saved search does not exist or the user cannot see it.",
+        inputSchema: {
+            search_id: z.string().uuid().describe("Private Equity saved search ID (from lighthouse_private_equity_list_saved_searches)"),
+            offset: z.number().int().min(0).optional().describe("Number of companies to skip (default 0)"),
+            limit: z.number().int().min(1).max(100).optional().describe("Companies per page, 1 to 100 (default 25)"),
+        },
+    }, async ({ search_id, offset, limit }) => {
+        try {
+            const res = await api.get(`/private-equity/saved-searches/${encodeURIComponent(search_id)}/results`, { offset, limit });
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("lighthouse_private_equity_get_company", {
+        title: "Get Private Equity Company",
+        description: "Read one company's stored Private Equity profile by company_id: the id of a row returned by lighthouse_private_equity_list_saved_search_results (a text id, not a UUID, and not a Discovery or CRM id). " +
+            "Returns the keys of a results row (without match) plus the full profile: legal_names, commercial_names, long_description, long_description_extracted, locations, classification ({ naics_secondary, nace, sic, isic }), target_markets, core_offerings, technology_focus, certification_focus, supply_chain_focus, business_tags, technologies and technologies_total, contact ({ primary_phone, phone_numbers, primary_email, emails }), socials, website_language, profile_created_at, is_fresh and run_count. " +
+            "READ ONLY: the profile as a Private Equity search of this workspace stored it, never refreshed. It never fetches the company again and never spends credits. " +
+            "WHEN TO USE: the user asks for details on one company from a Private Equity search's results. When crm_id is set, lighthouse_crm_get_record (record_type 'company') opens the CRM company. " +
+            "Not found when none of this workspace's Private Equity searches returned that company.",
+        inputSchema: {
+            company_id: z.string().min(1).describe("The company's id, as a row of lighthouse_private_equity_list_saved_search_results gives it"),
+        },
+    }, async ({ company_id }) => {
+        try {
+            const res = await api.get(`/private-equity/companies/${encodeURIComponent(company_id)}`);
+            return text(res);
+        }
+        catch (e) {
+            return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylighthouse/mcp-server",
-  "version": "0.2.3",
+  "version": "0.2.10",
   "description": "MCP server for the Lighthouse CRM API",
   "homepage": "https://trylighthouse.vc",
   "type": "module",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "rm -rf build && tsc && chmod 755 build/index.js && node scripts/check-no-comments.mjs",
     "dev": "tsc --watch",
+    "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {