capsulemcp 1.6.1 → 1.6.3

package/dist/http.js

@@ -1374,18 +1374,19 @@ function registerToolTask(server, name, description, schema, handler) {
 }
 
 // src/tools/parties.ts
-import { z as z4 } from "zod";
+import { z as z7 } from "zod";
 
-// src/tools/descriptions.ts
-var EMBED_TAGS_FIELDS_DESCRIPTION = "Comma-separated embeds, e.g. 'tags,fields'";
-var EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION = "Comma-separated embeds, e.g. 'attachments,participants'";
+// src/tools/body-helpers.ts
+function setRef(body, key, id) {
+  if (id) body[key] = { id };
+}
+function setNullableRef(body, key, id) {
+  if (id === null) body[key] = null;
+  else if (id !== void 0) body[key] = { id };
+}
 
-// src/tools/confirm-flag.ts
+// src/tools/define-batch.ts
 import { z as z2 } 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 });
-}
 
 // src/capsule/batch.ts
 function chunk(arr, size) {
@@ -1479,6 +1480,39 @@ function topFailureReasons(results, n) {
   return Array.from(counts.values()).sort((a, b) => b.count - a.count).slice(0, n);
 }
 
+// src/tools/define-batch.ts
+function defineBatch(args) {
+  const schema = z2.object({
+    items: z2.array(args.itemSchema).min(1).max(50).describe(args.itemDescription)
+  });
+  async function handler(input, opts = {}) {
+    return batchExecute(args.toolName, input.items, args.itemHandler, opts);
+  }
+  return { schema, handler };
+}
+
+// src/tools/descriptions.ts
+var EMBED_TAGS_FIELDS_DESCRIPTION = "Comma-separated embeds, e.g. 'tags,fields'";
+var EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION = "Comma-separated embeds, e.g. 'attachments,participants'";
+
+// src/tools/define-delete.ts
+import { z as z5 } from "zod";
+
+// src/tools/confirm-flag.ts
+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 z3.literal(true, { error: () => CONFIRM_REQUIRED_MESSAGE });
+}
+
+// src/tools/shared-schemas.ts
+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;
+}, z4.number().int().positive());
+
 // src/capsule/idempotent.ts
 var isCapsule404 = (err) => err instanceof CapsuleApiError && err.status === 404;
 var isCapsuleTagNotFound = (err) => err instanceof CapsuleApiError && err.status === 422 && /tag not found/i.test(err.message);
@@ -1501,13 +1535,33 @@ async function idempotentWithResult(op, success, alreadyDone, isAlreadyDoneError
   }
 }
 
+// src/tools/define-delete.ts
+function defineDelete(args) {
+  const { toolName, pathPrefix, confirmHint, idDescription } = args;
+  const schema = z5.object({
+    id: idDescription ? positiveId.describe(idDescription) : positiveId,
+    confirm: confirmFlag().describe(confirmHint)
+  });
+  async function handler(input) {
+    if (input.confirm !== true) {
+      throw new Error(`${toolName} requires confirm: true`);
+    }
+    return idempotent(
+      () => capsuleDelete(`${pathPrefix}/${input.id}`),
+      () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
+      () => ({ deleted: true, alreadyDeleted: true, id: input.id })
+    );
+  }
+  return { schema, handler };
+}
+
 // src/tools/custom-field-helpers.ts
-import { z as z3 } from "zod";
-var CustomFieldWriteSchema = z3.object({
-  definitionId: z3.number().int().positive().describe(
+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: z3.union([z3.string(), z3.number(), z3.boolean(), z3.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."
   )
 });
@@ -1523,24 +1577,24 @@ function mapFieldsForBody(fields) {
 }
 
 // src/tools/parties.ts
-var EmailAddressSchema = z4.object({
-  address: z4.string().email(),
-  type: z4.string().optional()
+var EmailAddressSchema = z7.object({
+  address: z7.string().email(),
+  type: z7.string().optional()
 });
-var PhoneNumberSchema = z4.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: z4.string().min(1),
-  type: z4.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 = z4.object({
-  street: z4.string().optional(),
-  city: z4.string().optional(),
-  state: z4.string().optional(),
-  country: z4.string().optional().describe(CountryDescription),
-  zip: z4.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";
@@ -1563,7 +1617,7 @@ function validateWebsiteAddress(data, ctx) {
     });
   }
 }
-var WebsiteServiceEnum = z4.enum([
+var WebsiteServiceEnum = z7.enum([
   "URL",
   "SKYPE",
   "TWITTER",
@@ -1582,19 +1636,19 @@ var WebsiteServiceEnum = z4.enum([
   "BLUESKY",
   "SNAPCHAT"
 ]);
-var WebsiteSchema = z4.object({
-  address: z4.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 = z4.object({
-  q: z4.string().optional().describe("Free-text search query"),
-  embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z4.number().int().positive().optional().default(1),
-  perPage: z4.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),
+  page: z7.number().int().positive().optional().default(1),
+  perPage: z7.number().int().min(1).max(100).optional().default(25)
 });
 async function searchParties(input) {
   const path = input.q ? "/parties/search" : "/parties";
@@ -1606,9 +1660,9 @@ async function searchParties(input) {
   });
   return { ...data, nextPage };
 }
-var getPartySchema = z4.object({
-  id: z4.number().int().positive().describe("Party ID"),
-  embed: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+var getPartySchema = z7.object({
+  id: positiveId.describe("Party ID"),
+  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParty(input) {
   const { data } = await capsuleGet(`/parties/${input.id}`, {
@@ -1616,11 +1670,11 @@ async function getParty(input) {
   });
   return data;
 }
-var getPartiesSchema = z4.object({
-  ids: z4.array(z4.number().int().positive()).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: z4.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z7.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getParties(input) {
   const { ids, embed } = input;
@@ -1638,10 +1692,10 @@ async function getParties(input) {
   );
   return { parties: responses.flatMap((r) => r.data.parties) };
 }
-var listPartyOpportunitiesSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  page: z4.number().int().positive().optional().default(1),
-  perPage: z4.number().int().min(1).max(100).optional().default(25)
+var listPartyOpportunitiesSchema = z7.object({
+  partyId: positiveId,
+  page: z7.number().int().positive().optional().default(1),
+  perPage: z7.number().int().min(1).max(100).optional().default(25)
 });
 async function listPartyOpportunities(input) {
   const { data, nextPage } = await capsuleGet(
@@ -1650,10 +1704,10 @@ async function listPartyOpportunities(input) {
   );
   return { ...data, nextPage };
 }
-var listPartyProjectsSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  page: z4.number().int().positive().optional().default(1),
-  perPage: z4.number().int().min(1).max(100).optional().default(25)
+var listPartyProjectsSchema = z7.object({
+  partyId: positiveId,
+  page: z7.number().int().positive().optional().default(1),
+  perPage: z7.number().int().min(1).max(100).optional().default(25)
 });
 async function listPartyProjects(input) {
   const { data, nextPage } = await capsuleGet(
@@ -1663,91 +1717,82 @@ async function listPartyProjects(input) {
   return { ...data, nextPage };
 }
 var PartyWriteBaseSchema = {
-  about: z4.string().optional(),
-  emailAddresses: z4.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: z4.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: z4.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: z4.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: z4.number().int().positive().optional().describe(
+  ownerId: positiveId.optional().describe(
     "Assign to user ID. On create_party, 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. Discover IDs via list_users."
   )
 };
-var createPartySchema = z4.object({
-  type: z4.enum(["person", "organisation"]),
+var createPartySchema = z7.object({
+  type: z7.enum(["person", "organisation"]),
   // person
-  firstName: z4.string().optional(),
-  lastName: z4.string().optional(),
-  title: z4.string().optional(),
-  jobTitle: z4.string().optional(),
-  organisationId: z4.number().int().positive().optional().describe("Link person to an existing organisation ID"),
+  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: z4.string().optional(),
+  name: z7.string().optional(),
   ...PartyWriteBaseSchema
 });
 async function createParty(input) {
   const { ownerId, organisationId, ...rest } = input;
   const body = { ...rest };
-  if (ownerId) body["owner"] = { id: ownerId };
-  if (organisationId) body["organisation"] = { id: organisationId };
+  setRef(body, "owner", ownerId);
+  setRef(body, "organisation", organisationId);
   return capsulePost("/parties", { party: body });
 }
-var updatePartySchema = z4.object({
-  id: z4.number().int().positive(),
-  firstName: z4.string().optional(),
-  lastName: z4.string().optional(),
-  title: z4.string().optional(),
-  jobTitle: z4.string().optional(),
-  name: z4.string().optional(),
-  fields: z4.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
+var updatePartySchema = z7.object({
+  id: positiveId,
+  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: z7.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_party")),
   ...PartyWriteBaseSchema
 });
 async function updateParty(input) {
-  const { id, ownerId, fields, ...rest } = input;
+  const { id, ownerId, organisationId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
-  if (ownerId) body["owner"] = { id: ownerId };
+  setRef(body, "owner", ownerId);
+  setNullableRef(body, "organisation", organisationId);
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/parties/${id}`, { party: body });
 }
-var batchUpdatePartySchema = z4.object({
-  items: z4.array(updatePartySchema).min(1).max(50).describe(
-    "Array of 1\u201350 update_party inputs. Each item is the same shape as a single update_party call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget (~4000 req/h)."
-  )
+var { schema: batchUpdatePartySchema, handler: batchUpdateParty } = defineBatch({
+  toolName: "batch_update_party",
+  itemSchema: updatePartySchema,
+  itemDescription: "Array of 1\u201350 update_party inputs. Each item is the same shape as a single update_party call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget (~4000 req/h).",
+  itemHandler: updateParty
 });
-async function batchUpdateParty(input, opts = {}) {
-  return batchExecute("batch_update_party", input.items, (item) => updateParty(item), opts);
-}
-var deletePartySchema = z4.object({
-  id: z4.number().int().positive(),
-  confirm: confirmFlag().describe(
-    "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 { schema: deletePartySchema, handler: deleteParty } = defineDelete({
+  toolName: "delete_party",
+  pathPrefix: "/parties",
+  confirmHint: "Must be set to true. Deletes the party AND all linked notes, tasks, opportunities, and projects (kases). Deleting an ORGANISATION does NOT delete people linked to it via organisationId \u2014 their `organisation` field is silently cleared to null and they survive as standalone records. Irreversible."
 });
-async function deleteParty(input) {
-  if (input.confirm !== true) {
-    throw new Error("delete_party requires confirm: true");
-  }
-  return idempotent(
-    () => capsuleDelete(`/parties/${input.id}`),
-    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
-    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
-  );
-}
-var addPartyEmailAddressSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  address: z4.string().email(),
-  type: z4.string().optional().describe("Free-form label, e.g. 'Work', 'Home'.")
+var addPartyEmailAddressSchema = z7.object({
+  partyId: positiveId,
+  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;
@@ -1757,9 +1802,9 @@ async function addPartyEmailAddress(input) {
     party: { emailAddresses: [item] }
   });
 }
-var removePartyEmailAddressByIdSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  emailAddressId: z4.number().int().positive().describe(
+var removePartyEmailAddressByIdSchema = z7.object({
+  partyId: positiveId,
+  emailAddressId: positiveId.describe(
     "Capsule's id for the email-address row. Read it from get_party (each entry in emailAddresses carries an id)."
   )
 });
@@ -1779,10 +1824,10 @@ async function removePartyEmailAddressById(input) {
     () => ({ removed: true, alreadyRemoved: true, partyId, emailAddressId })
   );
 }
-var addPartyPhoneNumberSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  number: z4.string().min(1),
-  type: z4.string().optional().describe("Free-form label, e.g. 'Work', 'Mobile'.")
+var addPartyPhoneNumberSchema = z7.object({
+  partyId: positiveId,
+  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;
@@ -1792,9 +1837,9 @@ async function addPartyPhoneNumber(input) {
     party: { phoneNumbers: [item] }
   });
 }
-var removePartyPhoneNumberByIdSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  phoneNumberId: z4.number().int().positive().describe(
+var removePartyPhoneNumberByIdSchema = z7.object({
+  partyId: positiveId,
+  phoneNumberId: positiveId.describe(
     "Capsule's id for the phone-number row. Read it from get_party (each entry in phoneNumbers carries an id)."
   )
 });
@@ -1814,14 +1859,14 @@ async function removePartyPhoneNumberById(input) {
     () => ({ removed: true, alreadyRemoved: true, partyId, phoneNumberId })
   );
 }
-var addPartyAddressSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  street: z4.string().optional(),
-  city: z4.string().optional(),
-  state: z4.string().optional(),
-  country: z4.string().optional().describe(CountryDescription),
-  zip: z4.string().optional(),
-  type: z4.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
+var addPartyAddressSchema = z7.object({
+  partyId: positiveId,
+  street: z7.string().optional(),
+  city: z7.string().optional(),
+  state: z7.string().optional(),
+  country: z7.string().optional().describe(CountryDescription),
+  zip: z7.string().optional(),
+  type: z7.string().optional().describe("Free-form label, e.g. 'Office', 'Home'.")
 });
 async function addPartyAddress(input) {
   const { partyId, ...rest } = input;
@@ -1833,9 +1878,9 @@ async function addPartyAddress(input) {
     party: { addresses: [item] }
   });
 }
-var removePartyAddressByIdSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  addressId: z4.number().int().positive().describe(
+var removePartyAddressByIdSchema = z7.object({
+  partyId: positiveId,
+  addressId: positiveId.describe(
     "Capsule's id for the address row. Read it from get_party (each entry in addresses carries an id)."
   )
 });
@@ -1855,9 +1900,9 @@ async function removePartyAddressById(input) {
     () => ({ removed: true, alreadyRemoved: true, partyId, addressId })
   );
 }
-var addPartyWebsiteSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  address: z4.string().min(1).describe(
+var addPartyWebsiteSchema = z7.object({
+  partyId: positiveId,
+  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.")
@@ -1870,9 +1915,9 @@ async function addPartyWebsite(input) {
     party: { websites: [item] }
   });
 }
-var removePartyWebsiteByIdSchema = z4.object({
-  partyId: z4.number().int().positive(),
-  websiteId: z4.number().int().positive().describe(
+var removePartyWebsiteByIdSchema = z7.object({
+  partyId: positiveId,
+  websiteId: positiveId.describe(
     "Capsule's id for the website row. Read it from get_party (each entry in websites carries an id)."
   )
 });
@@ -1894,20 +1939,32 @@ async function removePartyWebsiteById(input) {
 }
 
 // src/tools/opportunities.ts
-import { z as z5 } from "zod";
-var OpportunityValueSchema = z5.object({
-  amount: z5.number().nonnegative(),
-  currency: z5.string({
+import { z as z8 } from "zod";
+
+// src/tools/preserve-refs.ts
+async function readEntityRefs(path, responseKey) {
+  const { data } = await capsuleGet(path);
+  const entity = data[responseKey];
+  return {
+    teamId: entity?.team?.id ?? void 0,
+    stageId: entity?.stage?.id ?? void 0
+  };
+}
+
+// src/tools/opportunities.ts
+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 = z5.object({
-  q: z5.string().optional().describe("Free-text search query"),
-  embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z5.number().int().positive().optional().default(1),
-  perPage: z5.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),
+  page: z8.number().int().positive().optional().default(1),
+  perPage: z8.number().int().min(1).max(100).optional().default(25)
 });
 async function searchOpportunities(input) {
   const path = input.q ? "/opportunities/search" : "/opportunities";
@@ -1919,9 +1976,9 @@ async function searchOpportunities(input) {
   });
   return { ...data, nextPage };
 }
-var getOpportunitySchema = z5.object({
-  id: z5.number().int().positive(),
-  embed: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+var getOpportunitySchema = z8.object({
+  id: positiveId,
+  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunity(input) {
   const { data } = await capsuleGet(`/opportunities/${input.id}`, {
@@ -1929,11 +1986,11 @@ async function getOpportunity(input) {
   });
   return data;
 }
-var getOpportunitiesSchema = z5.object({
-  ids: z5.array(z5.number().int().positive()).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: z5.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z8.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getOpportunities(input) {
   const { ids, embed } = input;
@@ -1954,20 +2011,20 @@ async function getOpportunities(input) {
   );
   return { opportunities: responses.flatMap((r) => r.data.opportunities) };
 }
-var createOpportunitySchema = z5.object({
-  name: z5.string().min(1),
-  partyId: z5.number().int().positive().describe("ID of the party this opportunity belongs to"),
-  milestoneId: z5.number().int().positive().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."
+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: z5.string().optional(),
+  description: z8.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z5.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  probability: z5.number().int().min(0).max(100).optional(),
-  ownerId: z5.number().int().positive().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. Once set, this connector cannot clear the owner back to null (use Capsule's web UI). Discover IDs via list_users."
+  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. Once set, this connector cannot clear the owner back to null (use Capsule's web UI). 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: z5.number().int().positive().optional().describe(
+  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)."
   )
 });
@@ -1978,92 +2035,76 @@ async function createOpportunity(input) {
     party: { id: partyId },
     milestone: { id: milestoneId }
   };
-  if (ownerId) body["owner"] = { id: ownerId };
-  if (teamId) body["team"] = { id: teamId };
+  setRef(body, "owner", ownerId);
+  setRef(body, "team", teamId);
   return capsulePost("/opportunities", { opportunity: body });
 }
-var updateOpportunitySchema = z5.object({
-  id: z5.number().int().positive(),
-  name: z5.string().min(1).optional(),
-  milestoneId: z5.number().int().positive().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."
+var updateOpportunitySchema = z8.object({
+  id: positiveId,
+  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."
+  ),
+  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: z5.string().optional(),
+  description: z8.string().optional(),
   value: OpportunityValueSchema.optional(),
-  expectedCloseOn: z5.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-  probability: z5.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: z5.number().int().positive().optional().describe(
+  lostReasonId: positiveId.optional().describe(
     "Reason the opportunity was lost. Only meaningful when transitioning to a Lost milestone \u2014 Capsule silently drops it for other milestones. Without this set, a connector-driven Lost-close leaves `lostReason: null`. Discover IDs via list_lostreasons."
   ),
-  ownerId: z5.number().int().positive().optional().describe(
+  ownerId: positiveId.optional().describe(
     "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that. When you supply `ownerId` and omit `teamId`, the connector fetches the opportunity's current team and includes it in the PUT body to preserve it across the owner change. Without this defensive read, Capsule's PUT would clear the existing team (see NOTES-ON-CAPSULE-API.md \xA727 \u2014 same asymmetric semantic as /kases). Supply `teamId` explicitly on the same call to change the team instead."
   ),
-  teamId: z5.number().int().positive().nullable().optional().describe(
+  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: z5.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
+  fields: z8.array(CustomFieldWriteSchema).optional().describe(fieldsArrayDescriptor("get_opportunity"))
 });
 async function updateOpportunity(input) {
-  const { id, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
+  const { id, partyId, milestoneId, ownerId, teamId, lostReasonId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
-  if (milestoneId) body["milestone"] = { id: milestoneId };
+  setRef(body, "party", partyId);
+  setRef(body, "milestone", milestoneId);
   let resolvedTeamId = teamId;
   if (ownerId !== void 0 && teamId === void 0) {
-    const { data } = await capsuleGet(`/opportunities/${id}`);
-    resolvedTeamId = data.opportunity?.team?.id ?? void 0;
+    ({ teamId: resolvedTeamId } = await readEntityRefs(`/opportunities/${id}`, "opportunity"));
   }
-  if (ownerId) body["owner"] = { id: ownerId };
-  if (resolvedTeamId === null) body["team"] = null;
-  else if (resolvedTeamId !== void 0) body["team"] = { id: resolvedTeamId };
-  if (lostReasonId) body["lostReason"] = { id: lostReasonId };
+  setRef(body, "owner", ownerId);
+  setNullableRef(body, "team", resolvedTeamId);
+  setRef(body, "lostReason", lostReasonId);
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/opportunities/${id}`, {
     opportunity: body
   });
 }
-var batchUpdateOpportunitySchema = z5.object({
-  items: z5.array(updateOpportunitySchema).min(1).max(50).describe(
-    "Array of 1\u201350 update_opportunity inputs. Each item is the same shape as a single update_opportunity call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget."
-  )
+var { schema: batchUpdateOpportunitySchema, handler: batchUpdateOpportunity } = defineBatch({
+  toolName: "batch_update_opportunity",
+  itemSchema: updateOpportunitySchema,
+  itemDescription: "Array of 1\u201350 update_opportunity inputs. Each item is the same shape as a single update_opportunity call \u2014 id is required, every other field is optional. Capped at 50 so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget.",
+  itemHandler: updateOpportunity
 });
-async function batchUpdateOpportunity(input, opts = {}) {
-  return batchExecute(
-    "batch_update_opportunity",
-    input.items,
-    (item) => updateOpportunity(item),
-    opts
-  );
-}
-var deleteOpportunitySchema = z5.object({
-  id: z5.number().int().positive(),
-  confirm: confirmFlag().describe(
-    "Must be set to true. Permanently deletes the opportunity. Irreversible."
-  )
+var { schema: deleteOpportunitySchema, handler: deleteOpportunity } = defineDelete({
+  toolName: "delete_opportunity",
+  pathPrefix: "/opportunities",
+  confirmHint: "Must be set to true. Permanently deletes the opportunity. Irreversible."
 });
-async function deleteOpportunity(input) {
-  if (input.confirm !== true) {
-    throw new Error("delete_opportunity requires confirm: true");
-  }
-  return idempotent(
-    () => capsuleDelete(`/opportunities/${input.id}`),
-    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
-    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
-  );
-}
 
 // src/tools/projects.ts
-import { z as z6 } from "zod";
-var listProjectsSchema = z6.object({
-  status: z6.enum(["OPEN", "CLOSED"]).optional(),
-  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)
+import { z as z9 } from "zod";
+var listProjectsSchema = z9.object({
+  status: z9.enum(["OPEN", "CLOSED"]).optional(),
+  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z9.number().int().positive().optional().default(1),
+  perPage: z9.number().int().min(1).max(100).optional().default(25)
 });
 async function listProjects(input) {
   const { data, nextPage } = await capsuleGet("/kases", {
@@ -2074,9 +2115,9 @@ async function listProjects(input) {
   });
   return { ...data, nextPage };
 }
-var getProjectSchema = z6.object({
-  id: z6.number().int().positive(),
-  embed: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+var getProjectSchema = z9.object({
+  id: positiveId,
+  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProject(input) {
   const { data } = await capsuleGet(`/kases/${input.id}`, {
@@ -2084,11 +2125,11 @@ async function getProject(input) {
   });
   return data;
 }
-var getProjectsSchema = z6.object({
-  ids: z6.array(z6.number().int().positive()).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: z6.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
+  embed: z9.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function getProjects(input) {
   const { ids, embed } = input;
@@ -2106,21 +2147,21 @@ async function getProjects(input) {
   );
   return { kases: responses.flatMap((r) => r.data.kases) };
 }
-var createProjectSchema = z6.object({
-  name: z6.string().min(1),
-  partyId: z6.number().int().positive().describe("ID of the party linked to this project"),
-  description: z6.string().optional(),
-  status: z6.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
-  ownerId: z6.number().int().positive().optional().describe(
+var createProjectSchema = z9.object({
+  name: z9.string().min(1),
+  partyId: positiveId.describe("ID of the party linked to this project"),
+  description: z9.string().optional(),
+  status: z9.enum(["OPEN", "CLOSED"]).optional().describe("Defaults to OPEN when omitted."),
+  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."
   ),
-  teamId: z6.number().int().positive().optional().describe(
+  teamId: positiveId.optional().describe(
     "Assign to team ID (discover via list_teams). Capsule projects must always have at least one of {owner, team} set \u2014 Capsule returns 422 'owner or team is required' otherwise. Three ownership shapes are valid: owner alone, team alone, or owner+team (the user must be a member of the team \u2014 users can belong to multiple teams; 422 'owner is not a member of the team' otherwise). Tenant-specific board automations may set the team field on project creation (e.g. 'when project enters board X, set team to T'). If you observe a team set despite omitting `teamId`, check the target board's automation rules."
   ),
-  stageId: z6.number().int().positive().optional().describe(
+  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: z6.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD")
+  expectedCloseOn: z9.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD")
 });
 async function createProject(input) {
   const { partyId, ownerId, teamId, status, stageId, ...rest } = input;
@@ -2129,88 +2170,75 @@ async function createProject(input) {
     status: status ?? "OPEN",
     party: { id: partyId }
   };
-  if (ownerId) body["owner"] = { id: ownerId };
-  if (teamId) body["team"] = { id: teamId };
+  setRef(body, "owner", ownerId);
+  setRef(body, "team", teamId);
   if (stageId) body["stage"] = stageId;
   return capsulePost("/kases", { kase: body });
 }
-var updateProjectSchema = z6.object({
-  id: z6.number().int().positive(),
-  name: z6.string().min(1).optional(),
-  description: z6.string().optional(),
-  status: z6.enum(["OPEN", "CLOSED"]).optional(),
-  ownerId: z6.number().int().positive().nullable().optional().describe(
+var updateProjectSchema = z9.object({
+  id: positiveId,
+  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."
+  ),
+  ownerId: positiveId.nullable().optional().describe(
     "Reassign owner: pass a user ID to set, or `null` to unassign (matches the 'Unassign' option in Capsule's web UI). When you supply `ownerId` and omit `teamId` and/or `stageId`, the connector fetches the project's current omitted fields and includes them in the PUT body \u2014 this preserves them across the owner change (without it, Capsule's PUT would clear team; stage carry is defensive against the symmetric clear). Supply `teamId` and/or `stageId` explicitly on the same call to change them instead. `teamId: null` clears the team as part of an owner change. Constraints (Capsule enforces, 422 on violation): owner must be a member of the team if both are set; a project must always have at least one of {owner, team} set (cannot clear both)."
   ),
-  teamId: z6.number().int().positive().nullable().optional().describe(
+  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_project { 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'. A project must always have at least one of {owner, team} set \u2014 `teamId: null` on a project whose owner is already null returns 422 'owner or team is required'."
   ),
-  stageId: z6.number().int().positive().optional().describe(
+  stageId: positiveId.optional().describe(
     "Move the project to this stage (board column). 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: z6.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  fields: z6.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."
   )
 });
 async function updateProject(input) {
-  const { id, ownerId, teamId, stageId, fields, ...rest } = input;
+  const { id, partyId, ownerId, teamId, stageId, fields, ...rest } = input;
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
+  setRef(body, "party", partyId);
   let resolvedTeamId = teamId;
   let resolvedStageId = stageId;
   if (ownerId !== void 0 && (teamId === void 0 || stageId === void 0)) {
-    const { data } = await capsuleGet(`/kases/${id}`);
-    if (teamId === void 0) {
-      resolvedTeamId = data.kase?.team?.id ?? void 0;
-    }
-    if (stageId === void 0) {
-      resolvedStageId = data.kase?.stage?.id ?? void 0;
-    }
+    const current = await readEntityRefs(`/kases/${id}`, "kase");
+    if (teamId === void 0) resolvedTeamId = current.teamId;
+    if (stageId === void 0) resolvedStageId = current.stageId;
   }
-  if (ownerId === null) body["owner"] = null;
-  else if (ownerId !== void 0) body["owner"] = { id: ownerId };
-  if (resolvedTeamId === null) body["team"] = null;
-  else if (resolvedTeamId !== void 0) body["team"] = { id: resolvedTeamId };
+  setNullableRef(body, "owner", ownerId);
+  setNullableRef(body, "team", resolvedTeamId);
   if (resolvedStageId) body["stage"] = resolvedStageId;
   const mappedFields = mapFieldsForBody(fields);
   if (mappedFields !== void 0) body["fields"] = mappedFields;
   return capsulePut(`/kases/${id}`, { kase: body });
 }
-var deleteProjectSchema = z6.object({
-  id: z6.number().int().positive(),
-  confirm: confirmFlag().describe(
-    "Must be set to true. Permanently deletes the project (case). Consider update_project status='CLOSED' instead. Irreversible."
-  )
+var { schema: deleteProjectSchema, handler: deleteProject } = defineDelete({
+  toolName: "delete_project",
+  pathPrefix: "/kases",
+  confirmHint: "Must be set to true. Permanently deletes the project (case). Consider update_project status='CLOSED' instead. Irreversible."
 });
-async function deleteProject(input) {
-  if (input.confirm !== true) {
-    throw new Error("delete_project requires confirm: true");
-  }
-  return idempotent(
-    () => capsuleDelete(`/kases/${input.id}`),
-    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
-    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
-  );
-}
 
 // src/tools/tasks.ts
-import { z as z7 } from "zod";
-var listTasksSchema = z7.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: z7.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: z7.number().int().positive().optional().describe("Filter to tasks owned by this user ID"),
-  page: z7.number().int().positive().optional().default(1),
-  perPage: z7.number().int().min(1).max(100).optional().default(25)
+  ownerId: positiveId.optional().describe("Filter to tasks owned by this user ID"),
+  page: z10.number().int().positive().optional().default(1),
+  perPage: z10.number().int().min(1).max(100).optional().default(25)
 });
 async function listTasks(input) {
   const { data, nextPage } = await capsuleGet("/tasks", {
@@ -2224,15 +2252,15 @@ async function listTasks(input) {
   });
   return { ...data, nextPage };
 }
-var getTaskSchema = z7.object({
-  id: z7.number().int().positive().describe("Task ID")
+var getTaskSchema = z10.object({
+  id: positiveId.describe("Task ID")
 });
 async function getTask(input) {
   const { data } = await capsuleGet(`/tasks/${input.id}`);
   return data;
 }
-var getTasksSchema = z7.object({
-  ids: z7.array(z7.number().int().positive()).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."
   )
 });
@@ -2248,17 +2276,17 @@ async function getTasks(input) {
   );
   return { tasks: responses.flatMap((r) => r.data.tasks) };
 }
-var createTaskSchema = z7.object({
-  description: z7.string().min(1),
-  dueOn: z7.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"),
-  dueTime: z7.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z7.string().optional(),
-  ownerId: z7.number().int().positive().optional().describe(
+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."
   ),
-  partyId: z7.number().int().positive().optional().describe("Link task to a party (mutually exclusive with opportunityId/projectId)"),
-  opportunityId: z7.number().int().positive().optional().describe("Link task to an opportunity (mutually exclusive with partyId/projectId)"),
-  projectId: z7.number().int().positive().optional().describe("Link task to a project (mutually exclusive with partyId/opportunityId)")
+  partyId: positiveId.optional().describe("Link task to a party (mutually exclusive with opportunityId/projectId)"),
+  opportunityId: positiveId.optional().describe("Link task to an opportunity (mutually exclusive with partyId/projectId)"),
+  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);
@@ -2267,79 +2295,86 @@ async function createTask(input) {
   }
   const { ownerId, partyId, opportunityId, projectId, ...rest } = input;
   const body = { ...rest };
-  if (ownerId) body["owner"] = { id: ownerId };
-  if (partyId) body["party"] = { id: partyId };
-  if (opportunityId) body["opportunity"] = { id: opportunityId };
-  if (projectId) body["kase"] = { id: projectId };
+  setRef(body, "owner", ownerId);
+  setRef(body, "party", partyId);
+  setRef(body, "opportunity", opportunityId);
+  setRef(body, "kase", projectId);
   return capsulePost("/tasks", { task: body });
 }
-var updateTaskSchema = z7.object({
-  id: z7.number().int().positive(),
-  description: z7.string().min(1).optional(),
-  dueOn: z7.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
-  dueTime: z7.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
-  detail: z7.string().optional(),
+var updateTaskSchema = z10.object({
+  id: positiveId,
+  description: z10.string().min(1).optional(),
+  dueOn: z10.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("YYYY-MM-DD"),
+  dueTime: z10.string().regex(/^\d{2}:\d{2}$/).optional().describe("HH:MM in user's timezone"),
+  detail: z10.string().optional(),
   // 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: z7.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: z7.number().int().positive().optional().describe(
+  ownerId: positiveId.optional().describe(
     "Reassign owner to user ID. Once set, this connector cannot clear an owner back to null \u2014 use Capsule's web UI for that."
+  ),
+  partyId: positiveId.nullable().optional().describe(
+    "Re-link the task to a party by id, or `null` to orphan it. Mutually exclusive with `opportunityId` / `projectId` \u2014 Capsule enforces 'task can be related to at most one entity' server-side (422 if two parent-refs are set at once, verified in v1.6.3 wire-trace). To swap parent type atomically, pass the old one as `null` and the new one as an id in the same call."
+  ),
+  opportunityId: positiveId.nullable().optional().describe(
+    "Re-link the task to an opportunity by id, or `null` to orphan it. Mutually exclusive with `partyId` / `projectId` \u2014 see `partyId` for the XOR semantic."
+  ),
+  projectId: positiveId.nullable().optional().describe(
+    "Re-link the task to a project (kase) by id, or `null` to orphan it. Mutually exclusive with `partyId` / `opportunityId` \u2014 see `partyId` for the XOR semantic."
   )
 });
 async function updateTask(input) {
-  const { id, ownerId, ...rest } = 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')"
+    );
+  }
   const body = {};
   for (const [k, v] of Object.entries(rest)) {
     if (v !== void 0) body[k] = v;
   }
-  if (ownerId) body["owner"] = { id: ownerId };
+  setRef(body, "owner", ownerId);
+  setNullableRef(body, "party", partyId);
+  setNullableRef(body, "opportunity", opportunityId);
+  setNullableRef(body, "kase", projectId);
   return capsulePut(`/tasks/${id}`, { task: body });
 }
-var completeTaskSchema = z7.object({
-  id: z7.number().int().positive()
+var completeTaskSchema = z10.object({
+  id: positiveId
 });
 async function completeTask(input) {
   return capsulePut(`/tasks/${input.id}`, {
     task: { status: "COMPLETED" }
   });
 }
-var batchCompleteTaskSchema = z7.object({
-  ids: z7.array(z7.number().int().positive()).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."
   )
 });
 async function batchCompleteTask(input, opts = {}) {
   return batchExecute("batch_complete_task", input.ids, (id) => completeTask({ id }), opts);
 }
-var deleteTaskSchema = z7.object({
-  id: z7.number().int().positive(),
-  confirm: confirmFlag().describe(
-    "Must be set to true. Permanently deletes the task. To mark done without losing history use complete_task. Irreversible."
-  )
+var { schema: deleteTaskSchema, handler: deleteTask } = defineDelete({
+  toolName: "delete_task",
+  pathPrefix: "/tasks",
+  confirmHint: "Must be set to true. Permanently deletes the task. To mark done without losing history use complete_task. Irreversible."
 });
-async function deleteTask(input) {
-  if (input.confirm !== true) {
-    throw new Error("delete_task requires confirm: true");
-  }
-  return idempotent(
-    () => capsuleDelete(`/tasks/${input.id}`),
-    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
-    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
-  );
-}
 
 // src/tools/entries.ts
-import { z as z8 } from "zod";
+import { z as z11 } from "zod";
 var listEntriesPagination = {
-  page: z8.number().int().positive().optional().default(1),
-  perPage: z8.number().int().min(1).max(100).optional().default(25),
-  embed: z8.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+  page: z11.number().int().positive().optional().default(1),
+  perPage: z11.number().int().min(1).max(100).optional().default(25),
+  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
 };
-var listPartyEntriesSchema = z8.object({
-  partyId: z8.number().int().positive(),
+var listPartyEntriesSchema = z11.object({
+  partyId: positiveId,
   ...listEntriesPagination
 });
 async function listPartyEntries(input) {
@@ -2349,8 +2384,8 @@ async function listPartyEntries(input) {
   );
   return { ...data, nextPage };
 }
-var listOpportunityEntriesSchema = z8.object({
-  opportunityId: z8.number().int().positive(),
+var listOpportunityEntriesSchema = z11.object({
+  opportunityId: positiveId,
   ...listEntriesPagination
 });
 async function listOpportunityEntries(input) {
@@ -2360,8 +2395,8 @@ async function listOpportunityEntries(input) {
   );
   return { ...data, nextPage };
 }
-var listProjectEntriesSchema = z8.object({
-  projectId: z8.number().int().positive(),
+var listProjectEntriesSchema = z11.object({
+  projectId: positiveId,
   ...listEntriesPagination
 });
 async function listProjectEntries(input) {
@@ -2371,9 +2406,9 @@ async function listProjectEntries(input) {
   );
   return { ...data, nextPage };
 }
-var getEntrySchema = z8.object({
-  id: z8.number().int().positive(),
-  embed: z8.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
+var getEntrySchema = z11.object({
+  id: positiveId,
+  embed: z11.string().optional().describe(EMBED_ATTACHMENTS_PARTICIPANTS_DESCRIPTION)
 });
 async function getEntry(input) {
   const { data } = await capsuleGet(`/entries/${input.id}`, {
@@ -2381,7 +2416,7 @@ async function getEntry(input) {
   });
   return data;
 }
-var listEntriesSchema = z8.object({
+var listEntriesSchema = z11.object({
   ...listEntriesPagination
 });
 async function listEntries(input) {
@@ -2392,14 +2427,14 @@ async function listEntries(input) {
   });
   return { ...data, nextPage };
 }
-var addNoteSchema = z8.object({
-  content: z8.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: z8.number().int().positive().optional().describe("Link note to a party (mutually exclusive with opportunityId/projectId)"),
-  opportunityId: z8.number().int().positive().optional().describe("Link note to an opportunity (mutually exclusive with partyId/projectId)"),
-  projectId: z8.number().int().positive().optional().describe("Link note to a project (mutually exclusive with partyId/opportunityId)"),
-  entryAt: z8.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
+  partyId: positiveId.optional().describe("Link note to a party (mutually exclusive with opportunityId/projectId)"),
+  opportunityId: positiveId.optional().describe("Link note to an opportunity (mutually exclusive with partyId/projectId)"),
+  projectId: positiveId.optional().describe("Link note to a project (mutually exclusive with partyId/opportunityId)"),
+  entryAt: z11.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/).optional().describe(
     "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)."
   )
 });
@@ -2410,18 +2445,18 @@ async function addNote(input) {
     throw new Error("Provide exactly one of partyId, opportunityId, or projectId");
   }
   const body = { type: "note", content };
-  if (partyId) body["party"] = { id: partyId };
-  if (opportunityId) body["opportunity"] = { id: opportunityId };
-  if (projectId) body["kase"] = { id: projectId };
+  setRef(body, "party", partyId);
+  setRef(body, "opportunity", opportunityId);
+  setRef(body, "kase", projectId);
   if (entryAt !== void 0) body["entryAt"] = entryAt;
   return capsulePost("/entries", { entry: body });
 }
-var updateEntrySchema = z8.object({
-  id: z8.number().int().positive().describe("Entry ID to update"),
-  content: z8.string().min(1).optional().describe(
+var updateEntrySchema = z11.object({
+  id: positiveId.describe("Entry ID to update"),
+  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: z8.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`."
   )
 });
@@ -2435,30 +2470,20 @@ async function updateEntry(input) {
   }
   return capsulePut(`/entries/${id}`, { entry: body });
 }
-var deleteEntrySchema = z8.object({
-  id: z8.number().int().positive().describe("Entry (note/email/task-record) ID"),
-  confirm: confirmFlag().describe(
-    "Must be set to true. Permanently deletes the entry \u2014 use this to remove a note from a party/opportunity/project. Irreversible."
-  )
+var { schema: deleteEntrySchema, handler: deleteEntry } = defineDelete({
+  toolName: "delete_entry",
+  pathPrefix: "/entries",
+  confirmHint: "Must be set to true. Permanently deletes the entry \u2014 use this to remove a note from a party/opportunity/project. Irreversible.",
+  idDescription: "Entry (note/email/task-record) ID"
 });
-async function deleteEntry(input) {
-  if (input.confirm !== true) {
-    throw new Error("delete_entry requires confirm: true");
-  }
-  return idempotent(
-    () => capsuleDelete(`/entries/${input.id}`),
-    () => ({ deleted: true, alreadyDeleted: false, id: input.id }),
-    () => ({ deleted: true, alreadyDeleted: true, id: input.id })
-  );
-}
 
 // src/tools/pipelines.ts
-import { z as z9 } from "zod";
+import { z as z12 } from "zod";
 var paginationFields = {
-  page: z9.number().int().positive().optional(),
-  perPage: z9.number().int().min(1).max(100).optional()
+  page: z12.number().int().positive().optional(),
+  perPage: z12.number().int().min(1).max(100).optional()
 };
-var listPipelinesSchema = z9.object({ ...paginationFields });
+var listPipelinesSchema = z12.object({ ...paginationFields });
 async function listPipelines(input) {
   const { data, nextPage } = await capsuleGetCached("/pipelines", {
     page: input.page ?? 1,
@@ -2466,8 +2491,8 @@ async function listPipelines(input) {
   });
   return { ...data, nextPage };
 }
-var listMilestonesSchema = z9.object({
-  pipelineId: z9.number().int().positive(),
+var listMilestonesSchema = z12.object({
+  pipelineId: positiveId,
   ...paginationFields
 });
 async function listMilestones(input) {
@@ -2479,12 +2504,12 @@ async function listMilestones(input) {
 }
 
 // src/tools/boards.ts
-import { z as z10 } from "zod";
+import { z as z13 } from "zod";
 var paginationFields2 = {
-  page: z10.number().int().positive().optional(),
-  perPage: z10.number().int().min(1).max(100).optional()
+  page: z13.number().int().positive().optional(),
+  perPage: z13.number().int().min(1).max(100).optional()
 };
-var listBoardsSchema = z10.object({ ...paginationFields2 });
+var listBoardsSchema = z13.object({ ...paginationFields2 });
 async function listBoards(input) {
   const { data, nextPage } = await capsuleGetCached("/boards", {
     page: input.page ?? 1,
@@ -2492,8 +2517,8 @@ async function listBoards(input) {
   });
   return { ...data, nextPage };
 }
-var listStagesSchema = z10.object({
-  boardId: z10.number().int().positive().optional().describe(
+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
@@ -2508,7 +2533,7 @@ async function listStages(input) {
 }
 
 // src/tools/tags.ts
-import { z as z11 } from "zod";
+import { z as z14 } from "zod";
 var TAG_LIST_PATH = {
   parties: "/parties/tags",
   opportunities: "/opportunities/tags",
@@ -2519,11 +2544,11 @@ var ENTITY_TO_WRAPPER = {
   opportunities: "opportunity",
   kases: "kase"
 };
-var TagEntity = z11.enum(["parties", "opportunities", "kases"]).describe("Which entity type. Use 'kases' for projects (Capsule's legacy path name).");
-var listTagsSchema = z11.object({
-  entity: z11.enum(["parties", "opportunities", "kases"]).describe("The resource type to list tags for"),
-  page: z11.number().int().positive().optional(),
-  perPage: z11.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"),
+  page: z14.number().int().positive().optional(),
+  perPage: z14.number().int().min(1).max(100).optional()
 });
 async function listTags(input) {
   const path = TAG_LIST_PATH[input.entity];
@@ -2533,10 +2558,10 @@ async function listTags(input) {
   });
   return { ...data, nextPage };
 }
-var addTagSchema = z11.object({
+var addTagSchema = z14.object({
   entity: TagEntity,
-  entityId: z11.number().int().positive().describe("The party/opportunity/kase id."),
-  tagName: z11.string().min(1).describe(
+  entityId: positiveId.describe("The party/opportunity/kase id."),
+  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."
   )
 });
@@ -2549,10 +2574,10 @@ async function addTag(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "add_tag");
   return result;
 }
-var removeTagByIdSchema = z11.object({
+var removeTagByIdSchema = z14.object({
   entity: TagEntity,
-  entityId: z11.number().int().positive().describe("The party/opportunity/kase id."),
-  tagId: z11.number().int().positive().describe(
+  entityId: positiveId.describe("The party/opportunity/kase id."),
+  tagId: positiveId.describe(
     "The tag's id. Read via get_party / get_opportunity / get_project with embed='tags' \u2014 each tag entry in the response has an `id` field. list_tags returns the same ids for the same tags, so either source works; reading via embed first is the safer pattern because it confirms the tag is actually attached to this entity before you try to remove it (otherwise Capsule returns 422 'tag not found to delete'). Removing detaches the tag from this entity only; the tag definition itself persists in the tenant for other entities that share it."
   )
 });
@@ -2580,28 +2605,24 @@ async function removeTagById(input) {
   invalidateByPrefix(TAG_LIST_PATH[entity], "remove_tag_by_id");
   return result;
 }
-var batchAddTagSchema = z11.object({
-  items: z11.array(addTagSchema).min(1).max(50).describe(
-    "Array of 1\u201350 add_tag inputs. Useful for mass-tagging \u2014 e.g. 'tag these 20 contacts as RSAC26'. Each item is the same shape as a single add_tag call. The list_tags cache is invalidated for each affected entity type. Capped at 50."
-  )
+var { schema: batchAddTagSchema, handler: batchAddTag } = defineBatch({
+  toolName: "batch_add_tag",
+  itemSchema: addTagSchema,
+  itemDescription: "Array of 1\u201350 add_tag inputs. Useful for mass-tagging \u2014 e.g. 'tag these 20 contacts as RSAC26'. Each item is the same shape as a single add_tag call. The list_tags cache is invalidated for each affected entity type. Capped at 50.",
+  itemHandler: addTag
 });
-async function batchAddTag(input, opts = {}) {
-  return batchExecute("batch_add_tag", input.items, (item) => addTag(item), opts);
-}
-var batchRemoveTagByIdSchema = z11.object({
-  items: z11.array(removeTagByIdSchema).min(1).max(50).describe(
-    "Array of 1\u201350 remove_tag_by_id inputs. Each item is the same shape as a single remove_tag_by_id call. Detaches the tag from each specified entity; the tag definition itself persists in the tenant. Capped at 50."
-  )
+var { schema: batchRemoveTagByIdSchema, handler: batchRemoveTagById } = defineBatch({
+  toolName: "batch_remove_tag_by_id",
+  itemSchema: removeTagByIdSchema,
+  itemDescription: "Array of 1\u201350 remove_tag_by_id inputs. Each item is the same shape as a single remove_tag_by_id call. Detaches the tag from each specified entity; the tag definition itself persists in the tenant. Capped at 50.",
+  itemHandler: removeTagById
 });
-async function batchRemoveTagById(input, opts = {}) {
-  return batchExecute("batch_remove_tag_by_id", input.items, (item) => removeTagById(item), opts);
-}
 
 // src/tools/users.ts
-import { z as z12 } from "zod";
-var listUsersSchema = z12.object({
-  page: z12.number().int().positive().optional(),
-  perPage: z12.number().int().min(1).max(100).optional()
+import { z as z15 } from "zod";
+var listUsersSchema = z15.object({
+  page: z15.number().int().positive().optional(),
+  perPage: z15.number().int().min(1).max(100).optional()
 });
 async function listUsers(input) {
   const { data, nextPage } = await capsuleGetCached("/users", {
@@ -2610,32 +2631,32 @@ async function listUsers(input) {
   });
   return { ...data, nextPage };
 }
-var getCurrentUserSchema = z12.object({});
+var getCurrentUserSchema = z15.object({});
 async function getCurrentUser(_input) {
   const { data } = await capsuleGet("/users/current");
   return data;
 }
 
 // src/tools/filters.ts
-import { z as z13 } from "zod";
-var FilterConditionSchema = z13.object({
-  field: z13.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: z13.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: z13.union([z13.string(), z13.number(), z13.boolean(), z13.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 = z13.object({
-  conditions: z13.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: z13.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z13.number().int().positive().optional().default(1),
-  perPage: z13.number().int().min(1).max(100).optional().default(25)
+  embed: z16.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z16.number().int().positive().optional().default(1),
+  perPage: z16.number().int().min(1).max(100).optional().default(25)
 });
 async function runFilter(entityPath, input) {
   const { data, nextPage } = await capsuleSearch(
@@ -2666,12 +2687,12 @@ async function filterProjects(input) {
 }
 
 // src/tools/metadata.ts
-import { z as z14 } from "zod";
+import { z as z17 } from "zod";
 var paginationFields3 = {
-  page: z14.number().int().positive().optional(),
-  perPage: z14.number().int().min(1).max(100).optional().describe("Page size, max 100. Defaults to 100 for reference data.")
+  page: z17.number().int().positive().optional(),
+  perPage: z17.number().int().min(1).max(100).optional().describe("Page size, max 100. Defaults to 100 for reference data.")
 };
-var listTeamsSchema = z14.object({ ...paginationFields3 });
+var listTeamsSchema = z17.object({ ...paginationFields3 });
 async function listTeams(input) {
   const { data, nextPage } = await capsuleGetCached("/teams", {
     page: input.page ?? 1,
@@ -2679,7 +2700,7 @@ async function listTeams(input) {
   });
   return { ...data, nextPage };
 }
-var listLostReasonsSchema = z14.object({ ...paginationFields3 });
+var listLostReasonsSchema = z17.object({ ...paginationFields3 });
 async function listLostReasons(input) {
   const { data, nextPage } = await capsuleGetCached("/lostreasons", {
     page: input.page ?? 1,
@@ -2687,7 +2708,7 @@ async function listLostReasons(input) {
   });
   return { ...data, nextPage };
 }
-var listActivityTypesSchema = z14.object({ ...paginationFields3 });
+var listActivityTypesSchema = z17.object({ ...paginationFields3 });
 async function listActivityTypes(input) {
   const { data, nextPage } = await capsuleGetCached(
     "/activitytypes",
@@ -2698,12 +2719,12 @@ async function listActivityTypes(input) {
   );
   return { ...data, nextPage };
 }
-var getSiteSchema = z14.object({});
+var getSiteSchema = z17.object({});
 async function getSite(_input) {
   const { data } = await capsuleGetCached("/site");
   return data;
 }
-var listTrackDefinitionsSchema = z14.object({ ...paginationFields3 });
+var listTrackDefinitionsSchema = z17.object({ ...paginationFields3 });
 async function listTrackDefinitions(input) {
   const { data, nextPage } = await capsuleGetCached(
     "/trackdefinitions",
@@ -2711,7 +2732,7 @@ async function listTrackDefinitions(input) {
   );
   return { ...data, nextPage };
 }
-var listCategoriesSchema = z14.object({ ...paginationFields3 });
+var listCategoriesSchema = z17.object({ ...paginationFields3 });
 async function listCategories(input) {
   const { data, nextPage } = await capsuleGetCached("/categories", {
     page: input.page ?? 1,
@@ -2719,7 +2740,7 @@ async function listCategories(input) {
   });
   return { ...data, nextPage };
 }
-var listGoalsSchema = z14.object({ ...paginationFields3 });
+var listGoalsSchema = z17.object({ ...paginationFields3 });
 async function listGoals(input) {
   const { data, nextPage } = await capsuleGetCached("/goals", {
     page: input.page ?? 1,
@@ -2729,14 +2750,14 @@ async function listGoals(input) {
 }
 
 // src/tools/audit.ts
-import { z as z15 } from "zod";
-var listEmployeesSchema = z15.object({
-  partyId: z15.number().int().positive().describe(
+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: z15.number().int().positive().optional().default(1),
-  perPage: z15.number().int().min(1).max(100).optional().default(25),
-  embed: z15.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: z18.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION)
 });
 async function listEmployees(input) {
   const { data, nextPage } = await capsuleGet(
@@ -2745,15 +2766,15 @@ async function listEmployees(input) {
   );
   return { ...data, nextPage };
 }
-var DeletedSinceSchema = z15.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: z15.number().int().positive().optional().default(1),
-  perPage: z15.number().int().min(1).max(100).optional().default(25)
+  page: z18.number().int().positive().optional().default(1),
+  perPage: z18.number().int().min(1).max(100).optional().default(25)
 };
-var listDeletedPartiesSchema = z15.object(DeletedPagination);
+var listDeletedPartiesSchema = z18.object(DeletedPagination);
 async function listDeletedParties(input) {
   const { data, nextPage } = await capsuleGet("/parties/deleted", {
     since: input.since,
@@ -2762,7 +2783,7 @@ async function listDeletedParties(input) {
   });
   return { ...data, nextPage };
 }
-var listDeletedOpportunitiesSchema = z15.object(DeletedPagination);
+var listDeletedOpportunitiesSchema = z18.object(DeletedPagination);
 async function listDeletedOpportunities(input) {
   const { data, nextPage } = await capsuleGet("/opportunities/deleted", {
     since: input.since,
@@ -2771,7 +2792,7 @@ async function listDeletedOpportunities(input) {
   });
   return { ...data, nextPage };
 }
-var listDeletedProjectsSchema = z15.object(DeletedPagination);
+var listDeletedProjectsSchema = z18.object(DeletedPagination);
 async function listDeletedProjects(input) {
   const { data, nextPage } = await capsuleGet("/kases/deleted", {
     since: input.since,
@@ -2782,14 +2803,14 @@ async function listDeletedProjects(input) {
 }
 
 // src/tools/relationships.ts
-import { z as z16 } from "zod";
-var RelationshipEntity = z16.enum(["opportunities", "kases"]).describe("Which entity has the additional-party links. Use 'kases' for projects.");
-var listAdditionalPartiesSchema = z16.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: z16.number().int().positive().describe("ID of the opportunity or project."),
-  embed: z16.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z16.number().int().positive().optional().default(1),
-  perPage: z16.number().int().min(1).max(100).optional().default(25)
+  entityId: positiveId.describe("ID of the opportunity or project."),
+  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z19.number().int().positive().optional().default(1),
+  perPage: z19.number().int().min(1).max(100).optional().default(25)
 });
 async function listAdditionalParties(input) {
   const { data, nextPage } = await capsuleGet(
@@ -2798,10 +2819,12 @@ async function listAdditionalParties(input) {
   );
   return { ...data, nextPage };
 }
-var addAdditionalPartySchema = z16.object({
+var addAdditionalPartySchema = z19.object({
   entity: RelationshipEntity,
-  entityId: z16.number().int().positive(),
-  partyId: z16.number().int().positive().describe("ID of the party (person or organisation) to link as an additional party.")
+  entityId: positiveId,
+  partyId: positiveId.describe(
+    "ID of the party (person or organisation) to link as an additional party."
+  )
 });
 async function addAdditionalParty(input) {
   try {
@@ -2829,10 +2852,10 @@ async function addAdditionalParty(input) {
     throw err;
   }
 }
-var removeAdditionalPartySchema = z16.object({
+var removeAdditionalPartySchema = z19.object({
   entity: RelationshipEntity,
-  entityId: z16.number().int().positive(),
-  partyId: z16.number().int().positive(),
+  entityId: positiveId,
+  partyId: positiveId,
   confirm: confirmFlag().describe(
     "Must be set to true. Removes the link between the entity and the additional party. The party itself is not deleted. Reversible by re-adding the link."
   )
@@ -2859,11 +2882,11 @@ async function removeAdditionalParty(input) {
     })
   );
 }
-var listAssociatedProjectsSchema = z16.object({
-  opportunityId: z16.number().int().positive(),
-  embed: z16.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z16.number().int().positive().optional().default(1),
-  perPage: z16.number().int().min(1).max(100).optional().default(25)
+var listAssociatedProjectsSchema = z19.object({
+  opportunityId: positiveId,
+  embed: z19.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z19.number().int().positive().optional().default(1),
+  perPage: z19.number().int().min(1).max(100).optional().default(25)
 });
 async function listAssociatedProjects(input) {
   const { data, nextPage } = await capsuleGet(
@@ -2874,9 +2897,9 @@ async function listAssociatedProjects(input) {
 }
 
 // src/tools/custom-fields.ts
-import { z as z17 } from "zod";
-var CustomFieldEntity = z17.enum(["parties", "opportunities", "kases"]).describe("Which entity type's custom field schema to inspect. Use 'kases' for projects.");
-var listCustomFieldsSchema = z17.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) {
@@ -2885,9 +2908,9 @@ async function listCustomFields(input) {
   );
   return data;
 }
-var getCustomFieldSchema = z17.object({
+var getCustomFieldSchema = z20.object({
   entity: CustomFieldEntity,
-  fieldId: z17.number().int().positive().describe("Custom field definition id.")
+  fieldId: positiveId.describe("Custom field definition id.")
 });
 async function getCustomField(input) {
   const { data } = await capsuleGetCached(
@@ -2897,11 +2920,11 @@ async function getCustomField(input) {
 }
 
 // src/tools/tracks.ts
-import { z as z18 } from "zod";
-var TrackEntity = z18.enum(["parties", "opportunities", "kases"]).describe("Use 'kases' for projects.");
-var listEntityTracksSchema = z18.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: z18.number().int().positive()
+  entityId: positiveId
 });
 async function listEntityTracks(input) {
   const { data } = await capsuleGet(
@@ -2909,20 +2932,20 @@ async function listEntityTracks(input) {
   );
   return data;
 }
-var showTrackSchema = z18.object({
-  trackId: z18.number().int().positive()
+var showTrackSchema = z21.object({
+  trackId: positiveId
 });
 async function showTrack(input) {
   const { data } = await capsuleGet(`/tracks/${input.trackId}`);
   return data;
 }
-var applyTrackSchema = z18.object({
-  entity: z18.enum(["opportunities", "kases"]).describe("Which entity to apply the track to. Use 'kases' for projects."),
-  entityId: z18.number().int().positive(),
-  trackDefinitionId: z18.number().int().positive().describe(
+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: z18.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."
   )
 });
@@ -2935,9 +2958,9 @@ async function applyTrack(input) {
   if (input.startDate !== void 0) track["trackDateOn"] = input.startDate;
   return capsulePost("/tracks", { track });
 }
-var updateTrackSchema = z18.object({
-  trackId: z18.number().int().positive(),
-  fields: z18.record(z18.string(), z18.unknown()).describe(
+var updateTrackSchema = z21.object({
+  trackId: positiveId,
+  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."
   )
 });
@@ -2949,8 +2972,8 @@ async function updateTrack(input) {
     track: input.fields
   });
 }
-var removeTrackSchema = z18.object({
-  trackId: z18.number().int().positive(),
+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."
   )
@@ -2967,13 +2990,13 @@ async function removeTrack(input) {
 }
 
 // src/tools/attachments.ts
-import { z as z19 } 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 = z19.object({
-  id: z19.number().int().positive().describe("Attachment ID."),
-  maxSizeBytes: z19.number().int().positive().max(HARD_MAX_SIZE_BYTES).optional().describe(
+var getAttachmentSchema = z22.object({
+  id: positiveId.describe("Attachment ID."),
+  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.`
   )
 });
@@ -2988,22 +3011,22 @@ async function getAttachment(input) {
   }
   return { contentType, buffer, sizeBytes };
 }
-var uploadAttachmentSchema = z19.object({
-  filename: z19.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: z19.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: z19.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: z19.string().optional().describe(
+  content: z22.string().optional().describe(
     "Body text for the note that will hold the attachment. Defaults to '[attachment]' if omitted."
   ),
-  partyId: z19.number().int().positive().optional().describe("Link the new note to a party (mutually exclusive with opportunityId / projectId)."),
-  opportunityId: z19.number().int().positive().optional(),
-  projectId: z19.number().int().positive().optional()
+  partyId: positiveId.optional().describe("Link the new note to a party (mutually exclusive with opportunityId / projectId)."),
+  opportunityId: positiveId.optional(),
+  projectId: positiveId.optional()
 });
 function isValidBase64(s) {
   if (!/^[A-Za-z0-9+/]*={0,2}$/.test(s)) return false;
@@ -3053,23 +3076,23 @@ async function uploadAttachment(input) {
 }
 
 // src/tools/saved-filters.ts
-import { z as z20 } from "zod";
-var EntitySchema = z20.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 = z20.object({
+var listSavedFiltersSchema = z23.object({
   entity: EntitySchema
 });
 async function listSavedFilters(input) {
   const { data } = await capsuleGetCached(`/${input.entity}/filters`);
   return data;
 }
-var runSavedFilterSchema = z20.object({
+var runSavedFilterSchema = z23.object({
   entity: EntitySchema,
-  id: z20.number().int().positive().describe("The saved filter id (from list_saved_filters)."),
-  embed: z20.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
-  page: z20.number().int().positive().optional().default(1),
-  perPage: z20.number().int().min(1).max(100).optional().default(25)
+  id: positiveId.describe("The saved filter id (from list_saved_filters)."),
+  embed: z23.string().optional().describe(EMBED_TAGS_FIELDS_DESCRIPTION),
+  page: z23.number().int().positive().optional().default(1),
+  perPage: z23.number().int().min(1).max(100).optional().default(25)
 });
 async function runSavedFilter(input) {
   const { data, nextPage } = await capsuleGet(
@@ -3087,7 +3110,7 @@ function createCapsuleMcpServer(opts) {
   const server = new McpServer(
     {
       name: "capsulemcp",
-      version: "1.6.1",
+      version: "1.6.3",
       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
@@ -3190,7 +3213,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_party",
-      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId). Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
+      "Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, organisationId). For PERSON parties, organisationId links to an organisation or null unlinks the person from its organisation; for ORGANISATION parties Capsule silently ignores organisationId. Only the fields you provide are changed. Child arrays (emailAddresses / phoneNumbers / addresses / websites) on this tool are APPEND-ONLY: items are merged into the existing list, not replaced. For surgical changes \u2014 replacing one email, removing one phone number, fixing the type on one address \u2014 use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).",
       updatePartySchema,
       updateParty
     );
@@ -3325,7 +3348,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_opportunity",
-      "Update fields on an existing opportunity. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side.",
+      "Update fields on an existing opportunity, including the parent-reference field `partyId` to reassign the opp to a different primary party. Only the fields you provide are changed. Closed (Won/Lost) opportunities ARE editable \u2014 Capsule does not enforce closed-record immutability, so `value`, `description`, etc. can be changed on a Won opp without warning. If the workflow needs historical revenue numbers to be stable, enforce that caller-side. Capsule requires every opportunity to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
       updateOpportunitySchema,
       updateOpportunity
     );
@@ -3390,7 +3413,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_project",
-      "Update fields on an existing project. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning.",
+      "Update fields on an existing project, including the parent-reference field `partyId` to reassign the project to a different primary party. Only the fields you provide are changed. Use status='CLOSED' to close a project. CLOSED projects remain fully editable \u2014 Capsule does not enforce closed-record immutability. Stage moves and description edits on a CLOSED project are accepted without warning. Capsule requires every project to have a party \u2014 passing `partyId: null` is rejected with 422 'party is required'.",
       updateProjectSchema,
       updateProject
     );
@@ -3469,7 +3492,7 @@ function createCapsuleMcpServer(opts) {
     registerTool(
       server,
       "update_task",
-      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), and `ownerId`. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
+      "Update fields on an existing task: `description`, `dueOn`, `dueTime`, `detail`, `status` (OPEN or COMPLETED), `ownerId`, and the parent-reference fields `partyId`, `opportunityId`, `projectId`. Pass a parent id to re-link the task, or null on a parent field to orphan/unlink it; at most one parent id may be set in a single call, though null+id swaps are allowed. Only the fields you provide are changed. To mark a task done, prefer the dedicated `complete_task` tool \u2014 it's idempotent (a no-op success on an already-completed task) and semantically clearer than `update_task status=COMPLETED`. Capsule rejects directly setting status=PENDING (which exists only internally for track-driven tasks); use OPEN or COMPLETED. Completed tasks remain fully editable \u2014 Capsule does not enforce closed-record immutability.",
       updateTaskSchema,
       updateTask
     );
@@ -3672,7 +3695,7 @@ function createCapsuleMcpServer(opts) {
   registerTool(
     server,
     "list_teams",
-    "List all teams configured in the Capsule account. Useful as input for filter_* queries that scope by team, and for reporting. LIMITATION: returns team identity only (id, name, description, timestamps). Capsule's v2 API does not expose team\u2194user membership through any endpoint \u2014 `GET /teams/{id}/users` 404s, `embed=users` is silently ignored, and `GET /users/{id}` doesn't include a `teams` field. To determine whether a given user belongs to a given team, either check Capsule's web UI Team Membership page, or probe via `update_project { ownerId: U, teamId: T }` and read the response \u2014 422 'owner is not a member of the team' means U \u2209 T.",
+    "List all teams configured in the Capsule account. Useful as input for filter_* queries that scope by team, and for reporting. LIMITATION: returns team identity only (id, name, description, timestamps). Capsule's v2 API does not expose team\u2194user membership through any endpoint \u2014 `GET /teams/{id}/users` 404s, `embed=users` is silently ignored, and `GET /users/{id}` doesn't include a `teams` field. To determine whether a given user belongs to a given team, either check Capsule's web UI Team Membership page, or probe via `update_project { ownerId: U, teamId: T }` / `batch_update_opportunity { items: [{ id: <any opp>, ownerId: U, teamId: T }] }` and read the response \u2014 422 'owner is not a member of the team' means U \u2209 T. Both probe paths apply the same membership constraint server-side.",
     listTeamsSchema,
     listTeams
   );