Skip to main content
Glama
soil-dev

capsulemcp

by soil-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

update_party

Updates a party's name, about, title, job title, ownership/team, custom fields, and appends contact details without altering omitted fields.

Instructions

Update top-level fields on an existing party (about, firstName/lastName/name/title/jobTitle, ownerId, teamId, organisationId). ownerId and teamId both accept null to unassign — the combination {ownerId: null, teamId: <id>} puts a party into 'team-owned, no specific user' state (the common pattern when transferring ownership to a team after a user departs). For PERSON parties, organisationId links to an organisation or null unlinks; 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 — replacing one email, removing one phone number, fixing the type on one address — use the dedicated atomic tools: add_party_email_address / remove_party_email_address_by_id (and the phone/address/website equivalents).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYes
nameNo
aboutNo
titleNo
fieldsNoSet custom field values on this record. PARTIAL UPDATE: only the definitions you list are touched; any field NOT in this array is left unchanged. Discover available definitions via list_custom_fields; read current values via get_party with embed='fields'.
teamIdNoAssign to team ID (discover via list_teams). Pass a team ID to set, or `null` to unassign. Capsule enforces the owner∈team membership constraint — passing a team the current owner doesn't belong to returns 422 'owner is not a member of the team'. Combine `ownerId: null` + `teamId: <T>` in one call to transfer a party to team-ownership with no specific user (verified empirically in v1.6.4 wire-trace; the membership rule doesn't fire when owner is null).
ownerIdNoPass a user ID to set, or `null` to unassign (verified empirically in v1.6.4 wire-trace — Capsule accepts `owner: null` on PUT /parties/:id for both persons and organisations). Discover IDs via list_users. WARNING: Capsule's PUT on parties has the same asymmetric owner/team semantic documented in NOTES-ON-CAPSULE-API.md §27 for project updates — setting `owner` while omitting `team` is plausibly clearing-prone. When you supply `ownerId` and omit `teamId`, this connector reads the party's current team and includes it in the PUT body to preserve it across the owner change. Supply `teamId` explicitly to change it.
jobTitleNo
lastNameNo
websitesNoAPPEND-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.
addressesNoAPPEND-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 — 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).
firstNameNo
phoneNumbersNoAPPEND-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.
emailAddressesNoAPPEND-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).
organisationIdNoFor 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 — 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.3.1
    • changedInput schema / properties / emailAddresses / items / properties / address / pattern
      Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
  2. Changed4 schema fields changedv2.3.0
    • removedInput schema / properties / fields / items / properties / value / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / fields / items / properties / value / type
      Added value: +[
+  "string",
+  "number",
+  "boolean",
+  "null"
+]
    • changedInput schema / properties / fields / items / required
      Previous value: -[
-  "value"
-]New value: +[
+  "definitionId",
+  "value"
+]
    • addedInput schema / required
      Added value: +[
+  "id"
+]
  3. Changed1 schema field changedv2.1.2
    • changedInput schema / properties / ownerId / description
      Previous value: -"Pass a user ID to set, or `null` to unassign (verified empirically in v1.6.4 wire-trace — Capsule accepts `owner: null` on PUT /parties/:id for both persons and organisations). Discover IDs via list_users. WARNING: Capsule's PUT on /parties has the same asymmetric owner/team semantic documented in NOTES-ON-CAPSULE-API.md §27 for /kases — setting `owner` while omitting `team` is plausibly clearing-prone. When you supply `ownerId` and omit `teamId`, this connector reads the party's current team and includes it in the PUT body to preserve it across the owner change. Supply `teamId` explicitly to change it."New value: +"Pass a user ID to set, or `null` to unassign (verified empirically in v1.6.4 wire-trace — Capsule accepts `owner: null` on PUT /parties/:id for both persons and organisations). Discover IDs via list_users. WARNING: Capsule's PUT on parties has the same asymmetric owner/team semantic documented in NOTES-ON-CAPSULE-API.md §27 for project updates — setting `owner` while omitting `team` is plausibly clearing-prone. When you supply `ownerId` and omit `teamId`, this connector reads the party's current team and includes it in the PUT body to preserve it across the owner change. Supply `teamId` explicitly to change it."
  4. Addedv1.7.0
  5. Removedv1.6.2
  6. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only supply readOnlyHint=false and destructiveHint=false, so the description carries the full burden of behavior. It discloses append-only child-array semantics, partial-update behavior, silent ignoring of organisationId for ORGANISATION parties, and the team-owned null-owner combination - all non-obvious behaviors an agent needs to avoid data loss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six dense sentences, each carrying a distinct decision-relevant fact: the fields, null/unassignment semantics, organisation-type behavior, partial updates, append-only child arrays, and a pointer to atomic tools. No boilerplate, no repetition of what the schema already says clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter mutating tool with no output schema, the description covers the hard parts - ownership transfer, append-only boundaries, and atomic alternatives - that determine correctness. The only material gap is an explicit statement of the return payload (updated party vs. 204/empty), which the agent cannot infer from the description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 53%, so the description compensates by grouping parameters (top-level, owner/team/org, child arrays) and adding cross-parameter semantics like partial update and append-only behavior. The complex parameters already have detailed schema descriptions, and the remaining plain ones (name, title, firstName) are self-explanatory values, so the description adds the right sort of meta-semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a precise verb and resource ('Update top-level fields on an existing party') and then lists the exact fields it touches, making it clearly distinct from create_party, batch_update_party, and the atomic add/remove party-address tools. An agent can select it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-not-to-use guidance: for surgical changes it names the dedicated atomic tools (add_party_email_address / remove_party_email_address_by_id and equivalents) because child arrays are append-only. It also explains the ownerId/teamId null-combination pattern, so the agent knows both when to use this tool and when to go elsewhere.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools