indesign-nutria-mcp

Does 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 is a mutation/creation tool, yet the description says nothing about required permissions, whether the target document must already be open, what happens on failure, or what the resulting object/response looks like. The one sentence only restates purpose.

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 front-loaded and free of waste, so it reads cleanly. However, for an 11-parameter creation tool with no annotations it is under-sized rather than appropriately concise, leaving most call-relevant detail unaddressed.

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?

Given high complexity (11 params, 5 required, three enums), no annotations, and no output schema, a one-line description is inadequate. An agent lacks the behavioral and parameter context needed to invoke this reliably.

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 9% across 11 parameters (only document_id is documented), so the description must compensate and does not. It alludes loosely to 'insertion point' (insertionIndex) and 'text frame' (contentType), but leaves width, height, xOffset, yOffset, spaceAbove, anchorPoint, and anchoredPosition entirely unexplained.

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 (Create) and resource (anchored object) and even names two placement modes: 'at an insertion point or attach to a text frame.' This distinguishes it from its direct siblings like anchoredObject_setPosition or anchoredObject_release, though it does not explicitly differentiate from text_addFrame or shape_create.

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 explicit when-to-use or when-not-to-use guidance, and no named alternatives. It hints at two modes but does not say when to prefer one over the other, nor mention that a document must be open (implied only by the document_id parameter).

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. 'Get' implies a read, but there is no statement of what settings are returned, whether the object must exist, whether settings include position/anchor properties, or any permission requirement.

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 short, but it is under-specified rather than concise — it consumes the space without conveying any information beyond the tool name. Nothing meaningful is front-loaded because nothing meaningful is present.

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?

There is no output schema and no annotation coverage, so the description must explain what comes back and how to address the target. It leaves the required pageIndex/itemIndex addressing scheme unexplained and never says which settings are returned, making it inadequate for an agent to call or interpret this tool.

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 coverage is only 33%: document_id is well documented in the schema, but the two REQUIRED parameters pageIndex and itemIndex have no description in either the schema or the description. With low coverage, the description was required to compensate, and it adds zero parameter meaning.

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 states a verb and resource ('Get anchored object settings'), so the agent knows it is a read of anchored-object settings. However, it is essentially the tool name re-expanded into sentence case, with no scope details (which anchored object, which settings) and nothing to distinguish it from anchoredObject_setProperties, anchoredObject_setPosition, or anchoredObject_release. It sits between a vague purpose and a tautology.

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?

No when-to-use guidance, no prerequisites, and no named alternatives. The sibling set contains several anchoredObject_* tools and the agent is given no criterion for choosing getSettings over them.

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

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

With no annotations, the description carries the full behavioral burden, and it only says the object becomes a regular page item. It does not say whether position/text-wrap is preserved, whether the change is reversible, or what happens to the anchoring frame — the details an agent most needs for a mutation.

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?

A single, front-loaded sentence with no filler. It is efficient, though the brevity shades into under-specification rather than tightness.

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 mutation tool with no annotations, no output schema and two undocumented required parameters, the definition is materially incomplete. It omits preconditions, side effects and the indexing semantics needed to call it correctly.

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 33%: document_id is documented but pageIndex and itemIndex — both required — have no schema descriptions and no explanation in the description. The description adds zero parameter meaning, so an agent cannot tell how the target anchored object is identified.

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?

States a specific verb (release) and resource (anchored object) plus the resulting state (regular page item). That distinguishes it from the sibling verbs anchoredObject_create, setPosition, getSettings and setProperties, though it never names them explicitly.

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?

No when-to-use guidance, no preconditions (e.g. the object must already be anchored), and no mention of the sibling tools an agent might confuse this with. The agent must infer everything from the name.

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

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

No annotations are provided, so the description carries full behavioral burden. It implies a mutation but does not disclose permission requirements, whether offsets are relative or absolute, what happens to inline versus custom anchored objects, or whether changes are reversible. Only the bare fact of mutation is conveyed.

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 description is extremely short and front-loaded, with no wasted words. However, this brevity reflects under-specification rather than efficiency, since critical invocation details are absent.

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 an eight-parameter mutation tool with no annotations, no output schema, and low schema coverage, the four-word description is grossly inadequate. An agent cannot reliably infer coordinate semantics, enum meanings, or required context from it.

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 13%, with seven of eight parameters undocumented. The description adds no meaning beyond the tool name, leaving xOffset, yOffset, spaceAbove, anchorPoint, anchoredPosition, pageIndex, and itemIndex without explanation.

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 states a specific verb and resource ('Reposition an anchored object'), which is clearer than the name alone. However, it does not distinguish this from sibling tools like anchoredObject_setProperties or anchoredObject_create, so an agent cannot tell from the description why it would choose this one.

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 use this tool versus alternatives such as anchoredObject_setProperties or transform_* tools. No prerequisites, no exclusions, and no context about when repositioning is appropriate are provided.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Set' implies a mutation, but the description does not disclose permission requirements, reversibility, what happens to omitted properties, or the expected response.

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 description is a single sentence and is front-loaded, but it is under-specified rather than appropriately concise. It essentially restates the tool name without adding operational detail.

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 mutation tool with four parameters, three required parameters, a nested free-form properties object, and no annotations, the description is far too thin. It omits the parameter semantics an agent needs and provides no behavioral context beyond the word 'Set'.

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 25%, and only document_id is documented in the schema. The description does not explain pageIndex, itemIndex, or the structure/accepted keys of the nested properties object, so it fails to compensate for the coverage gap.

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 states a specific verb ('Set') and resource ('anchored object properties'), but 'properties' is vague and no scope or property types are identified. It does not differentiate this tool from siblings such as anchoredObject_setPosition or anchoredObject_getSettings.

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 when-to-use guidance, no prerequisites, and no alternatives named. An agent cannot tell from the description when to choose this over anchoredObject_setPosition or anchoredObject_create.

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

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

With no annotations provided, the description carries the full behavioral burden. 'List' implies a read-only operation, but it says nothing about ordering, pagination, whether the book must be open, or what happens with an invalid bookIndex. This is a significant disclosure gap for an unannotated tool.

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?

A single, front-loaded sentence with no wasted words. It is concise, though partly because it omits necessary detail rather than because it is efficiently complete.

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?

No annotations, no output schema, and an undocumented required parameter mean the description should do far more work. It does not explain the book context, the return contents, or the meaning of bookIndex, so an agent lacks enough to invoke it confidently.

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 coverage is 50%: document_id is documented but bookIndex — the sole required parameter — has no description in either the schema or the description. The description adds no parameter meaning at all, leaving the most important parameter's semantics (e.g. which index, how to obtain it, relative to book_list) unexplained.

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?

States a specific verb and resource ('List all documents in a book'), so an agent can tell it apart from book_list and book_open. However, it does not explicitly differentiate itself from siblings or clarify that it operates on an open book given the required bookIndex.

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 when-to-use guidance, no prerequisites (e.g. must the book already be open?), and no mention of alternatives such as book_list or book_synchronize. Usage is only implied by the name.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it falls short: it does not say what is returned (book filenames, paths, states), whether the call is read-only, or why a document_id would matter for a 'list all' operation. The mismatch between the parameter and the 'all open books' scope is left unexplained.

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?

A single compact sentence with no filler, and the resource being listed is front-loaded. Its brevity is appropriate, though it shades into under-specification rather than pure economy.

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 simple list tool with no output schema and no annotations, the description is minimally adequate, but it leaves unresolved how the document_id argument interacts with listing 'all open books' and gives no hint of the return payload.

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 100%, so the single document_id parameter is fully documented in the schema, giving a baseline of 3. The description adds no parameter meaning and arguably introduces tension with the parameter's 'which document to act on' semantics.

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?

States a specific verb and resource ('List all open books') so an agent knows the operation immediately. However, it gives no differentiation from the closely related siblings book_getDocuments and book_open, and 'all open books' appears to conflict with the document_id parameter the schema exposes.

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?

Usage is only implied: an agent can infer you call it to enumerate currently open books, but there is no statement of when to prefer it over book_getDocuments or book_open, and no prerequisites. No exclusions or alternatives are named.

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

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

With no annotations, the description carries the full behavioral burden, yet it discloses nothing beyond the verb: not whether opening loads the book into the Books panel, whether it is idempotent if the book is already open, what permissions or path constraints apply, or whether it mutates application state. For a state-changing open operation this is a significant gap.

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?

A single short sentence with no wasted words and the resource front-loaded. It is efficient, though the terseness is part of what leaves the behavioral and parameter gaps.

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 state-changing tool with no annotations, no output schema, and one undocumented required parameter, the description is not complete enough for an agent to call it correctly in ambiguous cases (e.g., relative paths, already-open books). It needs at least a path expectation and a note on post-open state.

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 50%: document_id is documented in the schema, but filePath has no description at all (only a type and minLength), and the description adds no path format, absolute-vs-relative, or extension requirements. With coverage this low, the description needed to compensate and does not.

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 ("Open") and resource ("InDesign book file (.indb)"), and the .indb qualifier implicitly separates it from document_open, which handles .indd documents. It stops short of naming that sibling or stating scope explicitly, so it is clear but not fully differentiated.

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?

No guidance on when to use this versus document_open, book_list, or book_getDocuments, and no prerequisites such as whether the file must exist on disk or whether the book must already be registered. The agent is left to infer usage entirely from the file extension.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about what synchronization overwrites (local overrides, styles, master pages), whether it is reversible, or what permissions are needed. "Synchronize" implies a mutating, potentially destructive operation with no warning given.

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?

A single short, front-loaded sentence with no padding, but it is under-specified rather than genuinely concise. There is no wasted wording, yet also very little content.

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 mutating tool with no annotations, no output schema, and a required parameter undocumented in both schema and description, the definition is materially incomplete. An agent cannot predict what will change or how to confirm success.

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 50%; document_id is well documented in the schema (referencing document_listOpen) but bookIndex has no description anywhere. The description adds no parameter meaning to compensate for the undocumented required parameter.

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?

"Synchronize book documents with the style source" gives a specific verb (synchronize) and resource (book documents), and distinguishes itself from the sibling book tools (book_list, book_open, book_getDocuments), which are read/management operations. The phrase "style source" is somewhat vague about which styles are pulled and in which direction, but the core action is clear.

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?

No indication of when to use this versus alternatives, no prerequisites (e.g., a book must be open), and no exclusions. The agent must infer that a book context is required and that this is distinct from style_listParagraph or master_apply.

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

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

No annotations are provided, so the description carries full behavioral burden. 'Create' implies mutation, but it says nothing about requiring an open document, permission or persistence needs, whether the new style is applied anywhere, or what happens with the document_id default. It only vaguely gestures at the target document.

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?

A single front-loaded sentence with no waste, but so short that it is under-specified rather than concise. Brevity here comes at the cost of required information.

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 an 11-parameter mutation tool with no annotations, no output schema, and almost no parameter documentation, the definition is far too thin. An agent lacks the information needed to invoke it correctly.

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?

With 11 parameters and only 9% schema description coverage (only document_id documented), the description mentions none of them — not name, basedOn, fillColor, insets, stroke, or paragraphStyle. It fails to compensate for the schema gap in any way.

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?

States a specific verb and resource ('Create a cell style'), which is unambiguous about the operation. However, it offers no differentiation from close siblings like tableStyle_create, style_createParagraph, or cellStyle_list — an agent must infer which style family applies.

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 use this versus the many other style-creation tools, nor any prerequisites or exclusions. The only context is the phrase 'in the active document', which is implied usage at best.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a safe read, but the description says nothing about the return shape, ordering, pagination, or what happens if no document is open. For a zero-annotation tool this leaves meaningful gaps.

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?

A single front-loaded sentence with no padding or redundancy. Nothing to trim.

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 trivial read-only list tool with no required parameters this is roughly adequate, but with no output schema and no annotations the description never tells the agent what a listing yields (names? IDs?) or how to use the result in follow-up calls. Minimum viable but with a clear gap.

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 100%, and the single document_id parameter is fully documented in the schema (name or 0-based index, defaulting to the front document). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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?

States a clear verb (list) and a specific resource (cell styles in the active document). An agent can distinguish it from cellStyle_create without opening the schema. It stops short of explicitly contrasting with the closely related style_listParagraph/style_listCharacter/tableStyle_list siblings, which is the only thing that would push it to a 5.

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?

The description only says what it does, not when to reach for it. It never mentions the alternative listing tools (style_listParagraph, style_listCharacter, tableStyle_list) that an agent must choose between, nor any precondition such as needing an open document.

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

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

With no annotations, the description must carry the behavioral load, and it discloses a non-obvious trait: the status comes from plugin-pushed state over the bridge rather than a live InDesign round-trip, which implies low cost and pushed-state freshness. It still omits the failure mode when the plugin/bridge is absent and does not state the read-only nature explicitly.

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?

Two sentences, zero filler, with the mechanism/scope stated first and the parameter guidance second. Every clause carries information.

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?

No output schema exists, so the description should describe the returned status shape, yet it only implies a changed/unchanged answer without specifying fields (timestamps, ids, counts) or behavior when no document is open. Adequate for choosing the tool, thin for interpreting its result.

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 coverage is only 50%: document_id is documented in the schema, but `since` is bare. The description compensates by giving its unit (epoch ms) and its decision semantics ('anything changed after that moment'), which is genuinely more than the schema provides.

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?

States a specific verb ('Report') and resource ('document change activity'), and adds a distinguishing qualifier: the data is 'pushed by the plugin over the bridge — no InDesign round-trip.' That separates it from sibling state-readers like document_getState, though it never names an alternative explicitly.

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?

Gives a concrete when-to-use: pass `since` to learn whether anything changed after a moment, 'e.g. to skip re-rendering a preview when nothing changed.' That is actionable context, but there are no exclusions or explicit alternatives (e.g. when to prefer document_getState).

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

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

No annotations are provided, so the description carries the full disclosure burden. It hints at operating on the 'selected item' (implying a required selection) but says nothing about what happens with no selection, whether the swatch must already exist, undo behavior, or the effect of target='both'. Significant behavioral gaps remain for a mutation tool.

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?

A single tight sentence that is front-loaded with the verb and resource. Nothing is wasted and the parenthetical is immediately useful.

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 3-parameter mutation tool with no annotations and no output schema needs more context than this one-liner provides. The document_id parameter is self-documented in the schema, but the selection requirement and failure/side-effect behavior are left unexplained.

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 coverage is only 33%, so the description should compensate. It maps 'swatch' to swatchName and 'fill or stroke' to the target enum, covering two of three parameters at a conceptual level, but adds no format or value semantics beyond what the schema already shows. Baseline 3 fits.

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?

States a specific verb (apply), resource (color swatch), and target (selected item, fill or stroke). The parenthetical clarifies the operation's scope. It does not, however, name or differentiate itself from nearby siblings like color_swatch_create/delete or table_setCellFill, so it stops short of a 5.

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?

No when-to-use guidance, no prerequisites, and no alternatives named despite many related color siblings (color_swatch_*, color_gradient_create, table_setCellFill/Stroke). The agent must infer that this applies to the current selection.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only restates the operation. It says nothing about name-collision behavior, whether the gradient becomes available as a swatch afterward, which document it lands in by default, or what the call returns.

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 front-loaded and wastes no words, but it is under-specified rather than genuinely concise. There is no structural elaboration to help an agent act on it.

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 4-parameter mutation tool with no annotations, no output schema, and 25% schema coverage, a one-line description is inadequate. An agent lacks the behavioral and parameter context needed to invoke it confidently.

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 25% (only document_id is documented), and the description adds no parameter meaning at all. The concepts of 'stops', 'type', and 'name' are never explained in the description, so it does not compensate for the coverage gap.

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 states a specific verb and resource ('Create a gradient swatch'), so an agent immediately knows it produces a gradient definition. However, it does not distinguish itself from the very similar sibling color_swatch_create, leaving ambiguity about which creation tool to pick for a gradient versus a flat swatch.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as color_swatch_create or color_apply. The agent is left to infer context entirely from the name.

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

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

No annotations are provided, so the description carries the behavioral burden. 'List all inks' clearly implies a read-only enumeration and specifies the scope as all inks, which is useful. However, it does not state permissions, default document behavior, or output structure, leaving some gaps for a tool with no annotation coverage.

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?

A single, front-loaded sentence with no wasted words. The scope ('all inks') and resource are immediately clear.

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 low-complexity, one-optional-parameter listing tool with no output schema, the description is largely complete. It names the resource and scope, though it could add a brief note about when this listing is useful relative to sibling color tools.

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 100%, so the single optional document_id parameter is already fully documented in the schema. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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?

States a specific verb (List) and resource (all inks in the document), so the core purpose is clear. It does not differentiate itself from sibling tools such as color_swatch_list or color_apply, but the name and description make the action understandable.

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 use this tool versus alternatives, nor any stated prerequisites or exclusions. The agent must infer that this is simply a read-only listing operation from the verb alone.

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

Does 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.

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

No annotations are provided, so the description carries the full burden. It signals a destructive mutation via 'Delete', but says nothing about whether the deletion is reversible (undo history, undo_beginGroup), what happens if the named swatch is absent, or whether the swatch is in use by applied colors.

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?

A single front-loaded sentence with no wasted words. It is efficient, though the extreme terseness leaves gaps that belong to other dimensions rather than being a structure problem.

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 destructive no-annotations tool with no output schema and only half the parameters documented, this description is too thin. It should at minimum cover reversibility and the not-found case.

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 coverage is 50%: document_id is documented in the schema, while the required 'name' property has no schema description. The phrase 'by name' partially compensates by clarifying what is being matched, but the description does not explain name-matching behavior (exact match, case sensitivity) or the default-document behavior of document_id.

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?

States a specific verb and resource ('Delete a color swatch') plus the lookup key ('by name'), which is enough to distinguish it from color_swatch_create and color_swatch_list. It does not name those siblings explicitly, so it falls short of the top tier.

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 use this versus color_swatch_create/list or color_apply, no prerequisites, and no exclusions. The agent must infer that this is the removal counterpart to color_swatch_create.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it only restates the operation. It does not say whether the operation is read-only and safe, whether it covers only document-level swatches or application/library-level swatches too, or how results are ordered/returned.

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?

A single short sentence with the resource and scope front-loaded and zero filler. It is efficient, though the brevity leaves no room for the routing or behavioral hints an agent would benefit from.

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 simple one-parameter read tool with fully described schema and no output schema, the description is minimally sufficient to invoke it correctly. It is incomplete on the behavioral side: no safety profile, no note on swatch scope, and no mention of the return shape, which is left entirely unspecified since no output schema exists.

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 100% and the single document_id parameter is documented in the schema, including the pointer to document_listOpen and the front-document default. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('List all color swatches') with a clear scope ('in the document'), so the agent knows exactly what the tool returns. It does not, however, differentiate itself from siblings with overlapping behavior such as export_getSwatches or color_ink_list.

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?

Usage is only implied: the tool enumerates swatches, so an agent infers it should be called when it needs the swatch inventory. There is no explicit statement of when to prefer this over export_getSwatches or color_ink_list, and no prerequisites are mentioned (e.g., whether a document must be open).

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

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

With no annotations, the description carries the full behavioral burden and discloses almost nothing. It does not say whether an existing file at outputPath is overwritten, whether the directory must exist, what permissions or open-document state are required, or what side effects occur on the document. For a tool that writes files to disk, that is a meaningful gap.

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?

A single short sentence with zero filler and the action front-loaded; nothing needs trimming. It is efficient but thin, so it scores well on structure without earning a top mark for information density.

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?

With three parameters, no annotations, and no output schema, the description is the only source of context and it omits the data-merge workflow position, file-writing semantics, and format tradeoffs. An agent could plausibly call it at the wrong point in the pipeline or overwrite a file unintentionally.

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 33%: only document_id is documented (via the schema itself), while format and outputPath are bare. The description adds nothing about format semantics (raster vs. vector tradeoffs of pdf/jpg/indd) or about outputPath conventions such as absolute vs. relative paths, extension handling, or overwrite behavior.

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?

Specific verb (export) plus resource (the merged document) and destination (a file), which is more precise than a bare name restatement. It does not, however, distinguish itself from siblings like export_document, export_batchFolder, or recipe_exportPreset, leaving the 'merged' qualifier as the only differentiator an agent can lean on.

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?

No guidance on when to use this versus export_document or export_batchFolder, and no prerequisites stated — e.g. whether a data source must be selected via dataMerge_selectDataSource or records merged via dataMerge_mergeRecords first. An agent has to infer the entire workflow position of this call.

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

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

No annotations, so the description carries the burden. It signals a read of the 'current data source', implying a data source must be selected, but does not state what happens if none is set or what the listing returns.

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 front-loaded sentence with no waste. Appropriately sized for a simple listing 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?

A simple 1-optional-param read tool with no output schema; the description covers the core operation but omits the dependency on a selected data source and the shape of the returned field list.

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 coverage is 100% for the single document_id parameter, and the schema describes it richly (name or 0-based index, defaults to front document). The description adds no parameter detail, so baseline 3 applies.

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?

Specific verb (List) plus resource (data merge fields) and scope (from the current data source). An agent can distinguish it from dataMerge_selectDataSource and dataMerge_mergeRecords, though the description does not name those siblings explicitly.

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?

Usage is only implied: you would call this after a data source exists to see available fields. No explicit when-to-use, prerequisites, or named alternatives are given.

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

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

With no annotations, the description carries the full burden but discloses almost nothing behavioral: it doesn't say the document is mutated in place, whether the operation is reversible, what generatePreview or alertWhenOverset do, or what limits exist. The only behavioral clue is the implied dependency on a selected data source.

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?

A single front-loaded sentence with no padding — the verb and resource lead. It is efficient, though its brevity is arguably under-specification rather than tight editing.

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 5-parameter, no-required-argument mutation tool with no annotations and no output schema, the description is far too thin. The four undocumented boolean/integer options and the mutation semantics are left unexplained, so an agent cannot call this correctly with confidence.

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 20% (just document_id), and the description adds no parameter meaning at all for the four undocumented options (linkImages, recordsPerPage, generatePreview, alertWhenOverset), leaving the agent to guess their effect and units. This fails to compensate for the low coverage.

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?

States a specific verb+resource ('Merge records into the document'), which is plainly distinct from the sibling dataMerge_selectDataSource/listFields/export/removeDataSource actions. It also ties the action to 'the selected data source,' implying the family's workflow, though it doesn't explicitly name the sibling needed first.

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 explicit when-to-use or when-not-to-use guidance and no alternatives named. The phrase 'using the selected data source' is only an implicit hint that dataMerge_selectDataSource must run first; nothing states preconditions, ordering, or how this differs from dataMerge_export.

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

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

No annotations are provided, so the description carries the full burden. 'Remove' implies a mutation, but it doesn't disclose reversibility, whether merged records are affected, whether the link to the source file is severed, or what happens on a document with no data source.

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?

A single sentence with the verb and object front-loaded and zero filler. Every word earns its place.

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 simple one-parameter operation this is barely adequate: it names the action but omits the state the document must be in and the side effects of removal. Given no annotations and no output schema, a bit more behavioral context would complete it.

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 100% and the single optional document_id parameter is fully documented in the schema (name or 0-based index, default front document). The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

States a specific verb (remove) and resource (data source) plus the scope (from the document). An agent knows exactly what it does, but the description never distinguishes it from the sibling dataMerge_selectDataSource or explains the relationship, so it falls short of a 5.

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 when-to-use guidance, no prerequisite (e.g. a data source must already be selected via dataMerge_selectDataSource), and no note on what happens if none is set. Usage must be inferred entirely from the name.

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

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

No annotations are provided, so the description bears the full disclosure burden. 'Select' implies a state-setting mutation, but the description doesn't say whether it replaces an existing data source, whether it requires an open document, or what happens to any previously linked source.

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?

A single front-loaded sentence with no waste. It is efficient, though very terse for a tool that mutates document state.

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 state-changing tool with no annotations and no output schema, the description omits key context: replacement semantics for existing data sources, prerequisite document state, and typical workflow position. It is under-specified rather than merely concise.

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 50%: document_id is documented in the schema, while filePath relies on its name. The description adds the accepted file formats, which is genuine value for filePath, but contributes nothing for the document-selection parameter, which the schema already covers.

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?

States a specific verb (select) plus the resource (a data-source file) and enumerates supported formats (CSV/TSV/XML). It is clearly distinguishable from siblings like dataMerge_removeDataSource and dataMerge_mergeRecords, though it never names them explicitly.

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?

The description gives no when-to-use guidance, no prerequisites (e.g. a document must be open), and no mention of the sibling alternatives in the dataMerge family. The user is left to infer that this is the setup step before mergeRecords.

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

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

With no annotations, the description carries the full burden, yet it does not disclose that closing may discard unsaved changes, what saveOptions 'no' versus 'ask' does, or whether a prompt appears. The phrase 'with save options' hints at the save control but explains none of its consequences.

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?

A single, front-loaded sentence with no wasted words. It is appropriately sized for a simple tool, though terseness contributes to the behavioral and parameter gaps rather than resolving them.

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 mutating close operation with no annotations, no output schema, and half the parameters undocumented, this is too thin. It omits save-option semantics, unsaved-change behavior, and the active-versus-document_id inconsistency.

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 coverage is 50%: document_id is well documented, but saveOptions has no schema description and the tool description only says 'with save options,' adding no meaning about the yes/no/ask enum or the default of 'no.' The description does not compensate for the coverage gap.

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?

States a specific verb and resource: closing an InDesign document. It is clearly distinct from document_save, document_open, and document_create. Minor tension: it says 'active' document while document_id lets callers target any open document.

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?

No guidance on when to close versus save first, no mention of unsaved-change behavior, and no alternatives named. Only the implied act of closing is conveyed.

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

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

With no annotations, the description carries the full burden and barely does. It never states whether the document is created in memory vs written to disk, the measurement unit (the A4 defaults 210x297 and margin 12 imply mm), reusable defaults, or what happens on failure, all of which matter for a creation tool.

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?

A single efficient, front-loaded sentence with no waste. It earns its place, though for a 9-parameter tool the brevity edges toward under-specification rather than tightness.

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?

Nine parameters, nested objects, low schema coverage, no output schema, and no annotations, yet only one sentence of guidance. The description is materially insufficient for an agent to call this tool correctly without inspecting the schema in depth.

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 coverage is only 11% (just document_id), so the description must compensate. It names three categories (dimensions, margins, settings) that loosely map to width/height, margins, and facingPages/orientation/pages/bleed/slug, but adds no units or default semantics and does not explain the surprising document_id parameter on a creation tool.

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?

States a specific verb+resource: 'Create a new InDesign document.' The word 'new' implicitly distinguishes it from sibling document_open, but no sibling is named explicitly and the listed facets (dimensions, margins, settings) are generic.

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?

No when-to-use guidance, no prerequisites, and no explicit routing against document_open or the page/master creation siblings. The only signal is the adjective 'new', leaving the agent to infer that this is the right tool for a fresh document.

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

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

With no annotations, the description carries the full burden. 'Get' implies a read-only operation and the enumerated return fields give useful behavioral context, but it says nothing about permissions, cost, or side effects, and no output schema exists to fill the gap.

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?

A single front-loaded sentence with zero waste. Slightly under-specified rather than over-long, but structurally efficient.

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 one-parameter read tool with no output schema, listing the returned fields (page count, dimensions, margins) is a genuine help. However it never reconciles 'active document' with the optional document_id parameter, and no output schema exists to clarify the full return shape.

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 coverage is 100% and the document_id description already explains the name-or-index convention and the front-document default. The description adds nothing beyond the schema and its phrase 'active document' arguably conflicts with the parameter's ability to target a non-active document.

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?

States a specific verb and resource ('Get detailed information about the active document') and enumerates the returned fields (page count, dimensions, margins). It is clear on its own, but it does not differentiate itself from close siblings like document_getState or document_getPageStories.

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?

No when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer that this is the general document-metadata tool versus document_getState or page_getInfo from the field list alone.

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

Does 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 implies a read operation but says nothing about whether a document must be open, what happens for an out-of-range pageIndex, what the returned story objects contain, or how they are ordered.

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?

A single tight sentence with the resource front-loaded and zero filler. It is efficient, though arguably under-specified rather than optimally sized.

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?

With no annotations, no output schema, and an undocumented required parameter, the description is too thin for an agent to call the tool correctly without trial and error, particularly around page indexing conventions.

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 coverage is only 50%: document_id is documented in the schema, but pageIndex has no description at all. The phrase 'a specific page' only weakly gestures at pageIndex and does not clarify its 0-based indexing, so the description fails to compensate for the coverage gap.

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?

Specific verb ('Get') and resource ('stories that appear on a specific page') clearly state the operation. It is distinguishable in substance from text_getStories, but the description never acknowledges its near-inverse sibling document_getStoryPages, leaving the agent to infer the direction of the mapping.

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 use this tool versus document_getStoryPages or text_getStories, no prerequisites (e.g. a document must be open), and no indication of ordering or scope of the result.

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

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

No annotations are provided, so the description carries the full burden. It discloses the complete set of returned values (a read/aggregate operation with no implied mutation) and thereby implies the safety profile, but it never explicitly states that it is read-only, nor does it mention permissions or side effects. Strong on behavior, one step short of explicit.

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?

Two sentences: the first front-loads the returned payload, the second front-loads the routing decision. Dense, zero filler, and no sentence repeats a structured field.

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?

There is no output schema, so the description must enumerate return values — and it does so exhaustively (document name, path, page count, size, margins, index, open document names, active layer, selection count). Combined with the explicit sibling routing, an agent has everything needed to call this correctly.

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 100% — the document_id parameter is fully documented in the schema (name or 0-based index, defaulting to the front document). The description adds no syntax or defaulting detail of its own, so this sits at the baseline for a high-coverage single-parameter tool.

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?

Names a specific verb ('Get') plus resource ('editing state') and then enumerates exactly what state is returned: front document fields, document index, open document names, active layer, and selection count. It also names the two siblings (document_getInfo, document_listOpen) it replaces, so an agent can distinguish it from them without opening either schema.

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?

The final sentence gives an explicit routing rule: prefer this over chaining document_getInfo and document_listOpen. Both the alternative tools and the condition that selects this one are stated, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full burden and discloses almost nothing: it does not state that this is a read-only query, what happens with an out-of-range storyIndex, or how the pages are represented. 'Get' weakly implies a read, but no permissions, error behavior, or result shape is described.

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?

A single, front-loaded sentence with no padding. The parenthetical is mildly redundant with 'pages covered' but does clarify intent, so it largely earns its place.

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?

With no output schema, the description should convey the return shape, but 'all pages' is vague (page indices? page objects? names?). Combined with the unexplained required storyIndex and zero annotation coverage, the definition is too thin for reliable invocation.

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 coverage is only 50%: document_id is documented in the schema (name via document_listOpen or 0-based index, defaults to front document), but storyIndex is undocumented in both schema and description. The description adds no parameter meaning to compensate for that gap.

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?

States a specific verb and resource ('Get all pages covered by a specific story'), which is unambiguous about the direction of the mapping. However, it never names the inverse sibling document_getPageStories, so the agent must infer the distinction from the names 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?

The parenthetical 'for finding which pages a story lives on' restates the purpose rather than giving when-to-use guidance. There is no mention of when to prefer document_getPageStories (the reverse lookup) or any prerequisite/context for choosing this tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a safe read, but nothing states it is read-only, whether a document must already be open, what happens with zero open documents, or what the return contains. For a tool with zero annotation coverage this is a notable gap.

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 tight sentence with the resource front-loaded and no filler. Appropriately sized for a trivial list operation, though it is so terse that it forgoes any useful addition.

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 simple parameterless-ish list tool with a fully documented schema, the description is minimally sufficient. It leaves the return format and the read-only nature unstated, which for a no-annotation tool is a mild completeness gap.

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 100% and the single document_id parameter is well documented in the schema (name or 0-based index, defaults to front document). The description adds nothing beyond that, so the baseline of 3 is appropriate.

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?

States a specific verb (List) and resource (currently open InDesign documents), which is clear and actionable. It doesn't explicitly differentiate itself from nearby siblings like document_getInfo or document_getState, but the scope (all open documents) is unambiguous.

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?

The description offers no when-to-use guidance, no prerequisites, and no alternatives. It doesn't tell the agent that this is the discovery step that supplies the document_id accepted by other tools, even though the schema hints at that relationship.

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

Does 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 says nothing about what happens on a missing/invalid path, whether opening modifies the file or locks it, whether it requires an active InDesign instance, or how it affects currently open documents. For a state-changing open operation with zero annotation coverage, this is a notable gap.

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?

A single, front-loaded sentence with zero padding. It is efficient, though the brevity comes at the cost of the missing usage and parameter details noted elsewhere rather than from trimming redundancy.

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?

With no annotations, no output schema, and undocumented parameters (showWindow, filePath), the description would need to compensate and does not. An agent lacks enough information to know what the tool returns on success/failure or how showWindow behaves.

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 33%: document_id is well documented in the schema, but filePath and showWindow have no descriptions anywhere. The phrase 'from file path' is the only hint about filePath (format, absolute vs relative) and showWindow (the ability to open without a window) is completely unexplained.

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 (open) and resource (an existing InDesign document) and names the input source (file path), which clearly separates it from document_create and book_open. It does not explicitly name a sibling as the alternative, but the purpose is unambiguous on its own.

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 reach for this tool versus document_create (new document) or preview_document, and no mention of prerequisites such as the file existing on disk. The word 'existing' is the only implicit usage signal.

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

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

With no annotations, the description carries the full burden for a write operation. It doesn't disclose whether saving to a new path changes the document's association, whether existing files are overwritten, or what 'ask' triggers, leaving destructive/overwrite behavior opaque.

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?

A single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the specification gaps rather than resolving them.

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 mutation tool with no annotations, no output schema, and 33% param coverage, the description is too thin. It omits overwrite behavior, the meaning of saveOptions, and any distinction from export or close, leaving an agent under-informed before calling it.

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 coverage is only 33%: document_id is documented in the schema, but filePath has no description and saveOptions (enum yes/no/ask) is completely unexplained. The description only loosely implies filePath via 'to a specific path' and adds no semantics for the enum, which is the most ambiguous parameter.

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?

Clear verb+resource: 'Save the active InDesign document' with an optional target path. It does not differentiate itself from siblings like export_document or document_close, so the agent must infer the save-vs-export boundary on its own.

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?

No guidance on when to use this versus export_document, document_close, or how to invoke a 'save as' flow. The mention that a path is 'optional' is the only usage hint, and saveOptions values (yes/no/ask) are never explained.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It says nothing about whether the effect replaces existing effects, whether it is undoable, whether it applies to a single item or all selected items, or how document_id resolves when omitted.

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?

A single short sentence with no waste, so it is not verbose. But it is under-specified rather than concise: every sentence "earns its place" only because there is just one and it conveys minimal information.

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 9-parameter mutation tool with no annotations, no output schema, and near-zero schema documentation, the description is far too thin. An agent gets no indication of permissions, reversibility, or how the required pageIndex/itemIndex pair identifies the target object.

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 11% – just document_id is documented. The description adds nothing about the eight other parameters (blur, mode, angle, color, opacity, distance, itemIndex, pageIndex); only defaults and numeric ranges in the schema hint at their meaning, so the description fails to compensate for the coverage gap.

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 states a specific verb and resource ("Apply a drop shadow effect to an object"), which is unambiguous and clearly separable from siblings like effect_applyFeather and effect_applyTransparency. It does not, however, explicitly name those alternatives or clarify what kind of object is targeted.

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 use this effect versus effect_applyFeather, effect_applyTransparency, or effect_applyGradientFeather, nor any prerequisites (e.g. that the item must be a page item on the given page). The agent is left to infer all routing from the name alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure and largely fails it. It implies a mutation on an object but never states what feathering does, what object types are valid, whether the operation is reversible/undoable, or what side effects it has.

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?

A single front-loaded sentence with no wasted words, which is structurally fine. However, its brevity comes at the cost of under-specification rather than genuine economy, so it is only adequate.

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 7-parameter mutation tool with no annotations, no output schema, and 14% schema coverage, a bare one-liner is wholly inadequate. Nothing an agent needs to invoke this correctly — valid targets, undo behavior, or parameter meaning — is present.

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 14% (just document_id), and the description adds no parameter meaning at all. The 7 parameters — including non-obvious ones like chamferWidth, noise, width, and type — are left completely undocumented in both places.

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?

States a clear verb+resource combination ('Apply a feather effect') that is unambiguous on its own. However, it does nothing to distinguish itself from the sibling effect_applyGradientFeather, so an agent cannot tell from the description alone which feather variant to pick.

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?

No when-to-use guidance, no prerequisites, and no reference to alternatives such as effect_applyGradientFeather or effect_applyTransparency, despite those siblings being the obvious near-duplicates. The agent must infer selection criteria entirely on its own.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: 'apply' implies a document mutation, but there is no statement of whether an existing feather/gradient is replaced, whether the change is undoable, what auth or selection state is required, or what happens to unspecified gradient attributes. This is thin for a 7-parameter mutation tool.

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?

A single front-loaded sentence with no filler or redundancy; it is efficient. The brevity is not wasteful, though it 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?

For a tool with 7 parameters, nested startPoint/endPoint objects, no output schema and no annotations, one bare sentence is wholly inadequate. An agent cannot determine how to shape the gradient or how this differs from effect_applyFeather.

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 14%, so the description must compensate, yet it mentions none of the seven parameters — not the linear/radial type, the angle range, or the startPoint/endPoint geometry that define the gradient. It adds zero meaning beyond the schema and leaves the critical gradient-shape parameters unexplained.

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 sentence names a specific verb (apply) and resource (gradient feather effect), so the basic action is clear. But it essentially restates the tool name and offers no differentiation from the sibling effect_applyFeather (plain feather) or effect_applyDropShadow/effect_applyTransparency, which is exactly the ambiguity an agent needs resolved.

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 when-to-use guidance, no prerequisites (e.g. does the object need to be selected?), and no mention of alternatives despite three sibling effect_* tools whose choice is non-obvious. The agent is left to infer everything from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only restates the two main effects. It does not disclose whether the operation is destructive, what it requires (valid item/page indices), or how unmentioned settings behave.

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?

A single front-loaded sentence with no wasted words. It is efficient, though the brevity reflects under-specification for a 7-parameter mutation tool rather than elegance.

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 mutation tool with no annotations, no output schema, and 7 parameters at 14% coverage, the description is far too thin. It omits optional toggles, target semantics, and any indication of effect or side effects.

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 14% (just document_id), leaving six parameters undocumented. The description's 'blend mode' and 'transparency' loosely map to blendMode/opacity but add no enum or range detail, and say nothing about knockoutGroup, isolatedBlending, pageIndex, or itemIndex.

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?

States a specific verb ('Set') plus the two effects it controls (transparency and blend mode), which maps to the opacity and blendMode parameters. It is reasonably distinct from effect_applyDropShadow/Feather siblings, though it omits the other knobs (knockoutGroup, isolatedBlending) it also governs.

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?

No when-to-use guidance, no prerequisites (e.g., an active selection or target item), and no mention of related effect siblings like effect_applyDropShadow. The agent must infer usage from the name alone.

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

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

With no annotations, the description carries the full burden. It does add real behavioral context — documents are opened invisibly and results are reported per file — but it omits failure semantics for a partially failing batch, whether opened documents are closed afterwards, whether existing PDFs are overwritten (the schema defaults overwrite=false), and any permission requirements.

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?

A single em-dash sentence with zero waste, front-loading the batch scope and the conversion target before the side-effect detail. Nothing is padded or repeated from the schema.

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 5-parameter write-producing tool with no annotations and no output schema, the description covers intent and return shape only in passing ('reports per-file results'). It leaves the document_id/batch mismatch, partial-failure behavior, and overwrite policy unexplained, so an agent cannot fully predict the call's outcome.

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 coverage sits at 60%: folderPath, outputDir and document_id carry descriptions while overwrite and timeoutMs have only defaults. The description adds no parameter-level meaning beyond restating the folder concept, and it never explains the oddly out-of-place document_id parameter on a folder-wide batch operation.

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 pairs a specific verb with a precise resource and scope: 'Export every InDesign (.indd) file in a folder to PDF in one run.' The folder-wide batch nature cleanly separates it from the single-document sibling export_document and from export_preflight, so an agent can route 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.

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

Usage is implied ('in one run' signals the batch alternative to looping a per-document export), but no sibling is named and there is no explicit when-to-use or when-not-to-use statement. An agent can infer the batch case but gets no help deciding between this and export_document or recipe_exportPreset.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing beyond the format list: no destination behavior, no overwrite semantics, no permission or open-document requirement, no indication of what 'package' produces. Listing the formats is the one piece of genuinely useful context.

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?

A single front-loaded sentence with the verb and resource first and the format list parenthetically, which is efficient. It is arguably too terse given the undocumented options and filePath, but there is no filler or redundancy beyond the enum restatement.

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 4-parameter I/O tool with a nested free-form options object, no annotations, and no output schema, the description leaves critical gaps: where output is written, what is returned, and what options are valid. An agent could call it with only a format, but could not confidently use filePath or options.

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 25% — just document_id is documented — and the format enum is self-describing. The description restates the format values (redundant with the enum, though it hints at user-facing naming) but adds nothing about filePath or the nested options object, which is a free-form additionalProperties bag. It partially compensates but leaves the two most opaque parameters unexplained.

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?

Names a specific verb and resource (export the document) and enumerates the target formats, so the operation is unmistakable. It does not distinguish itself from nearby siblings such as export_batchFolder, export_preflight, dataMerge_export, or recipe_exportPreset, and the 'active document' phrasing does not acknowledge the document_id parameter.

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?

No guidance on when to choose this tool versus the other export-family tools (batch folder export, preset-based export via recipe_exportPreset, preflight). There are no stated preconditions, such as whether the document must be saved or open, or what happens if an identical file already exists.

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

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

No annotations are provided, so the description carries the full burden. 'Arbitrary ExtendScript code' hints at broad power but does not disclose whether the code runs with full document-mutating privileges, whether it is sandboxed, how errors/exceptions are surfaced, or whether the operation is reversible. For an arbitrary code-execution tool this is a major transparency gap.

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?

A single front-loaded sentence with no wasted words. It is efficient, though for a tool of this complexity the brevity borders on under-specification rather than true conciseness.

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?

There is no output schema and no annotations, so the description must carry the behavioral and return-value burden. It says nothing about what executing the script returns, how failures are reported, or the safety implications of running arbitrary code, leaving the agent under-informed for a high-complexity operation.

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 50%: 'document_id' is well documented in the schema, but 'code' has no description at all. The description only restates 'ExtendScript code', adding no information about expected syntax, whether results are returned, or how output is captured.

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?

States a specific verb and resource ('Execute arbitrary ExtendScript code in InDesign'), which is far more informative than a tautology. However, it offers no differentiation from the sibling 'script_run', which almost certainly performs a similar or identical function, so an agent cannot tell the two apart.

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 use this tool versus 'script_run' or any of the many declarative siblings (e.g., text_setContent, image_place) that cover common operations. No preconditions, no mention of whether the document must be open or saved, no exclusion criteria.

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

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

No annotations are provided, so the description carries the full burden. It does not state that the operation is read-only/non-mutating, whether missing fonts are included, or what the returned data looks like. For a query tool with zero annotation coverage, this is thin.

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?

A single short, front-loaded sentence that identifies the scope of the operation with zero filler. Nothing is redundant or misplaced.

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 simple one-parameter read tool with full schema coverage, the description is nearly adequate, but with no output schema and no annotations it should clarify the return shape (e.g., font names) and whether missing fonts are reported, information an agent would otherwise have to discover at call 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 100% — document_id is fully documented in the schema (name or 0-based index, defaults to front document). The description contributes no additional parameter meaning beyond the word 'active', so the baseline 3 applies.

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?

States a specific verb ('Get') and resource ('all fonts used in the active document'), which is clearly scoped differently from the sibling font_list (available/system fonts) and font_missing_check. It does not explicitly name or contrast those siblings, so it stops short of a 5.

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?

The phrase 'used in the active document' implies a reporting/audit use case, and the schema notes document_id defaults to the front document. However, there is no explicit guidance on when to call this versus font_list, font_missing_check, or font_find, leaving selection to inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. Beyond implying a read via 'List', it says nothing about permissions, whether it covers only the front document, ordering, or size limits.

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?

A single short sentence with zero filler and no hedging. It is efficiently front-loaded, though its brevity is partly a symptom of 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?

For a listing tool with no annotations and no output schema, the description should at least hint at what is returned (names, IDs, spread objects) and confirm it is a safe read. Neither is present, so an agent has no basis for interpreting the result.

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 coverage is 100%, so the schema already documents document_id, its name-or-index union type, and its front-document default. Worse, the description's framing of 'the active document' narrows the scope in a way that conflicts with the optional document_id parameter, so it adds misleading rather than helpful semantics.

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?

States a specific verb ('List') and resource ('master spreads') with a scope ('active document'), so the operation itself is unambiguous. However, it does nothing to distinguish itself from the sibling master_list, which plausibly covers the same resource, leaving the agent to guess which to call.

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 when-to-use guidance, no prerequisites, and no named alternative. The description never explains how this differs from master_list, master_getPages, or master_create, which are the natural comparison points for an agent choosing a master-spread tool.

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

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

No annotations are provided, so the description carries the full burden. 'Get' correctly implies a read-only operation, which is useful, but it says nothing about return format, pagination, or whether the result includes swatch groups and inks. For a simple list operation this is acceptable but thin.

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 sentence, front-loaded with the verb and resource, with no filler. Every clause (the parenthetical type enumeration) earns its place.

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 read-only listing tool with one optional, fully documented parameter and no output schema, the description covers what is returned and from which document. The remaining gap is disambiguation from the similarly named color_swatch_list sibling.

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 coverage is 100% and the single optional document_id parameter is fully documented in the schema, including its default to the front document. The description adds no syntax or semantics beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource ('Get all swatches') and enumerates the swatch types (colors, gradients, tints), so the agent knows what it retrieves. However, it does not distinguish itself from the sibling color_swatch_list, which by name appears to cover the same ground, leaving overlap unresolved.

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?

The description gives no when-to-use guidance, no prerequisites, and never names an alternative such as color_swatch_list or color_ink_list. The agent must infer the choice purely from tool names.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It implies a read-only listing but does not state whether pageIndex filters results, whether all pages are scanned, what the return shape is, or whether only the active document is considered regardless of document_id.

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 description is a single front-loaded sentence with no wasted words. It is concise, though its brevity contributes to the missing behavioral and parameter context.

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 two-parameter tool with no annotations and no output schema, the description is inadequate. It does not explain how pageIndex works, how document_id relates to the 'active document' wording, or what the listing returns.

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 50%: document_id is documented in the schema, but pageIndex has no description. The tool description mentions 'active document' and ignores both parameters entirely, adding no meaning beyond the schema and even conflicting with the document_id parameter.

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?

States a clear verb and resource: 'List all tables in the active document.' However, it does not distinguish this from sibling tools such as table_list, so an agent cannot confidently choose between them from the description 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 guidance on when to use this tool versus alternatives such as table_list or table_getInfo. The description gives only a bare action statement and does not mention conditions, exclusions, or prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only listing but does not say what is returned, whether tags are document-wide or story-scoped, or how pagination/large tag sets are handled.

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?

A single short sentence with no waste and the scope front-loaded. It is efficient, though it may be too terse for the ambiguity it leaves.

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 listing tool with no output schema and no annotations, the description should at least describe the return shape or scope, and it does neither. It also ignores the sibling it most resembles.

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 coverage is 100%, so the single document_id parameter is already fully documented (name or 0-based index, defaults to front document). The description's phrase 'the active document' adds no detail beyond the schema default. Baseline 3 applies.

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?

States a specific verb and resource ('List XML tags'), but 'in the active document' is only one possible scope and the description never distinguishes this tool from the near-identical sibling xml_listTags. An agent cannot tell which of the two to call without opening both schemas.

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?

No when-to-use, no when-not-to-use, and no mention of the overlapping xml_listTags sibling. The only implicit signal is the 'export_' prefix, which is not explained.

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

Does 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 disclose whether the check is read-only, what it validates, whether it can modify the document, what permissions are needed, or what a failure looks like.

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?

It is a single front-loaded sentence with no filler, but its extreme brevity leaves a three-parameter, annotation-free tool under-specified rather than genuinely concise for the task at hand.

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?

With no annotations, no output schema, and 33% parameter coverage, the description should at minimum explain the check's scope, what profile controls, and how waitForCompletion affects behavior. It supplies none of this, leaving an agent unable to invoke it confidently.

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 33%: profile and waitForCompletion are undocumented, and the description adds no parameter semantics. Worse, 'active document' implies only the front document, understating document_id's ability to target another open document by name or index.

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?

Names a specific operation (preflight check) on a document, and the purpose is distinguishable from export actions at a high level. However, it says 'active document' even though document_id allows targeting any open document, and it does not explicitly differentiate itself from export_document or preview_document.

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?

The term 'preflight' implies this is used before an export, but the description gives no explicit when/when-not guidance, no prerequisites, and no named alternatives such as export_document or preview_document.

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

Does 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 say whether the change is destructive, requires an active selection, affects the front document, or is undoable — real gaps for a mutation tool.

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?

Five words, front-loaded and waste-free. But this brevity is under-specification rather than conciseness, since essential scope information is missing.

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 mutation tool with no annotations, no output schema, four parameters, and an ambiguous scope ("selected text" in which document?), the description leaves too much undefined for correct invocation.

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 25% (just document_id), and the description mentions no parameters at all — not fontName, size, or fontStyle. With 4 params and low coverage, the description fails to compensate.

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?

States a verb and resource ("Change font of selected text"), so the basic action is clear. However, it gives no differentiation from the sibling text_applyFont, which appears to overlap heavily, leaving the agent unsure which to pick.

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 when-to-use guidance and no named alternative, despite text_applyFont and text_applyCharStyle being obvious candidates. The agent must infer the selection context entirely.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing. It doesn't state that the operation is read-only (implied but unstated), whether matching is case-sensitive, substring or exact, whether missing fonts or styles are included, or what the result set looks like.

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?

Four words, zero filler, and the search scope is front-loaded. Its brevity is efficient, though it tips into under-specification rather than genuine conciseness for a search 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?

With no annotations, no output schema, and one of two parameters undocumented in the schema, the description should do considerably more. An agent cannot tell what a match returns (font names, font objects, missing-font flags) or how matching is performed, which is critical for a search tool.

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 coverage is 50%: document_id is fully documented in the schema, but the required 'query' parameter has no schema description at all. The phrase 'by name' partially compensates by signaling that query is a font-name string, though it says nothing about partial matching or case sensitivity.

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?

States a specific verb and resource ('Search fonts') plus the search axis ('by name'), so the agent knows this is a font lookup rather than a mutation. However, it offers no differentiation from the sibling font_list, which also retrieves fonts, leaving the agent to guess which to pick.

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?

No when-to-use guidance is given. It never says whether this is for locating a specific font before applying it (font_change/font_list) versus enumerating all fonts, and there are several plausible sibling alternatives (font_list, font_missing_check, text_search). The agent must infer the intent entirely.

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

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

With no annotations, the description carries the full burden. It implies a mutation at the cursor but says nothing about whether the operation is undoable, what happens if the target document lacks the font, whether an active insertion point is required, or any error behavior. Only the minimal 'inserts at cursor' trait is disclosed.