Create a new color swatch in an open InDesign document by defining its name, color model, and channel values.
Create a new color swatch
| Name | Required | Description | Default |
|---|---|---|---|
| red | No | ||
| blue | No | ||
| cyan | No | ||
| name | Yes | ||
| black | No | ||
| green | No | ||
| model | Yes | ||
| yellow | No | ||
| magenta | No | ||
| colorType | No | process | |
| document_id | No | Which open document to act on: a name (see document_listOpen) or a 0-based index. Defaults to the front document. |
Changes observed during successful MCP inspections.
v1.6.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure and delivers nothing: no mutation/reversibility notes, no permission or open-document requirement, no explanation that the swatch model determines which channel parameters apply. It also gives no hint of the result of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is tightly sized and front-loaded, but this is under-specification rather than conciseness. One short line does not earn its place against an 11-parameter, enum-bearing mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 11 parameters, two enums, model-dependent channel values, no annotations and no output schema, the description is grossly incomplete. An agent cannot reliably construct a valid call without guessing which parameters the chosen model requires.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 9% — only document_id is annotated — and 11 parameters are involved. The description adds no information about the model/colorType enums or the fact that rgb, cmyk, lab and spot models each use different channel parameters, leaving the critical parameter interplay entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Create a new color swatch'), so an agent immediately knows the operation. However, it draws no distinction from siblings like color_swatch_list, color_swatch_delete, color_gradient_create, or color_apply, leaving the agent to infer scope from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus alternatives. The agent gets no guidance on prerequisites (e.g. an open document) or on how this differs from color_gradient_create or color_apply, which operate in the same color space.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.