capsulemcp 1.7.0 → 1.8.1

package/dist/index.js

@@ -31,6 +31,22 @@ var chainHandlers = {
   "capsule.request": (ctx) => {
     ctx.capsuleCalls += 1;
   },
+  // A timed-out or connection-failed call is still an attempt that
+  // never reaches the `capsule.request` emit (it throws at the fetch
+  // stage). Count it here so `tool.chain.capsuleCalls` stays honest and
+  // a chain whose duration ballooned is explained by a visible failure.
+  "capsule.timeout": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  "capsule.error": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
+  // A request that exhausted its 429 retry is a real (doubly-attempted)
+  // outbound call that throws before `capsule.request` fires — count it
+  // so a chain whose latency ballooned on rate-limit backoff is explained.
+  "capsule.ratelimit": (ctx) => {
+    ctx.capsuleCalls += 1;
+  },
   // Cache-hit events feed the aggregate so the chain stat is right
   // even on tools whose Capsule calls all hit the cache.
   "cache.hit": (ctx) => {
@@ -166,6 +182,15 @@ var CapsuleApiError = class extends Error {
   }
   status;
 };
+var CapsuleTimeoutError = class extends CapsuleApiError {
+  constructor() {
+    super(
+      504,
+      `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
+    );
+    this.name = "CapsuleTimeoutError";
+  }
+};
 function getToken() {
   const token = process.env["CAPSULE_API_TOKEN"];
   if (!token) {
@@ -228,72 +253,74 @@ 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))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    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();
-    if (err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message))) {
-      throw new CapsuleApiError(
-        504,
-        `Capsule API request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s. The Capsule API may be slow or hung; retry after a short wait. If the failed call was a write/delete, read the entity first to see whether the change actually applied before retrying.`
-      );
+    const isAbort = isTimeoutAbort(err);
+    emitCapsuleFailure(
+      options?.method ?? "GET",
+      url,
+      Date.now() - startedAt,
+      isAbort ? "timeout" : "network",
+      isAbort ? void 0 : err
+    );
+    if (isAbort) {
+      throw new CapsuleTimeoutError();
     }
     throw err;
   }
 }
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
 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();
+  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();
+    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 {
-    return await body();
-  } finally {
+    const result = await body();
     emitCapsuleRequest(
       start.method,
       start.url,
@@ -301,15 +328,31 @@ async function consumeBody(start, body) {
       Date.now() - start.startedAt,
       start.retriedAfter429
     );
+    return result;
+  } catch (err) {
+    if (err instanceof CapsuleTimeoutError) {
+      emitCapsuleFailure(start.method, start.url, Date.now() - start.startedAt, "timeout");
+    } else {
+      emitCapsuleRequest(
+        start.method,
+        start.url,
+        start.res,
+        Date.now() - start.startedAt,
+        start.retriedAfter429
+      );
+    }
+    throw err;
   }
 }
-function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
-  let path = "";
+function redactedPath(url) {
   try {
-    path = redactPath(new URL(url).pathname);
+    return redactPath(new URL(url).pathname);
   } catch {
-    path = "?";
+    return "?";
   }
+}
+function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
+  const path = redactedPath(url);
   const lenHeader = res.headers.get("content-length");
   const responseBytes = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
   logEvent("capsule.request", {
@@ -321,6 +364,37 @@ function emitCapsuleRequest(method, url, res, durationMs, retriedAfter429) {
     ...retriedAfter429 ? { retriedAfter429: true } : {}
   });
 }
+function emitCapsuleFailure(method, url, elapsedMs, reason, err) {
+  const path = redactedPath(url);
+  if (reason === "timeout") {
+    logEvent(
+      "capsule.timeout",
+      { method, path, elapsedMs, timeoutMs: REQUEST_TIMEOUT_MS },
+      { force: true }
+    );
+    return;
+  }
+  const code = extractErrorCode(err);
+  logEvent(
+    "capsule.error",
+    { method, path, elapsedMs, ...code ? { code } : {} },
+    { force: true }
+  );
+}
+function emitCapsuleRateLimited(method, url, elapsedMs) {
+  logEvent(
+    "capsule.ratelimit",
+    { method, path: redactedPath(url), elapsedMs, status: 429 },
+    { force: true }
+  );
+}
+function extractErrorCode(err) {
+  const e = err;
+  const code = e?.cause?.code ?? e?.code;
+  if (typeof code === "string") return code;
+  if (typeof e?.name === "string" && e.name !== "Error") return e.name;
+  return void 0;
+}
 async function throwForStatus(res) {
   if (res.status === 401) {
     const detail = await parseErrorBody(res);
@@ -352,15 +426,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);
@@ -399,11 +477,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");
@@ -413,15 +487,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();
@@ -431,15 +501,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");
@@ -450,68 +516,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");
@@ -527,11 +585,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");
@@ -541,15 +595,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/server.ts
@@ -585,6 +635,44 @@ 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
+  "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 {
@@ -639,6 +727,22 @@ var abortControllers = /* @__PURE__ */ new Map();
 function registerAbortController(taskId, controller) {
   abortControllers.set(taskId, controller);
 }
+var evictionTimers = /* @__PURE__ */ new Map();
+var taskTtls = /* @__PURE__ */ new Map();
+function scheduleEviction(taskId, clientId, ttlMs) {
+  const existing = evictionTimers.get(taskId);
+  if (existing) clearTimeout(existing);
+  taskTtls.set(taskId, ttlMs);
+  const timer = setTimeout(() => {
+    owners.delete(taskId);
+    abortControllers.delete(taskId);
+    evictionTimers.delete(taskId);
+    taskTtls.delete(taskId);
+    logEvent("task.evicted", { taskId, clientId, reason: "ttl" });
+  }, ttlMs);
+  timer.unref?.();
+  evictionTimers.set(taskId, timer);
+}
 function countPerClient(clientId) {
   let n = 0;
   for (const owner of owners.values()) {
@@ -692,12 +796,7 @@ function createScopedTaskStore(clientId) {
         sessionId
       );
       owners.set(task.taskId, clientId);
-      const timer = setTimeout(() => {
-        owners.delete(task.taskId);
-        abortControllers.delete(task.taskId);
-        logEvent("task.evicted", { taskId: task.taskId, clientId, reason: "ttl" });
-      }, clampedTtl);
-      timer.unref?.();
+      scheduleEviction(task.taskId, clientId, clampedTtl);
       logEvent("task.created", {
         taskId: task.taskId,
         clientId,
@@ -716,6 +815,7 @@ function createScopedTaskStore(clientId) {
       }
       logEvent("task.transition", { taskId, clientId, status });
       await global.storeTaskResult(taskId, status, result, sessionId);
+      scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
     },
     async getTaskResult(taskId, sessionId) {
       if (owners.get(taskId) !== clientId) {
@@ -735,6 +835,7 @@ function createScopedTaskStore(clientId) {
       }
       if (status === "completed" || status === "failed" || status === "cancelled") {
         abortControllers.delete(taskId);
+        scheduleEviction(taskId, clientId, taskTtls.get(taskId) ?? getTasksConfig().defaultTtlMs);
       }
     },
     async listTasks(cursor, sessionId) {
@@ -780,27 +881,25 @@ function wrapAsText(result) {
   };
 }
 function registerTool(server2, name, description, schema, handler) {
+  if (!shouldRegister(name)) return;
   const registerWithSchema = server2.registerTool.bind(server2);
   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(server2, name, description, schema, handler) {
+  if (!shouldRegister(name)) return;
   const registerWithSchema = server2.experimental.tasks.registerToolTask.bind(
     server2.experimental.tasks
   );
@@ -811,7 +910,7 @@ function registerToolTask(server2, name, description, schema, handler) {
       description,
       inputSchema: schema,
       execution: { taskSupport: "optional" },
-      ...annotations ? { annotations } : {}
+      annotations
     },
     {
       createTask: async (input, extra) => {
@@ -871,7 +970,7 @@ function registerToolTask(server2, name, description, schema, handler) {
 }
 
 // src/tools/parties.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // src/tools/body-helpers.ts
 function setRef(body, key, id) {
@@ -881,9 +980,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 } from "zod";
+import { z as z2 } from "zod";
 
 // src/capsule/batch.ts
 function chunk(arr, size) {
@@ -902,37 +1014,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 };
@@ -977,10 +1095,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 } from "zod";
+function cloneWithDef(node, patch) {
+  const def = node.def;
+  return node.clone({ ...def, ...patch });
+}
+function stripDescriptions(schema) {
+  let node = schema;
+  if (node instanceof z.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 z.ZodArray) {
+    const element = stripDescriptions(node.def.element);
+    if (element !== node.def.element) node = cloneWithDef(node, { element });
+  } else if (node instanceof z.ZodOptional || node instanceof z.ZodNullable || node instanceof z.ZodDefault || node instanceof z.ZodReadonly) {
+    const innerType = stripDescriptions(node.def.innerType);
+    if (innerType !== node.def.innerType) node = cloneWithDef(node, { innerType });
+  } else if (node instanceof z.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 z.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 = z.object({
-    items: z.array(args.itemSchema).min(1).max(50).describe(args.itemDescription)
+  const itemSchema = stripDescriptions(args.itemSchema);
+  const schema = z2.object({
+    items: z2.array(itemSchema).min(1).max(50).describe(args.itemDescription)
   });
   async function handler(input, opts = {}) {
     return batchExecute(args.toolName, input.items, args.itemHandler, opts);
@@ -993,22 +1153,30 @@ 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 z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/tools/confirm-flag.ts
-import { z as z2 } from "zod";
+import { z as z3 } 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 z2.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
+  return z3.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
 }
 
 // src/tools/shared-schemas.ts
-import { z as z3 } from "zod";
-var positiveId = z3.preprocess((input) => {
+import { z as z4 } from "zod";
+var positiveId = z4.preprocess((input) => {
   if (typeof input !== "string") return input;
   const trimmed = input.trim();
   return /^\d+$/.test(trimmed) ? Number(trimmed) : input;
-}, z3.number().int().positive());
+}, z4.number().int().positive());
+var paginationFields = {
+  page: z4.number().int().positive().optional().default(1),
+  perPage: z4.number().int().min(1).max(100).optional().default(25)
+};
+var paginationFieldsNoDefaults = {
+  page: z4.number().int().positive().optional(),
+  perPage: z4.number().int().min(1).max(100).optional()
+};
 
 // src/capsule/idempotent.ts
 var isCapsule404 = (err) => err instanceof CapsuleApiError && err.status === 404;
@@ -1035,7 +1203,7 @@ async function idempotentWithResult(op, success, alreadyDone, isAlreadyDoneError
 // src/tools/define-delete.ts
 function defineDelete(args) {
   const { toolName, pathPrefix, confirmHint, idDescription } = args;
-  const schema = z4.object({
+  const schema = z5.object({
     id: idDescription ? positiveId.describe(idDescription) : positiveId,
     confirm: confirmFlag().describe(confirmHint)
   });
@@ -1078,16 +1246,17 @@ async function chunkedMultiGet(base, responseKey, ids, params) {
       (chunkIds) => capsuleGet(`${base}/${chunkIds.join(",")}`, params)
     )
   );
-  return { [responseKey]: responses.flatMap((r) => r.data[responseKey] ?? []) };
+  const merged = responses.flatMap((r) => r.data[responseKey] ?? []);
+  return { ...responses[0]?.data ?? {}, [responseKey]: merged };
 }
 
 // src/tools/custom-field-helpers.ts
-import { z as z5 } from "zod";
-var CustomFieldWriteSchema = z5.object({
+import { z as z6 } from "zod";
+var CustomFieldWriteSchema = z6.object({
   definitionId: positiveId.describe(
     "The custom-field definition id from list_custom_fields. Identifies which field on the entity to set."
   ),
-  value: z5.union([z5.string(), z5.number(), z5.boolean(), z5.null()]).describe(
+  value: z6.union([z6.string(), z6.number(), z6.boolean(), z6.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."
   )
 });
@@ -1103,24 +1272,24 @@ function mapFieldsForBody(fields) {
 }
 
 // src/tools/parties.ts
-var EmailAddressSchema = z6.object({
-  address: z6.string().email(),
-  type: z6.string().optional()
+var EmailAddressSchema = z7.object({
+  address: z7.string().email(),
+  type: z7.string().optional()
 });
-var PhoneNumberSchema = z6.object({
+var PhoneNumberSchema = z7.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: z6.string().min(1),
-  type: z6.string().optional()
+  number: z7.string().min(1),
+  type: z7.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 = z6.object({
-  street: z6.string().optional(),
-  city: z6.string().optional(),
-  state: z6.string().optional(),
-  country: z6.string().optional().describe(CountryDescription),
-  zip: z6.string().optional()
+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()
 });
 function validateWebsiteAddress(data, ctx) {
   const isUrlService = data.service === void 0 || data.service === "URL";
@@ -1143,7 +1312,7 @@ function validateWebsiteAddress(data, ctx) {
     });
   }
 }
-var WebsiteServiceEnum = z6.enum([
+var WebsiteServiceEnum = z7.enum([
   "URL",
   "SKYPE",
   "TWITTER",
@@ -1162,33 +1331,31 @@ var WebsiteServiceEnum = z6.enum([
   "BLUESKY",
   "SNAPCHAT"
 ]);
-var WebsiteSchema = z6.object({
-  address: z6.string().min(1).describe(
+var WebsiteSchema = z7.object({
+  address: z7.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 = z6.object({
-  q: z6.string().optional().describe("Free-text search query"),
-  embed: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z6.number().int().positive().optional().default(1),
-  perPage: z6.number().int().min(1).max(100).optional().default(25)
+var searchPartiesSchema = z7.object({
+  q: z7.string().optional().describe("Free-text search query"),
+  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...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 = z6.object({
+var getPartySchema = z7.object({
   id: positiveId.describe("Party ID"),
-  embed: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParty(input) {
   const { data } = await capsuleGet(`/parties/${input.id}`, {
@@ -1196,51 +1363,47 @@ async function getParty(input) {
   });
   return data;
 }
-var getPartiesSchema = z6.object({
-  ids: z6.array(positiveId).min(1).max(50).describe(
+var getPartiesSchema = z7.object({
+  ids: z7.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: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParties(input) {
   return chunkedMultiGet("/parties", "parties", input.ids, { embed: input.embed });
 }
-var listPartyOpportunitiesSchema = z6.object({
+var listPartyOpportunitiesSchema = z7.object({
   partyId: positiveId,
-  page: z6.number().int().positive().optional().default(1),
-  perPage: z6.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 = z6.object({
+var listPartyProjectsSchema = z7.object({
   partyId: positiveId,
-  page: z6.number().int().positive().optional().default(1),
-  perPage: z6.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: z6.string().optional(),
-  emailAddresses: z6.array(EmailAddressSchema).optional().describe(
+  about: z7.string().optional(),
+  emailAddresses: z7.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: z6.array(PhoneNumberSchema).optional().describe(
+  phoneNumbers: z7.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: z6.array(AddressSchema).optional().describe(
+  addresses: z7.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: z6.array(WebsiteSchema).optional().describe(
+  websites: z7.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(
@@ -1250,16 +1413,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 = z6.object({
-  type: z6.enum(["person", "organisation"]),
+var createPartySchema = z7.object({
+  type: z7.enum(["person", "organisation"]),
   // person
-  firstName: z6.string().optional(),
-  lastName: z6.string().optional(),
-  title: z6.string().optional(),
-  jobTitle: z6.string().optional(),
+  firstName: z7.string().optional(),
+  lastName: z7.string().optional(),
+  title: z7.string().optional(),
+  jobTitle: z7.string().optional(),
   organisationId: positiveId.optional().describe("Link person to an existing organisation ID"),
   // organisation
-  name: z6.string().optional(),
+  name: z7.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`."
@@ -1267,7 +1430,7 @@ var createPartySchema = z6.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: z6.array(CustomFieldWriteSchema).optional().describe(
+  fields: z7.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."
   )
 });
@@ -1281,17 +1444,17 @@ async function createParty(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/parties", { party: body });
 }
-var updatePartySchema = z6.object({
+var updatePartySchema = z7.object({
   id: positiveId,
-  firstName: z6.string().optional(),
-  lastName: z6.string().optional(),
-  title: z6.string().optional(),
-  jobTitle: z6.string().optional(),
-  name: z6.string().optional(),
+  firstName: z7.string().optional(),
+  lastName: z7.string().optional(),
+  title: z7.string().optional(),
+  jobTitle: z7.string().optional(),
+  name: z7.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: z6.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
+  fields: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
@@ -1322,10 +1485,42 @@ var { schema: deletePartySchema, handler: deleteParty } = defineDelete({
   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."
 });
-var addPartyEmailAddressSchema = z6.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 = z7.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 = z7.object({
   partyId: positiveId,
-  address: z6.string().email(),
-  type: z6.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
+  address: z7.string().email(),
+  type: z7.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
 });
 async function addPartyEmailAddress(input) {
   const { partyId, address, type } = input;
@@ -1335,32 +1530,17 @@ async function addPartyEmailAddress(input) {
     party: { emailAddresses: [item] }
   });
 }
-var removePartyEmailAddressByIdSchema = z6.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 = z6.object({
+var removePartyEmailAddressByIdSchema = removePartyEmailAddress.schema;
+var removePartyEmailAddressById = removePartyEmailAddress.handler;
+var addPartyPhoneNumberSchema = z7.object({
   partyId: positiveId,
-  number: z6.string().min(1),
-  type: z6.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
+  number: z7.string().min(1),
+  type: z7.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
 });
 async function addPartyPhoneNumber(input) {
   const { partyId, number, type } = input;
@@ -1370,36 +1550,21 @@ async function addPartyPhoneNumber(input) {
     party: { phoneNumbers: [item] }
   });
 }
-var removePartyPhoneNumberByIdSchema = z6.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 = z6.object({
+var removePartyPhoneNumberByIdSchema = removePartyPhoneNumber.schema;
+var removePartyPhoneNumberById = removePartyPhoneNumber.handler;
+var addPartyAddressSchema = z7.object({
   partyId: positiveId,
-  street: z6.string().optional(),
-  city: z6.string().optional(),
-  state: z6.string().optional(),
-  country: z6.string().optional().describe(CountryDescription),
-  zip: z6.string().optional(),
-  type: z6.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
+  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'.")
 });
 async function addPartyAddress(input) {
   const { partyId, ...rest } = input;
@@ -1411,31 +1576,16 @@ async function addPartyAddress(input) {
     party: { addresses: [item] }
   });
 }
-var removePartyAddressByIdSchema = z6.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 = z6.object({
+var removePartyAddressByIdSchema = removePartyAddress.schema;
+var removePartyAddressById = removePartyAddress.handler;
+var addPartyWebsiteSchema = z7.object({
   partyId: positiveId,
-  address: z6.string().min(1).describe(
+  address: z7.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.")
@@ -1448,58 +1598,41 @@ async function addPartyWebsite(input) {
     party: { websites: [item] }
   });
 }
-var removePartyWebsiteByIdSchema = z6.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 z7 } from "zod";
-var OpportunityValueSchema = z7.object({
-  amount: z7.number().nonnegative(),
-  currency: z7.string({
+import { z as z8 } from "zod";
+var OpportunityValueSchema = z8.object({
+  amount: z8.number().nonnegative(),
+  currency: z8.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 = 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 searchOpportunitiesSchema = z8.object({
+  q: z8.string().optional().describe("Free-text search query"),
+  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...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 = z7.object({
+var getOpportunitySchema = z8.object({
   id: positiveId,
-  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunity(input) {
   const { data } = await capsuleGet(`/opportunities/${input.id}`, {
@@ -1507,32 +1640,32 @@ async function getOpportunity(input) {
   });
   return data;
 }
-var getOpportunitiesSchema = z7.object({
-  ids: z7.array(positiveId).min(1).max(50).describe(
+var getOpportunitiesSchema = z8.object({
+  ids: z8.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: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunities(input) {
   return chunkedMultiGet("/opportunities", "opportunities", input.ids, { embed: input.embed });
 }
-var createOpportunitySchema = z7.object({
-  name: z7.string().min(1),
+var createOpportunitySchema = z8.object({
+  name: z8.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: z7.string().optional(),
+  description: z8.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z7.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  probability: z7.number().int().min(0).max(100).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(),
   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: z7.array(CustomFieldWriteSchema).optional().describe(
+  fields: z8.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."
   )
 });
@@ -1549,19 +1682,19 @@ async function createOpportunity(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/opportunities", { opportunity: body });
 }
-var updateOpportunitySchema = z7.object({
+var updateOpportunitySchema = z8.object({
   id: positiveId,
-  name: z7.string().min(1).optional(),
+  name: z8.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: z7.string().optional(),
+  description: z8.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z7.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-  probability: z7.number().int().min(0).max(100).optional().describe(
+  expectedCloseOn: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  probability: z8.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(
@@ -1573,7 +1706,7 @@ var updateOpportunitySchema = z7.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: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
   const { id, partyId, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
@@ -1609,25 +1742,23 @@ var { schema: deleteOpportunitySchema, handler: deleteOpportunity } = defineDele
 });
 
 // src/tools/projects.ts
-import { z as z8 } from "zod";
-var listProjectsSchema = z8.object({
-  status: z8.enum(["OPEN", "CLOSED"]).optional(),
-  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)
+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),
+  ...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 = z8.object({
+var getProjectSchema = z9.object({
   id: positiveId,
-  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProject(input) {
   const { data } = await capsuleGet(`/kases/${input.id}`, {
@@ -1635,20 +1766,20 @@ async function getProject(input) {
   });
   return data;
 }
-var getProjectsSchema = z8.object({
-  ids: z8.array(positiveId).min(1).max(50).describe(
+var getProjectsSchema = z9.object({
+  ids: z9.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: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProjects(input) {
   return chunkedMultiGet("/kases", "kases", input.ids, { embed: input.embed });
 }
-var createProjectSchema = z8.object({
-  name: z8.string().min(1),
+var createProjectSchema = z9.object({
+  name: z9.string().min(1),
   partyId: positiveId.describe("ID of the party linked to this project"),
-  description: z8.string().optional(),
-  status: z8.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
+  description: z9.string().optional(),
+  status: z9.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."
   ),
@@ -1658,8 +1789,8 @@ var createProjectSchema = z8.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: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  fields: z8.array(CustomFieldWriteSchema).optional().describe(
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z9.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."
   )
 });
@@ -1677,11 +1808,11 @@ async function createProject(input) {
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePost("/kases", { kase: body });
 }
-var updateProjectSchema = z8.object({
+var updateProjectSchema = z9.object({
   id: positiveId,
-  name: z8.string().min(1).optional(),
-  description: z8.string().optional(),
-  status: z8.enum(["OPEN", "CLOSED"]).optional(),
+  name: z9.string().min(1).optional(),
+  description: z9.string().optional(),
+  status: z9.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`."
   ),
@@ -1694,8 +1825,8 @@ var updateProjectSchema = z8.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: z8.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  fields: z8.array(CustomFieldWriteSchema).optional().describe(
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  fields: z9.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."
   )
 });
@@ -1734,23 +1865,22 @@ var { schema: deleteProjectSchema, handler: deleteProject } = defineDelete({
 });
 
 // src/tools/tasks.ts
-import { z as z9 } from "zod";
-var listTasksSchema = z9.object({
+import { z as z10 } from "zod";
+var listTasksSchema = z10.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: z9.enum(["OPEN", "COMPLETED"]).optional().describe(
+  status: z10.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: z9.number().int().positive().optional().default(1),
-  perPage: z9.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",
@@ -1759,28 +1889,27 @@ async function listTasks(input) {
     page: input.page,
     perPage: input.perPage
   });
-  return { ...data, nextPage };
 }
-var getTaskSchema = z9.object({
+var getTaskSchema = z10.object({
   id: positiveId.describe("Task ID")
 });
 async function getTask(input) {
   const { data } = await capsuleGet(`/tasks/${input.id}`);
   return data;
 }
-var getTasksSchema = z9.object({
-  ids: z9.array(positiveId).min(1).max(50).describe(
+var getTasksSchema = z10.object({
+  ids: z10.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 = z9.object({
-  description: z9.string().min(1),
-  dueOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"),
-  dueTime: z9.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z9.string().optional(),
+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(),
   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."
   ),
@@ -1789,10 +1918,7 @@ var createTaskSchema = z9.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);
@@ -1801,16 +1927,16 @@ async function createTask(input) {
   setRef(body, "kase", projectId);
   return capsulePost("/tasks", { task: body });
 }
-var updateTaskSchema = z9.object({
+var updateTaskSchema = z10.object({
   id: positiveId,
-  description: z9.string().min(1).optional(),
-  dueOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  dueTime: z9.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z9.string().optional(),
+  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(),
   // 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: z9.enum(["OPEN", "COMPLETED"]).optional().describe(
+  status: z10.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(
@@ -1828,12 +1954,7 @@ var updateTaskSchema = z9.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;
@@ -1844,7 +1965,7 @@ async function updateTask(input) {
   setNullableRef(body, "kase", projectId);
   return capsulePut(`/tasks/${id}`, { task: body });
 }
-var completeTaskSchema = z9.object({
+var completeTaskSchema = z10.object({
   id: positiveId
 });
 async function completeTask(input) {
@@ -1852,8 +1973,8 @@ async function completeTask(input) {
     task: { status: "COMPLETED" }
   });
 }
-var batchCompleteTaskSchema = z9.object({
-  ids: z9.array(positiveId).min(1).max(50).describe(
+var batchCompleteTaskSchema = z10.object({
+  ids: z10.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."
   )
 });
@@ -1867,77 +1988,59 @@ var { schema: deleteTaskSchema, handler: deleteTask } = defineDelete({
 });
 
 // src/tools/entries.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var listEntriesPagination = {
-  page: z10.number().int().positive().optional().default(1),
-  perPage: z10.number().int().min(1).max(100).optional().default(25),
-  embed: z10.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+  ...paginationFields,
+  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
 };
-var listPartyEntriesSchema = z10.object({
+var listPartyEntriesSchema = z11.object({
   partyId: positiveId,
   ...listEntriesPagination,
-  includeLinkedPersons: z10.boolean().optional().describe(
+  includeLinkedPersons: z11.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(
@@ -1972,31 +2075,31 @@ async function listPartyEntries(input) {
   );
   return { entries: slice, ...nextPage !== void 0 ? { nextPage } : {} };
 }
-var listOpportunityEntriesSchema = z10.object({
+var listOpportunityEntriesSchema = z11.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 = z10.object({
+var listProjectEntriesSchema = z11.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 = z10.object({
+var getEntrySchema = z11.object({
   id: positiveId,
-  embed: z10.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
 });
 async function getEntry(input) {
   const { data } = await capsuleGet(`/entries/${input.id}`, {
@@ -2004,34 +2107,30 @@ async function getEntry(input) {
   });
   return data;
 }
-var listEntriesSchema = z10.object({
+var listEntriesSchema = z11.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 = z10.object({
-  content: z10.string().min(1).describe(
+var addNoteSchema = z11.object({
+  content: z11.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: z10.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
+  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(
     "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);
@@ -2039,12 +2138,12 @@ async function addNote(input) {
   if (entryAt !== void 0) body["entryAt"] = entryAt;
   return capsulePost("/entries", { entry: body });
 }
-var updateEntrySchema = z10.object({
+var updateEntrySchema = z11.object({
   id: positiveId.describe("Entry ID to update"),
-  content: z10.string().min(1).optional().describe(
+  content: z11.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: z10.string().optional().describe(
+  subject: z11.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`."
   )
 });
@@ -2066,62 +2165,50 @@ var { schema: deleteEntrySchema, handler: deleteEntry } = defineDelete({
 });
 
 // src/tools/pipelines.ts
-import { z as z11 } from "zod";
-var paginationFields = {
-  page: z11.number().int().positive().optional(),
-  perPage: z11.number().int().min(1).max(100).optional()
-};
-var listPipelinesSchema = z11.object({ ...paginationFields });
+import { z as z12 } from "zod";
+var listPipelinesSchema = z12.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 = z11.object({
+var listMilestonesSchema = z12.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 z12 } from "zod";
-var paginationFields2 = {
-  page: z12.number().int().positive().optional(),
-  perPage: z12.number().int().min(1).max(100).optional()
-};
-var listBoardsSchema = z12.object({ ...paginationFields2 });
+import { z as z13 } from "zod";
+var listBoardsSchema = z13.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 = z12.object({
+var listStagesSchema = z13.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 z13 } from "zod";
+import { z as z14 } from "zod";
 var TAG_LIST_PATH = {
   parties: "/parties/tags",
   opportunities: "/opportunities/tags",
@@ -2132,24 +2219,22 @@ var ENTITY_TO_WRAPPER = {
   opportunities: "opportunity",
   kases: "kase"
 };
-var TagEntity = z13.enum(["parties", "opportunities", "kases"]).describe("Which entity type. Use 'kases' for projects (Capsule's legacy path name).");
-var listTagsSchema = z13.object({
-  entity: z13.enum(["parties", "opportunities", "kases"]).describe("The resource type to list tags for"),
-  page: z13.number().int().positive().optional(),
-  perPage: z13.number().int().min(1).max(100).optional()
+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"),
+  ...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 = z13.object({
+var addTagSchema = z14.object({
   entity: TagEntity,
   entityId: positiveId.describe("The party/opportunity/kase id."),
-  tagName: z13.string().min(1).describe(
+  tagName: z14.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."
   )
 });
@@ -2162,7 +2247,7 @@ async function addTag(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "add_tag");
   return result;
 }
-var removeTagByIdSchema = z13.object({
+var removeTagByIdSchema = z14.object({
   entity: TagEntity,
   entityId: positiveId.describe("The party/opportunity/kase id."),
   tagId: positiveId.describe(
@@ -2193,7 +2278,7 @@ async function removeTagById(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
   return result;
 }
-var deleteTagDefinitionSchema = z13.object({
+var deleteTagDefinitionSchema = z14.object({
   entity: TagEntity,
   tagId: positiveId.describe(
     "The tag definition's id (from list_tags, or embed='tags' on a record). NOT an entity id."
@@ -2229,44 +2314,41 @@ var { schema: batchRemoveTagByIdSchema, handler: batchRemoveTagById } = defineBa
 });
 
 // src/tools/users.ts
-import { z as z14 } from "zod";
-var listUsersSchema = z14.object({
-  page: z14.number().int().positive().optional(),
-  perPage: z14.number().int().min(1).max(100).optional()
+import { z as z15 } from "zod";
+var listUsersSchema = z15.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 = z14.object({});
+var getCurrentUserSchema = z15.object({});
 async function getCurrentUser(_input) {
   const { data } = await capsuleGet("/users/current");
   return data;
 }
 
 // src/tools/filters.ts
-import { z as z15 } from "zod";
-var FilterConditionSchema = z15.object({
-  field: z15.string().describe(
+import { z as z16 } from "zod";
+var FilterConditionSchema = z16.object({
+  field: z16.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: z15.string().describe(
+  operator: z16.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: z15.union([z15.string(), z15.number(), z15.boolean(), z15.null()]).describe(
+  value: z16.union([z16.string(), z16.number(), z16.boolean(), z16.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 = z15.object({
-  conditions: z15.array(FilterConditionSchema).min(1).describe(
+var FilterInputSchema = z16.object({
+  conditions: z16.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: z15.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z15.number().int().positive().optional().default(1),
-  perPage: z15.number().int().min(1).max(100).optional().default(25)
+  embed: z16.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...paginationFields
 });
 async function runFilter(entityPath, input) {
   const { data, nextPage } = await capsuleSearch(
@@ -2286,10 +2368,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) {
@@ -2297,139 +2376,126 @@ async function filterProjects(input) {
 }
 
 // src/tools/metadata.ts
-import { z as z16 } from "zod";
-var paginationFields3 = {
-  page: z16.number().int().positive().optional(),
-  perPage: z16.number().int().min(1).max(100).optional().describe("Page size, max 100. Defaults to 100 for reference data.")
+import { z as z17 } from "zod";
+var paginationFields2 = {
+  ...paginationFieldsNoDefaults,
+  perPage: paginationFieldsNoDefaults.perPage.describe(
+    "Page size, max 100. Defaults to 100 for reference data."
+  )
 };
-var listTeamsSchema = z16.object({ ...paginationFields3 });
+var listTeamsSchema = z17.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 = z16.object({ ...paginationFields3 });
+var listLostReasonsSchema = z17.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 = z16.object({ ...paginationFields3 });
+var listActivityTypesSchema = z17.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 = z16.object({});
+var getSiteSchema = z17.object({});
 async function getSite(_input) {
   const { data } = await capsuleGetCached("/site");
   return data;
 }
-var listTrackDefinitionsSchema = z16.object({ ...paginationFields3 });
+var listTrackDefinitionsSchema = z17.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 = z16.object({ ...paginationFields3 });
+var listCategoriesSchema = z17.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 = z16.object({ ...paginationFields3 });
+var listGoalsSchema = z17.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 z17 } from "zod";
-var listEmployeesSchema = z17.object({
+import { z as z18 } from "zod";
+var listEmployeesSchema = z18.object({
   partyId: positiveId.describe(
     "The organisation's party id. Returns the people whose `organisation` field links to this party."
   ),
-  page: z17.number().int().positive().optional().default(1),
-  perPage: z17.number().int().min(1).max(100).optional().default(25),
-  embed: z17.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  ...paginationFields,
+  embed: z18.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 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 = z17.string().describe(
+var DeletedSinceSchema = z18.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: z17.number().int().positive().optional().default(1),
-  perPage: z17.number().int().min(1).max(100).optional().default(25)
+  ...paginationFields
 };
-var listDeletedPartiesSchema = z17.object(DeletedPagination);
+var listDeletedPartiesSchema = z18.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 = z17.object(DeletedPagination);
+var listDeletedOpportunitiesSchema = z18.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 = z17.object(DeletedPagination);
+var listDeletedProjectsSchema = z18.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 z18 } from "zod";
-var RelationshipEntity = z18.enum(["opportunities", "kases"]).describe("Which entity has the additional-party links. Use 'kases' for projects.");
-var listAdditionalPartiesSchema = z18.object({
+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({
   entity: RelationshipEntity,
   entityId: positiveId.describe("ID of the opportunity or project."),
-  embed: z18.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z18.number().int().positive().optional().default(1),
-  perPage: z18.number().int().min(1).max(100).optional().default(25)
+  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...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 { ...data, nextPage };
+  return capsuleGetList(`/${input.entity}/${input.entityId}/parties`, {
+    embed: input.embed,
+    page: input.page,
+    perPage: input.perPage
+  });
 }
-var addAdditionalPartySchema = z18.object({
+var addAdditionalPartySchema = z19.object({
   entity: RelationshipEntity,
   entityId: positiveId,
   partyId: positiveId.describe(
@@ -2462,7 +2528,7 @@ async function addAdditionalParty(input) {
     throw err;
   }
 }
-var removeAdditionalPartySchema = z18.object({
+var removeAdditionalPartySchema = z19.object({
   entity: RelationshipEntity,
   entityId: positiveId,
   partyId: positiveId,
@@ -2492,24 +2558,23 @@ async function removeAdditionalParty(input) {
     })
   );
 }
-var listAssociatedProjectsSchema = z18.object({
+var listAssociatedProjectsSchema = z19.object({
   opportunityId: positiveId,
-  embed: z18.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z18.number().int().positive().optional().default(1),
-  perPage: z18.number().int().min(1).max(100).optional().default(25)
+  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...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 z19 } from "zod";
-var CustomFieldEntity = z19.enum(["parties", "opportunities", "kases"]).describe("Which entity type's custom field schema to inspect. Use 'kases' for projects.");
-var listCustomFieldsSchema = z19.object({
+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({
   entity: CustomFieldEntity
 });
 async function listCustomFields(input) {
@@ -2518,7 +2583,7 @@ async function listCustomFields(input) {
   );
   return data;
 }
-var getCustomFieldSchema = z19.object({
+var getCustomFieldSchema = z20.object({
   entity: CustomFieldEntity,
   fieldId: positiveId.describe("Custom field definition id.")
 });
@@ -2530,9 +2595,9 @@ async function getCustomField(input) {
 }
 
 // src/tools/tracks.ts
-import { z as z20 } from "zod";
-var TrackEntity = z20.enum(["parties", "opportunities", "kases"]).describe("Use 'kases' for projects.");
-var listEntityTracksSchema = z20.object({
+import { z as z21 } from "zod";
+var TrackEntity = z21.enum(["parties", "opportunities", "kases"]).describe("Use 'kases' for projects.");
+var listEntityTracksSchema = z21.object({
   entity: TrackEntity,
   entityId: positiveId
 });
@@ -2542,20 +2607,20 @@ async function listEntityTracks(input) {
   );
   return data;
 }
-var showTrackSchema = z20.object({
+var showTrackSchema = z21.object({
   trackId: positiveId
 });
 async function showTrack(input) {
   const { data } = await capsuleGet(`/tracks/${input.trackId}`);
   return data;
 }
-var applyTrackSchema = z20.object({
-  entity: z20.enum(["opportunities", "kases"]).describe("Which entity to apply the track to. Use 'kases' for projects."),
+var applyTrackSchema = z21.object({
+  entity: z21.enum(["opportunities", "kases"]).describe("Which entity to apply the track to. Use 'kases' for projects."),
   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: z20.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe(
+  startDate: z21.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."
   )
 });
@@ -2568,9 +2633,9 @@ async function applyTrack(input) {
   if (input.startDate !== void 0) track["trackDateOn"] = input.startDate;
   return capsulePost("/tracks", { track });
 }
-var updateTrackSchema = z20.object({
+var updateTrackSchema = z21.object({
   trackId: positiveId,
-  fields: z20.record(z20.string(), z20.unknown()).describe(
+  fields: z21.record(z21.string(), z21.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."
   )
 });
@@ -2582,7 +2647,7 @@ async function updateTrack(input) {
     track: input.fields
   });
 }
-var removeTrackSchema = z20.object({
+var removeTrackSchema = z21.object({
   trackId: 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."
@@ -2600,13 +2665,13 @@ async function removeTrack(input) {
 }
 
 // src/tools/attachments.ts
-import { z as z21 } from "zod";
+import { z as z22 } 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 = z21.object({
+var getAttachmentSchema = z22.object({
   id: positiveId.describe("Attachment ID."),
-  maxSizeBytes: z21.number().int().positive().max(HARD_MAX_SIZE_BYTES).optional().describe(
+  maxSizeBytes: z22.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.`
   )
 });
@@ -2621,17 +2686,17 @@ async function getAttachment(input) {
   }
   return { contentType, buffer, sizeBytes };
 }
-var uploadAttachmentSchema = z21.object({
-  filename: z21.string().min(1).describe(
+var uploadAttachmentSchema = z22.object({
+  filename: z22.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: z21.string().min(1).describe(
+  contentType: z22.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: z21.string().min(1).max(HARD_MAX_BASE64_CHARS).describe(
+  dataBase64: z22.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: z21.string().optional().describe(
+  content: z22.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)."),
@@ -2649,12 +2714,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)."
@@ -2679,37 +2739,36 @@ 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 z22 } from "zod";
-var EntitySchema = z22.enum(["parties", "opportunities", "kases"]).describe(
+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 = z22.object({
+var listSavedFiltersSchema = z23.object({
   entity: EntitySchema
 });
 async function listSavedFilters(input) {
   const { data } = await capsuleGetCached(`/${input.entity}/filters`);
   return data;
 }
-var runSavedFilterSchema = z22.object({
+var runSavedFilterSchema = z23.object({
   entity: EntitySchema,
   id: positiveId.describe("The saved filter id (from list_saved_filters)."),
-  embed: z22.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z22.number().int().positive().optional().default(1),
-  perPage: z22.number().int().min(1).max(100).optional().default(25)
+  embed: z23.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  ...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 { ...data, nextPage };
+  return capsuleGetList(`/${input.entity}/filters/${input.id}/results`, {
+    page: input.page,
+    perPage: input.perPage,
+    embed: input.embed
+  });
 }
 
 // src/server.ts
@@ -2720,7 +2779,7 @@ function createCapsuleMcpServer(opts) {
   const server2 = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.7.0",
+      version: "1.8.1",
       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
@@ -3170,20 +3229,72 @@ function createCapsuleMcpServer(opts) {
     listEntriesSchema,
     listEntries
   );
-  server2.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")) {
+    server2.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: [
             {
@@ -3193,8 +3304,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
@@ -3203,57 +3313,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(
       server2,
@@ -3457,11 +3518,28 @@ if (!process.env["CAPSULE_API_TOKEN"]) {
   );
   process.exit(1);
 }
-var server = createCapsuleMcpServer();
+var STDIO_CLIENT_ID = "stdio-local";
+var server = createCapsuleMcpServer({ clientId: STDIO_CLIENT_ID });
 var transport = new StdioServerTransport();
 if (isReadOnly()) {
   console.error("[capsulemcp] read-only mode: write/delete tools are not registered");
 }
+function exitOnDisconnect() {
+  let exiting = false;
+  const die = () => {
+    if (exiting) return;
+    exiting = true;
+    process.exit(0);
+  };
+  process.stdin.on("end", die);
+  process.stdin.on("close", die);
+  process.stdin.on("error", die);
+  process.stdout.on("error", die);
+  const orphanCheck = setInterval(() => {
+    if (process.ppid === 1) die();
+  }, 3e4);
+  orphanCheck.unref?.();
+}
 try {
   await server.connect(transport);
 } catch (err) {
@@ -3469,3 +3547,4 @@ try {
   console.error(`[capsulemcp] Failed to start: ${message}`);
   process.exit(1);
 }
+exitOnDisconnect();