capsulemcp 1.8.0 → 2.0.0

package/dist/http.js

@@ -156,6 +156,26 @@ function invalidateByPrefix(pathPrefix, trigger) {
   }
 }
 
+// src/capsule/normalize.ts
+var KEY_RENAMES = {
+  kase: "project",
+  kases: "projects",
+  restrictedKases: "restrictedProjects"
+};
+function normalizeProjectKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeProjectKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      out[KEY_RENAMES[key] ?? key] = normalizeProjectKeys(v);
+    }
+    return out;
+  }
+  return value;
+}
+
 // src/capsule/client.ts
 var DEFAULT_BASE_URL = "https://api.capsulecrm.com/api/v2";
 function baseUrl() {
@@ -271,38 +291,31 @@ async function parseErrorBody(res) {
   }
 }
 var REQUEST_TIMEOUT_MS = 6e4;
-function withTimeout(options) {
-  if (options && options.signal !== void 0) {
-    return { options, cleanup: () => {
-    } };
-  }
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-  timer.unref();
-  return {
-    options: { ...options ?? {}, signal: controller.signal },
-    cleanup: () => clearTimeout(timer)
-  };
+function isTimeoutAbort(err) {
+  return err instanceof Error && // AbortSignal.timeout rejects with a DOMException named
+  // "TimeoutError"; plain aborts (and older undici paths) surface
+  // as "AbortError" or carry "aborted" in the message.
+  (err.name === "TimeoutError" || err.name === "AbortError" || /aborted/i.test(err.message));
 }
 async function mapAbort(p) {
   try {
     return await p;
   } catch (err) {
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
+    if (isTimeoutAbort(err)) {
       throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
 async function fetchWithTimeout(url, options) {
-  const { options: opts, cleanup } = withTimeout(options);
   const startedAt = Date.now();
   try {
-    const res = await fetch(url, opts);
-    return { res, cleanup };
+    return await fetch(url, {
+      ...options ?? {},
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
   } catch (err) {
-    cleanup();
-    const isAbort = err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    const isAbort = isTimeoutAbort(err);
     emitCapsuleFailure(
       options?.method ?? "GET",
       url,
@@ -326,24 +339,22 @@ async function doFetch(url, options) {
   const startedAt = Date.now();
   const method = options?.method ?? "GET";
   const first = await fetchWithTimeout(url, options);
-  if (first.res.status === 429) {
-    const delay = parseRateLimitDelay(first.res);
-    first.cleanup();
-    await drainBody(first.res);
+  if (first.status === 429) {
+    const delay = parseRateLimitDelay(first);
+    await drainBody(first);
     await new Promise((resolve) => setTimeout(resolve, delay));
     const retried = await fetchWithTimeout(url, options);
-    if (retried.res.status === 429) {
-      retried.cleanup();
-      await drainBody(retried.res);
+    if (retried.status === 429) {
+      await drainBody(retried);
       emitCapsuleRateLimited(method, url, Date.now() - startedAt);
       throw new CapsuleApiError(
         429,
         "Rate limit exceeded after one retry. Please slow down your requests."
       );
     }
-    return { ...retried, startedAt, method, url, retriedAfter429: true };
+    return { res: retried, startedAt, method, url, retriedAfter429: true };
   }
-  return { ...first, startedAt, method, url, retriedAfter429: false };
+  return { res: first, startedAt, method, url, retriedAfter429: false };
 }
 async function consumeBody(start, body) {
   try {
@@ -436,7 +447,8 @@ async function throwForStatus(res) {
 }
 async function handleResponse(res) {
   await throwForStatus(res);
-  return mapAbort(res.json());
+  const body = await mapAbort(res.json());
+  return normalizeProjectKeys(body);
 }
 function buildUrl(path, params) {
   const url = new URL(`${baseUrl()}${path}`);
@@ -453,15 +465,19 @@ async function capsuleGet(path, params) {
   const token = getToken();
   const url = buildUrl(path, params);
   const start = await doFetch(url, { headers: baseHeaders(token) });
-  try {
-    return await consumeBody(start, async () => {
-      const data = await handleResponse(start.res);
-      const nextPage = parseNextPage(start.res.headers.get("Link"));
-      return { data, nextPage };
-    });
-  } finally {
-    start.cleanup();
-  }
+  return consumeBody(start, async () => {
+    const data = await handleResponse(start.res);
+    const nextPage = parseNextPage(start.res.headers.get("Link"));
+    return { data, nextPage };
+  });
+}
+async function capsuleGetList(path, params) {
+  const { data, nextPage } = await capsuleGet(path, params);
+  return { ...data, nextPage };
+}
+async function capsuleGetCachedList(path, params) {
+  const { data, nextPage } = await capsuleGetCached(path, params);
+  return { ...data, nextPage };
 }
 async function capsuleGetCached(path, params) {
   if (cacheDisabled()) return capsuleGet(path, params);
@@ -500,11 +516,7 @@ async function capsulePost(path, body) {
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
-  try {
-    return await consumeBody(start, () => handleResponse(start.res));
-  } finally {
-    start.cleanup();
-  }
+  return consumeBody(start, () => handleResponse(start.res));
 }
 async function capsulePostNoContent(path) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
@@ -514,15 +526,11 @@ async function capsulePostNoContent(path) {
     method: "POST",
     headers: baseHeaders(token)
   });
-  try {
-    await consumeBody(start, async () => {
-      if (start.res.status === 204) return;
-      await throwForStatus(start.res);
-      await mapAbort(start.res.text());
-    });
-  } finally {
-    start.cleanup();
-  }
+  await consumeBody(start, async () => {
+    if (start.res.status === 204) return;
+    await throwForStatus(start.res);
+    await mapAbort(start.res.text());
+  });
 }
 async function capsuleSearch(path, body, params) {
   const token = getToken();
@@ -532,15 +540,11 @@ async function capsuleSearch(path, body, params) {
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
-  try {
-    return await consumeBody(start, async () => {
-      const data = await handleResponse(start.res);
-      const nextPage = parseNextPage(start.res.headers.get("Link"));
-      return { data, nextPage };
-    });
-  } finally {
-    start.cleanup();
-  }
+  return consumeBody(start, async () => {
+    const data = await handleResponse(start.res);
+    const nextPage = parseNextPage(start.res.headers.get("Link"));
+    return { data, nextPage };
+  });
 }
 async function capsulePut(path, body) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("PUT");
@@ -551,68 +555,60 @@ async function capsulePut(path, body) {
     headers: { ...baseHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify(body)
   });
-  try {
-    return await consumeBody(start, () => handleResponse(start.res));
-  } finally {
-    start.cleanup();
-  }
+  return consumeBody(start, () => handleResponse(start.res));
 }
 async function capsuleGetBinary(path, maxBytes) {
   const token = getToken();
   const url = buildUrl(path);
   const start = await doFetch(url, { headers: baseHeaders(token) });
-  try {
-    return await consumeBody(start, async () => {
-      const res = start.res;
-      await throwForStatus(res);
-      const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
-      const declared = res.headers.get("Content-Length");
-      const declaredBytes = declared ? Number(declared) : NaN;
-      if (maxBytes !== void 0 && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
-        if (res.body) await res.body.cancel().catch(() => {
-        });
+  return consumeBody(start, async () => {
+    const res = start.res;
+    await throwForStatus(res);
+    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+    const declared = res.headers.get("Content-Length");
+    const declaredBytes = declared ? Number(declared) : NaN;
+    if (maxBytes !== void 0 && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+      if (res.body) await res.body.cancel().catch(() => {
+      });
+      return {
+        contentType,
+        buffer: Buffer.alloc(0),
+        truncated: true,
+        sizeBytes: declaredBytes
+      };
+    }
+    if (maxBytes !== void 0 && res.body) {
+      const reader = res.body.getReader();
+      const chunks = [];
+      let total = 0;
+      let truncated = false;
+      while (true) {
+        const { done, value } = await mapAbort(reader.read());
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+          truncated = true;
+          await reader.cancel().catch(() => {
+          });
+          break;
+        }
+        chunks.push(value);
+      }
+      if (truncated) {
         return {
           contentType,
           buffer: Buffer.alloc(0),
           truncated: true,
-          sizeBytes: declaredBytes
+          sizeBytes: total
         };
       }
-      if (maxBytes !== void 0 && res.body) {
-        const reader = res.body.getReader();
-        const chunks = [];
-        let total = 0;
-        let truncated = false;
-        while (true) {
-          const { done, value } = await mapAbort(reader.read());
-          if (done) break;
-          total += value.byteLength;
-          if (total > maxBytes) {
-            truncated = true;
-            await reader.cancel().catch(() => {
-            });
-            break;
-          }
-          chunks.push(value);
-        }
-        if (truncated) {
-          return {
-            contentType,
-            buffer: Buffer.alloc(0),
-            truncated: true,
-            sizeBytes: total
-          };
-        }
-        const buffer2 = Buffer.concat(chunks.map((c) => Buffer.from(c)));
-        return { contentType, buffer: buffer2, sizeBytes: buffer2.length };
-      }
-      const arrayBuffer = await mapAbort(res.arrayBuffer());
-      const buffer = Buffer.from(arrayBuffer);
-      return { contentType, buffer, sizeBytes: buffer.length };
-    });
-  } finally {
-    start.cleanup();
-  }
+      const buffer2 = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+      return { contentType, buffer: buffer2, sizeBytes: buffer2.length };
+    }
+    const arrayBuffer = await mapAbort(res.arrayBuffer());
+    const buffer = Buffer.from(arrayBuffer);
+    return { contentType, buffer, sizeBytes: buffer.length };
+  });
 }
 async function capsulePostBinary(path, body, contentType, filename) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("POST");
@@ -628,11 +624,7 @@ async function capsulePostBinary(path, body, contentType, filename) {
     },
     body
   });
-  try {
-    return await consumeBody(start, () => handleResponse(start.res));
-  } finally {
-    start.cleanup();
-  }
+  return consumeBody(start, () => handleResponse(start.res));
 }
 async function capsuleDelete(path) {
   if (isReadOnly()) throw new CapsuleReadOnlyError("DELETE");
@@ -642,15 +634,11 @@ async function capsuleDelete(path) {
     method: "DELETE",
     headers: baseHeaders(token)
   });
-  try {
-    await consumeBody(start, async () => {
-      if (start.res.status === 204) return;
-      await throwForStatus(start.res);
-      await mapAbort(start.res.text());
-    });
-  } finally {
-    start.cleanup();
-  }
+  await consumeBody(start, async () => {
+    if (start.res.status === 204) return;
+    await throwForStatus(start.res);
+    await mapAbort(start.res.text());
+  });
 }
 
 // src/auth/provider.ts
@@ -1171,6 +1159,45 @@ var ICONS = [
   }
 ];
 
+// src/server/tier.ts
+var CORE_TOOLS = /* @__PURE__ */ new Set([
+  // Parties
+  "search_parties",
+  "filter_parties",
+  "get_party",
+  "create_party",
+  "update_party",
+  "list_party_entries",
+  // Opportunities
+  "search_opportunities",
+  "filter_opportunities",
+  "get_opportunity",
+  "create_opportunity",
+  "update_opportunity",
+  // Projects
+  "search_projects",
+  "filter_projects",
+  "list_projects",
+  "get_project",
+  "create_project",
+  "update_project",
+  // Tasks
+  "list_tasks",
+  "get_task",
+  "create_task",
+  "update_task",
+  "complete_task",
+  // Timeline + tags + identity
+  "add_note",
+  "list_tags",
+  "add_tag",
+  "get_current_user"
+]);
+function shouldRegister(name) {
+  if (process.env["CAPSULE_MCP_TIER"] !== "core") return true;
+  return CORE_TOOLS.has(name);
+}
+
 // src/tasks/store.ts
 import { InMemoryTaskStore } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
 import {
@@ -1379,27 +1406,25 @@ function wrapAsText(result) {
   };
 }
 function registerTool(server, name, description, schema, handler) {
+  if (!shouldRegister(name)) return;
   const registerWithSchema = server.registerTool.bind(server);
   const annotations = inferAnnotations(name);
-  registerWithSchema(
-    name,
-    { description, inputSchema: schema, ...annotations ? { annotations } : {} },
-    async (input) => {
-      const startedAt = Date.now();
-      const argFields = argFieldNames(input);
-      const clientId = getRequestContext()?.clientId;
-      try {
-        const result = await handler(input);
-        emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "success" });
-        return wrapAsText(result);
-      } catch (err) {
-        emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "error" });
-        throw err;
-      }
+  registerWithSchema(name, { description, inputSchema: schema, annotations }, async (input) => {
+    const startedAt = Date.now();
+    const argFields = argFieldNames(input);
+    const clientId = getRequestContext()?.clientId;
+    try {
+      const result = await handler(input);
+      emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "success" });
+      return wrapAsText(result);
+    } catch (err) {
+      emitToolCall({ tool: name, clientId, argFields, startedAt, outcome: "error" });
+      throw err;
     }
-  );
+  });
 }
 function registerToolTask(server, name, description, schema, handler) {
+  if (!shouldRegister(name)) return;
   const registerWithSchema = server.experimental.tasks.registerToolTask.bind(
     server.experimental.tasks
   );
@@ -1410,7 +1435,7 @@ function registerToolTask(server, name, description, schema, handler) {
       description,
       inputSchema: schema,
       execution: { taskSupport: "optional" },
-      ...annotations ? { annotations } : {}
+      annotations
     },
     {
       createTask: async (input, extra) => {
@@ -1470,7 +1495,7 @@ function registerToolTask(server, name, description, schema, handler) {
 }
 
 // src/tools/parties.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/tools/body-helpers.ts
 function setRef(body, key, id) {
@@ -1480,9 +1505,22 @@ function setNullableRef(body, key, id) {
   if (id === null) body[key] = null;
   else if (id !== void 0) body[key] = { id };
 }
+function assertSingleParentRef(toolName, refs, opts = {}) {
+  const set = [refs.partyId, refs.opportunityId, refs.projectId].filter(
+    (v) => typeof v === "number"
+  ).length;
+  if (opts.required && set !== 1) {
+    throw new Error(`${toolName}: provide exactly one of partyId, opportunityId, or projectId`);
+  }
+  if (set > 1) {
+    throw new Error(
+      `${toolName}: provide at most one of partyId, opportunityId, or projectId \u2014 Capsule allows a record to be related to at most one entity`
+    );
+  }
+}
 
 // src/tools/define-batch.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/capsule/batch.ts
 function chunk(arr, size) {
@@ -1501,37 +1539,43 @@ function getBatchConcurrency() {
     MAX_CONCURRENCY
   );
 }
-async function batchExecute(tool, items, action, options = {}) {
-  const concurrency = getBatchConcurrency();
+async function mapWithConcurrency(items, limit, fn) {
   const results = new Array(items.length);
-  const startedAt = Date.now();
-  const signal = options.signal;
   let cursor = 0;
   async function worker() {
     while (true) {
       const i = cursor;
       cursor += 1;
       if (i >= items.length) return;
-      if (signal?.aborted) {
-        results[i] = {
-          ok: false,
-          error: { message: "cancelled by tasks/cancel" }
-        };
-        continue;
-      }
-      try {
-        const result = await action(items[i], i);
-        results[i] = { ok: true, result };
-      } catch (err) {
-        results[i] = { ok: false, error: extractError(err) };
-      }
+      results[i] = await fn(items[i], i);
     }
   }
   const workers = [];
-  for (let w = 0; w < Math.min(concurrency, items.length); w++) {
+  for (let w = 0; w < Math.min(limit, items.length); w++) {
     workers.push(worker());
   }
   await Promise.all(workers);
+  return results;
+}
+async function batchExecute(tool, items, action, options = {}) {
+  const concurrency = getBatchConcurrency();
+  const startedAt = Date.now();
+  const signal = options.signal;
+  const results = await mapWithConcurrency(
+    items,
+    concurrency,
+    async (item, i) => {
+      if (signal?.aborted) {
+        return { ok: false, error: { message: "cancelled by tasks/cancel" } };
+      }
+      try {
+        const result = await action(item, i);
+        return { ok: true, result };
+      } catch (err) {
+        return { ok: false, error: extractError(err) };
+      }
+    }
+  );
   const succeeded = results.filter((r) => r.ok).length;
   const failed = results.length - succeeded;
   const summary = { total: results.length, succeeded, failed };
@@ -1576,10 +1620,52 @@ function topFailureReasons(results, n) {
   return Array.from(counts.values()).sort((a, b) => b.count - a.count).slice(0, n);
 }
 
+// src/tools/strip-descriptions.ts
+import { z as z2 } from "zod";
+function cloneWithDef(node, patch) {
+  const def = node.def;
+  return node.clone({ ...def, ...patch });
+}
+function stripDescriptions(schema) {
+  let node = schema;
+  if (node instanceof z2.ZodObject) {
+    const shape = node.def.shape;
+    const next = {};
+    let changed = false;
+    for (const [key, child] of Object.entries(shape)) {
+      next[key] = stripDescriptions(child);
+      if (next[key] !== child) changed = true;
+    }
+    if (changed) node = cloneWithDef(node, { shape: next });
+  } else if (node instanceof z2.ZodArray) {
+    const element = stripDescriptions(node.def.element);
+    if (element !== node.def.element) node = cloneWithDef(node, { element });
+  } else if (node instanceof z2.ZodOptional || node instanceof z2.ZodNullable || node instanceof z2.ZodDefault || node instanceof z2.ZodReadonly) {
+    const innerType = stripDescriptions(node.def.innerType);
+    if (innerType !== node.def.innerType) node = cloneWithDef(node, { innerType });
+  } else if (node instanceof z2.ZodUnion) {
+    const options = node.def.options.map(stripDescriptions);
+    if (options.some((o, i) => o !== node.def.options[i])) {
+      node = cloneWithDef(node, { options });
+    }
+  } else if (node instanceof z2.ZodPipe) {
+    const inSchema = stripDescriptions(node.def.in);
+    const outSchema = stripDescriptions(node.def.out);
+    if (inSchema !== node.def.in || outSchema !== node.def.out) {
+      node = cloneWithDef(node, { in: inSchema, out: outSchema });
+    }
+  }
+  if (node.description !== void 0) {
+    node = node.meta({ description: void 0 });
+  }
+  return node;
+}
+
 // src/tools/define-batch.ts
 function defineBatch(args) {
-  const schema = z2.object({
-    items: z2.array(args.itemSchema).min(1).max(50).describe(args.itemDescription)
+  const itemSchema = stripDescriptions(args.itemSchema);
+  const schema = z3.object({
+    items: z3.array(itemSchema).min(1).max(50).describe(args.itemDescription)
   });
   async function handler(input, opts = {}) {
     return batchExecute(args.toolName, input.items, args.itemHandler, opts);
@@ -1587,27 +1673,51 @@ function defineBatch(args) {
   return { schema, handler };
 }
 
-// src/tools/descriptions.ts
-var EMBED_TAGS_FIELDS_DESCRIPTION = "Comma-separated embeds, e.g. 'tags,fields'";
-var EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION = "Comma-separated embeds, e.g. 'attachments,participants'";
-
 // src/tools/define-delete.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/tools/confirm-flag.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var CONFIRM_REQUIRED_MESSAGE = "confirm: true is required to perform this destructive operation (set the parameter explicitly to acknowledge the destructive intent)";
 function confirmFlag() {
-  return z3.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
+  return z4.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
 }
 
 // src/tools/shared-schemas.ts
-import { z as z4 } from "zod";
-var positiveId = z4.preprocess((input) => {
+import { z as z5 } from "zod";
+var positiveId = z5.preprocess((input) => {
   if (typeof input !== "string") return input;
   const trimmed = input.trim();
   return /^\d+$/.test(trimmed) ? Number(trimmed) : input;
-}, z4.number().int().positive());
+}, z5.number().int().positive());
+var paginationFields = {
+  page: z5.number().int().positive().optional().default(1),
+  perPage: z5.number().int().min(1).max(100).optional().default(25)
+};
+var paginationFieldsNoDefaults = {
+  page: z5.number().int().positive().optional(),
+  perPage: z5.number().int().min(1).max(100).optional()
+};
+var ENTITY_PATH = {
+  parties: "parties",
+  opportunities: "opportunities",
+  projects: "kases"
+};
+function embedParam(allowed) {
+  return z5.string().superRefine((value, ctx) => {
+    const tokens = value.split(",").map((t) => t.trim());
+    for (const token of tokens) {
+      if (token === "" || !allowed.includes(token)) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Unknown embed token '${token}'. Valid tokens: ${allowed.join(", ")} (comma-separated). Capsule silently ignores unknown tokens, so this is rejected client-side to prevent silently-missing data.`
+        });
+      }
+    }
+  }).describe(`Comma-separated embeds. Valid tokens: ${allowed.join(", ")}.`).optional();
+}
+var RECORD_EMBEDS = ["tags", "fields", "missingImportantFields"];
+var ENTRY_EMBEDS = ["attachments", "participants"];
 
 // src/capsule/idempotent.ts
 var isCapsule404 = (err) => err instanceof CapsuleApiError && err.status === 404;
@@ -1634,7 +1744,7 @@ async function idempotentWithResult(op, success, alreadyDone, isAlreadyDoneError
 // src/tools/define-delete.ts
 function defineDelete(args) {
   const { toolName, pathPrefix, confirmHint, idDescription } = args;
-  const schema = z5.object({
+  const schema = z6.object({
     id: idDescription ? positiveId.describe(idDescription) : positiveId,
     confirm: confirmFlag().describe(confirmHint)
   });
@@ -1682,12 +1792,12 @@ async function chunkedMultiGet(base, responseKey, ids, params) {
 }
 
 // src/tools/custom-field-helpers.ts
-import { z as z6 } from "zod";
-var CustomFieldWriteSchema = z6.object({
+import { z as z7 } from "zod";
+var CustomFieldWriteSchema = z7.object({
   definitionId: positiveId.describe(
     "The custom-field definition id from list_custom_fields. Identifies which field on the entity to set."
   ),
-  value: z6.union([z6.string(), z6.number(), z6.boolean(), z6.null()]).describe(
+  value: z7.union([z7.string(), z7.number(), z7.boolean(), z7.null()]).describe(
     "The new value. String for TEXT / DATE / LIST / LARGE_TEXT / LINK fields, number for NUMBER fields, boolean for BOOLEAN fields. Clearing: pass null for TEXT / NUMBER / DATE / LIST (Capsule removes the row). BOOLEAN does NOT accept null (Capsule returns 422 'invalid type for field'); use `value: false` instead. Note BOOLEAN fields are observably **two-state**: a row exists with `value: true`, or no row exists. Setting `value: false` removes the row entirely \u2014 readers should treat absent BOOLEAN rows as equivalent to false. Tri-state BOOLEAN semantics (true / false / unknown) are not achievable through Capsule's API. Audit-log noise: sending value=null on a field that's already empty/cleared is accepted by Capsule but still bumps the parent entity's `updatedAt`. Read the current value via embed='fields' first if `updatedAt` is being used as a 'last meaningful change' signal. NUMBER quirks: Capsule stores numerics correctly but the read-back via embed=fields returns them as STRINGS (e.g. value=3 reads as '3'); callers comparing values must coerce. TEXT quirks: value='' has the same observable effect as value=null (row removed); empty-string and never-set are indistinguishable."
   )
 });
@@ -1703,24 +1813,24 @@ function mapFieldsForBody(fields) {
 }
 
 // src/tools/parties.ts
-var EmailAddressSchema = z7.object({
-  address: z7.string().email(),
-  type: z7.string().optional()
+var EmailAddressSchema = z8.object({
+  address: z8.string().email(),
+  type: z8.string().optional()
 });
-var PhoneNumberSchema = z7.object({
+var PhoneNumberSchema = z8.object({
   // Capsule rejects empty strings with `phoneNumber.number: number is
   // required`. Enforce at the schema layer to catch typos pre-call,
   // matching how EmailAddressSchema's address field behaves.
-  number: z7.string().min(1),
-  type: z7.string().optional()
+  number: z8.string().min(1),
+  type: z8.string().optional()
 });
 var CountryDescription = "Country name. Capsule validates this against a small canonical-English-name dictionary; inputs not in the dictionary are REJECTED with 422 'address.country: unknown country' (NOT silently passed through or normalised). Probed examples \u2014 accepted: `United States`, `United Kingdom`, `Czechia`, `Germany`. Aliased: `USA \u2192 United States`. Rejected: `United States of America`, `Czech Republic` (use `Czechia`), `UK`/`Britain` (use `United Kingdom`), `Deutschland` (use `Germany`). Empty string is accepted and stored as `null` \u2014 a de-facto 'clear' shape. To discover an accepted name, read an existing party that already has the country set.";
-var AddressSchema = z7.object({
-  street: z7.string().optional(),
-  city: z7.string().optional(),
-  state: z7.string().optional(),
-  country: z7.string().optional().describe(CountryDescription),
-  zip: z7.string().optional()
+var AddressSchema = z8.object({
+  street: z8.string().optional(),
+  city: z8.string().optional(),
+  state: z8.string().optional(),
+  country: z8.string().optional().describe(CountryDescription),
+  zip: z8.string().optional()
 });
 function validateWebsiteAddress(data, ctx) {
   const isUrlService = data.service === void 0 || data.service === "URL";
@@ -1743,7 +1853,7 @@ function validateWebsiteAddress(data, ctx) {
     });
   }
 }
-var WebsiteServiceEnum = z7.enum([
+var WebsiteServiceEnum = z8.enum([
   "URL",
   "SKYPE",
   "TWITTER",
@@ -1762,33 +1872,31 @@ var WebsiteServiceEnum = z7.enum([
   "BLUESKY",
   "SNAPCHAT"
 ]);
-var WebsiteSchema = z7.object({
-  address: z7.string().min(1).describe(
+var WebsiteSchema = z8.object({
+  address: z8.string().min(1).describe(
     "The website address. A URL when service='URL', or a handle (e.g. '@acmeco') for social services like 'TWITTER', 'INSTAGRAM'. Capsule names this field `address` regardless of service type."
   ),
   service: WebsiteServiceEnum.optional().describe(
     "Service type. One of: URL, SKYPE, TWITTER, LINKED_IN, FACEBOOK, XING, FEED, GOOGLE_PLUS, FLICKR, GITHUB, YOUTUBE, INSTAGRAM, PINTEREST, TIKTOK, THREADS, BLUESKY, SNAPCHAT. Defaults to 'URL' if omitted."
   )
 }).superRefine(validateWebsiteAddress);
-var searchPartiesSchema = z7.object({
-  q: z7.string().optional().describe("Free-text search query"),
-  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z7.number().int().positive().optional().default(1),
-  perPage: z7.number().int().min(1).max(100).optional().default(25)
+var searchPartiesSchema = z8.object({
+  q: z8.string().optional().describe("Free-text search query"),
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function searchParties(input) {
   const path = input.q ? "/parties/search" : "/parties";
-  const { data, nextPage } = await capsuleGet(path, {
+  return capsuleGetList(path, {
     q: input.q,
     embed: input.embed,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var getPartySchema = z7.object({
+var getPartySchema = z8.object({
   id: positiveId.describe("Party ID"),
-  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getParty(input) {
   const { data } = await capsuleGet(`/parties/${input.id}`, {
@@ -1796,51 +1904,47 @@ async function getParty(input) {
   });
   return data;
 }
-var getPartiesSchema = z7.object({
-  ids: z7.array(positiveId).min(1).max(50).describe(
+var getPartiesSchema = z8.object({
+  ids: z8.array(positiveId).min(1).max(50).describe(
     "Array of party IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel. Result shape is identical regardless of input size."
   ),
-  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getParties(input) {
   return chunkedMultiGet("/parties", "parties", input.ids, { embed: input.embed });
 }
-var listPartyOpportunitiesSchema = z7.object({
+var listPartyOpportunitiesSchema = z8.object({
   partyId: positiveId,
-  page: z7.number().int().positive().optional().default(1),
-  perPage: z7.number().int().min(1).max(100).optional().default(25)
+  ...paginationFields
 });
 async function listPartyOpportunities(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/parties/${input.partyId}/opportunities`,
-    { page: input.page, perPage: input.perPage }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/parties/${input.partyId}/opportunities`, {
+    page: input.page,
+    perPage: input.perPage
+  });
 }
-var listPartyProjectsSchema = z7.object({
+var listPartyProjectsSchema = z8.object({
   partyId: positiveId,
-  page: z7.number().int().positive().optional().default(1),
-  perPage: z7.number().int().min(1).max(100).optional().default(25)
+  ...paginationFields
 });
 async function listPartyProjects(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/parties/${input.partyId}/kases`,
-    { page: input.page, perPage: input.perPage }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/parties/${input.partyId}/kases`, {
+    page: input.page,
+    perPage: input.perPage
+  });
 }
 var PartyWriteBaseSchema = {
-  about: z7.string().optional(),
-  emailAddresses: z7.array(EmailAddressSchema).optional().describe(
+  about: z8.string().optional(),
+  emailAddresses: z8.array(EmailAddressSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_email_address and remove_party_email_address_by_id. Passing `[]` here is a silent no-op (does not clear the list and does not advance updatedAt)."
   ),
-  phoneNumbers: z7.array(PhoneNumberSchema).optional().describe(
+  phoneNumbers: z8.array(PhoneNumberSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_phone_number and remove_party_phone_number_by_id."
   ),
-  addresses: z7.array(AddressSchema).optional().describe(
+  addresses: z8.array(AddressSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_address and remove_party_address_by_id. The `country` field is mapped through Capsule's country dictionary \u2014 see `add_party_address.country` for the dictionary edges (small canonical-English-name list; inputs not in the dictionary are REJECTED with 422, not silently dropped)."
   ),
-  websites: z7.array(WebsiteSchema).optional().describe(
+  websites: z8.array(WebsiteSchema).optional().describe(
     "APPEND-ONLY: items are merged into the existing list, never replaced. For atomic add/remove/replace use add_party_website and remove_party_website_by_id."
   ),
   ownerId: positiveId.nullable().optional().describe(
@@ -1850,16 +1954,16 @@ var PartyWriteBaseSchema = {
     "Assign to team ID (discover via list_teams). Pass a team ID to set, or `null` to unassign. Capsule enforces the owner\u2208team membership constraint \u2014 passing a team the current owner doesn't belong to returns 422 'owner is not a member of the team'. Combine `ownerId: null` + `teamId: <T>` in one call to transfer a party to team-ownership with no specific user (verified empirically in v1.6.4 wire-trace; the membership rule doesn't fire when owner is null)."
   )
 };
-var createPartySchema = z7.object({
-  type: z7.enum(["person", "organisation"]),
+var createPartySchema = z8.object({
+  type: z8.enum(["person", "organisation"]),
   // person
-  firstName: z7.string().optional(),
-  lastName: z7.string().optional(),
-  title: z7.string().optional(),
-  jobTitle: z7.string().optional(),
+  firstName: z8.string().optional(),
+  lastName: z8.string().optional(),
+  title: z8.string().optional(),
+  jobTitle: z8.string().optional(),
   organisationId: positiveId.optional().describe("Link person to an existing organisation ID"),
   // organisation
-  name: z7.string().optional(),
+  name: z8.string().optional(),
   ...PartyWriteBaseSchema,
   ownerId: positiveId.optional().describe(
     "Assign to user ID. Defaults to the API-token owner when omitted. To create a team-owned party with no specific user, first create the party, then call update_party with `ownerId: null` and `teamId`."
@@ -1867,9 +1971,24 @@ var createPartySchema = z7.object({
   teamId: positiveId.optional().describe(
     "Assign to team ID (discover via list_teams). Omit to leave team unset on create. To clear an existing team or create a team-owned party with no specific owner, use update_party after creation."
   ),
-  fields: z7.array(CustomFieldWriteSchema).optional().describe(
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(
     fieldsArrayDescriptor("get_party") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /parties accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update."
   )
+}).superRefine((data, ctx) => {
+  if (data.type === "person" && !data.firstName && !data.lastName) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["firstName"],
+      message: "create_party: a person requires firstName and/or lastName"
+    });
+  }
+  if (data.type === "organisation" && !data.name) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["name"],
+      message: "create_party: an organisation requires name"
+    });
+  }
 });
 async function createParty(input) {
   const { ownerId, teamId, organisationId, fields, ...rest } = input;
@@ -1881,17 +2000,17 @@ async function createParty(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/parties", { party: body });
 }
-var updatePartySchema = z7.object({
+var updatePartySchema = z8.object({
   id: positiveId,
-  firstName: z7.string().optional(),
-  lastName: z7.string().optional(),
-  title: z7.string().optional(),
-  jobTitle: z7.string().optional(),
-  name: z7.string().optional(),
+  firstName: z8.string().optional(),
+  lastName: z8.string().optional(),
+  title: z8.string().optional(),
+  jobTitle: z8.string().optional(),
+  name: z8.string().optional(),
   organisationId: positiveId.nullable().optional().describe(
     "For PERSON parties: link to an organisation by id, or `null` to unlink (the person becomes an orphan / standalone record). Discover org IDs via search_parties / filter_parties with type=organisation. For ORGANISATION parties: silently ignored by Capsule's API \u2014 organisations don't have a parent organisation in the data model. Empirically verified in v1.6.3 wire-trace; no client-side type guard since the no-op is harmless."
   ),
-  fields: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
@@ -1920,12 +2039,44 @@ var { schema: batchUpdatePartySchema, handler: batchUpdateParty } = defineBatch(
 var { schema: deletePartySchema, handler: deleteParty } = defineDelete({
   toolName: "delete_party",
   pathPrefix: "/parties",
-  confirmHint: "Must be set to true. Deletes the party AND all linked notes, tasks, opportunities, and projects (kases). Deleting an ORGANISATION does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. Irreversible."
+  confirmHint: "Must be set to true. Deletes the party AND all linked notes, tasks, opportunities, and projects. Deleting an ORGANISATION does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. Irreversible."
 });
-var addPartyEmailAddressSchema = z7.object({
+function definePartySubResourceRemove(opts) {
+  const shape = {
+    partyId: positiveId,
+    [opts.idField]: positiveId.describe(
+      `Capsule's id for the ${opts.rowNoun} row. Read it from get_party (each entry in ${opts.arrayKey} carries an id).`
+    )
+  };
+  const schema = z8.object(shape);
+  async function handler(input) {
+    const partyId = input["partyId"];
+    const rowId = input[opts.idField];
+    return idempotentWithResult(
+      () => capsulePut(`/parties/${partyId}`, {
+        party: { [opts.arrayKey]: [{ id: rowId, _delete: true }] }
+      }),
+      (result) => ({
+        removed: true,
+        alreadyRemoved: false,
+        partyId,
+        [opts.idField]: rowId,
+        ...result
+      }),
+      () => ({
+        removed: true,
+        alreadyRemoved: true,
+        partyId,
+        [opts.idField]: rowId
+      })
+    );
+  }
+  return { schema, handler };
+}
+var addPartyEmailAddressSchema = z8.object({
   partyId: positiveId,
-  address: z7.string().email(),
-  type: z7.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
+  address: z8.string().email(),
+  type: z8.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
 });
 async function addPartyEmailAddress(input) {
   const { partyId, address, type } = input;
@@ -1935,32 +2086,17 @@ async function addPartyEmailAddress(input) {
     party: { emailAddresses: [item] }
   });
 }
-var removePartyEmailAddressByIdSchema = z7.object({
-  partyId: positiveId,
-  emailAddressId: positiveId.describe(
-    "Capsule's id for the email-address row. Read it from get_party (each entry in emailAddresses carries an id)."
-  )
+var removePartyEmailAddress = definePartySubResourceRemove({
+  arrayKey: "emailAddresses",
+  idField: "emailAddressId",
+  rowNoun: "email-address"
 });
-async function removePartyEmailAddressById(input) {
-  const { partyId, emailAddressId } = input;
-  return idempotentWithResult(
-    () => capsulePut(`/parties/${partyId}`, {
-      party: { emailAddresses: [{ id: emailAddressId, _delete: true }] }
-    }),
-    (result) => ({
-      removed: true,
-      alreadyRemoved: false,
-      partyId,
-      emailAddressId,
-      ...result
-    }),
-    () => ({ removed: true, alreadyRemoved: true, partyId, emailAddressId })
-  );
-}
-var addPartyPhoneNumberSchema = z7.object({
+var removePartyEmailAddressByIdSchema = removePartyEmailAddress.schema;
+var removePartyEmailAddressById = removePartyEmailAddress.handler;
+var addPartyPhoneNumberSchema = z8.object({
   partyId: positiveId,
-  number: z7.string().min(1),
-  type: z7.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
+  number: z8.string().min(1),
+  type: z8.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
 });
 async function addPartyPhoneNumber(input) {
   const { partyId, number, type } = input;
@@ -1970,36 +2106,21 @@ async function addPartyPhoneNumber(input) {
     party: { phoneNumbers: [item] }
   });
 }
-var removePartyPhoneNumberByIdSchema = z7.object({
-  partyId: positiveId,
-  phoneNumberId: positiveId.describe(
-    "Capsule's id for the phone-number row. Read it from get_party (each entry in phoneNumbers carries an id)."
-  )
+var removePartyPhoneNumber = definePartySubResourceRemove({
+  arrayKey: "phoneNumbers",
+  idField: "phoneNumberId",
+  rowNoun: "phone-number"
 });
-async function removePartyPhoneNumberById(input) {
-  const { partyId, phoneNumberId } = input;
-  return idempotentWithResult(
-    () => capsulePut(`/parties/${partyId}`, {
-      party: { phoneNumbers: [{ id: phoneNumberId, _delete: true }] }
-    }),
-    (result) => ({
-      removed: true,
-      alreadyRemoved: false,
-      partyId,
-      phoneNumberId,
-      ...result
-    }),
-    () => ({ removed: true, alreadyRemoved: true, partyId, phoneNumberId })
-  );
-}
-var addPartyAddressSchema = z7.object({
+var removePartyPhoneNumberByIdSchema = removePartyPhoneNumber.schema;
+var removePartyPhoneNumberById = removePartyPhoneNumber.handler;
+var addPartyAddressSchema = z8.object({
   partyId: positiveId,
-  street: z7.string().optional(),
-  city: z7.string().optional(),
-  state: z7.string().optional(),
-  country: z7.string().optional().describe(CountryDescription),
-  zip: z7.string().optional(),
-  type: z7.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
+  street: z8.string().optional(),
+  city: z8.string().optional(),
+  state: z8.string().optional(),
+  country: z8.string().optional().describe(CountryDescription),
+  zip: z8.string().optional(),
+  type: z8.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
 });
 async function addPartyAddress(input) {
   const { partyId, ...rest } = input;
@@ -2011,31 +2132,16 @@ async function addPartyAddress(input) {
     party: { addresses: [item] }
   });
 }
-var removePartyAddressByIdSchema = z7.object({
-  partyId: positiveId,
-  addressId: positiveId.describe(
-    "Capsule's id for the address row. Read it from get_party (each entry in addresses carries an id)."
-  )
+var removePartyAddress = definePartySubResourceRemove({
+  arrayKey: "addresses",
+  idField: "addressId",
+  rowNoun: "address"
 });
-async function removePartyAddressById(input) {
-  const { partyId, addressId } = input;
-  return idempotentWithResult(
-    () => capsulePut(`/parties/${partyId}`, {
-      party: { addresses: [{ id: addressId, _delete: true }] }
-    }),
-    (result) => ({
-      removed: true,
-      alreadyRemoved: false,
-      partyId,
-      addressId,
-      ...result
-    }),
-    () => ({ removed: true, alreadyRemoved: true, partyId, addressId })
-  );
-}
-var addPartyWebsiteSchema = z7.object({
+var removePartyAddressByIdSchema = removePartyAddress.schema;
+var removePartyAddressById = removePartyAddress.handler;
+var addPartyWebsiteSchema = z8.object({
   partyId: positiveId,
-  address: z7.string().min(1).describe(
+  address: z8.string().min(1).describe(
     "The website address. A URL when service='URL', or a handle (e.g. '@acmeco') for social services."
   ),
   service: WebsiteServiceEnum.optional().describe("Defaults to 'URL' if omitted.")
@@ -2048,58 +2154,41 @@ async function addPartyWebsite(input) {
     party: { websites: [item] }
   });
 }
-var removePartyWebsiteByIdSchema = z7.object({
-  partyId: positiveId,
-  websiteId: positiveId.describe(
-    "Capsule's id for the website row. Read it from get_party (each entry in websites carries an id)."
-  )
+var removePartyWebsite = definePartySubResourceRemove({
+  arrayKey: "websites",
+  idField: "websiteId",
+  rowNoun: "website"
 });
-async function removePartyWebsiteById(input) {
-  const { partyId, websiteId } = input;
-  return idempotentWithResult(
-    () => capsulePut(`/parties/${partyId}`, {
-      party: { websites: [{ id: websiteId, _delete: true }] }
-    }),
-    (result) => ({
-      removed: true,
-      alreadyRemoved: false,
-      partyId,
-      websiteId,
-      ...result
-    }),
-    () => ({ removed: true, alreadyRemoved: true, partyId, websiteId })
-  );
-}
+var removePartyWebsiteByIdSchema = removePartyWebsite.schema;
+var removePartyWebsiteById = removePartyWebsite.handler;
 
 // src/tools/opportunities.ts
-import { z as z8 } from "zod";
-var OpportunityValueSchema = z8.object({
-  amount: z8.number().nonnegative(),
-  currency: z8.string({
+import { z as z9 } from "zod";
+var OpportunityValueSchema = z9.object({
+  amount: z9.number().nonnegative(),
+  currency: z9.string({
     error: (iss) => iss.code === "invalid_type" && iss.input === void 0 ? "currency is required when amount is set (3-letter ISO 4217 code, e.g. 'USD', 'EUR', 'GBP')" : void 0
   }).length(3).describe(
     "ISO 4217 currency code (3 letters), e.g. 'GBP', 'USD', 'EUR'. Required when amount is set."
   )
 });
-var searchOpportunitiesSchema = z8.object({
-  q: z8.string().optional().describe("Free-text search query"),
-  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z8.number().int().positive().optional().default(1),
-  perPage: z8.number().int().min(1).max(100).optional().default(25)
+var searchOpportunitiesSchema = z9.object({
+  q: z9.string().optional().describe("Free-text search query"),
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function searchOpportunities(input) {
   const path = input.q ? "/opportunities/search" : "/opportunities";
-  const { data, nextPage } = await capsuleGet(path, {
+  return capsuleGetList(path, {
     q: input.q,
     embed: input.embed,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var getOpportunitySchema = z8.object({
+var getOpportunitySchema = z9.object({
   id: positiveId,
-  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getOpportunity(input) {
   const { data } = await capsuleGet(`/opportunities/${input.id}`, {
@@ -2107,32 +2196,32 @@ async function getOpportunity(input) {
   });
   return data;
 }
-var getOpportunitiesSchema = z8.object({
-  ids: z8.array(positiveId).min(1).max(50).describe(
+var getOpportunitiesSchema = z9.object({
+  ids: z9.array(positiveId).min(1).max(50).describe(
     "Array of opportunity IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
   ),
-  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getOpportunities(input) {
   return chunkedMultiGet("/opportunities", "opportunities", input.ids, { embed: input.embed });
 }
-var createOpportunitySchema = z8.object({
-  name: z8.string().min(1),
+var createOpportunitySchema = z9.object({
+  name: z9.string().min(1),
   partyId: positiveId.describe("ID of the party this opportunity belongs to"),
   milestoneId: positiveId.describe(
     "ID of the pipeline milestone to place this opportunity at. The milestone implicitly determines the pipeline \u2014 there is no separate pipelineId parameter. Discover via list_pipelines / list_milestones. NOTE: some Capsule tenants configure **pipeline / milestone-reached automation rules** that mutate `owner` and/or `team` immediately after creation \u2014 e.g. an 'Assign to a Team' action that fires on entry to a specific milestone and has been observed to clear `owner` as an automation side-effect. If you observe a newly-created opp landing with `owner: null` despite passing `ownerId`, the cause is almost certainly a milestone automation on the destination pipeline rather than the connector. Documented workaround: follow `create_opportunity` with an immediate `batch_update_opportunity({items: [{id, ownerId, teamId}]})` carrying both fields \u2014 PUT does not re-fire milestone-reached triggers, so the owner sticks."
   ),
-  description: z8.string().optional(),
+  description: z9.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  probability: z8.number().int().min(0).max(100).optional(),
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  probability: z9.number().int().min(0).max(100).optional(),
   ownerId: positiveId.optional().describe(
     "Assign to user ID. Defaults to the API-token owner when omitted \u2014 note that opportunities do NOT inherit owner from the linked party, even though one might expect it. To clear owner later, call update_opportunity with `ownerId: null`. Discover IDs via list_users. WARNING: tenant pipeline / milestone-reached automation can mutate this field post-create \u2014 see the `milestoneId` description for details and the chained-PUT workaround."
   ),
   teamId: positiveId.optional().describe(
     "Assign to team ID (discover via list_teams). Independent from `ownerId` \u2014 setting one does NOT clear the other on create. Three ownership shapes are valid: owner alone, team alone, or owner+team (the owner must be a member of the team; users can belong to multiple teams \u2014 422 'owner is not a member of the team' otherwise)."
   ),
-  fields: z8.array(CustomFieldWriteSchema).optional().describe(
+  fields: z9.array(CustomFieldWriteSchema).optional().describe(
     fieldsArrayDescriptor("get_opportunity") + " Capsule's POST /opportunities accepts the same `fields[]` shape as PUT (inferred by symmetry with the v1.6.5 wire-trace findings on POST /parties and POST /kases \u2014 the tenant probed had no opportunity custom fields configured, so this is unverified empirically). Setting custom fields on creation removes the create-then-update ritual."
   )
 });
@@ -2149,23 +2238,23 @@ async function createOpportunity(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/opportunities", { opportunity: body });
 }
-var updateOpportunitySchema = z8.object({
+var updateOpportunitySchema = z9.object({
   id: positiveId,
-  name: z8.string().min(1).optional(),
+  name: z9.string().min(1).optional(),
   partyId: positiveId.optional().describe(
     "Reassign the opportunity to a different primary party. Capsule requires every opportunity to have a party \u2014 passing `null` is rejected with 422 'party is required' (use Capsule's web UI if you need to dissolve the link entirely). Discover ids via search_parties / filter_parties. No defensive read-modify-write needed: this connector verified empirically (v1.6.3 wire-trace) that `party` is a standalone PUT field on /opportunities and does not interact with the asymmetric owner/team semantic from NOTES-ON-CAPSULE-API.md \xA727. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_project.partyId`."
   ),
   milestoneId: positiveId.optional().describe(
     "Move the opportunity to this milestone. Side effects depend on the target: closing milestones (Won/Lost) auto-set `closedOn` to today and `probability` to the milestone default (100/0), preserving `lastOpenMilestone` as the previous open stage; moving back to an open milestone clears `closedOn` and re-applies the milestone's default probability (Won/Lost is reversible \u2014 no separate reopen tool). WARNING: Capsule does NOT validate that the new milestone belongs to the opportunity's current pipeline. Passing a milestoneId from a different pipeline silently relocates the opportunity across pipelines, and `lastOpenMilestone` may then reference a milestone in the previous pipeline. Verify against the opportunity's current pipeline (read the opp first, list its pipeline's milestones via list_milestones) before passing a cross-pipeline id. NOTE: changing `milestoneId` can fire **pipeline / milestone-reached automations** that mutate `owner` / `team` on the destination milestone (same shape as `create_opportunity` \u2014 see its `milestoneId` description for the owner-clearing automation caveat). If a milestone-change-and-owner-set in the same call lands with `owner: null`, follow up with a second `update_opportunity` (or `batch_update_opportunity`) carrying both `ownerId` and `teamId` \u2014 milestone-reached triggers only fire on the transition, so a subsequent PUT preserves your values."
   ),
-  description: z8.string().optional(),
+  description: z9.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-  probability: z8.number().int().min(0).max(100).optional().describe(
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  probability: z9.number().int().min(0).max(100).optional().describe(
     "Win probability 0\u2013100. On an open milestone this overrides the milestone's default probability. CANNOT be set in the same call as a closing milestone (Won/Lost) \u2014 Capsule processes the milestone change first, the opportunity becomes closed, then the probability update is rejected as edit-on-closed-opp with 422 'probability can be updated only for open opportunity'. To close an opportunity, leave probability out of the call: it auto-snaps to 100% (Won) or 0% (Lost)."
   ),
   lostReasonId: positiveId.optional().describe(
-    "Reason the opportunity was lost. Only meaningful when transitioning to a Lost milestone \u2014 Capsule silently drops it for other milestones. Without this set, a connector-driven Lost-close leaves `lostReason: null`. Discover IDs via list_lostreasons."
+    "Reason the opportunity was lost. Only meaningful when transitioning to a Lost milestone \u2014 Capsule silently drops it for other milestones. Without this set, a connector-driven Lost-close leaves `lostReason: null`. Discover IDs via list_lost_reasons."
   ),
   ownerId: positiveId.nullable().optional().describe(
     "Reassign owner: pass a user ID to set, or `null` to unassign (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `owner: null` on PUT /opportunities/:id, mirroring the v1.6.4 finding on /parties; brings update_opportunity into parity with update_party and update_project). When you supply `ownerId` and omit `teamId`, the connector fetches the opportunity's current team and includes it in the PUT body to preserve it across the owner change. Without this defensive read, Capsule's PUT would clear the existing team (see NOTES-ON-CAPSULE-API.md \xA727 \u2014 same asymmetric semantic as /kases). Supply `teamId` explicitly on the same call to change the team instead. Combine `ownerId: null` + `teamId: <T>` in one call to transfer an opportunity to team-ownership with no specific user (verified empirically in v1.6.5; the owner-clears-team semantic doesn't fire when owner is being cleared to null)."
@@ -2173,7 +2262,7 @@ var updateOpportunitySchema = z8.object({
   teamId: positiveId.nullable().optional().describe(
     "Reassign team: pass a team ID (discover via list_teams) to set, or `null` to unassign. Capsule preserves the existing owner across a team change (server-side), so `update_opportunity { teamId }` alone is safe \u2014 the owner is carried through. Owner must be a member of the new team or Capsule returns 422 'owner is not a member of the team'. Independent from `ownerId` \u2014 setting `teamId` does NOT clear the owner."
   ),
-  fields: z8.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
+  fields: z9.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
   const { id, partyId, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
@@ -2209,25 +2298,37 @@ var { schema: deleteOpportunitySchema, handler: deleteOpportunity } = defineDele
 });
 
 // src/tools/projects.ts
-import { z as z9 } from "zod";
-var listProjectsSchema = z9.object({
-  status: z9.enum(["OPEN", "CLOSED"]).optional(),
-  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z9.number().int().positive().optional().default(1),
-  perPage: z9.number().int().min(1).max(100).optional().default(25)
+import { z as z10 } from "zod";
+var searchProjectsSchema = z10.object({
+  q: z10.string().optional().describe("Free-text search query"),
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
+});
+async function searchProjects(input) {
+  const path = input.q ? "/kases/search" : "/kases";
+  return capsuleGetList(path, {
+    q: input.q,
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
+}
+var listProjectsSchema = z10.object({
+  status: z10.enum(["OPEN", "CLOSED"]).optional(),
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function listProjects(input) {
-  const { data, nextPage } = await capsuleGet("/kases", {
+  return capsuleGetList("/kases", {
     status: input.status,
     embed: input.embed,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var getProjectSchema = z9.object({
+var getProjectSchema = z10.object({
   id: positiveId,
-  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getProject(input) {
   const { data } = await capsuleGet(`/kases/${input.id}`, {
@@ -2235,20 +2336,20 @@ async function getProject(input) {
   });
   return data;
 }
-var getProjectsSchema = z9.object({
-  ids: z9.array(positiveId).min(1).max(50).describe(
+var getProjectsSchema = z10.object({
+  ids: z10.array(positiveId).min(1).max(50).describe(
     "Array of project IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
   ),
-  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function getProjects(input) {
-  return chunkedMultiGet("/kases", "kases", input.ids, { embed: input.embed });
+  return chunkedMultiGet("/kases", "projects", input.ids, { embed: input.embed });
 }
-var createProjectSchema = z9.object({
-  name: z9.string().min(1),
+var createProjectSchema = z10.object({
+  name: z10.string().min(1),
   partyId: positiveId.describe("ID of the party linked to this project"),
-  description: z9.string().optional(),
-  status: z9.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
+  description: z10.string().optional(),
+  status: z10.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
   ownerId: positiveId.optional().describe(
     "Assign to user ID. Defaults to the API-token owner when omitted, same as create_party / create_opportunity / create_task. NOTE: some Capsule tenants configure board-level **automation rules** that mutate `owner` (and `team`) on project creation \u2014 e.g. an automation that clears `owner` when a project enters a particular board. If you observe a project landing with unexpected `owner: null` after a create_project with `ownerId`, check the target board's automation configuration. Capsule's API itself does not drop `ownerId` when `stageId` is also supplied."
   ),
@@ -2258,8 +2359,8 @@ var createProjectSchema = z9.object({
   stageId: positiveId.optional().describe(
     "Stage (board column) to place the project on. Discover IDs via list_stages \u2014 each stage belongs to one Board, so picking a stageId implicitly picks the board. If omitted, the project is created with no stage assignment (and won't appear on any board). NOTE: tenant-specific board automation rules may run on project creation and mutate `owner` / `team` fields. See `create_project.ownerId` / `create_project.teamId` for the automation caveat. Capsule's create endpoint itself preserves the `ownerId` / `teamId` you supply \u2014 any clearing you observe traces to board automations, not the API."
   ),
-  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  fields: z9.array(CustomFieldWriteSchema).optional().describe(
+  expectedCloseOn: z10.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z10.array(CustomFieldWriteSchema).optional().describe(
     fieldsArrayDescriptor("get_project") + " Verified empirically in v1.6.5 wire-trace: Capsule's POST /kases accepts the same `fields[]` shape as PUT, so callers can set custom field values on creation without a follow-up update. Project-specific: setting a field whose definition lives under a 'data tag' populates the row's internal tagId but does NOT auto-add the data tag to the project's tags array \u2014 use add_tag explicitly if you want it visible via embed=tags."
   )
 });
@@ -2277,11 +2378,11 @@ async function createProject(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/kases", { kase: body });
 }
-var updateProjectSchema = z9.object({
+var updateProjectSchema = z10.object({
   id: positiveId,
-  name: z9.string().min(1).optional(),
-  description: z9.string().optional(),
-  status: z9.enum(["OPEN", "CLOSED"]).optional(),
+  name: z10.string().min(1).optional(),
+  description: z10.string().optional(),
+  status: z10.enum(["OPEN", "CLOSED"]).optional(),
   partyId: positiveId.optional().describe(
     "Reassign the project to a different primary party. Capsule requires every project to have a party \u2014 passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties. NOTE: parent-ref nullability differs by entity \u2014 `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_opportunity.partyId`."
   ),
@@ -2294,8 +2395,8 @@ var updateProjectSchema = z9.object({
   stageId: positiveId.nullable().optional().describe(
     "Move the project to this stage (board column), or `null` to remove from all stages (verified empirically in v1.6.5 wire-trace \u2014 Capsule accepts `stage: null` on PUT /kases/:id and the project no longer appears on any board). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board \u2014 passing a stageId from a different board silently relocates the project across boards. Team and other board-derived defaults are NOT updated to match the new board. Verify against the project's current board (read the project first, list its board's stages) before passing a cross-board id."
   ),
-  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  fields: z9.array(CustomFieldWriteSchema).optional().describe(
+  expectedCloseOn: z10.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z10.array(CustomFieldWriteSchema).optional().describe(
     fieldsArrayDescriptor("get_project") + " Project-specific: setting a field whose definition lives under a 'data tag' populates the row's internal tagId but does NOT auto-add the data tag to the project's tags array \u2014 use add_tag explicitly if you want it visible via embed=tags."
   )
 });
@@ -2309,7 +2410,7 @@ async function updateProject(input) {
   let resolvedTeamId = teamId;
   let resolvedStageId = stageId;
   if (ownerId !== void 0 && (teamId === void 0 || stageId === void 0)) {
-    const current = await readEntityRefs(`/kases/${id}`, "kase");
+    const current = await readEntityRefs(`/kases/${id}`, "project");
     if (teamId === void 0) resolvedTeamId = current.teamId;
     if (stageId === void 0) resolvedStageId = current.stageId;
   }
@@ -2334,23 +2435,22 @@ var { schema: deleteProjectSchema, handler: deleteProject } = defineDelete({
 });
 
 // src/tools/tasks.ts
-import { z as z10 } from "zod";
-var listTasksSchema = z10.object({
+import { z as z11 } from "zod";
+var listTasksSchema = z11.object({
   // Note: Capsule has a third internal status `PENDING` (a task that's
   // part of an active track but not yet "open"), but it can only be
   // reached via track machinery — it is NOT directly settable by
   // /tasks PUT, and a list filter for it returns the same as OPEN
   // anyway. We expose only the two values that are actually filterable
   // by the v2 API.
-  status: z10.enum(["OPEN", "COMPLETED"]).optional().describe(
+  status: z11.enum(["OPEN", "COMPLETED"]).optional().describe(
     "Defaults to OPEN when omitted. Pass COMPLETED to filter to completed tasks, or 'OPEN' explicitly."
   ),
   ownerId: positiveId.optional().describe("Filter to tasks owned by this user ID"),
-  page: z10.number().int().positive().optional().default(1),
-  perPage: z10.number().int().min(1).max(100).optional().default(25)
+  ...paginationFields
 });
 async function listTasks(input) {
-  const { data, nextPage } = await capsuleGet("/tasks", {
+  return capsuleGetList("/tasks", {
     // Default 'OPEN' applied here (not via zod .default()) so that
     // z.infer keeps `status` optional for callers that omit it.
     status: input.status ?? "OPEN",
@@ -2359,28 +2459,27 @@ async function listTasks(input) {
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var getTaskSchema = z10.object({
+var getTaskSchema = z11.object({
   id: positiveId.describe("Task ID")
 });
 async function getTask(input) {
   const { data } = await capsuleGet(`/tasks/${input.id}`);
   return data;
 }
-var getTasksSchema = z10.object({
-  ids: z10.array(positiveId).min(1).max(50).describe(
+var getTasksSchema = z11.object({
+  ids: z11.array(positiveId).min(1).max(50).describe(
     "Array of task IDs (1\u201350). Capsule's native batch-fetch endpoint caps at 10 per request; the connector transparently splits larger sets into 10-id chunks and fans out the Capsule calls in parallel."
   )
 });
 async function getTasks(input) {
   return chunkedMultiGet("/tasks", "tasks", input.ids);
 }
-var createTaskSchema = z10.object({
-  description: z10.string().min(1),
-  dueOn: z10.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"),
-  dueTime: z10.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z10.string().optional(),
+var createTaskSchema = z11.object({
+  description: z11.string().min(1),
+  dueOn: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"),
+  dueTime: z11.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
+  detail: z11.string().optional(),
   ownerId: positiveId.optional().describe(
     "Assign to user ID. Defaults to the API-token owner when omitted. Once set, this connector cannot clear the owner back to null \u2014 use Capsule's web UI for that."
   ),
@@ -2389,10 +2488,7 @@ var createTaskSchema = z10.object({
   projectId: positiveId.optional().describe("Link task to a project (mutually exclusive with partyId/opportunityId)")
 });
 async function createTask(input) {
-  const linked = [input.partyId, input.opportunityId, input.projectId].filter(Boolean);
-  if (linked.length > 1) {
-    throw new Error("Provide at most one of partyId, opportunityId, or projectId");
-  }
+  assertSingleParentRef("create_task", input);
   const { ownerId, partyId, opportunityId, projectId, ...rest } = input;
   const body = { ...rest };
   setRef(body, "owner", ownerId);
@@ -2401,16 +2497,16 @@ async function createTask(input) {
   setRef(body, "kase", projectId);
   return capsulePost("/tasks", { task: body });
 }
-var updateTaskSchema = z10.object({
+var updateTaskSchema = z11.object({
   id: positiveId,
-  description: z10.string().min(1).optional(),
-  dueOn: z10.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  dueTime: z10.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z10.string().optional(),
+  description: z11.string().min(1).optional(),
+  dueOn: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  dueTime: z11.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
+  detail: z11.string().optional(),
   // Capsule rejects direct sets of `PENDING` (which is a track-machinery
   // internal state) with 422 "cannot set task status to PENDING".
   // Only OPEN and COMPLETED are settable here.
-  status: z10.enum(["OPEN", "COMPLETED"]).optional().describe(
+  status: z11.enum(["OPEN", "COMPLETED"]).optional().describe(
     "Set to OPEN or COMPLETED. (PENDING exists internally for track-driven tasks but cannot be set directly via this tool \u2014 Capsule rejects it.) Setting status: OPEN on an already-open task is a true no-op (does not advance updatedAt)."
   ),
   ownerId: positiveId.optional().describe(
@@ -2428,12 +2524,7 @@ var updateTaskSchema = z10.object({
 });
 async function updateTask(input) {
   const { id, ownerId, partyId, opportunityId, projectId, ...rest } = input;
-  const setCount = [partyId, opportunityId, projectId].filter((v) => typeof v === "number").length;
-  if (setCount > 1) {
-    throw new Error(
-      "update_task: provide at most one of partyId, opportunityId, or projectId (Capsule rejects multi-parent tasks with 422 'task can be related to at most one entity')"
-    );
-  }
+  assertSingleParentRef("update_task", { partyId, opportunityId, projectId });
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
@@ -2444,7 +2535,7 @@ async function updateTask(input) {
   setNullableRef(body, "kase", projectId);
   return capsulePut(`/tasks/${id}`, { task: body });
 }
-var completeTaskSchema = z10.object({
+var completeTaskSchema = z11.object({
   id: positiveId
 });
 async function completeTask(input) {
@@ -2452,8 +2543,8 @@ async function completeTask(input) {
     task: { status: "COMPLETED" }
   });
 }
-var batchCompleteTaskSchema = z10.object({
-  ids: z10.array(positiveId).min(1).max(50).describe(
+var batchCompleteTaskSchema = z11.object({
+  ids: z11.array(positiveId).min(1).max(50).describe(
     "Array of 1\u201350 task ids to mark COMPLETED in parallel. Each id resolves to one PUT /tasks/{id}; failures (e.g. 404 for a deleted task) surface per-item in the result array, the rest still complete. Capped at 50."
   )
 });
@@ -2467,77 +2558,59 @@ var { schema: deleteTaskSchema, handler: deleteTask } = defineDelete({
 });
 
 // src/tools/entries.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var listEntriesPagination = {
-  page: z11.number().int().positive().optional().default(1),
-  perPage: z11.number().int().min(1).max(100).optional().default(25),
-  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+  ...paginationFields,
+  embed: embedParam(ENTRY_EMBEDS)
 };
-var listPartyEntriesSchema = z11.object({
+var listPartyEntriesSchema = z12.object({
   partyId: positiveId,
   ...listEntriesPagination,
-  includeLinkedPersons: z11.boolean().optional().describe(
+  includeLinkedPersons: z12.boolean().optional().describe(
     "When true AND `partyId` is an ORGANISATION, also include entries filed against the organisation's linked people (the persons whose `organisation` field references this org). The connector enumerates linked persons via `GET /parties/{orgId}/people`, fans out `GET /parties/{personId}/entries` in parallel (concurrency-capped, default 5 / configurable via `CAPSULE_MCP_BATCH_CONCURRENCY`), and merges into a single feed sorted by `entryAt` descending, deduped by entry id. Default is `false` \u2014 single GET, existing behaviour unchanged. WHY THIS FLAG EXISTS: Capsule's API files each entry against exactly one party row (verified v1.6.6 wire-trace probe 4 \u2014 POST /entries rejects multi-party bodies with 422 'entry must be linked to either a party, opportunity or kase'). For an organisation with multiple contacts, captured emails almost always land on a person row, not the org. As a result, `list_party_entries(orgId)` with `includeLinkedPersons: false` will miss recent customer-facing email \u2014 even though the org's own `lastContactedAt` is updated by the activity. This flag is the correct call for any 'what's new with $ORG?' question. WHEN `partyId` IS A PERSON: silently no-op \u2014 persons have no linked-people relationship in Capsule's data model, so the flag is functionally inert (the connector still issues a cheap `/people` check; the response is empty). LATENCY: 1 + N round trips for an org with N linked people, concurrency-capped (typical: 2-3 waves for N=10). Linked-person enumeration reads the first 100 linked people; use list_employees for explicit pagination when an organisation has more contacts than that. Use `includeLinkedPersons: false` for fast pre-screen reads where you only need the org-row entries (e.g. invoice/contract notes that are typically filed at the org level). PAGINATION CAVEAT: `page` and `perPage` apply to the MERGED window, and the merge has a hard ceiling \u2014 it reliably orders only the most-recent ~100 entries across the org + its people (each party is fetched at Capsule's per-party cap of 100, and a top-100-per-party merge is correct only up to global position 100). Windows that cross the ceiling are truncated to the entries still inside that top-100 set; windows starting beyond it return no entries and end the feed. It does NOT continue into older history. To read a specific contact's full timeline beyond the merged ceiling, call `list_party_entries` on that person's id directly (the default single-GET path paginates natively with no ceiling). For the LLM-driven 'what's the latest with $ORG' query this is the typical use of, the first page is exact and the ceiling is never reached."
   )
 });
+var PER_PARTY_FETCH_CAP = 100;
 async function fanOutPartyEntries(partyIds, embed, perPage) {
-  const concurrency = getBatchConcurrency();
-  const results = new Array(partyIds.length);
-  let cursor = 0;
-  async function worker() {
-    while (true) {
-      const i = cursor;
-      cursor += 1;
-      if (i >= partyIds.length) return;
-      const id = partyIds[i];
-      const { data, nextPage } = await capsuleGet(
-        `/parties/${id}/entries`,
-        {
-          embed,
-          page: 1,
-          perPage
-        }
-      );
-      results[i] = { entries: data.entries, nextPage };
-    }
-  }
-  const workers = [];
-  for (let w = 0; w < Math.min(concurrency, partyIds.length); w++) {
-    workers.push(worker());
-  }
-  await Promise.all(workers);
-  return results;
+  return mapWithConcurrency(partyIds, getBatchConcurrency(), async (id) => {
+    const { data, nextPage } = await capsuleGet(`/parties/${id}/entries`, {
+      embed,
+      page: 1,
+      perPage
+    });
+    return { entries: data.entries, nextPage };
+  });
 }
 function mergedTimelineCandidatePerParty(page, perPage) {
-  return Math.min(page * perPage, 100);
+  return Math.min(page * perPage, PER_PARTY_FETCH_CAP);
 }
 function mergedTimelineNextPage(page, perPage, mergedLength, upstreamHasNextPage) {
   const requestedWindowEnd = page * perPage;
   if (mergedLength > requestedWindowEnd) return page + 1;
-  const nextWindowWithinCap = requestedWindowEnd < 100;
+  const nextWindowWithinCap = requestedWindowEnd < PER_PARTY_FETCH_CAP;
   if (nextWindowWithinCap && upstreamHasNextPage) return page + 1;
   return void 0;
 }
 async function listPartyEntries(input) {
   const { partyId, embed, page, perPage, includeLinkedPersons } = input;
   if (!includeLinkedPersons) {
-    const { data, nextPage: nextPage2 } = await capsuleGet(
-      `/parties/${partyId}/entries`,
-      { embed, page, perPage }
-    );
-    return { ...data, nextPage: nextPage2 };
+    return capsuleGetList(`/parties/${partyId}/entries`, {
+      embed,
+      page,
+      perPage
+    });
   }
   const { data: peopleData } = await capsuleGet(
     `/parties/${partyId}/people`,
-    { page: 1, perPage: 100 }
+    { page: 1, perPage: PER_PARTY_FETCH_CAP }
   );
   const peopleIds = (peopleData.parties ?? []).map((p) => p.id);
   if (peopleIds.length === 0) {
-    const { data, nextPage: nextPage2 } = await capsuleGet(
-      `/parties/${partyId}/entries`,
-      { embed, page, perPage }
-    );
-    return { ...data, nextPage: nextPage2 };
+    return capsuleGetList(`/parties/${partyId}/entries`, {
+      embed,
+      page,
+      perPage
+    });
   }
   const targetIds = [partyId, ...peopleIds];
   const perPartyPages = await fanOutPartyEntries(
@@ -2572,31 +2645,31 @@ async function listPartyEntries(input) {
   );
   return { entries: slice, ...nextPage !== void 0 ? { nextPage } : {} };
 }
-var listOpportunityEntriesSchema = z11.object({
+var listOpportunityEntriesSchema = z12.object({
   opportunityId: positiveId,
   ...listEntriesPagination
 });
 async function listOpportunityEntries(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/opportunities/${input.opportunityId}/entries`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/opportunities/${input.opportunityId}/entries`, {
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
 }
-var listProjectEntriesSchema = z11.object({
+var listProjectEntriesSchema = z12.object({
   projectId: positiveId,
   ...listEntriesPagination
 });
 async function listProjectEntries(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/kases/${input.projectId}/entries`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/kases/${input.projectId}/entries`, {
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
 }
-var getEntrySchema = z11.object({
+var getEntrySchema = z12.object({
   id: positiveId,
-  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+  embed: embedParam(ENTRY_EMBEDS)
 });
 async function getEntry(input) {
   const { data } = await capsuleGet(`/entries/${input.id}`, {
@@ -2604,34 +2677,30 @@ async function getEntry(input) {
   });
   return data;
 }
-var listEntriesSchema = z11.object({
+var listEntriesSchema = z12.object({
   ...listEntriesPagination
 });
 async function listEntries(input) {
-  const { data, nextPage } = await capsuleGet("/entries", {
+  return capsuleGetList("/entries", {
     embed: input.embed,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var addNoteSchema = z11.object({
-  content: z11.string().min(1).describe(
+var addNoteSchema = z12.object({
+  content: z12.string().min(1).describe(
     "Note body text. Stored verbatim and treated as MARKDOWN \u2014 Capsule's web UI renders the markdown when displaying. Pass markdown source ('# Heading', '**bold**', '- bullet'), not HTML."
   ),
   partyId: positiveId.optional().describe("Link note to a party (mutually exclusive with opportunityId/projectId)"),
   opportunityId: positiveId.optional().describe("Link note to an opportunity (mutually exclusive with partyId/projectId)"),
   projectId: positiveId.optional().describe("Link note to a project (mutually exclusive with partyId/opportunityId)"),
-  entryAt: z11.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
+  entryAt: z12.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
     "ISO-8601 timestamp for when this note actually happened (e.g. '2024-03-15T14:30:00Z'). Defaults to now. Use this for backdating historical notes when migrating from another system. `entryAt` is preserved across subsequent update_entry calls; only `updatedAt` advances on edits. Note attribution flows to the API-token owner \u2014 there is no way to record a note as authored by a different user via this connector (a `creatorId` parameter would enable audit-attribution spoofing on shared-connector deployments, so it is intentionally not exposed)."
   )
 });
 async function addNote(input) {
   const { content, partyId, opportunityId, projectId, entryAt } = input;
-  const linked = [partyId, opportunityId, projectId].filter(Boolean);
-  if (linked.length !== 1) {
-    throw new Error("Provide exactly one of partyId, opportunityId, or projectId");
-  }
+  assertSingleParentRef("add_note", input, { required: true });
   const body = { type: "note", content };
   setRef(body, "party", partyId);
   setRef(body, "opportunity", opportunityId);
@@ -2639,12 +2708,12 @@ async function addNote(input) {
   if (entryAt !== void 0) body["entryAt"] = entryAt;
   return capsulePost("/entries", { entry: body });
 }
-var updateEntrySchema = z11.object({
+var updateEntrySchema = z12.object({
   id: positiveId.describe("Entry ID to update"),
-  content: z11.string().min(1).optional().describe(
+  content: z12.string().min(1).optional().describe(
     "New body text for the entry. For notes, this is the markdown content; for emails, the body. Provide only if you want to change it."
   ),
-  subject: z11.string().optional().describe(
+  subject: z12.string().optional().describe(
     "New subject line. Mostly meaningful on email-type entries; on plain notes Capsule accepts the call (HTTP 200) but **does not store the subject and does not advance `updatedAt`** \u2014 a true no-op for inapplicable fields. `entryAt` (when the note was authored) is preserved across edits; `updatedAt` advances only when an applicable field actually changes. To sort/filter by 'when did this happen', use `entryAt`; for 'last touched', use `updatedAt`."
   )
 });
@@ -2666,103 +2735,89 @@ var { schema: deleteEntrySchema, handler: deleteEntry } = defineDelete({
 });
 
 // src/tools/pipelines.ts
-import { z as z12 } from "zod";
-var paginationFields = {
-  page: z12.number().int().positive().optional(),
-  perPage: z12.number().int().min(1).max(100).optional()
-};
-var listPipelinesSchema = z12.object({ ...paginationFields });
+import { z as z13 } from "zod";
+var listPipelinesSchema = z13.object({ ...paginationFieldsNoDefaults });
 async function listPipelines(input) {
-  const { data, nextPage } = await capsuleGetCached("/pipelines", {
+  return capsuleGetCachedList("/pipelines", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var listMilestonesSchema = z12.object({
+var listMilestonesSchema = z13.object({
   pipelineId: positiveId,
-  ...paginationFields
+  ...paginationFieldsNoDefaults
 });
 async function listMilestones(input) {
-  const { data, nextPage } = await capsuleGetCached(
+  return capsuleGetCachedList(
     `/pipelines/${input.pipelineId}/milestones`,
     { page: input.page ?? 1, perPage: input.perPage ?? 100 }
   );
-  return { ...data, nextPage };
 }
 
 // src/tools/boards.ts
-import { z as z13 } from "zod";
-var paginationFields2 = {
-  page: z13.number().int().positive().optional(),
-  perPage: z13.number().int().min(1).max(100).optional()
-};
-var listBoardsSchema = z13.object({ ...paginationFields2 });
+import { z as z14 } from "zod";
+var listBoardsSchema = z14.object({ ...paginationFieldsNoDefaults });
 async function listBoards(input) {
-  const { data, nextPage } = await capsuleGetCached("/boards", {
+  return capsuleGetCachedList("/boards", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var listStagesSchema = z13.object({
+var listStagesSchema = z14.object({
   boardId: positiveId.optional().describe(
     "Optional. If provided, returns only the stages defined on that specific board (uses /boards/{id}/stages). Omit to get all stages across all boards in one call."
   ),
-  ...paginationFields2
+  ...paginationFieldsNoDefaults
 });
 async function listStages(input) {
   const path = input.boardId !== void 0 ? `/boards/${input.boardId}/stages` : "/stages";
-  const { data, nextPage } = await capsuleGetCached(path, {
+  return capsuleGetCachedList(path, {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
 
 // src/tools/tags.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var TAG_LIST_PATH = {
   parties: "/parties/tags",
   opportunities: "/opportunities/tags",
-  kases: "/kases/tags"
+  projects: "/kases/tags"
 };
 var ENTITY_TO_WRAPPER = {
   parties: "party",
   opportunities: "opportunity",
-  kases: "kase"
+  projects: "kase"
 };
-var TagEntity = z14.enum(["parties", "opportunities", "kases"]).describe("Which entity type. Use 'kases' for projects (Capsule's legacy path name).");
-var listTagsSchema = z14.object({
-  entity: z14.enum(["parties", "opportunities", "kases"]).describe("The resource type to list tags for"),
-  page: z14.number().int().positive().optional(),
-  perPage: z14.number().int().min(1).max(100).optional()
+var TagEntity = z15.enum(["parties", "opportunities", "projects"]).describe("Which entity type.");
+var listTagsSchema = z15.object({
+  entity: z15.enum(["parties", "opportunities", "projects"]).describe("The resource type to list tags for"),
+  ...paginationFieldsNoDefaults
 });
 async function listTags(input) {
   const path = TAG_LIST_PATH[input.entity];
-  const { data, nextPage } = await capsuleGetCached(path, {
+  return capsuleGetCachedList(path, {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var addTagSchema = z14.object({
+var addTagSchema = z15.object({
   entity: TagEntity,
   entityId: positiveId.describe("The party/opportunity/kase id."),
-  tagName: z14.string().min(1).describe(
+  tagName: z15.string().min(1).describe(
     "Name of the tag to attach. Capsule resolves by name: if a tag with this name already exists in the tenant it is attached to the entity; if not, Capsule creates the tag and attaches it. Names are tenant-global. Capsule matches case-INSENSITIVELY when resolving (so 'VIP' and 'vip' attach the same tag), preserving the canonical casing from whichever variant was created first. To ensure consistent casing in your tag list, call list_tags first and reuse the exact name from there. Idempotent \u2014 re-attaching an already-attached tag is harmless."
   )
 });
 async function addTag(input) {
   const { entity, entityId, tagName } = input;
   const wrapper = ENTITY_TO_WRAPPER[entity];
-  const result = await capsulePut(`/${entity}/${entityId}`, {
+  const result = await capsulePut(`/${ENTITY_PATH[entity]}/${entityId}`, {
     [wrapper]: { tags: [{ name: tagName }] }
   });
   invalidateByPrefix(TAG_LIST_PATH[entity], "add_tag");
   return result;
 }
-var removeTagByIdSchema = z14.object({
+var removeTagByIdSchema = z15.object({
   entity: TagEntity,
   entityId: positiveId.describe("The party/opportunity/kase id."),
   tagId: positiveId.describe(
@@ -2773,7 +2828,7 @@ async function removeTagById(input) {
   const { entity, entityId, tagId } = input;
   const wrapper = ENTITY_TO_WRAPPER[entity];
   const result = await idempotentWithResult(
-    () => capsulePut(`/${entity}/${entityId}`, {
+    () => capsulePut(`/${ENTITY_PATH[entity]}/${entityId}`, {
       [wrapper]: { tags: [{ id: tagId, _delete: true }] }
     }),
     (result2) => ({
@@ -2793,7 +2848,7 @@ async function removeTagById(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
   return result;
 }
-var deleteTagDefinitionSchema = z14.object({
+var deleteTagDefinitionSchema = z15.object({
   entity: TagEntity,
   tagId: positiveId.describe(
     "The tag definition's id (from list_tags, or embed='tags' on a record). NOT an entity id."
@@ -2808,7 +2863,7 @@ async function deleteTagDefinition(input) {
     throw new Error("delete_tag_definition requires confirm: true");
   }
   const result = await idempotent(
-    () => capsuleDelete(`/${entity}/tags/${tagId}`),
+    () => capsuleDelete(`/${ENTITY_PATH[entity]}/tags/${tagId}`),
     () => ({ deleted: true, alreadyDeleted: false, entity, tagId }),
     () => ({ deleted: true, alreadyDeleted: true, entity, tagId })
   );
@@ -2829,44 +2884,41 @@ var { schema: batchRemoveTagByIdSchema, handler: batchRemoveTagById } = defineBa
 });
 
 // src/tools/users.ts
-import { z as z15 } from "zod";
-var listUsersSchema = z15.object({
-  page: z15.number().int().positive().optional(),
-  perPage: z15.number().int().min(1).max(100).optional()
+import { z as z16 } from "zod";
+var listUsersSchema = z16.object({
+  ...paginationFieldsNoDefaults
 });
 async function listUsers(input) {
-  const { data, nextPage } = await capsuleGetCached("/users", {
+  return capsuleGetCachedList("/users", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var getCurrentUserSchema = z15.object({});
+var getCurrentUserSchema = z16.object({});
 async function getCurrentUser(_input) {
   const { data } = await capsuleGet("/users/current");
   return data;
 }
 
 // src/tools/filters.ts
-import { z as z16 } from "zod";
-var FilterConditionSchema = z16.object({
-  field: z16.string().describe(
+import { z as z17 } from "zod";
+var FilterConditionSchema = z17.object({
+  field: z17.string().describe(
     "The Capsule filter-side field name (these differ from response field names \u2014 e.g. response.createdAt is filter-side 'addedOn', response.lastContactedAt is filter-side 'lastContactedOn'). Common: 'addedOn' (date created), 'updatedOn' (date last modified), 'lastContactedOn' (parties only), 'name', 'tag', 'owner', 'team', 'type' (parties: person|organisation), 'milestone' (opportunities), 'status' (opp/project: OPEN|CLOSED), 'closedOn' (opp/project), 'expectedCloseOn' (opp/project), 'hasTags', 'hasEmailAddress' (parties), 'isOpen', 'isStale' (opportunities), 'custom:{fieldId}'. Full per-entity list: https://developer.capsulecrm.com/v2/reference/filters"
   ),
-  operator: z16.string().describe(
+  operator: z17.string().describe(
     "The filter operator. Common: 'is', 'is not' (use value=null to test for null), 'contains', 'does not contain', 'is greater than', 'is less than', 'is within last' (date fields, value=integer days), 'is more than' (date fields, value=integer days ago), 'starts with', 'ends with'. Operator validity depends on the field's type."
   ),
-  value: z16.union([z16.string(), z16.number(), z16.boolean(), z16.null()]).describe(
+  value: z17.union([z17.string(), z17.number(), z17.boolean(), z17.null()]).describe(
     "The value to compare against. For 'is within last' on date fields, pass an integer number of days. For tag filters, pass the tag name (string) or tag id (number). For 'is not' null tests, pass null literally."
   )
 });
-var FilterInputSchema = z16.object({
-  conditions: z16.array(FilterConditionSchema).min(1).describe(
+var FilterInputSchema = z17.object({
+  conditions: z17.array(FilterConditionSchema).min(1).describe(
     "Array of filter conditions. All conditions are ANDed together. To get newest records, use a date condition like {field: 'addedOn', operator: 'is within last', value: 7} and pick the highest-id row from the result (Capsule IDs are monotonic)."
   ),
-  embed: z16.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z16.number().int().positive().optional().default(1),
-  perPage: z16.number().int().min(1).max(100).optional().default(25)
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function runFilter(entityPath, input) {
   const { data, nextPage } = await capsuleSearch(
@@ -2886,10 +2938,7 @@ async function filterParties(input) {
 }
 var filterOpportunitiesSchema = FilterInputSchema;
 async function filterOpportunities(input) {
-  return runFilter(
-    "opportunities",
-    input
-  );
+  return runFilter("opportunities", input);
 }
 var filterProjectsSchema = FilterInputSchema;
 async function filterProjects(input) {
@@ -2897,139 +2946,129 @@ async function filterProjects(input) {
 }
 
 // src/tools/metadata.ts
-import { z as z17 } from "zod";
-var paginationFields3 = {
-  page: z17.number().int().positive().optional(),
-  perPage: z17.number().int().min(1).max(100).optional().describe("Page size, max 100. Defaults to 100 for reference data.")
+import { z as z18 } from "zod";
+var paginationFields2 = {
+  ...paginationFieldsNoDefaults,
+  perPage: paginationFieldsNoDefaults.perPage.describe(
+    "Page size, max 100. Defaults to 100 for reference data."
+  )
 };
-var listTeamsSchema = z17.object({ ...paginationFields3 });
+var listTeamsSchema = z18.object({ ...paginationFields2 });
 async function listTeams(input) {
-  const { data, nextPage } = await capsuleGetCached("/teams", {
+  return capsuleGetCachedList("/teams", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var listLostReasonsSchema = z17.object({ ...paginationFields3 });
+var listLostReasonsSchema = z18.object({ ...paginationFields2 });
 async function listLostReasons(input) {
-  const { data, nextPage } = await capsuleGetCached("/lostreasons", {
+  return capsuleGetCachedList("/lostreasons", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var listActivityTypesSchema = z17.object({ ...paginationFields3 });
+var listActivityTypesSchema = z18.object({ ...paginationFields2 });
 async function listActivityTypes(input) {
-  const { data, nextPage } = await capsuleGetCached(
-    "/activitytypes",
-    {
-      page: input.page ?? 1,
-      perPage: input.perPage ?? 100
-    }
-  );
-  return { ...data, nextPage };
+  return capsuleGetCachedList("/activitytypes", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
 }
-var getSiteSchema = z17.object({});
+var getSiteSchema = z18.object({});
 async function getSite(_input) {
   const { data } = await capsuleGetCached("/site");
   return data;
 }
-var listTrackDefinitionsSchema = z17.object({ ...paginationFields3 });
+var listTrackDefinitionsSchema = z18.object({ ...paginationFields2 });
 async function listTrackDefinitions(input) {
-  const { data, nextPage } = await capsuleGetCached(
-    "/trackdefinitions",
-    { page: input.page ?? 1, perPage: input.perPage ?? 100 }
-  );
-  return { ...data, nextPage };
+  return capsuleGetCachedList("/trackdefinitions", {
+    page: input.page ?? 1,
+    perPage: input.perPage ?? 100
+  });
 }
-var listCategoriesSchema = z17.object({ ...paginationFields3 });
+var listCategoriesSchema = z18.object({ ...paginationFields2 });
 async function listCategories(input) {
-  const { data, nextPage } = await capsuleGetCached("/categories", {
+  return capsuleGetCachedList("/categories", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
-var listGoalsSchema = z17.object({ ...paginationFields3 });
+var listGoalsSchema = z18.object({ ...paginationFields2 });
 async function listGoals(input) {
-  const { data, nextPage } = await capsuleGetCached("/goals", {
+  return capsuleGetCachedList("/goals", {
     page: input.page ?? 1,
     perPage: input.perPage ?? 100
   });
-  return { ...data, nextPage };
 }
 
 // src/tools/audit.ts
-import { z as z18 } from "zod";
-var listEmployeesSchema = z18.object({
+import { z as z19 } from "zod";
+var listEmployeesSchema = z19.object({
   partyId: positiveId.describe(
     "The organisation's party id. Returns the people whose `organisation` field links to this party."
   ),
-  page: z18.number().int().positive().optional().default(1),
-  perPage: z18.number().int().min(1).max(100).optional().default(25),
-  embed: z18.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  ...paginationFields,
+  embed: embedParam(RECORD_EMBEDS)
 });
 async function listEmployees(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/parties/${input.partyId}/people`,
-    { page: input.page, perPage: input.perPage, embed: input.embed }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/parties/${input.partyId}/people`, {
+    page: input.page,
+    perPage: input.perPage,
+    embed: input.embed
+  });
 }
-var DeletedSinceSchema = z18.string().describe(
+var DeletedSinceSchema = z19.string().describe(
   "REQUIRED. ISO-8601 timestamp; only deletions on or after this point are returned. Example: '2026-01-01T00:00:00Z'."
 );
 var DeletedPagination = {
   since: DeletedSinceSchema,
-  page: z18.number().int().positive().optional().default(1),
-  perPage: z18.number().int().min(1).max(100).optional().default(25)
+  ...paginationFields
 };
-var listDeletedPartiesSchema = z18.object(DeletedPagination);
+var listDeletedPartiesSchema = z19.object(DeletedPagination);
 async function listDeletedParties(input) {
-  const { data, nextPage } = await capsuleGet("/parties/deleted", {
+  return capsuleGetList("/parties/deleted", {
     since: input.since,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var listDeletedOpportunitiesSchema = z18.object(DeletedPagination);
+var listDeletedOpportunitiesSchema = z19.object(DeletedPagination);
 async function listDeletedOpportunities(input) {
-  const { data, nextPage } = await capsuleGet("/opportunities/deleted", {
+  return capsuleGetList("/opportunities/deleted", {
     since: input.since,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var listDeletedProjectsSchema = z18.object(DeletedPagination);
+var listDeletedProjectsSchema = z19.object(DeletedPagination);
 async function listDeletedProjects(input) {
-  const { data, nextPage } = await capsuleGet("/kases/deleted", {
+  return capsuleGetList("/kases/deleted", {
     since: input.since,
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
 
 // src/tools/relationships.ts
-import { z as z19 } from "zod";
-var RelationshipEntity = z19.enum(["opportunities", "kases"]).describe("Which entity has the additional-party links. Use 'kases' for projects.");
-var listAdditionalPartiesSchema = z19.object({
+import { z as z20 } from "zod";
+var RelationshipEntity = z20.enum(["opportunities", "projects"]).describe("Which entity has the additional-party links.");
+var listAdditionalPartiesSchema = z20.object({
   entity: RelationshipEntity,
   entityId: positiveId.describe("ID of the opportunity or project."),
-  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z19.number().int().positive().optional().default(1),
-  perPage: z19.number().int().min(1).max(100).optional().default(25)
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function listAdditionalParties(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/${input.entity}/${input.entityId}/parties`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
+  return capsuleGetList(
+    `/${ENTITY_PATH[input.entity]}/${input.entityId}/parties`,
+    {
+      embed: input.embed,
+      page: input.page,
+      perPage: input.perPage
+    }
   );
-  return { ...data, nextPage };
 }
-var addAdditionalPartySchema = z19.object({
+var addAdditionalPartySchema = z20.object({
   entity: RelationshipEntity,
   entityId: positiveId,
   partyId: positiveId.describe(
@@ -3038,7 +3077,9 @@ var addAdditionalPartySchema = z19.object({
 });
 async function addAdditionalParty(input) {
   try {
-    await capsulePostNoContent(`/${input.entity}/${input.entityId}/parties/${input.partyId}`);
+    await capsulePostNoContent(
+      `/${ENTITY_PATH[input.entity]}/${input.entityId}/parties/${input.partyId}`
+    );
     return {
       linked: true,
       alreadyLinked: false,
@@ -3062,7 +3103,7 @@ async function addAdditionalParty(input) {
     throw err;
   }
 }
-var removeAdditionalPartySchema = z19.object({
+var removeAdditionalPartySchema = z20.object({
   entity: RelationshipEntity,
   entityId: positiveId,
   partyId: positiveId,
@@ -3075,7 +3116,7 @@ async function removeAdditionalParty(input) {
     throw new Error("remove_additional_party requires confirm: true");
   }
   return idempotent(
-    () => capsuleDelete(`/${input.entity}/${input.entityId}/parties/${input.partyId}`),
+    () => capsuleDelete(`/${ENTITY_PATH[input.entity]}/${input.entityId}/parties/${input.partyId}`),
     () => ({
       removed: true,
       alreadyRemoved: false,
@@ -3092,70 +3133,69 @@ async function removeAdditionalParty(input) {
     })
   );
 }
-var listAssociatedProjectsSchema = z19.object({
+var listAssociatedProjectsSchema = z20.object({
   opportunityId: positiveId,
-  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z19.number().int().positive().optional().default(1),
-  perPage: z19.number().int().min(1).max(100).optional().default(25)
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function listAssociatedProjects(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/opportunities/${input.opportunityId}/kases`,
-    { embed: input.embed, page: input.page, perPage: input.perPage }
-  );
-  return { ...data, nextPage };
+  return capsuleGetList(`/opportunities/${input.opportunityId}/kases`, {
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
 }
 
 // src/tools/custom-fields.ts
-import { z as z20 } from "zod";
-var CustomFieldEntity = z20.enum(["parties", "opportunities", "kases"]).describe("Which entity type's custom field schema to inspect. Use 'kases' for projects.");
-var listCustomFieldsSchema = z20.object({
+import { z as z21 } from "zod";
+var CustomFieldEntity = z21.enum(["parties", "opportunities", "projects"]).describe("Which entity type's custom field schema to inspect.");
+var listCustomFieldsSchema = z21.object({
   entity: CustomFieldEntity
 });
 async function listCustomFields(input) {
   const { data } = await capsuleGetCached(
-    `/${input.entity}/fields/definitions`
+    `/${ENTITY_PATH[input.entity]}/fields/definitions`
   );
   return data;
 }
-var getCustomFieldSchema = z20.object({
+var getCustomFieldSchema = z21.object({
   entity: CustomFieldEntity,
-  fieldId: positiveId.describe("Custom field definition id.")
+  id: positiveId.describe("Custom field definition id.")
 });
 async function getCustomField(input) {
   const { data } = await capsuleGetCached(
-    `/${input.entity}/fields/definitions/${input.fieldId}`
+    `/${input.entity}/fields/definitions/${input.id}`
   );
   return data;
 }
 
 // src/tools/tracks.ts
-import { z as z21 } from "zod";
-var TrackEntity = z21.enum(["parties", "opportunities", "kases"]).describe("Use 'kases' for projects.");
-var listEntityTracksSchema = z21.object({
+import { z as z22 } from "zod";
+var TrackEntity = z22.enum(["parties", "opportunities", "projects"]).describe("Which entity type.");
+var listEntityTracksSchema = z22.object({
   entity: TrackEntity,
   entityId: positiveId
 });
 async function listEntityTracks(input) {
   const { data } = await capsuleGet(
-    `/${input.entity}/${input.entityId}/tracks`
+    `/${ENTITY_PATH[input.entity]}/${input.entityId}/tracks`
   );
   return data;
 }
-var showTrackSchema = z21.object({
-  trackId: positiveId
+var getTrackSchema = z22.object({
+  id: positiveId
 });
-async function showTrack(input) {
-  const { data } = await capsuleGet(`/tracks/${input.trackId}`);
+async function getTrack(input) {
+  const { data } = await capsuleGet(`/tracks/${input.id}`);
   return data;
 }
-var applyTrackSchema = z21.object({
-  entity: z21.enum(["opportunities", "kases"]).describe("Which entity to apply the track to. Use 'kases' for projects."),
+var applyTrackSchema = z22.object({
+  entity: z22.enum(["opportunities", "projects"]).describe("Which entity to apply the track to."),
   entityId: positiveId,
   trackDefinitionId: positiveId.describe(
     "The trackDefinition to apply (from list_track_definitions). Auto-creates task definitions on the target entity per the track's rules."
   ),
-  startDate: z21.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe(
+  startDate: z22.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe(
     "Optional ISO-8601 date (YYYY-MM-DD) the track should start from \u2014 drives task due-date calculations (each task's `dueOn` is computed as startDate + the track-definition's `daysAfter` offset). Defaults to today if omitted. Useful for scheduling a renewal-queue track against a future contract end-date, or backfilling tracks for historical projects."
   )
 });
@@ -3168,9 +3208,9 @@ async function applyTrack(input) {
   if (input.startDate !== void 0) track["trackDateOn"] = input.startDate;
   return capsulePost("/tracks", { track });
 }
-var updateTrackSchema = z21.object({
-  trackId: positiveId,
-  fields: z21.record(z21.string(), z21.unknown()).describe(
+var updateTrackSchema = z22.object({
+  id: positiveId,
+  fields: z22.record(z22.string(), z22.unknown()).describe(
     "Object of fields to update on the track. Capsule's PUT semantics are partial \u2014 only the fields you provide are changed. Common: { complete: true } to mark a track completed. Capsule rejects unknown keys; consult Capsule's docs for the full updatable set."
   )
 });
@@ -3178,12 +3218,12 @@ async function updateTrack(input) {
   if (Object.keys(input.fields).length === 0) {
     throw new Error("update_track: provide at least one field in `fields`");
   }
-  return capsulePut(`/tracks/${input.trackId}`, {
+  return capsulePut(`/tracks/${input.id}`, {
     track: input.fields
   });
 }
-var removeTrackSchema = z21.object({
-  trackId: positiveId,
+var removeTrackSchema = z22.object({
+  id: positiveId,
   confirm: confirmFlag().describe(
     "Must be set to true. Removes the track instance from its entity. **Capsule also deletes the auto-tasks the track created when it was applied** \u2014 they go with the track and become unreachable (404 on GET /tasks/{id}, gone from list_tasks on the parent entity). If you need any of those tasks to outlive the track, copy their content into fresh tasks (or use the web UI) before calling remove_track."
   )
@@ -3193,20 +3233,20 @@ async function removeTrack(input) {
     throw new Error("remove_track requires confirm: true");
   }
   return idempotent(
-    () => capsuleDelete(`/tracks/${input.trackId}`),
-    () => ({ removed: true, alreadyRemoved: false, trackId: input.trackId }),
-    () => ({ removed: true, alreadyRemoved: true, trackId: input.trackId })
+    () => capsuleDelete(`/tracks/${input.id}`),
+    () => ({ removed: true, alreadyRemoved: false, id: input.id }),
+    () => ({ removed: true, alreadyRemoved: true, id: input.id })
   );
 }
 
 // src/tools/attachments.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 var DEFAULT_MAX_SIZE_BYTES = 5 * 1024 * 1024;
 var HARD_MAX_SIZE_BYTES = 25 * 1024 * 1024;
 var HARD_MAX_BASE64_CHARS = Math.ceil(HARD_MAX_SIZE_BYTES / 3) * 4;
-var getAttachmentSchema = z22.object({
+var getAttachmentSchema = z23.object({
   id: positiveId.describe("Attachment ID."),
-  maxSizeBytes: z22.number().int().positive().max(HARD_MAX_SIZE_BYTES).optional().describe(
+  maxSizeBytes: z23.number().int().positive().max(HARD_MAX_SIZE_BYTES).optional().describe(
     `Refuse to return content over this size (default ${DEFAULT_MAX_SIZE_BYTES} bytes \u2248 5MB; max ${HARD_MAX_SIZE_BYTES} bytes \u2248 25MB). Files exceeding the cap return metadata only with a 'truncated: true' flag.`
   )
 });
@@ -3221,17 +3261,17 @@ async function getAttachment(input) {
   }
   return { contentType, buffer, sizeBytes };
 }
-var uploadAttachmentSchema = z22.object({
-  filename: z22.string().min(1).describe(
+var uploadAttachmentSchema = z23.object({
+  filename: z23.string().min(1).describe(
     "Filename Capsule should record (e.g. 'contract.pdf'). Capsule does NOT validate consistency between filename, contentType, and the actual bytes \u2014 a typo in either is accepted and the file is stored as labelled."
   ),
-  contentType: z22.string().min(1).describe(
+  contentType: z23.string().min(1).describe(
     "MIME type of the file (e.g. 'application/pdf', 'image/png', 'text/plain'). Trusted by Capsule verbatim; not cross-checked against `filename` or the actual bytes."
   ),
-  dataBase64: z22.string().min(1).max(HARD_MAX_BASE64_CHARS).describe(
+  dataBase64: z23.string().min(1).max(HARD_MAX_BASE64_CHARS).describe(
     "File contents, base64-encoded. Decoded server-side and uploaded as the request body. Maximum 25 MB per attachment (Capsule's documented limit); the connector rejects oversized base64 before uploading. The inbound HTTP body limit is ~35 MB which leaves room for the base64 expansion of a 25 MB binary."
   ),
-  content: z22.string().optional().describe(
+  content: z23.string().optional().describe(
     "Body text for the note that will hold the attachment. Defaults to '[attachment]' if omitted."
   ),
   partyId: positiveId.optional().describe("Link the new note to a party (mutually exclusive with opportunityId / projectId)."),
@@ -3249,12 +3289,7 @@ function decodedBase64Size(s) {
   return s.length / 4 * 3 - padding;
 }
 async function uploadAttachment(input) {
-  const linked = [input.partyId, input.opportunityId, input.projectId].filter(Boolean);
-  if (linked.length !== 1) {
-    throw new Error(
-      "upload_attachment: provide exactly one of partyId, opportunityId, or projectId"
-    );
-  }
+  assertSingleParentRef("upload_attachment", input, { required: true });
   if (!isValidBase64(input.dataBase64)) {
     throw new Error(
       "upload_attachment: dataBase64 is not valid base64 \u2014 Node's tolerant decoder would silently produce corrupt bytes. Verify the encoding (RFC 4648, padded with '=' to a multiple of 4 chars)."
@@ -3279,37 +3314,39 @@ async function uploadAttachment(input) {
     content: input.content ?? "[attachment]",
     attachments: [{ token }]
   };
-  if (input.partyId) entryBody["party"] = { id: input.partyId };
-  if (input.opportunityId) entryBody["opportunity"] = { id: input.opportunityId };
-  if (input.projectId) entryBody["kase"] = { id: input.projectId };
+  setRef(entryBody, "party", input.partyId);
+  setRef(entryBody, "opportunity", input.opportunityId);
+  setRef(entryBody, "kase", input.projectId);
   return capsulePost("/entries", { entry: entryBody });
 }
 
 // src/tools/saved-filters.ts
-import { z as z23 } from "zod";
-var EntitySchema = z23.enum(["parties", "opportunities", "kases"]).describe(
-  "Which entity type the filter operates over. Use 'kases' for projects (Capsule's legacy name)."
-);
-var listSavedFiltersSchema = z23.object({
+import { z as z24 } from "zod";
+var EntitySchema = z24.enum(["parties", "opportunities", "projects"]).describe("Which entity type the filter operates over.");
+var listSavedFiltersSchema = z24.object({
   entity: EntitySchema
 });
 async function listSavedFilters(input) {
-  const { data } = await capsuleGetCached(`/${input.entity}/filters`);
+  const { data } = await capsuleGetCached(
+    `/${ENTITY_PATH[input.entity]}/filters`
+  );
   return data;
 }
-var runSavedFilterSchema = z23.object({
+var runSavedFilterSchema = z24.object({
   entity: EntitySchema,
   id: positiveId.describe("The saved filter id (from list_saved_filters)."),
-  embed: z23.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z23.number().int().positive().optional().default(1),
-  perPage: z23.number().int().min(1).max(100).optional().default(25)
+  embed: embedParam(RECORD_EMBEDS),
+  ...paginationFields
 });
 async function runSavedFilter(input) {
-  const { data, nextPage } = await capsuleGet(
-    `/${input.entity}/filters/${input.id}/results`,
-    { page: input.page, perPage: input.perPage, embed: input.embed }
+  return capsuleGetList(
+    `/${ENTITY_PATH[input.entity]}/filters/${input.id}/results`,
+    {
+      page: input.page,
+      perPage: input.perPage,
+      embed: input.embed
+    }
   );
-  return { ...data, nextPage };
 }
 
 // src/server.ts
@@ -3320,7 +3357,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.8.0",
+      version: "2.0.0",
       description: "Read and (optionally) modify Capsule CRM data \u2014 parties, opportunities, projects, tasks, timeline entries, pipelines, tags.",
       websiteUrl: "https://github.com/soil-dev/capsulemcp",
       icons: ICONS
@@ -3437,7 +3474,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "delete_party",
-      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a party (person or organisation). Cascades to all linked notes, tasks, opportunities, AND projects (kases). Deleting an organisation does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. TRACK INSTANCES applied to cascaded opportunities/projects are NOT cleaned up either \u2014 they survive as orphan records reachable only by track id via show_track. Use remove_track on each track explicitly before deleting the parent party if orphan accumulation matters (rare in practice \u2014 orphans are unreachable from normal navigation). Requires confirm=true. Always read the party first with get_party and confirm with the user before calling. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the party was already gone (Capsule's 404 is caught internally so reconciliation loops can re-issue safely).",
+      "DESTRUCTIVE & IRREVERSIBLE: permanently delete a party (person or organisation). Cascades to all linked notes, tasks, opportunities, AND projects. Deleting an organisation does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. TRACK INSTANCES applied to cascaded opportunities/projects are NOT cleaned up either \u2014 they survive as orphan records reachable only by track id via get_track. Use remove_track on each track explicitly before deleting the parent party if orphan accumulation matters (rare in practice \u2014 orphans are unreachable from normal navigation). Requires confirm=true. Always read the party first with get_party and confirm with the user before calling. Idempotent on retry: response is `{deleted: true, alreadyDeleted: false, id}` on a fresh delete or `{deleted: true, alreadyDeleted: true, id}` if the party was already gone (Capsule's 404 is caught internally so reconciliation loops can re-issue safely).",
       deletePartySchema,
       deleteParty
     );
@@ -3536,7 +3573,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server,
     "list_additional_parties",
-    "List secondary party links on an opportunity or project. The 'main' party is on the entity itself (opportunity.party); additional parties are e.g. partners, consultants, or referrers also involved in the deal. Set entity to 'opportunities' or 'kases' (Capsule's term for projects).",
+    "List secondary party links on an opportunity or project. The 'main' party is on the entity itself (opportunity.party); additional parties are e.g. partners, consultants, or referrers also involved in the deal. Set entity to 'opportunities' or 'projects'.",
     listAdditionalPartiesSchema,
     listAdditionalParties
   );
@@ -3577,10 +3614,17 @@ function createCapsuleMcpServer(opts) {
       deleteOpportunity
     );
   }
+  registerTool(
+    server,
+    "search_projects",
+    "Free-text search projects in Capsule CRM (matches name and description). Returns results in Capsule's default order (no sort parameter is supported here). Omit `q` to list all projects. For structured queries \u2014 'most recent project', 'projects opened this month', 'projects tagged X' \u2014 use filter_projects instead.",
+    searchProjectsSchema,
+    searchProjects
+  );
   registerTool(
     server,
     "list_projects",
-    "List projects (cases) in Capsule CRM, optionally filtered by status. Returns results in Capsule's default order (no sort parameter is supported here). For structured queries \u2014 'most recent project', 'projects opened this month', 'projects tagged X' \u2014 use filter_projects instead.",
+    "List projects (cases) in Capsule CRM, optionally filtered by status. Returns results in Capsule's default order (no sort parameter is supported here). For free-text matching use search_projects; for structured queries \u2014 'most recent project', 'projects opened this month', 'projects tagged X' \u2014 use filter_projects instead.",
     listProjectsSchema,
     listProjects
   );
@@ -3608,7 +3652,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server,
     "list_deleted_projects",
-    "Audit feature: list projects deleted on or after a given timestamp. The `since` parameter is REQUIRED. Response also includes a `restrictedKases` key for records the integration user can't read fully.",
+    "Audit feature: list projects deleted on or after a given timestamp. The `since` parameter is REQUIRED. Response also includes a `restrictedProjects` key for records the integration user can't read fully.",
     listDeletedProjectsSchema,
     listDeletedProjects
   );
@@ -3770,20 +3814,72 @@ function createCapsuleMcpServer(opts) {
     listEntriesSchema,
     listEntries
   );
-  server.tool(
-    "get_attachment",
-    "Download an attachment by id. Returns image content for image/* types (Claude can describe it natively); decoded text for text/* and application/json (small files); JSON metadata + base64 payload for other binary types (PDF, Office docs, etc.). Files exceeding maxSizeBytes (default 5MB) return metadata only with a `truncated: true` flag.",
-    getAttachmentSchema.shape,
-    // get_attachment is read-only — downloads a binary, never mutates.
-    // Mirrors the auto-inferred `{readOnlyHint: true, destructiveHint:
-    // false}` that `registerTool` applies to every other `get_*` tool.
-    // Explicit destructiveHint: false is load-bearing — MCP spec
-    // defaults destructiveHint to `true`, so omitting it would (in
-    // some client implementations) classify this read as destructive.
-    { readOnlyHint: true, destructiveHint: false },
-    async (input) => {
-      const result = await getAttachment(input);
-      if (result.truncated) {
+  if (shouldRegister("get_attachment")) {
+    server.tool(
+      "get_attachment",
+      "Download an attachment by id. Returns image content for image/* types (Claude can describe it natively); decoded text for text/* and application/json (small files); JSON metadata + base64 payload for other binary types (PDF, Office docs, etc.). Files exceeding maxSizeBytes (default 5MB) return metadata only with a `truncated: true` flag.",
+      getAttachmentSchema.shape,
+      // get_attachment is read-only — downloads a binary, never mutates.
+      // Mirrors the auto-inferred `{readOnlyHint: true, destructiveHint:
+      // false}` that `registerTool` applies to every other `get_*` tool.
+      // Explicit destructiveHint: false is load-bearing — MCP spec
+      // defaults destructiveHint to `true`, so omitting it would (in
+      // some client implementations) classify this read as destructive.
+      { readOnlyHint: true, destructiveHint: false },
+      async (input) => {
+        const result = await getAttachment(input);
+        if (result.truncated) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    id: input.id,
+                    contentType: result.contentType,
+                    sizeBytes: result.sizeBytes,
+                    truncated: true,
+                    message: `File exceeds the size cap (${input.maxSizeBytes ?? "default"} bytes). Increase maxSizeBytes if you need the bytes; max is 25MB.`
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        const baseType = result.contentType.split(";")[0].trim().toLowerCase();
+        if (baseType.startsWith("image/")) {
+          return {
+            content: [
+              {
+                type: "image",
+                data: result.buffer.toString("base64"),
+                mimeType: result.contentType
+              }
+            ]
+          };
+        }
+        const isText = baseType.startsWith("text/") || baseType === "application/json" || baseType === "application/xml";
+        if (isText) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    id: input.id,
+                    contentType: result.contentType,
+                    sizeBytes: result.sizeBytes
+                  },
+                  null,
+                  2
+                )
+              },
+              { type: "text", text: result.buffer.toString("utf8") }
+            ]
+          };
+        }
         return {
           content: [
             {
@@ -3793,8 +3889,7 @@ function createCapsuleMcpServer(opts) {
                   id: input.id,
                   contentType: result.contentType,
                   sizeBytes: result.sizeBytes,
-                  truncated: true,
-                  message: `File exceeds the size cap (${input.maxSizeBytes ?? "default"} bytes). Increase maxSizeBytes if you need the bytes; max is 25MB.`
+                  base64: result.buffer.toString("base64")
                 },
                 null,
                 2
@@ -3803,57 +3898,8 @@ function createCapsuleMcpServer(opts) {
           ]
         };
       }
-      const baseType = result.contentType.split(";")[0].trim().toLowerCase();
-      if (baseType.startsWith("image/")) {
-        return {
-          content: [
-            {
-              type: "image",
-              data: result.buffer.toString("base64"),
-              mimeType: result.contentType
-            }
-          ]
-        };
-      }
-      const isText = baseType.startsWith("text/") || baseType === "application/json" || baseType === "application/xml";
-      if (isText) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  id: input.id,
-                  contentType: result.contentType,
-                  sizeBytes: result.sizeBytes
-                },
-                null,
-                2
-              )
-            },
-            { type: "text", text: result.buffer.toString("utf8") }
-          ]
-        };
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                id: input.id,
-                contentType: result.contentType,
-                sizeBytes: result.sizeBytes,
-                base64: result.buffer.toString("base64")
-              },
-              null,
-              2
-            )
-          }
-        ]
-      };
-    }
-  );
+    );
+  }
   if (!readOnly) {
     registerTool(
       server,
@@ -3921,14 +3967,14 @@ function createCapsuleMcpServer(opts) {
   );
   registerTool(
     server,
-    "list_lostreasons",
+    "list_lost_reasons",
     "List all configured opportunity-loss reasons (e.g. 'Poor Qualification', 'Lost to competitor', 'Price too high'). Returns each reason's id and name; the set is account-configured rather than a fixed enum, so call this to discover valid ids before referencing a lostReason in update_opportunity when closing a deal as lost. Useful for analysing closed-lost opportunities by reason.",
     listLostReasonsSchema,
     listLostReasons
   );
   registerTool(
     server,
-    "list_activitytypes",
+    "list_activity_types",
     "List all configured activity types (e.g. Call, Meeting, Email). These are the categories used when logging timeline entries via add_note. Returns each type's id and name. The set is account-configured rather than a fixed enum, so call this to discover valid values before referencing an activityType in entry creation.",
     listActivityTypesSchema,
     listActivityTypes
@@ -3956,10 +4002,10 @@ function createCapsuleMcpServer(opts) {
   );
   registerTool(
     server,
-    "show_track",
+    "get_track",
     "Fetch a single track instance by id. Returns the minimal Capsule projection: id, description, trackDateOn, direction, and the array of tasks attached to the track. Capsule's GET /tracks/{id} does NOT include a trackDefinition link, an entity reference, or a completion field \u2014 to find the entity a track is applied to, use list_entity_tracks (which lists track instances by their parent entity); to check completion, the track-tasks' own statuses are the proxy.",
-    showTrackSchema,
-    showTrack
+    getTrackSchema,
+    getTrack
   );
   registerTool(
     server,
@@ -3992,7 +4038,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server,
     "list_tags",
-    "List all tags available for a given entity type (parties, opportunities, or kases). Returns each tag's id, name, and any data-tag field schema. Tags are entity-specific \u2014 a party tag is not interchangeable with an opportunity tag. Use this to discover valid tag ids before calling add_tag, or to display the tag catalogue to the user when they ask 'what tags do we use?'",
+    "List all tags available for a given entity type (parties, opportunities, or projects). Returns each tag's id, name, and any data-tag field schema. Tags are entity-specific \u2014 a party tag is not interchangeable with an opportunity tag. Use this to discover valid tag ids before calling add_tag, or to display the tag catalogue to the user when they ask 'what tags do we use?'",
     listTagsSchema,
     listTags
   );
@@ -4014,7 +4060,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "delete_tag_definition",
-      "DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION from an entity type's tag namespace (parties / opportunities / kases). Unlike remove_tag_by_id \u2014 which detaches a tag from ONE record and leaves the definition intact for others \u2014 this removes the definition itself, so the tag disappears from EVERY record that shared it. Use it to clean up stray / mistyped / test tag definitions polluting the tenant-global list. Requires confirm=true. Always read the affected tag first via list_tags and confirm with the user; if you only want to untag one record, use remove_tag_by_id instead. Irreversible (re-creating by name via add_tag mints a brand-new id). Idempotent on retry: `{deleted: true, alreadyDeleted: false, entity, tagId}` on a fresh delete, or `{deleted: true, alreadyDeleted: true, entity, tagId}` if the definition was already gone (Capsule's 404 is caught). Endpoint verified empirically (DELETE /<entity>/tags/{id} \u2192 204).",
+      "DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION from an entity type's tag namespace (parties / opportunities / projects). Unlike remove_tag_by_id \u2014 which detaches a tag from ONE record and leaves the definition intact for others \u2014 this removes the definition itself, so the tag disappears from EVERY record that shared it. Use it to clean up stray / mistyped / test tag definitions polluting the tenant-global list. Requires confirm=true. Always read the affected tag first via list_tags and confirm with the user; if you only want to untag one record, use remove_tag_by_id instead. Irreversible (re-creating by name via add_tag mints a brand-new id). Idempotent on retry: `{deleted: true, alreadyDeleted: false, entity, tagId}` on a fresh delete, or `{deleted: true, alreadyDeleted: true, entity, tagId}` if the definition was already gone (Capsule's 404 is caught). Endpoint verified empirically (DELETE /<entity>/tags/{id} \u2192 204).",
       deleteTagDefinitionSchema,
       deleteTagDefinition
     );
@@ -4229,77 +4275,51 @@ a{color:#1e3a8a}
     }
     next();
   };
-  app2.post(
-    "/mcp",
+  const mcpGuards = [
     guardOrigin,
     requireBearerAuth({
       verifier: oauthProvider2,
       resourceMetadataUrl: mcpResourceMetadataUrl
     }),
     mcpRateLimit,
-    guardProtocolVersion,
-    express.json({ limit: jsonLimit2 }),
-    async (req, res) => {
-      try {
-        const clientId = req.auth?.clientId;
-        const server = createCapsuleMcpServer({ clientId });
-        const transport = new StreamableHTTPServerTransport({});
-        res.on("close", () => {
-          void transport.close();
-          void server.close();
-        });
-        await withRequestContext({ clientId }, async () => {
-          await server.connect(transport);
-          await transport.handleRequest(req, res, req.body);
-        });
-      } catch (err) {
-        const name = err instanceof Error ? err.name : typeof err;
-        const status = err && typeof err === "object" && "status" in err ? Number(err.status) : void 0;
-        const summary = status !== void 0 ? `${name} ${status}` : name;
-        if (process.env["MCP_HTTP_DEBUG"] === "1") {
-          const message = err instanceof Error ? err.message : String(err);
-          console.error(`[capsulemcp] /mcp error: ${summary} \u2014 ${message}`);
-        } else {
-          console.error(`[capsulemcp] /mcp error: ${summary}`);
-        }
-        if (!res.headersSent) {
-          res.status(500).json({ error: "internal_error" });
-        }
-      }
-    }
-  );
-  app2.get(
-    "/mcp",
-    guardOrigin,
-    requireBearerAuth({
-      verifier: oauthProvider2,
-      resourceMetadataUrl: mcpResourceMetadataUrl
-    }),
-    mcpRateLimit,
-    guardProtocolVersion,
-    (_req, res) => {
-      res.set("Allow", "POST").status(405).json({
-        error: "method_not_allowed",
-        message: "Use POST for MCP requests; this server runs in stateless mode."
+    guardProtocolVersion
+  ];
+  const methodNotAllowed = (_req, res) => {
+    res.set("Allow", "POST").status(405).json({
+      error: "method_not_allowed",
+      message: "Use POST for MCP requests; this server runs in stateless mode."
+    });
+  };
+  app2.post("/mcp", ...mcpGuards, express.json({ limit: jsonLimit2 }), async (req, res) => {
+    try {
+      const clientId = req.auth?.clientId;
+      const server = createCapsuleMcpServer({ clientId });
+      const transport = new StreamableHTTPServerTransport({});
+      res.on("close", () => {
+        void transport.close();
+        void server.close();
       });
-    }
-  );
-  app2.delete(
-    "/mcp",
-    guardOrigin,
-    requireBearerAuth({
-      verifier: oauthProvider2,
-      resourceMetadataUrl: mcpResourceMetadataUrl
-    }),
-    mcpRateLimit,
-    guardProtocolVersion,
-    (_req, res) => {
-      res.set("Allow", "POST").status(405).json({
-        error: "method_not_allowed",
-        message: "Use POST for MCP requests; this server runs in stateless mode."
+      await withRequestContext({ clientId }, async () => {
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
       });
+    } catch (err) {
+      const name = err instanceof Error ? err.name : typeof err;
+      const status = err && typeof err === "object" && "status" in err ? Number(err.status) : void 0;
+      const summary = status !== void 0 ? `${name} ${status}` : name;
+      if (process.env["MCP_HTTP_DEBUG"] === "1") {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[capsulemcp] /mcp error: ${summary} \u2014 ${message}`);
+      } else {
+        console.error(`[capsulemcp] /mcp error: ${summary}`);
+      }
+      if (!res.headersSent) {
+        res.status(500).json({ error: "internal_error" });
+      }
     }
-  );
+  });
+  app2.get("/mcp", ...mcpGuards, methodNotAllowed);
+  app2.delete("/mcp", ...mcpGuards, methodNotAllowed);
   return app2;
 }