Skip to main content
Glama
soil-dev

capsulemcp

by soil-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

batch_add_tag

Tag multiple contacts, opportunities, or projects at once by submitting a list of entity IDs and tag names. Processes up to 50 items in parallel, returning per-item results and a summary.

Instructions

Attach tags to many entities in parallel — e.g. tag a list of 20 contacts as 'RSAC26' after a conference, or apply the 'Departed' tag to 10 people in a layoff batch. Pass items: [{ entity, entityId, tagName }, ...] (1–50 items). Each item is processed identically to a single add_tag call. Connector fans out parallel HTTP requests, default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY). Returns { results: [{ok, ...} per item], summary: {total, succeeded, failed} }. The list_tags cache is invalidated for each affected entity type.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemsYesArray of 1–50 add_tag inputs. Useful for mass-tagging — 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.3.0
    • changedInput schema / properties / items / items / required
      Previous value: -[
-  "entity",
-  "tagName"
-]New value: +[
+  "entity",
+  "entityId",
+  "tagName"
+]
  2. Changed4 schema fields changedv2.1.2
    • removedInput schema / properties / items / items / properties / entity / description
      Removed value: -"Which entity type. Use 'kases' for projects (Capsule's legacy path name)."
    • changedInput schema / properties / items / items / properties / entity / enum
      Previous value: -[
-  "parties",
-  "opportunities",
-  "kases"
-]New value: +[
+  "parties",
+  "opportunities",
+  "projects"
+]
    • removedInput schema / properties / items / items / properties / entityId / description
      Removed value: -"The party/opportunity/kase id."
    • removedInput schema / properties / items / items / properties / tagName / description
      Removed value: -"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 — re-attaching an already-attached tag is harmless."
  3. Addedv1.7.0
  4. Removedv1.6.2
  5. Addedv1.6.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnly/destructive annotations, it discloses parallel fan-out, the default concurrency cap (CAPSULE_MCP_BATCH_CONCURRENCY=5), cache invalidation per entity type, and the exact result/summary shape. These are non-obvious side effects the annotations alone would not convey.

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 front-loaded with purpose, then gives usage shape, runtime behavior, return value, and cache side effect in a few sentences with no filler. Each sentence carries distinct information.

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?

With no output schema, the description compensates by specifying the returned { results, summary } shape. It also covers item count limits, concurrency behavior, per-item equivalence to add_tag, and cache invalidation, which is complete for the tool's complexity.

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?

The input schema already documents the item structure fully (100% coverage), so the baseline is 3. The description adds value by showing the exact array shape inline, tying it to realistic mass-tagging examples, and explaining that each item behaves like a standalone add_tag call, going slightly beyond the schema baseline.

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 opens with a specific verb and resource ('Attach tags to many entities in parallel'), supported by concrete scenarios and an explicit comparison to the single add_tag call. This clearly distinguishes batch_add_tag from siblings like add_tag and batch_remove_tag_by_id.

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

Usage Guidelines4/5

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

The examples (RSAC26 conference tagging, layoff batches) define when batch tagging is appropriate, and the 1–50 item cap plus 'each item is processed identically to a single add_tag call' grounds the usage model. It does not explicitly say to use add_tag for a single item, but that alternative is strongly implied.

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