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 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?

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 provided, the description carries the full burden of behavioral disclosure. It fails to mention that closing with save=false may discard unsaved changes, or whether any confirmation prompt appears. The save parameter's behavioral impact is not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence, front-loaded and to the point. Every word earns its place; there is no irrelevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool is simple, the description omits the critical consequence of not saving. It doesn't clarify that closing without saving will lose changes, which is essential for safe use. The schema mentions the save default but not the behavioral outcome.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage for the only parameter (save), describing it as 'Save before closing'. The description adds no additional meaning beyond the schema, 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 clearly states the action (close) and the target (current document), using a specific verb and resource. It distinguishes itself from sibling tools like save_document and open_document, as 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 provides no guidance on when to use this tool versus alternatives, nor does it explain the implications of the save parameter (e.g., whether to save before closing). With siblings like save_document, this missing context is significant.

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 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'Create a text frame' without indicating any side effects (e.g., current page placement, whether it replaces existing frames, return values, or error conditions). This is minimal and leaves the agent guessing about important 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 a single sentence that is front-loaded with the core action ('Create a text frame') and adds a qualifier ('advanced formatting options'). It is concise with no wasted words, though it could be slightly more detailed without becoming bloated.

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 13 parameters and no output schema or annotations, the description is inadequate. It does not explain what happens after creation, how the frame is placed on a page, whether it interacts with the currently active page, or what the response will contain. This level of detail is insufficient for an AI agent to safely invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 92%, with most parameters well-documented (x, y, width, height, content, fontSize, etc.). The description adds only a vague 'advanced formatting options' phrase that does not provide specific syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already 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 uses a specific verb ('Create') and resource ('text frame'), clearly distinguishing it from sibling tools like edit_text_frame, create_rectangle, and create_ellipse. 'Advanced formatting options' hints at richer capabilities without obscuring the 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?

Usage is implied by the name and description - it's for creating a new text frame. However, it does not explicitly state when to choose this over alternatives (e.g., edit_text_frame for modifying, or other create_* tools), nor does it provide exclusions or prerequisites.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It fails to mention side effects (e.g., whether it modifies a document, creates new files), permissions, or the nature of the output. The agent cannot anticipate any consequences of invoking this 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 short (one sentence), which is concise, but it is under-specified. It contains no meaningful content beyond the tool name, so the brevity is not a sign of efficiency but of missing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a data merge tool with 4 parameters, no output schema, and no annotations. The description does not explain the overall operation, the role of dataSourcePath and outputFolder, or whether recordRange and fileFormat affect behavior. It is inadequate for an 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 75%, but the description adds no parameter-level information. For fileFormat, which lacks a description in the schema, the description does not clarify possible values or defaults. The tool description merely repeats the operation name and offers no insight into how parameters interact.

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 essentially a tautology of the tool name 'data_merge' — it restates the operation without specifying what data merge entails or how it differs from sibling tools like populate_table or export_pdf. No specific verb beyond 'perform' or resource beyond 'data merge' is provided, so the agent cannot infer the actual 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 provides no guidance on when to use this tool versus alternatives. There are no mentions of prerequisites, typical scenarios, or exclusions. An agent seeking to decide between data_merge and other tools like populate_table or create_document gets no help.

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 states the delete action but does not warn about irreversibility, impact on document structure or references, or potential error conditions. This is a significant gap for a destructive 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 sentence, nine words long, and delivers the essential function without any unnecessary words. It is highly 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?

The tool is simple with one parameter and no output schema, so a minimal description could suffice. However, important context is missing: the destructive nature of the operation is not disclosed, and whether pageIndex is zero-based is not clarified. This leaves the description adequate but not fully 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%, with pageIndex described as 'Page index to delete'. The description adds no additional parameter semantics, but since the schema already covers it, 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 a specific verb 'delete' with a clear resource 'page from the document', which distinguishes it from sibling tools like add_page, duplicate_page, and navigate_to_page. It unambiguously states 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, nor does it mention prerequisites, exclusions, or related tools. It simply states the function without contextual usage information.

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 must carry the burden of behavioral disclosure. It only says 'edit properties' without mentioning side effects, prerequisites, error behavior, or what happens to the document. 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, front-loaded sentence with no wasted words. It is concise and immediately understood.

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 (7 parameters, mutation, no output schema, no annotations), the description is minimal and incomplete. It lacks prerequisites, side effects, and usage context beyond the basic operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (86%), and the description adds no extra parameter meaning beyond the schema. Baseline of 3 is appropriate since the schema handles the parameter documentation.

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 'Edit properties of an existing text frame' clearly states the verb (edit), resource (text frame), and scope (existing, not create). It distinguishes well from sibling tools like create_text_frame.

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 this tool is for modifying existing text frames, but it does not explicitly state when to use it versus alternatives or provide exclusions. Usage context is present but not elaborated.

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 behavioral traits. It merely states that it executes ExtendScript code but does not warn that arbitrary code can have destructive side effects, access the file system, or require specific permissions. This is a significant omission for a code execution 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, clear sentence with no unnecessary words or repetition. It is appropriately concise 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?

Given the complexity and potential risk of executing arbitrary code, the description is severely incomplete. It does not mention error handling, return values, or that this tool should be used as a last resort when no specialized sibling tool exists. The lack of warnings and context makes this inadequate for safe usage.

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 describes the single 'code' parameter at 100% coverage, so the description adds little beyond that. The tool description essentially restates the parameter purpose without adding new semantic meaning. Baseline of 3 is appropriate given 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 verb 'execute' and the resource 'InDesign' with a specific language (ExtendScript). It distinguishes itself from sibling tools that perform specific operations like export or creation. However, it could be slightly more explicit about being a general-purpose fallback for operations not covered by other 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?

The description provides no guidance on when to use this tool versus the many specific sibling tools (e.g., export_pdf, create_rectangle). It does not mention that it is intended for advanced or custom operations beyond the provided tools, nor does it offer any exclusions or warnings.

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 says the document is exported as EPUB, without mentioning side effects like file creation, overwriting, or whether existing files are replaced. It also doesn't clarify any dependencies or limitations, providing minimal transparency beyond the basic 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 extremely concise, using only four words without wasted verbiage. It is front-loaded with the core action. However, it may be too terse for a tool with four parameters, though the conciseness dimension rewards brevity, so this is still 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?

This export tool has four parameters, no output schema, and no annotations. The description only states the basic export action, omitting essential context such as output file behavior, version selection, or image handling. It is completely inadequate for an agent to invoke the tool correctly without additional inference.

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 documents filePath and includeImages, but version and imageFormat are only defined by enums/defaults with no descriptions. The description adds no parameter information whatsoever, failing to compensate for the 50% schema coverage gap. The agent lacks guidance on choosing EPUB2 vs EPUB3 or image formats.

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 action (export) and the target format (EPUB), distinguishing it from sibling tools like export_pdf and export_images. However, it doesn't elaborate on the scope or specifics, so it lacks some differentiation beyond the format name.

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 export_pdf or package_document. There is no mention of prerequisites, contexts, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the basic action, omitting side effects (e.g., creating image files), file naming, overwrite behavior, or permission requirements. The export action implies file creation, but this is not made explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded, using five words to state the core purpose. However, it is arguably under-specified rather than efficiently concise, so a slightly lower score than 5 is warranted.

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 5 parameters, no output schema, and no annotations, the description is far from complete. It fails to mention required parameters, output behavior, or interaction with document state. The agent would need to infer key details from the schema 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 description coverage is 80% (4 of 5 params described), so the description does not need to compensate heavily. The description adds no parameter details beyond what the schema already 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 'Export pages as images' uses a specific verb (export) and resource (pages) and clearly distinguishes from sibling tools like export_pdf and export_epub by specifying image output. It is concise 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. It does not mention exclusions, prerequisites (e.g., open document), or scenarios where export_pdf or export_epub would be more 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?

With no annotations, the description carries the full burden for behavioral disclosure. It only says 'Export document as PDF' and offers no details on side effects like file overwriting, permissions, or system impact, which is insufficient for a mutation-like 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 redundant wording. It is front-loaded with the primary action, but the brevity borders on under-specification rather than efficient 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 tool with 7 parameters, no annotations, and no output schema, one sentence is inadequate. It fails to explain return behavior, side effects, or any operational context, leaving the agent with insufficient information for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'advanced options' but does not explain any specific parameter. Schema coverage is 71% (5/7 params have descriptions), so the description adds no value beyond the schema, and the remaining parameters (preset, colorProfile) lack meaningful semantic 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 states a clear verb ('Export') and resource ('document as PDF'), making the tool's purpose obvious. It implicitly distinguishes from siblings like export_images and export_epub, though it does not explicitly reference them.

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 like export_images or package_document. The description offers no context about appropriate use cases or prerequisites.

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

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

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 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?

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 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?

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?

With no annotations provided, the description has the full burden of disclosing behavioral traits. It only states the high-level action and doesn't mention that packaging copies files to an output folder, includes fonts/linked files, or creates a report, leaving side effects and outputs unclear.

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, front-loaded with the core purpose, and contains no redundant words. It is appropriately concise for the information it conveys.

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 (packaging with multiple options) and the absence of annotations and output schema, the description is too sparse. It fails to explain the packaging concept, what the output looks like, or any caveats, making it 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?

All four parameters have descriptions in the schema, so the description adds no additional semantic value beyond what the schema already provides. Baseline of 3 is appropriate for full 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 states a clear action ('package') and a specific resource ('document') in the context of print production, distinguishing it from export or info tools. However, it doesn't elaborate on what packaging entails, which is a minor gap.

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 'for print production' implies when to use the tool, but there's no explicit comparison to alternatives like preflight_document or export_pdf, nor any exclusions. It provides context but not full guidance.

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 the full burden of behavioral disclosure. It does not state that saving overwrites the existing file, what happens when filePath is provided, or whether any prompts or confirmations occur. The description is too thin to inform the agent about 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?

The description is a single, front-loaded sentence that uses minimal words to convey the core action. Every word earns its place, and there is no fluff.

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 should disclose return behavior and side effects. It only states the action, leaving out important context like overwriting behavior and what the tool returns on success or failure. The parameter behavior is only visible in the schema, not the description.

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% because the only parameter (filePath) has a description. The tool description adds little beyond the schema, so the baseline of 3 applies. The schema already explains that filePath is for saving to a new path.

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 ('save') and names the resource ('current document'), clearly distinguishing it from sibling tools like export_pdf, package_document, and close_document. The purpose is immediately obvious.

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 export_pdf or package_document. There is no mention of prerequisites (e.g., an open document) or scenarios where save is preferred over export.

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

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

No annotations are provided, so the description carries the full burden. 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.