Skip to main content
Glama
soil-dev

capsulemcp

by soil-dev

batch_update_project

Update up to 50 projects in a single parallel call to handle bulk stage transitions, owner reassignments, or closures without sequential requests.

Instructions

Update 1–50 projects in parallel. Same input shape as update_project but wrapped in an items array. Use this — not N sequential update_project calls — for mass stage transitions (e.g. move a board column of projects to a new stage), bulk owner reassignments after a personnel change, or batch closures. Mirrors batch_update_party and batch_update_opportunity — identical fan-out shape across the three entity types. Connector fans out parallel HTTP requests, default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }. Partial failures possible; Capsule has no rollback.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemsYesArray of 1–50 update_project inputs. Each item is the same shape as a single update_project call — 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). Mirrors batch_update_party and batch_update_opportunity — same shape across the three entity types.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.3.0
    • removedInput schema / properties / items / items / properties / fields / items / properties / value / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / items / items / properties / fields / items / properties / value / type
      Added value: +[
      +  "string",
      +  "number",
      +  "boolean",
      +  "null"
      +]
    • changedInput schema / properties / items / items / properties / fields / items / required
      Previous value: -[
      -  "value"
      -]New value: +[
      +  "definitionId",
      +  "value"
      +]
    • addedInput schema / properties / items / items / required
      Added value: +[
      +  "id"
      +]
  2. Changed9 schema fields changedv2.1.2
    • removedInput schema / properties / items / items / properties / expectedCloseOn / description
      Removed value: -"YYYY-MM-DD"
    • removedInput schema / properties / items / items / properties / fields / description
      Removed value: -"Set 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_project with embed='fields'. 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 — use add_tag explicitly if you want it visible via embed=tags."
    • removedInput schema / properties / items / items / properties / fields / items / properties / definitionId / description
      Removed value: -"The custom-field definition id from list_custom_fields. Identifies which field on the entity to set."
    • removedInput schema / properties / items / items / properties / fields / items / properties / value / description
      Removed value: -"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 — 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."
    • removedInput schema / properties / items / items / properties / ownerId / description
      Removed value: -"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 — 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)."
    • removedInput schema / properties / items / items / properties / partyId / description
      Removed value: -"Reassign the project to a different primary party. Capsule requires every project to have a party — passing `null` is rejected with 422 'party is required' (verified empirically in v1.6.3 wire-trace). Discover ids via search_parties / filter_parties. NOTE: parent-ref nullability differs by entity — `update_task.partyId` IS nullable (orphan task), but opportunities and projects must always have a parent party. The same applies to `update_opportunity.partyId`."
    • removedInput schema / properties / items / items / properties / stageId / description
      Removed value: -"Move the project to this stage (board column), or `null` to remove from all stages (verified empirically in v1.6.5 wire-trace — Capsule accepts `stage: null` on PUT /kases/:id and the project no longer appears on any board). Discover IDs via list_stages. Owner and team are preserved across stage-only updates (Capsule's PUT semantic). WARNING (cross-board): Capsule does NOT validate that the new stage belongs to the project's current board — 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."
    • addedInput schema / properties / items / items / properties / startOn
      Added value: +{
      +  "anyOf": [
      +    {
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • removedInput schema / properties / items / items / properties / teamId / description
      Removed value: -"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 — 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 — `teamId: null` on a project whose owner is already null returns 422 'owner or team is required'."
  3. Addedv1.7.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It does this well by revealing parallel HTTP fan-out, a default concurrency cap of 5 (with env var), the return shape, possible partial failures, and the absence of rollback. This is exactly the kind of operational context an agent needs.

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?

The description is dense but every sentence contributes: identity, usage guidance, sibling parity, concurrency behavior, return shape, and failure semantics. It is front-loaded with the core action and scopes the tool before diving into operational details.

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

Completeness5/5

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

For a batch mutation tool with no output schema, the description is unusually complete: it covers the input contract, when to use it, how it executes, what it returns, partial-failure behavior, and lack of rollback. There is no critical operational gap that would prevent correct invocation.

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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics about the items array: it wraps update_project inputs, is capped at 50 for rate-limit reasons, and mirrors sibling batch tools' shape. This goes beyond the schema's structural definition and explains why the constraint exists.

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 states a specific verb ('Update 1–50 projects in parallel'), names the resource, and explicitly contrasts itself with update_project and sibling batch tools. An agent can immediately distinguish this from sequential project updates and from batch_update_party/batch_update_opportunity without inspecting schemas.

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-to-use guidance: mass stage transitions, bulk owner reassignments, batch closures — and explicitly says to use this rather than N sequential update_project calls. It also names the sibling batch tools it mirrors, which helps an agent generalize the fan-out shape across entity types.

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