Server Quality Checklist

Tool Scores

• replace_assetB
  3/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavior. It only states the action and equivalence to relink_asset, without mentioning side effects (e.g., whether the original file is deleted), permissions, reversibility, or return values. This is minimal disclosure 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.

  Conciseness5/5

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

  The description is a single, concise sentence with a parenthetical clarification. It is front-loaded with the verb and resource, and every word adds value without redundancy.

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

  Completeness2/5

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

  For a tool with 4 parameters, no annotations, and no output schema, this description is far too sparse. It omits prerequisites, error behavior, output format, and any operational context. The only extra context is the pointer to relink_asset, which relies on knowing that tool's behavior.

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

  Parameters2/5

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

  Schema description coverage is 50% (name and linkId are described, filePath and timeoutSec are not). The description adds no parameter-specific meaning, only the general notion of 'another file' which loosely maps to filePath but does not clarify the requirements or relationships between parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific action: 'Replace a placed asset with another file', which identifies the verb and resource. However, it does not distinguish itself from siblings; it equates itself to relink_asset ('same as relink_asset'), which is a sibling tool, reducing differentiation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The description gives an explicit alternative by saying 'same as relink_asset', implying the agent can use either tool interchangeably. However, it lacks explicit context for when to prefer this tool over others, and there are no exclusions or prerequisites mentioned.

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

• check_missing_linksB
  3.1/5.0
  Behavior2/5

  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 implies a read-only reporting action but does not mention whether it makes network requests (though the timeoutSec parameter suggests it might), what side effects occur, or what the output format is. This is insufficient for an agent to understand 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler or repetition. It efficiently conveys the core purpose without wasting words.

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

  Completeness2/5

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

  The tool has only one optional parameter and no output schema, so the description must explain the parameter and the expected return value. It does neither, leaving the agent uncertain about how to invoke the tool and interpret results.

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

  Parameters2/5

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

  The schema defines timeoutSec as an optional integer with a range, but the description does not explain what this timeout applies to or how it affects the link-checking process. With zero schema description coverage, the description should compensate for this gap, but it does not.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: reporting missing, inaccessible, or out-of-date links in the active document. This is a specific verb+resource construction that distinguishes the tool from siblings like scan_document or get_document_model, which are broader in scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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 simply states what it does without context about prerequisites, typical use cases, or when another tool would be preferable.

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

• relink_assetB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavioral traits such as mutability, path validation, or reversibility. It only says 'Relink' which implies mutation but does not mention whether the operation is destructive, whether the new path must exist, or what errors may occur. 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.

  Conciseness5/5

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

  The description is a single sentence that states the core purpose without extra words. It is front-loaded and efficient, earning its place as a concise summary. No redundant phrasing or filler.

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

  Completeness2/5

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

  Given the tool has 4 parameters, no annotations, no output schema, and sibling tools with overlapping functionality, this description is too thin. It fails to explain prerequisites, selection of the asset, success/failure behavior, or relationship to replace_asset/embed_asset. A minimal viable description for this complexity should include at least usage context.

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

  Parameters3/5

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

  The schema description coverage is 75%, leaving timeoutSec without a description. The tool description adds zero parameter semantics and doesn't clarify how to select the asset (name vs linkId) or that filePath is required. The schema provides most meaning, but the description's silence on ambiguity between name and linkId prevents a higher score.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Relink') and resource ('a placed asset') with a clear target ('new file path on disk'), making the action unmistakable. It also differentiates from sibling tools like replace_asset and embed_asset by focusing on relinking (path update) rather than replacement or embedding.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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 replace_asset or embed_asset. It lacks context like 'use when a linked asset's file has moved' or 'prefer this over replace_asset when only the path changes.' No exclusions or prerequisites are stated.

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

• create_styleB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It mentions the creation sources (selection item, basedOn, font size spec) but does not disclose behavioral traits such as whether an existing style with the same name is overwritten, whether it mutates the document model, or any side effects. The description adds some input context but not enough 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.

  Conciseness5/5

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

  The description is a single sentence with no filler. It front-loads the core action and captures the primary variants. Zero wasted words.

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

  Completeness2/5

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

  With 6 parameters, a nested spec object, and no output schema, the description is too brief to be complete for correct invocation. It omits crucial details like the meaning of styleKind, the behavior of name, and any prerequisites. The three modes are hinted at but not fully explained, and the required name parameter is absent from the description.

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

  Parameters2/5

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

  Schema description coverage is only 17% (only fromTarget has a description). The description mentions selection item, basedOn, and font size spec, which partially maps to fromTarget, basedOn, and spec. However, it fails to explain the required 'name' parameter, styleKind enum, or timeoutSec. With low schema coverage, the description must compensate, but it does not.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool creates a paragraph, character, or object style, which is a specific verb+resource. It also mentions the three modes of creation (from selection, basedOn, or font size spec), distinguishing it from sibling tools like apply_style and update_style.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The usage context is implied by the verb 'create' - this is for creating new styles, not applying or updating them. However, there is no explicit guidance about when to use this vs. update_style, or any exclusions (e.g., when the style already exists).

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

• update_styleB
  3.3/5.0
  Behavior2/5

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

  No annotations are present, so the description must carry full weight for behavioral disclosure. It lists the types of updates but does not mention potential side effects (e.g., impact on styles based on this style), required permissions, persistence, or return values. 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence that wastes no words. It efficiently communicates the core purpose and the main operations. This is an appropriate size for a tool description, though it sacrifices completeness for brevity.

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

  Completeness2/5

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

  With 7 parameters, nested objects, no annotations, and no output schema, the description is far too sparse to be complete. It does not explain key semantics (e.g., what 'copy from an item' means, how styleKind influences behavior, or what the tool returns). This is inadequate for a tool of this complexity.

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

  Parameters2/5

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

  Schema description coverage is only 14%, and the description only loosely maps to four of seven parameters ('spec', 'basedOn', 'rename' for newName, 'copy from an item' for fromTarget). It omits the required 'style' parameter, styleKind, and timeoutSec, and does not clarify complex nested structures. The description adds some meaning but fails to compensate for the low schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the tool's action ('Update') and resource ('existing style definition'), and lists the specific operations possible: 'spec, basedOn, rename, or copy from an item'. This distinguishes it from sibling tools like create_style (which creates new styles) and apply_style (which applies styles to content).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The use case is implied: it's for modifying existing styles, not creating or applying. However, no explicit when-to-use/when-not-to-use guidance or mention of alternative tools is provided. The word 'existing' gives a hint, but the description does not proactively steer users away from create_style or apply_style.

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

• embed_assetB
  3.4/5.0
  Behavior2/5

  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 reveals the basic effect (unlinking from disk) but omits whether the operation is reversible, whether it modifies the document file, any permission requirements, or side effects on existing links. For a mutating tool, this is insufficient.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes meaning.

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

  Completeness2/5

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

  The tool has three parameters (including timeoutSec) and no output schema. The description does not explain what happens after embedding, error conditions, or the purpose of timeoutSec. Given the mutation potential and lack of annotations, key behavioral context is missing.

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

  Parameters3/5

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

  Schema description coverage is 67% (name and linkId are described). The description adds minimal semantic context beyond the schema, mainly 'linked asset' which aligns with the parameter descriptions but does not clarify timeoutSec or how the parameters relate to the embedding process.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action ('Embed a linked asset') and the key consequence ('unlink from disk'), distinguishing it from siblings like relink_asset or replace_asset. The verb and resource are 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.

  Usage Guidelines3/5

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

  Usage is implied by the phrase 'unlink from disk' — the tool is for making a linked asset part of the document. However, there is no explicit guidance about when to choose this over alternatives like relink_asset or replace_asset, nor any prerequisites or context.

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

• get_selectionB
  3.4/5.0
  Behavior3/5

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

  Without annotations, the description carries the full burden. It discloses the cache-sync side effect, which is useful, but it does not explain implications such as whether the cache is overwritten, failure behaviors, or if an active document is required. It provides some behavioral insight but not comprehensive coverage.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys the main action and side effect without unnecessary detail. Every word earns its place.

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

  Completeness3/5

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

  The description covers the core purpose and return value (stable UUIDs) and mentions the cache side effect, but it lacks parameter explanations and usage guidance. Given the tool has 2 optional parameters and no output schema, this is only partially complete.

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

  Parameters1/5

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

  Schema coverage is 0%, and the description makes no mention of timeoutSec or writeUuids. The agent is left to guess what these parameters control, despite the boolean likely toggling the cache sync. The description does not compensate for the lack of parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb ('Read'), the object ('current InDesign selection'), and the outcome ('stable UUIDs'), while also mentioning the side effect ('sync them into the session cache'). This differentiates it from sibling tools like get_document_model and analyze_page, which have different purposes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The description implies usage when the agent needs stable UUIDs for the current selection, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or trade-offs. The context is clear but not fully explicit.

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

• apply_styleA
  3.7/5.0
  Behavior2/5

  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 says 'Apply' with no mention of side effects, reversibility, permissions, or return behavior. It fails to explain what happens to existing styles or whether the operation is a mutation beyond the implicit meaning.

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

  Conciseness5/5

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

  Two sentences: the first states the action, the second gives selection guidance. The text is front-loaded and every word earns its place, with no unrelated or redundant content.

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

  Completeness2/5

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

  The tool has 4 parameters, a complex target union, no output schema, and no annotations, making this description inadequate. It omits crucial context about parameter formats, return values, and operational behavior, leaving an agent without enough information to invoke the tool correctly.

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

  Parameters2/5

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

  Schema coverage is only 25% (styleKind has a default), and the description adds no details about the 'style' value (must be an existing style name), the 'target' variants (string, uuid, role, or selection), or 'timeoutSec'. It merely echoes the styleKind enum without clarifying semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Apply a paragraph, character, or object style to target item(s)' with a specific verb and resource, distinguishing it from style creation/update/list tools. It also mentions the applicable style kinds, aligning with the styleKind enum.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description explicitly advises 'Prefer execute_batch when combining with other ops,' giving a clear alternative for batch scenarios. This provides conditional guidance for when to use this tool versus a sibling, which is exactly what the dimension looks for.

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

• layout_operationA
  3.7/5.0
  Behavior2/5

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

  With no annotations, the description must disclose behavioral traits, but it only mentions 'thin wrapper' and prerequisites. It does not state that layout operations likely mutate the document, possible side effects, or return behavior. The description lacks crucial behavioral disclosure.

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

  Conciseness5/5

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

  The description is concise at two sentences, front-loaded with the operation list. Both sentences add valuable information without redundancy, and the structure is easy to scan.

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

  Completeness2/5

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

  Given 8 parameters, 5 operations, and no output schema, the description is far from complete. It provides prerequisites but leaves operation semantics, parameter usage, and return values unexplained. This is insufficient for a tool of this complexity.

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

  Parameters2/5

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

  Schema description coverage is only 13%, so the description must compensate for undocumented parameters. It only mentions that role targets need analyze_page, and repeats operation names already in the enum. It fails to explain axis, align, gapPt, startPt, marginPt, timeoutSec, or target variants beyond a single mention.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the tool as a layout helper with specific operations (align, distribute, center, stack, applyMargins), which immediately conveys its purpose. It also differentiates from sibling tools like execute_batch by noting it's a thin wrapper.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description explicitly advises to prefer execute_batch when combining with other operations, and specifies prerequisites: scan_document is required, and role targets need analyze_page. This gives clear when-to-use and when-not-to-use guidance relative to alternatives.

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

• list_assetsA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It does disclose one important behavioral trait: the tool can either read from cache or force a refresh from InDesign, which may affect performance and freshness. However, it does not disclose whether the operation is read-only, potential failure modes when InDesign is unavailable, or output pagination/order. The description adds some context beyond the schema but remains incomplete.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. It begins with the action ('List') and immediately specifies the resource and key output fields, making it easy for an agent to parse quickly.

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

  Completeness4/5

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

  For a simple list tool with three optional parameters and no output schema, the description provides the core purpose, the output fields, and the cache/refresh option. It lacks explicit safety guarantees or error semantics, but given the simplicity and the presence of sibling tools, it is reasonably complete for an agent to invoke it correctly.

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

  Parameters2/5

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

  Schema description coverage is 67%, with timeoutSec lacking a description. The tool description explains 'refresh from InDesign' which partially aligns with the refresh parameter, but the schema already states 'If true, re-read links from InDesign (default: cache)', so the description adds little new meaning. It does not address timeoutSec at all, leaving a gap that the description fails to compensate for.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb+resource combination: 'List placed links/assets' followed by the output fields (path, status, page). This clearly distinguishes it from sibling tools like check_missing_links, relink_asset, or list_styles, which focus on specific asset types or mutations.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The description implies when to use the tool—whenever you need to list placed assets—by stating the output fields and the cache/refresh modes. However, it does not explicitly contrast it with alternatives or mention cases where a sibling tool like check_missing_links would be more appropriate. The guidance is implied but not explicit.

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

• refresh_documentA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description must carry the burden of disclosing behavior. It does mention that the tool invalidates and reloads, which implies a potential loss of cached data. However, it does not elaborate on side effects, return values, or failure modes, leaving gaps in transparency.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and then adds usage guidance. Every word earns its place with no redundancy or fluff.

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

  Completeness2/5

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

  Given that there is no output schema and annotations are absent, the description should explain return behavior and parameter semantics at least at a high level. It does not. The tool has four parameters with vague meanings, and the description only addresses when to use it, not what the parameters do or what the tool returns. This makes the description incomplete for a tool that likely has nuanced behavior.

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

  Parameters2/5

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

  Schema description coverage is only 25%, with only 'pages' described. The description itself does not mention any parameters. The schema provides some minimal info (depth enum, timeoutSec min/max), but the semantics of depth and writeUuids remain unclear. The description fails to compensate for the low schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Invalidate and reload the Document Model from InDesign.' This specifies the action (invalidate/reload), the resource (Document Model), and the source (InDesign), distinguishing it from siblings like get_document_model or scan_document.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description provides explicit usage context: 'Use only after manual edits in InDesign or when the cache may be stale — not before every mutation.' This tells when to use it, when not to use it, and implies alternatives (normal access without refresh).

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

• snapshotA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description must disclose behavior. It reveals a dependency on the session cache and suggests a required prior scan, which is useful. However, it does not specify side effects (e.g., whether capturing modifies state), nor does it describe output formats for list/diff modes, leaving gaps.

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

  Conciseness5/5

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

  Two sentences, front-loaded with purpose and modes, followed by a critical dependency. No redundant words, every sentence contributes new information.

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

  Completeness3/5

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

  The description covers modes and the capture dependency, but lacks a mapping of parameters to modes and does not explain expected return values (no output schema). Given the tool's multi-mode complexity, this is a noticeable gap, though it remains serviceable for a broad understanding.

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

  Parameters3/5

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

  Schema coverage is low (25%), only mode has a description. The description explains mode values and mentions diff requires two snapshots, but it does not clarify the roles of 'label', 'beforeId', or 'afterId' beyond schema type definitions. This adds some context but leaves key parameters under-specified.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool captures or inspects Document Model snapshots, with distinct modes (before, after, list, diff). This is specific and distinctive among sibling tools, which focus on document analysis or editing, not snapshots.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  The description provides a clear prerequisite ('run scan_document first') for capture mode, indicating the workflow context. It doesn't explicitly exclude alternatives, but the snapshot functionality is unique among siblings, so usage is implied.

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

• analyze_pageA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It discloses that the tool classifies items and stores them on the Document Model, and implies a dependency on scan_document. However, it does not detail side effects like overwriting existing roles, reversibility, or the effect of the 'persist' parameter, leaving some transparency gaps.

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

  Conciseness5/5

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

  The description is concise and well-structured. It front-loads the main purpose, includes the list of roles for clarity, and then provides the workflow in a compact arrow sequence. Every sentence adds value without redundancy.

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

  Completeness4/5

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

  For a tool with 2 parameters, no output schema, and no annotations, the description is quite complete. It explains what the tool does, the prerequisite (scan_document), and how it fits into the broader pipeline. It could mention more about error conditions or the persist default, but these are minor gaps.

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

  Parameters3/5

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

  The input schema provides 100% coverage for both parameters (pageIndex and persist), so the baseline is 3. The description does not add extra meaning beyond listing the roles; it only indirectly relates to 'persist' via 'store them on the Document Model.'

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Classify page items into semantic roles' and 'store them on the Document Model.' It uses a specific verb (classify) and resource (page items), and distinguishes itself from siblings by outlining its position in the workflow with scan_document and execute_batch.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  Provides explicit usage guidance: 'Call after scan_document' and shows the typical flow 'scan → analyze_page → execute_batch → summarize_changes.' This clearly identifies when to invoke it, though it doesn't mention explicit alternatives or exclusions.

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

• execute_operationA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must disclose side effects. It does reveal checkpoint behavior (saves .indd copy to _checkpoints/, requires no target) and frames checkpoint as a safety step before risky edits. However, it does not mention the mutating/destructive nature of other operations, potential error cases, or how skipCheckpoint interacts, leaving a significant transparency gap.

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

  Conciseness5/5

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

  Two sentences with no wasted words. The first sentence front-loads the core purpose; the second adds the most important exception and usage rule. Excellent structure.

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

  Completeness2/5

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

  With 22 parameters, very low schema coverage, and no output schema, this description is far too brief to be complete. It covers the wrapper concept and checkpoint details but ignores most operation parameters and returns. A complex operation tool needs more context to be reliably invokable.

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

  Parameters3/5

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

  Schema coverage is only 18%, so the description should compensate. It clarifies that checkpoint requires no target and that tag/keep are checkpoint-specific, providing some value. But it does not explain the x/y/dx/dy, find/replace, fill, style, or target resolution options, leaving most parameter semantics undocumented.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description explicitly labels the tool as a 'thin single-op wrapper around execute_batch' and lists the ten operations it supports. This clearly distinguishes it from the sibling execute_batch tool and specifies its function and scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  Provides explicit guidance: use for single operations, and 'prefer execute_batch when issuing two or more ops.' It also explains the checkpoint rationale and when to use it, offering clear decision context.

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

• layout_assistantA
  4.1/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry transparent behavioral info. It discloses the fix mechanism (execute_batch), notes units are points, and implies diagnose/preview are non-destructive while fix is a mutation. However, it omits side effects (e.g., whether it modifies the document directly, undo behavior, or any requirements like needing an open document) and doesn't describe the output of the diagnose/preview modes, leaving gaps for an agent to infer.

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

  Conciseness5/5

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

  The description is three sentences, each purposeful: the first states the core purpose, the second lists the modes, and the third provides workflow and unit context. It front-loads the most important information and contains no wasted words, achieving high information density in a compact text.

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

  Completeness3/5

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

  For a tool with 8 parameters, no output schema, and no annotations, the description covers the core purpose, modes, and workflow but leaves significant gaps. It doesn't explain what diagnose/preview return (e.g., a list of issues, a plan), what the plan structure looks like, or what the effects of fix are beyond 'execute_batch'. The lack of an output schema makes these omissions more impactful, so while the description is adequate for a common case, it's incomplete for an agent to fully anticipate the tool's behavior.

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

  Parameters4/5

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

  The schema already documents 7 of 8 parameters (88% coverage), so the baseline is 3. The description adds meaningful value by stating 'Units are points' (clarifying marginPt and minGapPt) and by mentioning the relationship between fix and execute_batch, which provides context for the mode parameter. It doesn't describe every parameter, but the additional unit context justifies a 4, slightly above the baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific action ('Diagnose or fix') and a clear resource ('page layout') with concrete problem types ('overlapping/tight text, items outside margins'). It enumerates the three modes, which immediately distinguishes the tool from sibling tools like scan_document (which scans) and analyze_page (analyzes). The explicit mode list and mention of execute_batch clearly differentiate its role.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  It provides explicit sequencing guidance ('Prefer after scan_document (+ analyze_page for title roles)'), which tells the agent when in a workflow it should be invoked. It also clarifies that fix applies via execute_batch, implying a batched operation. However, it doesn't explicitly name alternatives or explain when not to use this tool, so it's not a 5.

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

• ping_indesignA
  4.2/5.0
  Behavior3/5

  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 what is checked (app open, version, active document) but does not describe failure behavior, return values, or whether it is a read-only operation. Some context is added via the timeoutSec parameter mention, but the behavior on unreachable InDesign remains unclear.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the purpose and immediately followed by a usage directive. No redundant or wasted words, making it highly efficient.

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

  Completeness4/5

  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 covers the purpose, what is checked, and when to call it. A minor gap is the lack of return format or failure behavior, but for a health-check tool the description is largely complete.

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

  Parameters3/5

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

  Schema coverage is 100% and the parameter timeoutSec already includes a description saying 'Optional override; prefer INDESIGN_SCRIPT_TIMEOUT_SEC for the adapter'. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool checks if Adobe InDesign is reachable, specifying the exact checks (app open, version, active document). It also distinguishes the tool from siblings by explicitly directing 'Call first in a session before scan_document', making its role unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: 'Call first in a session before scan_document'. This names the exact sibling to be used after and establishes the tool as the initial health check. No exclusions are needed for this type of tool.

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

• summarize_changesA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It explains the diffing action, mentions the default pair selection, and implies a read-only summarization behavior. It does not explicitly state side effects or failure cases, but for a read-only summarizer this is reasonably transparent.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, no redundant wording. Every sentence adds value: one for the operation, one for usage context.

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

  Completeness4/5

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

  Given no output schema, the description should convey the return value; 'agent-readable summary' is somewhat vague but sufficient. It also mentions dependencies and default behavior. Could be improved by specifying what happens when no before/after pair exists, but overall it is complete enough for a simple tool.

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

  Parameters3/5

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

  Schema coverage is 0% and parameters are optional, so the description must compensate. The names beforeId and afterId are self-explanatory and the 'Defaults to...' hint clarifies optional behavior, but it never directly explains how these parameters override the defaults. This is a moderate gap.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource: 'Diff snapshot before vs after into agent-readable summary.' This clearly states what the tool does and distinguishes it from siblings like execute_batch or scan_document by focusing on summarizing differences rather than executing or scanning.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  Explicitly says 'Call after execute_batch (or layout_assistant fix),' providing clear contextual timing. It also notes the default behavior for before/after pairs, but does not mention alternatives or when not to use the tool, so it stops short of a 5.

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

• preview_batchA
  4.3/5.0
  Behavior4/5

  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 explicitly states 'no InDesign writes', making the non-destructive nature clear, and 'against the cached Document Model' indicates it operates on cached data. However, it does not disclose what the dry-run returns or potential side effects beyond writes, so it falls short of a perfect score.

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

  Conciseness5/5

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

  The description is three short sentences, each adding critical information: purpose/safety, dependency, and preference. There is no fluff or repetition; it is perfectly front-loaded with the most important information.

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

  Completeness3/5

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

  The description covers purpose, safety, and sequencing, but with no output schema, it lacks any mention of return values or error behavior. It also doesn't state what happens if called before scan_document. Given the tool's role in a batch workflow, this is a notable gap, though the input parameter is fully documented in the schema.

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

  Parameters3/5

  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 tool description itself does not discuss the 'commands' parameter, but the schema provides detailed semantics for it (e.g., list of ops, examples, geometry notes). No additional parameter meaning is needed from the description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's core purpose: 'Dry-run a batch against the cached Document Model' with an explicit parenthetical '(no InDesign writes)'. This distinguishes it from sibling tools like execute_batch and scan_document by specifying it is a non-mutating preview operation on a cached model.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  Provides explicit usage guidance: 'Call after scan_document' establishes a required precondition, and 'Prefer preview_batch before a large execute_batch' gives a clear recommendation for when to use this tool over its primary alternative. This is specific and actionable.

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

• execute_batchA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses the single undo transaction, automatic on-disk checkpoint, refusal when checkpoint saving fails, and cache update via modelPatch. It also explains the 'no way back' implication of skipCheckpoint. This is rich, non-obvious behavior clearly surfaced.

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

  Conciseness4/5

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

  The description is compact—three sentences—and front-loads the key 'preferred mutation path' concept. It is dense with jargon (ENTIRE_SCRIPT, modelPatch, dispatcher round-trip) which may reduce readability, but every sentence earns its place by adding workflow, alternative guidance, or flow context. It could be more scannable with a brief plain-language opener.

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

  Completeness4/5

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

  For a complex mutation tool with no output schema, the description covers prerequisites, process, safety gate, alternatives, and typical next step (summarize_changes). It does not state what the tool returns or how success/errors are surfaced beyond the checkpoint refusal, which is a notable gap. Because of the rich context provided, it remains highly complete overall.

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

  Parameters4/5

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

  Schema coverage is high (83%), so the baseline is 3, and the schema already documents commands, timeoutSec, checkpointTag, skipCheckpoint, and transactionName well. The description adds workflow context by prescribing 'resolve targets → checkpoint gate' and noting the need for prior scan_document/analyze_page for role targets, which slightly enhances command parameter semantics. It doesn't add detail beyond the schema for other parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly positions execute_batch as the 'Preferred mutation path' and explicitly contrasts it with execute_operation/layout_operation, distinguishing its role as the batch-level tool. It never states the simple phrase 'executes a batch of commands,' but the typical flow and the mention of 'combining ops' make the purpose evident. A direct verb+object statement would push this to 5.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: 'ALWAYS prefer this over execute_operation / layout_operation when combining ops' and provides a concrete typical flow. It also defines a key prerequisite for mutating batches (automatic checkpoint) and warns via skipCheckpoint when rollback is intentionally sacrificed. This is exemplary when-to-use and when-to-be-careful guidance.

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

• get_document_modelA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the transparency burden. It discloses caching behavior, the conditions for triggering a rescan (forceRefresh or cache empty), and implies a potentially expensive rescan. It doesn't cover error conditions or return shape, but for a read-like summary tool the key behaviors are addressed.

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

  Conciseness5/5

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

  A single sentence that front-loads the primary action, then adds the key conditional behavior. Every word earns its place with no redundancy or filler.

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

  Completeness4/5

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

  For a tool with four optional parameters, no output schema, and no annotations, the description provides the essential use-case context: cached summary retrieval with rescan conditions. It doesn't detail the return value, but the name and purpose make that predictable. The combination of schema descriptions and this concise overview is sufficient for correct invocation.

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

  Parameters4/5

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

  Schema coverage is 75%, so baseline is 3. The description adds meaning to forceRefresh and cache-related parameters (maxAgeMs, cache empty), and the phrase 'without rescanning' clarifies the tool's core mechanism. It doesn't explicitly mention timeoutSec or includeItems, but these are already documented well in the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Return a summary') and names the resource ('cached Document Model'), clearly distinguishing it from sibling tools like scan_document or refresh_document. The phrase 'without rescanning InDesign' further sharpens its identity as a cache-reading operation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  It implicitly provides usage context: use when you want a summary without rescanning, unless the cache is empty or forceRefresh is set. It doesn't explicitly name alternatives or state when to avoid, but the 'without rescanning' phrasing contrasts with scan_document, offering usable guidance.

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

• list_stylesA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses that data comes from a cache (with a refresh option) and indicates a dependency on scan_document. However, it does not detail cache miss behavior or potential side effects of refreshing, leaving some gaps.

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

  Conciseness5/5

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

  Two concise sentences with no redundancy. Front-loaded with the core purpose, followed by usage guidance. Every sentence adds value.

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

  Completeness4/5

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

  For a simple listing tool, the description provides essential context: what it returns, when to use, and how to apply styles. It lacks return format details and timeout explanation, but the absence of an output schema and the tool's simplicity keep the score high.

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

  Parameters3/5

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

  Schema coverage is 67%, with descriptions for refresh and styleKind. The description adds meaning to these (cache vs refresh, style kinds) but says nothing about timeoutSec. Baseline 3 applies since the description partially compensates but not fully.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists paragraph, character, and object styles from the Document Model cache or refreshes from InDesign. This specific verb-resource pairing distinguishes it from siblings like apply_style or create_style.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  Explicitly instructs to prefer using after scan_document and names apply_style / execute_batch as alternatives for applying styles. This provides clear when-to-use and alternative guidance.

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

• scan_documentA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool caches the document and writes stable UUID labels, and warns against repeated calls. However, it does not disclose what happens if called multiple times, whether existing labels are overwritten, or the exact cost/impact of the scan. Still, it adds meaningful context beyond the schema.

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

  Conciseness5/5

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

  The description is two sentences with no fluff. It front-loads the core action and follows with essential usage guidance. Every word earns its place, making it both concise and well-structured.

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

  Completeness4/5

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

  For a 4-parameter tool with no output schema, the description covers the core workflow: scan once, cache, then use execute_batch. It introduces the 'session Document Model cache' concept and clarifies the tool's role in the edit workflow. However, it does not explain how to access the cache later (e.g., via get_document_model) or describe return values, leaving minor gaps.

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

  Parameters3/5

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

  The schema description coverage is 75%, so the description does not need to compensate heavily. The description mentions 'write stable mcp:<uuid> labels' which aligns with the writeUuids parameter, but does not provide additional semantic detail for depth, timeoutSec, or captureSnapshot beyond what the schema already offers. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool scans the active InDesign document into the session Document Model cache and writes mcp:<uuid> labels, distinguishing it from siblings like refresh_document and get_document_model. It also specifies the timing ('ONCE per session before planning edits'), making the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  The description explicitly instructs to call it once per session before planning edits, and directs the agent to use execute_batch for subsequent operations rather than repeated scans. This provides clear when-to-use and when-not-to-use guidance with an explicit alternative.

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