Apply a list to a specific paragraph in an open InDesign document by providing page, frame, paragraph, and list name. Set level for nesting.
Apply a list to a specific paragraph
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| listName | Yes | ||
| pageIndex | Yes | ||
| frameIndex | Yes | ||
| document_id | No | Which open document to act on: a name (see document_listOpen) or a 0-based index. Defaults to the front document. | |
| paragraphIndex | Yes |
Changes observed during successful MCP inspections.
v1.6.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state whether 'Apply' overwrites existing list formatting, how numbering restarts, whether the listName must reference a defined list, or what errors occur on an invalid paragraph address.
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?
One short, front-loaded sentence with no filler, which is structurally clean but far too terse for a six-parameter mutation tool. The brevity reflects under-specification rather than disciplined concision.
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?
A mutation tool with no annotations, no output schema, six parameters at 17% documentation coverage, and no statement of prerequisites or side effects. The description leaves the agent without the information needed to call it correctly the first time.
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 only 17% (just document_id), leaving pageIndex, frameIndex, paragraphIndex, listName, and level undocumented in both schema and description. The description's phrase 'specific paragraph' hints at the three-index addressing scheme but never explains it, and it says nothing about level or the listName format.
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 gives a specific verb ('Apply') and resource ('list') plus the target ('a specific paragraph'), which is clearer than the bare name. However, it does not distinguish this from the very similar sibling list_applyToSelection, which applies a list to whatever is selected rather than to an explicitly addressed paragraph.
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 guidance on when to prefer this over list_applyToSelection, nor any mention that a list must first exist via list_define or that list_removeFromParagraph is the inverse operation. The agent must infer the workflow from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.