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

With no annotations, the description carries the full burden for behavioral disclosure, but it only states the action without mentioning side effects, default position, or permission requirements. It is minimal and doesn't reveal important 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?

The description is a single, front-loaded sentence with no extraneous content. It is appropriately concise.

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 the tool mutates a document and has no annotations or output schema, the description is insufficient. It fails to mention that pages can be added before/after specific pages, the default of appending to the end, or how masterPage affects the new page.

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?

The description adds no insight into the parameters. While the schema provides descriptions for pageIndex and masterPage and an enum for position, the description itself doesn't help clarify parameter usage beyond what is already in the schema.

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 'Add a new page to the document' uses a specific verb and resource, clearly indicating the action. It distinguishes from sibling tools like delete_page and duplicate_page by specifying 'add' rather than other operations.

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 is provided on when to use this tool versus alternatives such as duplicate_page or navigate_to_page. The description lacks context about prerequisites or scenarios.

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. 'Analyze' suggests a read-only inspection, but the description does not state side effects, permission requirements, or what happens to the frame or objects.

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 concise sentence with the core action front-loaded and clarifying examples in parentheses. It is efficient and easy to scan, though 'etc.' is a minor vagueness.

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, so the description should explain what the analysis returns or what effects it has. It only states the tool's scope, leaving agent expectations about output and behavior incomplete.

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?

The input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds only slight context about selected versus specified frames, but it does not add meaningful semantics beyond the schema.

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: analyze embedded objects such as MathML formulas and graphics, and scopes it to a selected or specified text frame. This distinguishes it from siblings like analyze_text_problems and get_selected_objects, though it does not explicitly name any sibling.

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 implies usage by mentioning selected or specified frames, but it gives no explicit guidance on when to choose this tool over alternatives or when not to use it. No exclusions or close-sibling comparisons 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?

With no annotations, the description carries the full burden of behavioral disclosure. 'Analyze' and 'Shows' imply a read-only operation, but the description does not explicitly state that no changes are made, what kinds of problems are detected, or what the output 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?

Two short sentences communicate the core purpose and expected result without filler. The purpose is front-loaded and every word contributes meaning.

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?

The description is adequate for a focused analysis tool, but without an output schema or annotations it leaves important context unspecified, such as what constitutes 'common problems', whether the operation is read-only, and how the selection parameters affect the analysis. The schema covers parameter mechanics, but the overall tool behavior remains thin.

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?

The description adds no parameter-specific meaning, but all three parameters already have descriptions in the schema at 100% coverage. The baseline of 3 applies because the description does not need to compensate for schema gaps.

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 action ('Analyze imported text') and a clear goal ('for common problems before cleaning'), which distinguishes it from cleaning tools like clean_imported_text. However, 'common problems' is vague and it does not explicitly differentiate from find_typography_issues, 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 'before cleaning' implies when the tool should be used, and the overall purpose suggests a pre-cleaning analysis step. But there is no explicit guidance on when to prefer this over find_typography_issues or analyze_embedded_objects, and no when-not-to-use conditions.

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 full burden. It does not disclose that this is a mutation operation, what document changes occur, or any error conditions. This is a significant transparency gap for a tool that modifies objects.

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, terse sentence with no waste, but it is under-specified for a tool with 4 parameters and no annotations. It could include more useful detail without becoming verbose.

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 and no output schema, this description is incomplete. It fails to explain side effects, required object context, or what 'apply color' entails (fill/stroke), leaving major gaps in operational context.

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 75%, with descriptions for swatchName, objectIndex, and pageIndex, plus an enum for property. The description adds no additional parameter semantics beyond what the schema provides, 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?

The description 'Apply color to an object' clearly names the action and target, distinguishing it from siblings like create_color_swatch and apply_paragraph_style. However, it lacks specificity about the color property (fill vs stroke) and how the object is identified (objectIndex), so it's not fully precise.

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 apply_paragraph_style or create_color_swatch. No prerequisites, exclusions, or context 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?

With no annotations provided, the description carries the full burden. It does not disclose whether the operation is destructive/reversible, what happens when objectIndex is missing and no selection exists, or whether existing styles are overridden. The minimal text provides no behavioral detail beyond the action itself.

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, tightly worded sentence with no redundancy. It front-loads the action and target. However, it is arguably under-specified, though that's not a conciseness issue.

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?

The tool has no annotations or output schema, and the description offers only the core action. It fails to explain selection vs. objectIndex behavior, error conditions, or document prerequisites, leaving significant gaps for an agent 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?

Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description's mention of 'selected objects' adds slight context for objectIndex's optionality, but it doesn't add substantive meaning beyond the schema.

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 ('apply') and resource ('object style') targeting 'selected objects', clearly distinguishing it from siblings like apply_paragraph_style (different style type) and create/modify_object_style (different action). A single sentence communicates exactly what the tool does.

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 'to selected objects' implies the use case requiring a selection, but no explicit guidance is given on when to prefer this over create_object_style or modify_object_style, nor any exclusion conditions. It's implied usage at best, with no alternatives mentioned.

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. The description only states the basic action and does not disclose side effects, whether it modifies the document, error behavior if the style does not exist, or any permissions required. This is a significant gap 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?

The description is a single concise sentence with no fluff. It is front-loaded with the core action. However, it may be under-specified given the tool's 5 parameters, but from a pure conciseness standpoint it is efficient and 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?

The tool has 5 parameters, no output schema, and no annotations. The description is very brief and does not cover return values, side effects, or conditions under which it should be used. It is not complete enough for an agent to use the tool confidently without additional assumptions.

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 baseline is 3. The description 'Apply a paragraph style to text' adds no additional meaning beyond the schema. The schema already provides descriptions for each parameter, and the description does not explain relationships between parameters (e.g., startIndex/endIndex scope) or provide usage context.

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 'Apply a paragraph style to text' is a clear verb+resource statement. It specifies the action (apply) and the object (paragraph style), and it distinguishes from sibling tools like create_paragraph_style and list_styles, which handle creation and listing respectively.

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 provides no guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., an open document, existing text frame) or any exclusions. There is no reference to sibling tools or scenarios where this tool is preferred.

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 does disclose concrete transformations: removing double paragraph breaks, trailing spaces, manual formatting, bullet lists, and hardcoded chapter numbers. It does not, however, mention side effects such as whether edits are destructive, whether they apply to a specific frame or the whole document, or whether changes are reversible.

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 well-structured sentence with a clear front-loaded purpose and a useful list of examples. The trailing 'etc.' is mildly vague but does not introduce meaningful bloat.

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?

The tool has nine optional parameters and no output schema or annotations, so the description should explain how targeting works, what the defaults do, and what the agent can expect after invocation. It does not clarify the relationship between `pageIndex`, `frameIndex`, and `useSelectedFrame`, nor does it describe the return value or whether the operation changes the document immediately.

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?

The schema description coverage is 100%, so the parameters are already documented at the schema level. The tool description adds no additional parameter-level semantics beyond naming the same problem areas, which keeps it at the baseline rather than elevating it.

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 uses a specific verb ('clean') and a clear resource ('imported text'), and it enumerates concrete typography problems it addresses. It does not explicitly differentiate itself from the overlapping sibling `fix_typography_in_selection`, so it is clear but not fully distinguished.

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 'imported text' implies the appropriate context: use this after importing text that has formatting issues. However, the description gives no explicit guidance on when to choose this tool over closely related siblings like `fix_typography_in_selection`, `find_typography_issues`, or `analyze_text_problems`.

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 burden of behavioral disclosure. It only says 'close the current document' and does not disclose the potential for data loss, the need to confirm destructive actions, or the effects of the save parameter. The schema hints at data loss, but the description itself does not.

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 appropriately concise for a simple operation, though it omits valuable context about destructive behavior.

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 action with no annotations and no output schema, the description is incomplete. An agent calling close_document({}) might lose unsaved data because the description does not explain the save/confirm behavior or warn about consequences. Additional context is necessary for safe use.

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 parameters are already fully documented. The description adds no additional meaning about how save or confirmDestructive affect the close operation, 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?

The description states a specific verb ('Close') and resource ('current document'), making the tool's core purpose immediately clear. It is distinct from siblings like open_document and save_document, though it does not add detail about what 'current' means in multi-document contexts.

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 guidance on when to use this tool versus alternatives, when it is safe to close, or what state the document must be in. Sibling tools like save_document exist, but no selection criteria are offered.

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 full burden of behavioral disclosure. It only restates the name and provides no details on side effects, return values, error handling, or how the new style interacts with the 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?

The description is a single, clean sentence with no wasted words. It is concise but does not elaborate on usage or behavior, which slightly limits its value.

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 the tool has 7 parameters, no output schema, and no annotations, the one-line description is insufficient. It omits return behavior, preconditions, and operational context, making the tool harder to invoke 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%, and each parameter has a basic description (e.g., 'Font size in points'). The tool description adds no extra parameter-level meaning, so the baseline 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?

The description clearly states the action 'Create' and the resource 'character style', distinguishing it from sibling tools like create_paragraph_style. It is specific and 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?

No guidance is provided on when to use this tool versus alternatives such as create_paragraph_style. The description does not mention typical use cases or exclusions.

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 burden of behavioral disclosure. It states 'create' but does not mention side effects, whether it modifies the current document, permission requirements, or behavior on duplicate names. This is under-specified 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?

The description is a single sentence with no filler, making it extremely concise and front-loaded. It earns its place without wasting words.

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?

The description is minimal and does not explain the dependency between colorValues and colorModel, nor mention return values or document impact. With no annotations, no output schema, and 4 parameters, this is inadequate for a complete understanding.

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?

The schema already provides descriptions for name, spotColor, and colorValues, so the description adds no additional parameter semantics. However, the colorModel parameter lacks a description, and the relationship between colorValues and colorModel (especially LAB) is not clarified, leaving some gaps.

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 'Create a new color swatch' uses the specific verb 'create' with the resource 'color swatch', clearly distinguishing it from sibling tools like create_rectangle or apply_color. It is unambiguous about the tool's function.

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 provides no guidance on when to use this tool versus alternatives like apply_color or list_color_swatches. It lacks any contextual usage notes or exclusions.

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 burden of disclosing side effects. It only says 'Create a new InDesign document' without explaining whether the document becomes active, how it relates to unsaved changes, or what the tool returns. This is a significant gap for a mutating operation.

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 concise sentence, which is good for front-loading the core purpose. However, 'with advanced options' is somewhat vague and could be considered filler, preventing a perfect score.

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 12 parameters, no annotations, and no output schema, the description is too sparse to provide a complete picture. It does not mention presets, custom dimensions, or what happens after creation, leaving the agent uncertain about expected inputs and outcomes.

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 92%, so nearly all parameters have descriptive text in the schema. The description's phrase 'advanced options' adds no specific parameter meaning, and the schema already handles parameter explanations. Baseline 3 is appropriate since the description does not need 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?

The description clearly states 'Create a new InDesign document' with a specific verb and resource, distinguishing it from sibling tools that create other elements (e.g., create_rectangle, create_table). The phrase 'with advanced options' hints at extensive configuration but does not obscure the primary purpose.

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 usage is implied by the verb 'create' and the resource 'document'—agents can infer it is for new document creation. However, there is no explicit guidance on when not to use it (e.g., for existing documents use open_document) or mention of alternatives, so it falls short of clear contextual differentiation.

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 present, so the description must carry the burden. It only repeats the action without disclosing side effects (e.g., adds to the document, uses pageIndex), required permissions, or interaction with the active document. The description is essentially a tautology of the tool name.

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 concise sentence with no filler. It is front-loaded with the action, but it is so minimal that it offers little beyond the tool name. Still, it is not verbose, so it scores average.

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 8 parameters and no output schema, the description is insufficient. It does not explain what the function returns, how it behaves on page changes, or any required context like an open document. This is significantly under-specified.

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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no additional parameter semantics, relying entirely on the schema.

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 clearly states the verb 'Create' and the resource 'ellipse shape', indicating the tool's purpose. However, it lacks any scope such as 'on the active page' or 'in the current document', which prevents it from fully distinguishing from other creation tools.

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 is provided on when to use this tool versus alternatives like create_rectangle or create_text_frame. It does not mention prerequisites, target page, or typical scenarios.

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 must disclose behavior, but it only states the core action. It does not mention whether the new layer becomes active, what return value is produced, or any side effects.

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 redundant detail. 'New' is slightly redundant with 'create,' but overall it is efficiently 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?

For a creation tool with no annotations and no output schema, the description is too sparse. It does not specify whether the layer is created in the active document, whether it becomes active, or what the return value is. Given the four parameters and sibling context, a bit more context is needed.

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?

The input schema has 100% coverage with descriptions for all four parameters (name, color, locked, visible). Since the schema already documents parameters thoroughly, the baseline 3 applies; the description adds no extra parameter 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?

The description clearly states the action ('Create') and resource ('layer'), identifying the tool's function among many create_* siblings. However, it offers no additional scoping or differentiation from layer-related operations like set_active_layer, 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 guidance on when to use this tool versus alternatives. There are no conditions, prerequisites, or references to sibling tools; the usage is only implied by the verb '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 burden of behavioral disclosure. It only states 'Create a new object style,' which implies a mutation but gives no details on side effects, whether creation is idempotent, what happens to existing styles, or any required permissions. This is a significant gap for a create operation.

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 concise sentence with no wasted words. It is appropriately sized for a simple create operation, though it lacks any additional structural elements like bullet points or examples. It is not overlong, but it is also very minimal.

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 six parameters, no output schema, and no annotations, this description is incomplete. It does not explain how the parameters interact, what the expected result of creation is, whether any parameters are conditional, or what the tool returns. An agent would need to guess at many behavioral aspects.

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?

The input schema has 100% description coverage for all six parameters, so the schema already documents each parameter's meaning. The tool description itself adds no parameter-specific context, but the baseline of 3 applies because the schema does the heavy lifting.

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 action (create) and resource (object style), making the purpose clear. It does not explicitly differentiate from siblings like create_paragraph_style or create_character_style, but the tool name itself disambiguates. It's a concise, unambiguous statement of what the tool does.

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 provides no guidance on when to use this tool versus alternatives such as modify_object_style or apply_object_style. There is no mention of prerequisites, conditions, or exclusions, leaving the agent to infer usage solely 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?

With no annotations provided, the description must disclose behavioral traits on its own, but it only states the basic action. It fails to mention side effects, persistence, required permissions, or return behavior, offering no context beyond the obvious creation action.

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 concise sentence with no filler, but it is under-specified rather than efficiently structured. It conveys the core purpose but omits any additional context that would justify such brevity.

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?

Despite having 9 parameters and no output schema or annotations, the description provides only a one-line purpose. It does not explain what a paragraph style is, what the parameters do, when to use the tool, or what happens upon creation, making it wholly inadequate for the tool's complexity.

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 high (89%), so the schema already documents most parameters. The tool description adds no parameter information, so it neither enhances nor detracts from the baseline. However, the single undocumented parameter 'alignment' is not explained by the description either.

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 clearly states the tool's function: 'Create a new paragraph style'. It uses a specific verb ('create') and resource ('paragraph style'), and it distinguishes from sibling tools like 'create_character_style' by explicitly mentioning 'paragraph style'.

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 provides no guidance on when to use this tool versus alternatives such as 'create_character_style' or 'apply_paragraph_style'. It neither states context nor exclusions, leaving the agent to 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?

No annotations are provided, so the description must disclose behavioral traits. It only says 'create', which implies a write operation, but offers no details on side effects, coordinate system, permissions, or how it affects the document. This is a minimal disclosure that adds little beyond the tool's name.

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, short sentence with no wasted words. It is front-loaded and easy to parse, effectively stating the core purpose without unnecessary elaboration.

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 9 parameters, no output schema, and no annotations, this description is incomplete. It doesn't explain how the rectangle is positioned (e.g., coordinate origin), what units are used, or how it integrates with the current document state. The schema covers parameter meanings, but the overall behavior and usage context are unclear.

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?

The schema provides descriptions for all 9 parameters (100% coverage), so the description doesn't need to explain them. The tool description adds no parameter-specific meaning, matching the baseline score for high schema 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?

The description clearly states the action (create) and the object (rectangle shape), which distinguishes it from sibling tools like create_ellipse or create_text_frame. While it doesn't elaborate on scope or behavior, it is a straightforward, non-misleading statement of the tool's core function.

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 provides no guidance on when to use this tool versus alternatives such as create_ellipse or create_table. It simply names the operation without any contextual cues for selection, leaving the agent to infer usage purely from the tool 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?

With no annotations, the description carries full burden for behavioral disclosure. It only states 'Create a table' and gives no information about side effects, reversibility, required document state, or any other behavioral traits.

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, but this is under-specification rather than conciseness. A single phrase like 'Create a table' does not provide enough information to justify its brevity, similar to the 'Process' example.

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 9 parameters, no annotations, and no output schema, the description is completely inadequate. It fails to explain the tool's behavior, return value, or usage context, making it nearly impossible for an AI agent to use 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%, so each parameter has its own description (e.g., 'X position in mm'). The tool description adds no additional meaning beyond the schema, fitting the baseline of 3.

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 'Create a table' uses a clear verb and resource, and the schema details dimensions and rows/columns. However, it lacks scope information (e.g., on which page) and does not distinguish from sibling tools like create_rectangle or populate_table.

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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., an open document) or exclusions, leaving the AI agent without context for 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 burden of behavioral disclosure. It doesn't state whether this creates a new frame on the current page, whether it replaces existing content, what happens with default values, or whether it requires an open document. 'Advanced formatting options' hints at capabilities but doesn't disclose side effects or 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?

The description is a single concise sentence that is front-loaded with the core action. It's efficient, though 'advanced formatting options' is somewhat generic and could be more specific without adding length.

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 13 parameters, no annotations, and no output schema, the description is too thin. It doesn't explain the tool's role in the document workflow, whether it requires an active document, how it relates to text frame selection, or what the return value is. The schema covers parameters but the description fails to provide the operational context an agent needs.

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 92%, so the schema already documents most parameters well. The description adds the phrase 'advanced formatting options' which hints at the formatting parameters (fontSize, alignment, fontStyle, textColor, fontFamily, characterStyle, paragraphStyle) but doesn't add specific meaning beyond what the schema provides. Baseline 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?

The description states a specific verb ('Create') and resource ('text frame') and mentions 'advanced formatting options', which distinguishes it from simpler creation tools. However, it doesn't explicitly differentiate from sibling tools like edit_text_frame or insert_markdown_text, and 'advanced formatting options' is vague about what those options are.

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 tool versus alternatives like insert_markdown_text, edit_text_frame, or create_rectangle. The description doesn't mention prerequisites (e.g., an open document) or context for when this is the right choice. The agent must infer usage from the name and schema.

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 must disclose behavioral traits. It fails to mention side effects, such as the generation of multiple files (implied by confirmDestructive), required permissions, or any destructive nature. The description gives no information about what the operation actually does at a behavioral level, making it impossible for an agent to anticipate 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?

While the description is only one sentence long, this is under-specification rather than conciseness. It does not front-load critical information or earn its brevity. The sentence is too generic to be useful and fails to convey the tool's purpose or behavior.

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 the tool's complexity (5 parameters, a confirmDestructive flag, no annotations, no output schema), the description is entirely insufficient. An agent has no understanding of what a data merge does, what the parameters mean, or what the tool will produce. This is a severe gap that makes the tool effectively unusable without external documentation.

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 high (80%), with descriptions for outputFolder, dataSourcePath, recordRange, and confirmDestructive. The description adds no extra meaning beyond the schema; it does not clarify how the parameters relate to the merge operation or provide usage examples. Baseline of 3 is appropriate because the schema carries the load.

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 'Perform data merge operation' is extremely vague and essentially restates the tool name. It does not specify what data merge entails, what inputs it takes, or what output it produces. It does not differentiate from sibling tools like create_document or export_pdf, leaving an agent unclear on when this tool is appropriate.

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. No mention of typical use cases, prerequisites, or conditions that would favor data_merge over other tools. An agent has no context to decide if this is the right tool for a task.

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 disclosing behavior. It only says 'Delete a page' and does not state that deletion is permanent, that confirmDestructive must be true, or any side effects. The schema partially covers this via the confirmDestructive parameter, but the description itself adds no behavioral transparency.

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 short sentence with no filler and the core action is front-loaded. It is concise, though it achieves brevity by omitting important caveats.

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 mutation tool with no annotations and no output schema, the description is too sparse. It does not explain that confirmation is required, that deletion is irreversible, or what happens to the page's contents. The schema compensates for some of this, but the overall context is incomplete.

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%, with both pageIndex and confirmDestructive already documented. The description adds no additional parameter meaning, 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?

The description states the exact action ('Delete a page') and the resource ('from the document'), which is specific and unambiguous. It clearly differentiates from sibling tools like add_page, duplicate_page, and navigate_to_page because deletion is a distinct operation.

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 about when to use this tool versus alternatives, such as add_page or duplicate_page. The description simply names the operation without mentioning prerequisites, destructive implications, or that it is the irreversible counterpart to adding a page.

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 burden of behavioral disclosure. 'Duplicate a page' implies mutation but does not state whether the original page remains unchanged, whether the copy is deep or shallow, or any side effects. This is a significant transparency gap for a mutating 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?

The description is extremely concise and front-loaded, but it is under-specified for a tool with a required parameter and an optional position parameter. It is not overly verbose, but the brevity sacrifices necessary context, making it minimally acceptable.

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 the lack of annotations, no output schema, and only a one-line description, the context is incomplete. The description does not explain the duplicate behavior (e.g., whether content is copied, where it is inserted) or provide enough information for an agent to use it correctly without guesswork.

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?

The description adds no meaning beyond the input schema. The schema documents pageIndex but leaves position undocumented (50% coverage). The description could have clarified the position parameter's purpose or the default 'after', but it remains silent, failing to compensate for the schema 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 uses a specific verb ('duplicate') and resource ('page'), clearly indicating the action. It distinguishes from sibling tools like add_page and delete_page, but lacks explicit scope details such as where the duplicate is placed or that it copies all content, preventing a higher score.

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 provides no guidance on when to use this tool versus alternatives like add_page or delete_page. There is no context about use cases, prerequisites, or exclusions, leaving the agent without clear selection 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 says 'Edit properties' which implies mutation, but doesn't disclose whether changes are reversible, whether the frame must be on a specific page, what happens if frameIndex is invalid, or whether the tool updates only provided properties or resets unspecified ones. The pageIndex parameter hints at page context but the description doesn't explain its role.

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 with a clear workflow hint. The WORKFLOW prefix is useful and front-loaded. No wasted words, though it could be slightly more explicit about which properties are editable.

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 and no output schema, the description is adequate but has gaps. It explains the prerequisite lookup step, but doesn't clarify behavior on partial updates, error cases, or how textColor/fontFamily values should be formatted. The sibling list shows related style tools, but the description doesn't route to them.

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 86%, so the schema already documents most parameters. The description adds the workflow context for frameIndex, but doesn't clarify ambiguous parameters like textColor format (hex? name?) or whether content replaces all text or inserts. The alignment enum is self-documenting. Baseline 3 is appropriate since schema does most of the work.

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 clear verb and resource: 'Edit properties of an existing text frame.' It distinguishes itself from create_text_frame (creation) and get_text_content (reading), though it doesn't explicitly name a sibling. The workflow hint about finding frameIndex adds context.

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 WORKFLOW instruction explicitly tells the agent to first call list_text_frames() or get_selected_objects() to find the correct frameIndex. This is clear usage guidance for a prerequisite step, though it doesn't explicitly state when not to use this tool versus alternatives like modify_character_style or apply_paragraph_style.

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 the schema warning clearly discloses that the code can access filesystem, network, and system APIs. The environment-variable requirement is also surfaced. It stops short of describing return values or error behavior, so it is strong but not exhaustive.

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 compact, front-loaded with a warning symbol and the environment requirement, and contains no filler. It is slightly under-sized relative to the power and risk of arbitrary code execution, but the structure is scannable and 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?

The description covers the essential purpose, the required environment variable, and the dangerous capabilities of the code. However, it lacks usage boundary guidance and does not describe what happens after execution or what the tool returns, which matters given there is no output schema or annotations to fill those gaps.

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 parameter is already well documented in the schema: 'ExtendScript/JavaScript code to execute in InDesign' plus a danger warning. The main description adds no meaningful parameter semantics beyond what the schema already provides, so the high-coverage 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?

The description uses a specific verb ('Execute') and resource ('custom ExtendScript code in InDesign'), making the tool's purpose immediately clear. The word 'custom' and the code-execution scope distinguish it from the many specialized sibling tools that perform fixed InDesign operations.

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 communicates a required precondition (INDESIGN_ALLOW_ARBITRARY_CODE=1) but does not explicitly say when this tool should be used instead of a dedicated sibling tool. It implies an escape-hatch role, but there are no explicit when-to-use/when-not-to-use instructions or named alternatives.

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 burden of behavioral disclosure. It fails to mention that the tool can overwrite files (despite the confirmDestructive parameter), that it may include images by default, or that it supports multiple EPUB versions and image formats. The description is a bare statement of intent with no behavioral context, leaving the agent unaware of side effects like file overwriting or default behaviors.

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, efficient sentence with no wasted words. It front-loads the core action and format. However, it is so brief that it misses opportunities to add behavioral context, but for what it states, it is concise and well-structured.

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 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain the overwrite confirmation requirement, the default EPUB version, or the image handling behavior. An agent would need to inspect the schema carefully and still might not know when to choose this over export_pdf or export_images. The description is minimally viable but leaves significant gaps.

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 60%, so the schema already documents filePath, imageFormat, includeImages, and confirmDestructive. The description adds no parameter-level detail beyond what the schema provides. The version parameter lacks a description in the schema and the description doesn't compensate, but the enum values are self-explanatory. Baseline 3 is appropriate since the schema does most of the work.

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 'Export document as EPUB' clearly states the verb (export), resource (document), and target format (EPUB). It distinguishes from sibling tools like export_pdf and export_images by naming the specific format. However, it doesn't explicitly differentiate from other export tools or mention the document context (e.g., current open document), which would make it fully 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 provides no guidance on when to use this tool versus alternatives like export_pdf or export_images. It doesn't mention prerequisites (e.g., a document must be open), nor does it explain when EPUB export is appropriate. The only implied usage is 'export as EPUB,' which is not enough to route an agent correctly among the many sibling export tools.

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. 'Export pages as images' does not reveal that this writes files to disk, may overwrite existing files, or that confirmDestructive must be true. The description also fails to note that the document itself is not modified but external image files are created.

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 fluff. It is efficient and easy to parse, though it is under-specified. The conciseness is good, but the lack of additional context prevents a perfect score.

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 6-parameter export tool with no output schema and no annotations, this description is seriously incomplete. It does not explain pageRange syntax, the mandatory confirmation flag, the effect of includeBleed, or what files are produced. An agent would likely call this incorrectly without additional knowledge.

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 83%, so the baseline is 3 even though the description adds no parameter details. The schema documents most parameters, but the description does not clarify the pageRange syntax or the meaning of confirmDestructive, leaving a small gap that the high coverage 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?

The description clearly states the action (Export), the resource (pages), and the output (images). This distinguishes it from sibling tools like export_pdf and export_epub, though it doesn't mention the specific image formats or that folderPath is required, which are left to the 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?

There is no guidance on when to use this tool versus alternatives, no mention of the required confirmDestructive parameter, and no indication that folderPath must be writable. An agent would have no basis for choosing this over export_pdf or export_epub, or for understanding the confirmation requirement.

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. 'Export' implies a file-writing operation, but the description does not warn about file overwrite, side effects, or any prerequisites. The confirmDestructive parameter reveals overwrite risk, but that lives only in the schema, not the description.

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, focused sentence with no wasted words. It is front-loaded with the core action, though it is somewhat under-specified rather than overly verbose.

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 8 parameters, no annotations, and no output schema, the description is too thin. It omits the destructive overwrite behavior, any caveats about presets or color profiles, and what constitutes 'advanced options.' An agent must rely entirely on the schema without additional operational context.

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 88%, so the parameters are already well-documented (preset, pageRange, includeBleed, etc.). The description's phrase 'advanced options' loosely implies the parameter set but adds no specific meaning beyond the schema, so a 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?

The description uses a specific verb (export) and resource (document as PDF), and the mention of 'advanced options' signals configurability beyond a basic export. It is clear enough to distinguish from export_images and export_epub by name, though it lacks explicit sibling differentiation.

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 is given about when to use this tool versus alternatives like export_images or export_epub. The description simply states what the tool does, leaving the agent to infer usage solely from the tool name and sibling list.

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 burden of disclosing behavioral traits. It only states the basic operation and does not mention whether formatting is preserved, how replacements are applied (e.g., one-by-one or all), or the effect of options like regex or scope. 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?

The description is a single, concise sentence with no filler words. It is efficiently front-loaded but lacks depth; however, conciseness is about economy, and this achieves that.

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?

The tool has multiple parameters and options, but the description gives no hint about return values, behavior with edge cases, or how options interact. Without annotations or an output schema, the bare description is insufficient for an agent to fully understand the tool's behavior.

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 high (83%), with descriptions for most parameters. The description does not add meaningful parameter-level information beyond what the schema already provides, 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?

The description clearly states the tool's function with a specific verb and resource: 'Find and replace text'. This is distinct from sibling tools, though it does not explicitly mention alternatives or scope variations.

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 provides no guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It simply states the action without any contextual instruction.

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 full responsibility for disclosing behavioral traitsepth. It only says the tool analyzes text and gives examples, but does not state whether it mutates content, what its output format is, how selection vs frame vs page scoping works, or whether it is read-only. The 'analyze' wording implies non-destructive behavior but leaves significant ambiguity.

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 efficient sentence with no filler and useful examples. It could be slightly improved by front-loading the primary use case, but as written it is concise and directly communicates the tool's core function.

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 three optional parameters and no output schema, the description omits key context: what the analysis returns, whether it modifies the document, how to scope the analysis, and when to prefer this over sibling tools. The schema helps with parameter names but not with the overall call flow or result interpretation.

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 baseline is 3. The parameters are each described minimally ('Page index', 'Text frame index to analyze', 'Analyze currently selected text frame'), and the description does not add extra meaning beyond the schema. It also does not explain how pageIndex, frameIndex, and useSelectedFrame interact or take precedence.

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 clearly states the tool's function: analyze text for common typography issues, with concrete examples like wrong spaces in dates, straight quotes, and double spaces. This distinguishes it from fix_typography_in_selection by implying detection rather than correction, though it does not explicitly contrast it with the overlapping sibling analyze_text_problems.

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 is provided about when to use this tool versus alternatives such as fix_typography_in_selection, clean_imported_text, or analyze_text_problems. The description gives no conditions, prerequisites, or recommended workflow context.

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 burden of disclosing behavior. It does explain the main effect: fixing typographic elements in a selected text/story. However, it does not mention irreversibility, whether changes are applied in place, or the precise handling of 'other typographic elements', leaving some behavioral ambiguity.

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 very concise and front-loaded. The first sentence names the operation and target, and the second briefly enumerates the corrections. There is no redundant information or padding.

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 the 7 optional parameters and no required fields, the description is minimally adequate. The schema covers all parameters, and the description covers purpose, but the interaction between selection-related parameters (pageIndex, frameIndex, useSelectedFrame) is not clarified, and usage relative to sibling tools is not addressed.

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 parameters are already well documented. The description adds only high-level context about date, quote, and dash corrections, and does not clarify the selection mechanics among pageIndex, frameIndex, and useSelectedFrame beyond the schema.

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 action ('Fix typography') on a clear resource ('selected text or story') and lists the corrections made (dates, quotes, dashes). It is clear and functionally specific, though it does not explicitly contrast with sibling tools like find_typography_issues or clean_imported_text.

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 'selected text or story' implies the tool operates on an active selection, giving some usage context. However, it does not explain when to prefer this over related tools such as find_typography_issues or clean_imported_text, and no exclusions or prerequisites are stated.

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 provide all behavioral context, but it only states that it 'gets detailed information'. It does not disclose what the information includes, whether it is a read-only operation, if it has side effects, performance implications, or what the return format is. Thus, the description lacks transparency about the tool's behavior.

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, concise sentence that is front-loaded with the action ('Get') and clearly names the resource ('detailed information about the current InDesign document'). Every word earns its place; there is no waste or excessive elaboration.

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?

The tool has no output schema, no annotations, and no parameters, so the description bears full responsibility for explaining what the tool returns. Saying 'detailed information' is vague and does not specify the structure or breadth of the returned data. An agent cannot know from this description what information will actually be retrieved, making it insufficiently complete for reliable selection and 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and it correctly avoids any parameter-related details. This is appropriate given the empty input schema.

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 clear verb and resource: 'Get detailed information about the current InDesign document'. It is not a tautology and has a specific focus on document info. However, it does not distinguish from sibling tools like view_document or list_styles, which may also provide document-related information.

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 guidance on when to use this tool versus alternatives. It is a single declarative sentence without context on prerequisites, exclusions, or preferred scenarios. No sibling tools are referenced, so the agent has no basis for choosing this tool over others.

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. The verb 'Get' clearly indicates a read-only operation, and 'currently selected objects in InDesign' explains what state is being read. However, it does not disclose what happens with no selection or multiple selections, nor what shape the returned 'information' takes.

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 two short sentences with no filler or restatement of the tool name. The first sentence states the exact action and resource, and the second adds a practical usage context, making it well-structured and front-loaded.

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 zero-parameter getter, the core invocation is clear, and the text-frame usage context is helpful. But with no output schema and no annotations, the description should specify what 'information' is returned (for example, object IDs, types, or bounds) and how no-selection cases are handled. As written, it is minimally viable but incomplete.

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?

The input schema has zero properties, so there are no parameters for the description to document. The phrase 'currently selected' effectively communicates that the tool relies on the active InDesign selection state rather than explicit arguments, which is the only parameter-like context needed here.

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 uses a clear getter verb and scopes the resource to 'currently selected objects in InDesign,' which is distinct from listing all text frames or getting document info. The text-frame note adds a concrete workflow, but the description does not explicitly contrast it with sibling selection/text tools like get_text_content or fix_typography_in_selection.

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 second sentence gives an explicit context: 'ESSENTIAL for working with user-selected text frames.' This tells an agent when this tool is relevant and signals that it operates on the user's current selection. It stops short of 5 because it does not mention when not to use it or name alternatives.

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 behavioral disclosure burden. It does disclose a key behavior: line breaks are normalized to spaces. It also implies read-only extraction via the verb 'extract'. However, it does not explain potential error behavior when neither a selection nor a frameIndex exists, or what happens when both are provided.

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 two tight sentences with no filler. The core action and input sources are front-loaded, and the normalization behavior and recommendation are stated in minimal words. Every sentence adds value.

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 extraction tool with optional parameters and no output schema, the description is mostly adequate, but it leaves some gaps. It does not explicitly state the return type beyond 'raw text content', nor does it clarify edge cases like truncation via maxLength or the relationship between pageIndex and frameIndex. These gaps are moderate for an agent deciding whether and how to invoke 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%, so the baseline is 3. The description adds little beyond the schema, though it does reinforce the normalizeSpaces behavior by mentioning line-break normalization. No additional parameter semantics or usage constraints are given for maxLength, pageIndex, or frameIndex.

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 uses a specific verb ('Extract') and resource ('raw text content') and clearly identifies the possible input sources: selected text frame, insertion point, or specific frame. It also differentiates itself from sibling tools like list_text_frames and get_selected_objects by focusing on actual text extraction rather than object listing or selection inspection.

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 'RECOMMENDED for text extraction' tag gives general guidance on when to use the tool, and the description explains it handles different selection types and specific frames. However, it does not explicitly name alternatives or state when not to use this tool, such as when listing frame metadata or editing text instead.

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 disclose side effects, but it only says 'Insert' and 'automatic formatting.' It does not mention that replaceContent defaults to true and would replace existing frame content, nor any other mutation or failure behavior. This leaves a potentially destructive default hidden from an agent choosing or invoking the 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?

Two short sentences with the key action and object first, followed by concrete syntax examples. There is no filler and no repetition of schema fields.

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?

The schema documents all five parameters and covers prerequisites for frameIndex, so the tool is callable, but the description omits the replace-vs-append default and there is no return-value guidance or explicit alternative routing. For a mutating 5-parameter tool with no annotations and no output schema, this is adequate but not complete.

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 baseline is 3, and the description still adds value by specifying accepted markdown syntax ('# headers, **bold**, *italic*'). It also explains that formatting reuses existing paragraph and character styles, which clarifies why no style parameters are required. It does not add parameter-level detail for pageIndex/frameIndex/replaceContent, but the schema already covers those.

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 ('Insert'), a target resource ('text frame'), and a distinctive behavior ('automatic formatting using existing paragraph and character styles'). It clearly separates this tool from siblings like get_text_content, create_text_frame, and apply_paragraph_style. The markdown examples further pin down the tool's purpose.

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 implies the use case—inserting markdown-formatted content into an existing frame—but never names alternatives or states when not to use it. The frameIndex parameter description in the schema gives a prerequisite, but the tool description itself provides no explicit routing versus edit_text_frame or clean_imported_text. This is adequate implied guidance, not explicit selection 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?

With no annotations, the description carries the full burden. The verb 'list' implies a non-destructive read operation, and 'all' indicates comprehensive coverage. However, it does not disclose details such as whether default swatches are included or the format of the returned data.

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, clear sentence that directly conveys the tool's purpose without unnecessary words.

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?

The description explains the basic function but omits details about the return structure (e.g., whether it returns names, color values, or both). Since there is no output schema, these details would need to be in the description to be complete, but they are missing.

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?

The tool has zero parameters, so the baseline score is 4. The description adds no parameter information because none is needed.

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 clearly states the action (List), the resource (color swatches), and the scope (in the document). It distinguishes from sibling tools like create_color_swatch and apply_color by focusing on read-only listing.

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 is provided on when to use this tool versus alternatives. There is no mention of related tools like create_color_swatch or apply_color, nor any context about typical use cases.

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 mentions that it lists searches but does not disclose what happens if the document is closed, whether it returns names and/or patterns, or any side effects (though listing is likely read-only). The analogy is helpful but does not cover behavioral details.

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 concise sentence, with the analogy adding value without unnecessary length. It is front-loaded with the core action. No wasted words.

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 the simplicity (zero params, no output schema), the description is mostly complete for an agent to know what it does. However, it lacks details on the return format or any behavior in edge cases (e.g., no searches found). For a simple list tool, this is acceptable but could be improved.

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?

The tool has zero parameters, so the description does not need to explain parameter semantics. The baseline for zero parameters is 4, but the description adds little beyond stating the tool lists searches; it could have elaborated on the structure of the listing (e.g., names vs. patterns). Thus, a 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?

The description clearly states the tool lists saved GREP searches in the document, using a specific verb and resource. It also provides a helpful analogy ('like DATUM search for dates') to clarify the concept. However, it does not explicitly differentiate from siblings, though no sibling seems to offer similar functionality.

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 implies usage when the agent needs to know available GREP searches, and the analogy helps understanding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites (e.g., document must be open). With no annotations, more explicit guidance would be better.

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 present, and the description does not disclose any behavioral traits such as return format, ordering, or side effects. The read-only nature is implied but never explicitly stated, and the description adds no procedural 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 concise sentence that directly states the operation without any extraneous words. It is front-loaded and easy to parse.

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 zero-parameter list operation, the description is functionally complete. It does not explain return values, but given the simplicity of the tool and absence of an output schema, the provided information is sufficient for a competent agent to use 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?

There are zero parameters, so the baseline is 4. The description adds no parameter semantics, but none are needed as the tool takes no inputs.

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 uses a specific verb 'list' and clearly identifies the resource ('all layers in the document'), distinguishing it from sibling tools like create_layer or set_active_layer. This is unambiguous and immediately 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention any related tools or exclusions, leaving the agent to infer usage from the name alone. For a simple listing tool this is a gap, though not severe.

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?

Since no annotations are provided, the description must carry the full burden. It does not disclose that this is a read-only operation, whether it includes hidden or built-in styles, or what the return format is. The verb 'list' implies reading, but no behavioral details are added.

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 that is efficient and front-loaded. Every word contributes to conveying the core purpose without unnecessary elaboration.

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?

The tool is simple with one optional parameter and no output schema. The description is adequate for a basic read operation, but it does not mention possible return values, filtering, or any behavioral nuances, leaving some gaps for an agent to infer. Given the low complexity, this is minimally viable.

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 0%, so the description must compensate for parameter documentation. It completely omits the styleType parameter and its filter options, despite those being essential for non-default behavior. The schema itself is self-explanatory, but the description fails to add meaningful value.

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 clearly states the action (list) and the resource (available styles in the document). It is specific enough to distinguish from sibling tools like list_color_swatches or list_layers, though it doesn't mention the optional styleType filter, which slightly narrows the scope in the 'all' default sense.

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 is provided on when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned. The description is only a bare functional statement with no context for the AI agent.

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 usefully discloses that the operation lists frames and includes indices, previews, and selection status. However, it does not mention preview truncation, invalid page indices, or whether the operation is strictly read-only beyond the verb 'list'.

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 that states the action, scope, and output essentials without filler. Every word contributes to understanding.

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, but the description names the key returned elements (indices, content preview, selection status). For a simple list operation with one optional parameter, this is nearly complete; only minor details like output format or preview limits are missing.

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%: pageIndex is described as 'Page index to inspect' with a default of 0. The description adds no additional parameter meaning, 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?

The description names a specific verb ('List'), a clear resource ('text frames'), and the scope ('on a page'), plus concrete output details (indices, content preview, selection status). This distinguishes it from siblings like get_text_content or get_selected_objects by focusing on the full set of frames with metadata.

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 guidance about when to use this tool versus alternatives such as get_text_content or get_selected_objects. It states what the tool does, but not when it is preferred, when it should be avoided, or what prerequisites exist.

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, but it only states the action and object. It does not mention that changes overwrite the style definition, how existing text using the style is affected, whether missing style names cause errors, or any permission requirements. This is a significant gap 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?

The description is a single, direct sentence with no filler or repetition. It front-loads the action and target resource, making it instantly scannable.

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?

Although the schema documents parameter names and types, the description provides no context about side effects, return values, error conditions, or the relationship between modifying a character style and text that already uses it. For a tool with no annotations and no output schema, this is too thin for an agent to understand the full implications of 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 description coverage is 100%, so all six parameters already have meaningful descriptions in the schema. The tool description adds no parameter-level detail beyond the generic phrase 'properties', but because the schema does the heavy lifting, the baseline score 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?

The description uses a specific verb ('Modify') with a specific resource ('existing character style'), which clearly distinguishes it from sibling tools like create_character_style and modify_paragraph_style. The word 'existing' also signals that this is not a creation tool.

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 'existing character style' implies this tool is for modifying already-created styles rather than creating new ones, but it never explicitly states when to choose this tool over create_character_style, modify_paragraph_style, or modify_object_style. The guidance is present only by implication from the name and the word 'existing'.

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 exist, so the description must carry the behavioral burden. It states that properties are modified but does not disclose side effects, whether the style is mutated in place, whether changes propagate to objects using the style, or any prerequisites. This is thin 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?

The description is a single, front-loaded sentence with no filler. It is concise and readable, though 'properties' is generic and could have named the actual modifiable fields for extra clarity.

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 several closely related sibling tools, the description is too minimal. It fails to explain when to use it, what side effects occur, or how it differs from applying or creating object styles.

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 input schema already documents all five parameters. The description adds no parameter-level meaning beyond the schema, so the baseline score 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?

The description uses a specific verb ('Modify') plus a clear resource ('existing object style'). It differentiates from siblings like create_object_style, apply_object_style, modify_paragraph_style, and modify_character_style.

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 is given about when to use this tool versus the many related style tools. It does not mention alternatives, prerequisites, or exclusion conditions; usage is only implied by the tool 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 this sparse description carries the full burden. It discloses that the tool modifies an existing style but does not mention whether changes are applied in-place, affect content already using the style, require a certain document context, or what happens if the style does not exist. For a mutation tool, this lack of behavioral disclosure 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?

One short, grammatically complete sentence that immediately states the operation and target. No filler or redundant phrasing.

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?

The tool has 8 parameters with complete schema descriptions, one required parameter, and no output schema, so the description needn't cover return values. However, because there are no annotations, the description should include behavioral context (e.g., that styleName must reference an existing style, that at least one property should be supplied, and the in-place mutation effect); it does not.

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 each parameter has a description (e.g., 'Leading (line spacing) in points', 'Font size in points'). The tool description adds no parameter-specific meaning, but the schema already fully documents the parameters, 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?

The description uses the specific verb 'Modify' with resource 'paragraph style' and the qualifier 'existing', which clearly differentiates it from create_paragraph_style and apply_paragraph_style, as well as modify_character_style. The purpose 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 does not explicitly state when to use this tool versus alternatives. Context is implied by the word 'existing' (i.e., not for creating new styles) and by naming 'paragraph style' (not character/object styles), but no explicit when-to-use or exclusion guidance is 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only repeats the tool's purpose ('navigate') and provides no details about whether this changes the current page in the UI, requires an open document, or has side effects. This is a minimal and uninformative description.

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 short sentence, which is concise. However, it is under-specified and does not provide additional structure or context that would help an agent understand its role, especially given the presence of related sibling tools.

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 no annotations, no output schema, and a simple one-parameter schema, the description should ideally clarify navigation context, such as whether it sets the active page or just scrolls. The current description is too thin to fully disambiguate from zoom_to_page or view_document, leaving the agent uncertain about the tool's exact behavior.

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?

The input schema has 100% coverage for the single parameter, including a description ('Page index to navigate to'). The tool description adds no additional meaning beyond what is already in the schema, so the baseline score 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?

The description clearly states the action ('navigate') and the resource ('a specific page'), which is a distinct operation from creating or editing pages. However, it does not differentiate from sibling tools like zoom_to_page, which also involve moving to a page.

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 is provided on when to use this tool versus alternatives such as zoom_to_page or view_document. The description gives no usage context, prerequisites, or exclusions.

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 must disclose behavioral traits, but it only states the action without explaining side effects, error handling (e.g., file not found), or whether InDesign must be running. It does not describe what happens when the document is opened or whether it replaces the currently open 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?

The description is a single, focused sentence with no redundant words. It is perfectly concise and front-loaded, though it sacrifices behavioral detail for brevity.

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 tool with one parameter and no output schema, the description provides the basic purpose but omits behavioral context that would help an agent fully understand the operation's effects. It is adequate but not complete, especially given the absence of annotations.

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% for the single parameter filePath, so the schema fully documents it. The description adds no additional meaning beyond the schema, resulting in the baseline score of 3.

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 'Open an existing InDesign document' clearly states the action (open) and the resource (existing InDesign document), distinguishing it from siblings like create_document, close_document, and save_document. It is specific and 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?

No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites or exclusions mentioned. For instance, it does not state whether the document must be closed already or if there are format restrictions beyond the schema's filePath description.

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. It only names the operation; it does not disclose side effects such as creating folders, copying fonts/linked files, potential overwriting, or the destructive implications hinted at by confirmDestructive.

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 concise sentence with no wasted words. However, for a tool with five parameters and no annotations, it is arguably under-specified rather than appropriately 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?

Given the tool's complexity, lack of annotations, absence of an output schema, and many sibling tools, the description is too terse. It does not explain what packaging involves, what confirmDestructive protects against, or what the agent should expect after 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 100%, so the input schema already explains each parameter clearly. The tool description adds no additional parameter meaning, so the baseline score 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?

The description states a specific action ('Package') and resource ('document'), with a clear purpose ('for print production'). It is understandable on its own, but it does not explicitly distinguish this from sibling tools like export_pdf or preflight_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?

There is no guidance on when to use this tool versus alternatives such as export_pdf, preflight_document, or save_document. The phrase 'for print production' vaguely implies context, but no exclusions, prerequisites, or alternative routing 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 must disclose behavior, but it only states the action without any details about side effects, permissions, or document mutations. It does not explain how parameters like createFrame affect the operation or whether the image is embedded or linked.

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 short sentence, which is concise, but it lacks substantive content and includes filler ('advanced options'). It is not structured to convey important details, though it is not excessively long.

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 8 parameters, no annotations, and no output schema, the description is substantially incomplete. It does not explain the tool's overall effect, return value, or how it fits into a document-editing workflow. The schema helps with parameters but leaves the tool's behavior and integration context 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?

The input schema already provides descriptions for 7 of 8 parameters, with high coverage (88%). The description adds no additional parameter semantics; the only undocumented parameter (fitOption) remains vague, but the baseline score of 3 is appropriate given the schema's 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?

The description identifies the action ('place') and resource ('an image'), making the core purpose clear. However, 'advanced options' is vague and does not elaborate on what those options are, and there is no explicit differentiation from sibling tools beyond the resource type.

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 provides no guidance on when to use this tool versus alternatives like create_rectangle or create_text_frame. There is no mention of prerequisites, use cases, or exclusions, leaving the agent to infer applicability.

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 full responsibility for behavior. It only states 'Populate table with data' without disclosing whether existing data is replaced, how headers are handled, or any side effects. No mention of tableIndex/pageIndex requirements or error conditions.

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 one short sentence with no wasted words, but it is under-specified. It earns some credit for being concise, but the brevity sacrifices necessary detail, making it less useful than a moderately detailed description.

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 the absence of annotations and output schema, the description should explain the tool's effect on the document and any return values. It fails to mention whether data replaces or appends, whether headers are included, or what happens on success. The 100% schema coverage helps parameters but not overall context.

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?

The input schema already provides 100% description coverage for all four parameters, so the baseline is 3. The tool description adds no additional parameter meaning beyond what the schema already states, such as the structure of 'data' or the meaning of 'includeHeaders'.

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 uses a clear verb-resource structure ('Populate table') and identifies the resource as a table. It does not explicitly distinguish from siblings like create_table or data_merge, but the action 'populate' suggests filling an existing table, which is reasonably clear. However, it lacks detail on scope (which table, how data maps).

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 is provided on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., table must already exist) or contrast with data_merge or edit_text_frame. There is no context about typical use cases.

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 must carry the full burden of behavioral disclosure. It fails to state whether the tool is safe/read-only, what output or return value it produces, or any side effects. The term 'preflight' implies checking, but the description does not explicitly assure non-mutating behavior.

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 concise, but it is under-specified to the point of being vague. It lacks structural elements like mention of parameters, behavior, or context that would make the conciseness effective.

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 and no annotations, the description is insufficient for the agent to understand the tool's result or behavior. Given the complexity of a preflight check (likely producing a report), a one-line description is grossly inadequate for successful invocation and output interpretation.

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% (only 'profile' has a description). The tool description adds no information about either parameter; it doesn't explain 'scope' beyond the schema enum/default or clarify how 'profile' is used. The description fails to compensate for the partial schema 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?

The description uses the specific verb 'Run' with the resource 'preflight check on the document', clearly indicating the tool's function. It is distinct from siblings like 'package_document' or 'export_pdf' because 'preflight' is a recognized term in print workflows, though it doesn't elaborate on what the check entails.

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. It doesn't mention that preflight is typically run before export/package, nor does it state any prerequisites or exclusions among the sibling tools.

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 full responsibility for behavioral disclosure. It only states 'save', but does not explain side effects (e.g., overwriting without confirmation), requirements (confirmDestructive), or return behavior. The schema description of confirmDestructive hints at overwrite, but the tool description itself is silent on these behaviors.

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 with zero unnecessary words. It is maximally concise and front-loaded with the core action and object.

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 no output schema and no annotations, the description is severely underspecified. It lacks information about return values, error cases, what happens when filePath is omitted, or the role of confirmDestructive. An agent cannot fully anticipate the tool's behavior from this description alone.

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% (both parameters have descriptions), so the schema already documents parameter meaning. The description adds nothing beyond the schema, so a 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?

The description clearly states a specific verb ('Save') and resource ('the current document'), which is unambiguous and distinguishes it from all sibling tools (no other save operation exists). It is immediately obvious what the tool does.

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 is provided on when to use this tool versus alternatives or any prerequisites (e.g., a document must be open). There is no mention of typical use cases or conditions, leaving the agent to infer when saving is appropriate.

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 only says 'Set the active layer,' which implies a state change, but does not disclose side effects, error behavior if the layer does not exist, or any impact on subsequent operations. This is a significant gap 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?

The description is a single sentence, but it essentially restates the tool name and provides no extra information. It is under-specified rather than appropriately concise, similar to the 'Process' example where brevity comes at the cost of usefulness.

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 no annotations, no output schema, and only a minimal description, the tool lacks essential context such as prerequisites, behavior, and return value. For a simple setter, it might be acceptable, but the absence of any additional information makes it incomplete for an agent to use 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?

The input schema has 100% coverage for the single parameter 'layerName' with description 'Layer name to activate'. The tool description adds no additional 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?

The description 'Set the active layer' clearly states the action (setting) and the resource (active layer). It distinguishes from sibling tools like create_layer and list_layers, though it doesn't explicitly clarify what 'active layer' means or its significance.

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, no prerequisites (e.g., layer must exist), and no mention of typical use cases. The agent is left without context for selecting this tool appropriately.

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 must carry the full burden of behavioral disclosure. It does not state whether the tool is read-only, what 'visual representation' means (e.g., image, UI preview, data), or any side effects or permissions required.

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 conveys the essential scope efficiently.

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 parameters and no output schema, the description should clarify what the agent will receive or experience, but it does not. The missing return format and behavioral details are significant gaps, especially given similar sibling tools that return structured info or files.

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?

The tool has zero parameters, making schema coverage trivially complete. With no parameters to document, the baseline is 4, and the description adds no parameter-specific meaning because none are needed.

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 clearly states the action ('Get visual representation and detailed info') and the resource ('current document'), avoiding tautology. However, it does not distinguish this from the sibling get_document_info, which also provides detailed info about a 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?

There is no guidance on when to use this tool versus alternatives like get_document_info or export_images. No context, prerequisites, or exclusions 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?

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the action without explaining side effects, view changes, or interactions with pageIndex and fitOption. It does not reveal whether the zoom is temporary or persists, nor does it mention any prerequisites.

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 short phrase, which is structurally brief and front-loaded, but it is overly terse and omits necessary context. It is concise but at the expense of clarity.

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 the tool has two parameters, an enum, and no output schema, the description is far too minimal to provide complete context. It does not explain the fit options, the meaning of pageIndex, or how this tool fits among view-related siblings, leaving significant gaps.

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% with only pageIndex having a description. The description does not elaborate on fitOption's meaning or how it interacts with pageIndex. It fails to compensate for the lack of schema documentation on the enum 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?

The description 'Zoom and fit page in view' identifies the core action (zoom/fit) and target (page in view). It clearly indicates the tool's primary function, though it does not explicitly mention the fit options or differentiate from sibling tools like navigate_to_page.

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 is given on when to use this tool versus alternatives such as navigate_to_page or view_document. The description lacks context about typical scenarios or exclusions, leaving the agent to infer usage.

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