Server Quality Checklist

Tool Scores

• ast_get_operation_previewB
  3.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well covered. The description adds the behavioral detail that diffs are retained (i.e., this isn't a live diff computation) and that it can optionally filter by file. No annotation contradiction. Reasonable but not rich behavioral context beyond what annotations give.

  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?

  Single sentence, front-loaded with the core purpose ('Retrieves exact unified diffs'), and efficiently conveys the optional file-filtering behavior. No wasted words. Could arguably add more context but stays tight.

  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 tool has an output schema, so return-value documentation isn't needed. With good annotations (read-only, idempotent) and an output schema, the main gap is explaining the 'prepared operation' lifecycle - how an operation becomes prepared and whether this preview reflects the exact diff that ast_apply_operation will execute. Given the sibling apply tool, a brief flow hint would improve completeness.

  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 50% - the file parameter has a description ('Optional affected file path to retrieve only its diff') but operation_id only has a UUID format with no prose description. The description references the file-filtering capability, reinforcing the file param, but doesn't add meaning to the required operation_id beyond its name. Baseline 3 is appropriate given partial coverage.

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

  Purpose3/5

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

  The description says 'Retrieves exact unified diffs retained for a prepared operation', which is a clear verb+resource statement. However, 'prepared operation' is a domain concept that isn't explained, and it doesn't clearly distinguish from sibling ast_apply_operation (which likely consumes these diffs). The word 'complete' and 'optional one file at a time' add some scope clarity.

  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 this is for inspecting diffs BEFORE applying an operation, given the 'prepared operation' wording and the existence of ast_apply_operation sibling. But there's no explicit statement of when to use this vs ast_apply_operation, and no mention of prerequisites (e.g., must a prepared operation exist first?). The guidance is implied through context rather than stated.

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

• ast_find_referencesA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, which covers the safety and scope profile. The description adds the note that results are 'bounded' (via limit) and that 'declaration impact' is included by default, which is useful context beyond the annotations. It doesn't discuss edge cases like unmounted files or config requirements beyond what params imply, but with strong annotation coverage the bar is lower.

  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?

  A single, dense sentence in the description that packs the verb, resource, filtering scope, bounded nature, and output format. It's front-loaded and every phrase carries meaning. No filler or 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?

  With an output schema present, return-format explanation isn't needed. The tool has 6 parameters but 3 are simple pagination fields (limit, offset) covered clearly by schema descriptions. The description plus the schema's parameter descriptions plus strong annotations create a fairly complete picture. Minor gaps: no guidance on what happens when symbol_path is invalid, and the relationship to rename planning isn't stated—but given the strong supporting structure, this is adequate.

  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 83% (5 of 6 parameters have descriptions in the schema). The description itself adds little beyond schema: it clarifies the return is 'bounded project-relative locations,' which connects to limit/offset params. include_declaration is the only param without a schema description (coverage gap), and the description partially compensates by noting 'including declaration impact by default,' which maps to that param's default of true. This is baseline-adequate with mild value added.

  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 states it 'Finds type-resolved references' and returns 'project-relative locations, including declaration impact by default.' This clearly identifies the verb (find references), the resource (semantic symbols), and the scope (project-relative). It distinguishes from sibling tools like ast_search_symbols (which finds symbols) and ast_get_symbol_source (which gets source), though it doesn't explicitly name alternatives.

  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 for finding references to a symbol, and the symbol_path parameter notes it must be 'returned by an outline or symbol search.' This gives implicit guidance on prerequisite steps. However, there's no explicit when-to-use vs alternatives, nor mention that this is the correct tool for impact analysis/rename planning (ast_rename_symbol exists as a sibling).

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

• ast_get_diagnosticsA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that diagnostics are 'bounded and normalized' and that existing errors are 'preserved as evidence for write-operation delta checks' — useful context beyond annotations. However, it doesn't describe return format details or error behaviors (e.g., what happens if the path is invalid or project_root is malformed), though the output schema exists to cover return shape.

  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?

  Two concise sentences with no filler. The first sentence states the core function and scope, and the second sentence adds a meaningful behavioral context point about evidence preservation for delta checks. Efficient and front-loaded.

  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 the read-only annotations, 100% schema param coverage, and an output schema existing, the description does what's needed: it clarifies the project-vs-file scope and the role diagnostics play in delta checks. There's nothing critical missing for an agent to use this tool effectively, given the structured fields carry most of the burden.

  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 all four parameters are already documented in the schema (limit, offset, file_path, project_root). The description adds the 'project vs single file' semantic for file_path by mentioning 'for a project or one source file,' which adds modest value beyond the schema's 'Optional project-relative or absolute file path.' With full schema coverage, the baseline 3 is appropriate.

  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 it returns bounded normalized TypeScript diagnostics for a project or a single source file, using a specific verb ('returns') and resource ('TypeScript diagnostics'). It distinguishes itself from siblings, which handle file listing, symbol ops, and references — none of which overlap with diagnostics. A point is lost for not naming a sibling diagnostic tool explicitly, but among the listed siblings none is a direct alternative, so the differentiation is inherent.

  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 indicates scope (project vs single file) which implies when to pass file_path vs omit it, but it doesn't explicitly state when to use this tool versus alternatives or provide exclusion conditions. The second sentence about 'evidence for write-operation delta checks' hints at usage context but is vague about specific workflows. No explicit when-not guidance is provided.

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

• ast_get_symbol_sourceA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral detail that it returns only one declaration and the project-relative location, not the full file. With robust annotations, the bar is lower, and the description adds reasonable context about output granularity without contradicting annotations.

  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?

  Single sentence, zero fluff, front-loaded with the core action ('Returns exactly one declaration'). Every word earns its place. The 'not the complete file' qualifier is valuable disambiguation rather than 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?

  Given the tool's low complexity (3 params, all documented), the annotations fully covering safety, and the existence of an output schema, the description is complete for the retrieval use case. It clarifies output granularity (single symbol vs file) which is a meaningful detail. Could note return format but the output schema covers that. Slightly more example context could push it to 5.

  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 all three parameters (project_root, file_path, symbol_path) are already documented in the schema with clear descriptions. The description itself does not add meaning beyond the schema, but per the baseline rule, 3 is appropriate when schema does the heavy lifting. Symbol path format like 'formatDate' or 'UserService.create' is already illustrated 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 is specific: 'Returns exactly one declaration or implementation with its project-relative location, not the complete file.' The verb 'returns' clearly states the action, the resource is a specific symbol declaration/implementation, and it explicitly distinguishes from returning the complete file. This differentiates it from sibling tools like ast_search_symbols (search/broadcast) and ast_find_references (locations), setting a clear scope of single-symbol retrieval.

  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 for retrieving a single symbol's declaration, but does not explicitly state when to prefer this over siblings like ast_search_symbols or ast_get_outline. The 'not the complete file' clause offers some contrast, but there is no explicit when/when-not guidance or named alternatives. Context is clear for a basic retrieve operation but lacks directional guidance.

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

• ast_apply_operationA
  3.9/5.0
  Behavior4/5

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

  Annotations declare destructiveHint=true and idempotentHint=true, which is consistent with the description. The description adds beyond annotations by disclosing that conflicts abort before writes, that it verifies the plan hash and workspace fingerprint, and that retries after success are idempotent. There is a small output schema available. This provides solid behavioral context matching the destructive and idempotent hints.

  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 one tight sentence covering purpose, safety verification, conflict behavior, and idempotency. No wasted words. Could arguably be two sentences for readability, but it's efficient and front-loaded with the core purpose.

  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 destructive write tool with 2 parameters, 100% schema coverage and an output schema, the description covers the key operational concerns: verifying the plan before applying, conflict abort behavior, and idempotent retries. Given the annotations already disclose destructive/idempotent traits and the schema documents parameters, this is reasonably complete. It could mention what the output contains or preconditions like requiring a prepare step to have been executed.

  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% with both parameters described (plan_hash as 'returned by the same prepare operation', operation_id as 'Identifier returned by a prepare operation'). The description reinforces the relationship between the parameters and the prepare step but adds no format or validation details beyond the schema. Baseline of 3 is appropriate since schema does the heavy lifting.

  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 states the verb 'Applies' with a clear resource ('the reviewed plan') and specifies the exact operation: applying a prepared structural operation. It distinguishes from siblings by framing itself as the application step after a prepare step, but it doesn't explicitly name a sibling alternative (like ast_get_operation_preview for previewing), so sibling differentiation is implicit rather than explicit.

  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 gives clear when-to-use context: you apply 'exactly the reviewed plan' after verifying it, implying this should follow a prepare/preview flow (siblings include ast_get_operation_preview). It notes conflicts abort before writes, giving conflict-handling behavior. However, it doesn't explicitly say 'don't use this before reviewing' or name alternatives for when not to use it.

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

• ast_get_outlineA
  3.9/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which already cover the safety profile well. The description adds useful behavioral context: it's body-free by design, and symbol metadata is opt-in to avoid duplicating signature text. This adds value beyond annotations by explaining the trade-off rationale.

  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 tight sentences, zero waste. The first sentence states the core purpose, the second explains the opt-in design decision. Every word earns its place, and the response is front-loaded with the primary function.

  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?

  With an output schema present, the return structure is already documented. Annotations cover safety and idempotency. For a single-file read-only outline tool with good schema/annotation coverage, the description is adequately complete. It might mention error behavior (e.g., unparseable file) but that's a minor gap given the other coverage.

  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 100%, so the schema documents all 3 parameters. The description adds meaningful context: the include_symbols parameter's purpose (opt-in detailed metadata) and the relationship to body-free output, which clarifies the default behavior beyond the 'default: false' schema hint. However, it doesn't elaborate much beyond what the schema conveys.

  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 states 'Returns body-free declaration signatures for one TypeScript/JavaScript file' - a specific verb+resource+scope. It clearly differentiates from siblings like ast_get_symbol_source (which returns source) and ast_search_symbols (search). However, it doesn't explicitly name alternatives, and the distinction from ast_get_symbol_source could be sharper.

  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 notes that 'Detailed symbol metadata is opt-in' and file scope is 'one file', giving some implied usage context. It does not explicitly state when to use this vs ast_get_symbol_source or ast_search_symbols, nor mention prerequisites like needing the file to exist or be parseable. Usage context 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.

• ast_rename_symbolA
  3.9/5.0
  Behavior4/5

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

  The description adds meaningful behavioral context beyond annotations: it explicitly states 'without writing' and 'this tool always prepares,' confirming read-only behavior consistent with readOnlyHint=true. It also discloses the workflow nuance that preview review and operation_id application are required, and mentions the dry_run compatibility field is disabled. No contradictions with annotations.

  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?

  Two sentences, efficient and front-loaded. The description wastes no words and packages meaning about behavior plus the follow-up workflow. Minor gap: could mention the output (operation_id) format, but output schema exists to cover that.

  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 6-parameter tool with an output schema and strong annotations (readOnlyHint=true), the description does reasonable work. It explains the prepare-only workflow and the apply step. However, it doesn't clarify the semantic relationship between file_path/symbol_path (how the path is resolved) or what 'exact hash-bound' means practically, which is non-trivial given the tool's complexity.

  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 50%, covering dry_run, new_name, and allow_new_errors in the schema. The description adds minimal parameter-level meaning beyond the schema - it notes the dry_run field is a 'Compatibility field' and that direct application is disabled. However, critical params like file_path, symbol_path, and project_root lack description coverage and the tool description doesn't clarify their semantics either, leaving ambiguity in how symbol_path and new_name interact.

  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 states it 'Prepares an exact hash-bound rename plan without writing' - a specific verb (prepare) with resource (rename plan). It distinguishes from siblings by mentioning it doesn't write and points to ast_apply_operation for application, though the sibling differentiation is implicit rather than explicitly naming competing rename tools. Clear purpose that distinguishes from application tools.

  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 clear usage context: 'Review the preview and apply its operation_id with ast_apply_operation.' This instructs when/how to use the tool and points to the appropriate next tool. However, it doesn't explicitly say when NOT to use this versus alternatives like ast_replace_symbol_body or when to prefer this tool over others in the sibling set.

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

• ast_search_symbolsA
  4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well covered. The description adds that it searches 'structurally' and returns 'exact file/symbol selectors' usable by sibling tools, which is useful behavioral context beyond the annotations. It doesn't describe output format specifics, but since an output schema exists, that's acceptable.

  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?

  One clear sentence covering both what it does and the key value proposition (returns selectors consumable by other AST tools). No wasted words, front-loaded with the verb and resource.

  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 read-only search tool with 100% schema coverage, output schema present, and clear annotations, the description is sufficient. It positions the tool's output as inputs to sibling AST tools, which is the key integration context. No missing critical information for agent invocation.

  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 schema documents all 6 parameters thoroughly on its own. The description adds the framing that returned selectors can feed other AST tools, but doesn't need to duplicate parameter details. Baseline 3 is appropriate since schema does the heavy lifting and description adds marginal integration context.

  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 has a specific verb+resource ('searches declarations') with a clear scope ('structurally') and states the output purpose (selectors for other AST tools). This distinguishes it from siblings like ast_list_files (file listing) and ast_get_outline (hierarchy), plus the output framing differentiates it from ast_find_references.

  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: it's the entry-point search tool producing selectors for downstream AST tools. It doesn't explicitly name alternatives or state when not to use it, but the reference to 'the other AST tools' and the structural search framing gives reasonable context for when this is appropriate.

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

• ast_replace_symbol_bodyA
  4.1/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, and the description aligns: the dry_run parameter clarifies 'Direct application is disabled; this tool always prepares.' This is a valuable behavioral disclosure. It adds that the tool produces a 'hash-bound' result and that changes go through a plan/prepare step, which goes beyond the annotation baseline.

  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 action, zero filler. The supported-types list is useful and concise. Every clause earns its place.

  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 there's an output schema, return-value explanation isn't needed. The tool's relationship to ast_apply_operation is implied but not spelled out — for a prepare-only operation, clarifying that the prepared plan must subsequently be applied would strengthen completeness. Otherwise, the description covers purpose, supported symbols, and the prepare-only nature well.

  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 description coverage is only 50%, so the description should compensate. It notably adds that new_body is 'without the enclosing braces' — a critical format detail. The dry_run/compatibility semantics are also clarified. However, symbol_path format and project_root semantics aren't explained in the description, leaving those to schema.

  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 states a specific verb+resource ('prepares a hash-bound body replacement') and clarifies scope ('preserving the signature'). It lists supported symbol types (declarations, methods, accessors, function-valued variables/properties). However, it doesn't explicitly distinguish from siblings like ast_rename_symbol or ast_get_operation_preview beyond the general subject matter.

  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 implies when to use this tool (when you need a body swap while keeping the signature) and lists what it supports, which gives context. However, it doesn't explicitly state when NOT to use it or name alternative tools like ast_get_operation_preview/ast_apply_operation as the pipeline for applying changes, which would clarify the workflow relationship.

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

• ast_list_filesA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is fully covered. The description adds meaningful behavioral context: results are deterministic (stable ordering), project-relative (path format), and paginated (offset/limit support). This adds value beyond the annotations without contradicting them.

  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, dense sentence that packs all essential information: what it lists, scope (tsconfig-included), qualities (deterministic, paginated), and format (project-relative). Zero wasted words, all meaning-bearing.

  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 has an output schema and 100% parameter coverage, so the description needn't elaborate on return format. For a fairly simple file-listing tool, the description suffices. It could note whether the result includes hidden/JSON/config files or how glob_filter interacts with pagination, but for the complexity level, it's complete enough.

  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% — all 4 parameters (limit, offset, glob_filter, project_root) have descriptions in the schema itself. The description mentions 'paginated' which aligns with limit/offset and 'project-relative' which aligns with glob_filter, but doesn't add meaning beyond what the schema already documents. 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 uses a specific verb (lists) with a clear resource (source files included by project's tsconfig) and adds distinctive modifiers: deterministic, project-relative, paginated. It clearly distinguishes from siblings like ast_search_symbols and ast_get_outline which operate on symbols and outlines respectively, whereas this lists raw files.

  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 implies this is the entry-point tool for traversing the project's file set, distinct from sibling tools that operate on symbols/outlines/source. However, it doesn't explicitly state when NOT to use it or name specific alternative tools. The 'deterministic, project-relative, paginated' framing gives clear context, but no explicit exclusions or alternatives beyond what's implicit.

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