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 explains the classification logic and what triggers each category, which is helpful. However, it does not explicitly state that the tool is read-only or specify prerequisites like a git repository or tsconfig.json, despite the schema mentioning these.

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

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

The description is two sentences, front-loaded with the primary function and immediately followed by the intended use case. No filler words; every clause contributes value.

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

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

With no output schema, the description adequately communicates the possible return values by naming the two classification categories and their meanings. It also covers the main use case. It could be improved by mentioning error cases (e.g., file not under git), but for a simple analysis tool this is fairly complete.

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

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

Schema coverage is 100% (both file_path and project_root have descriptions), so the baseline is 3. The tool description adds no additional meaning beyond the schema; it merely references 'file' and 'HEAD version' without clarifying parameter usage.

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

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

The description clearly states the tool's function: comparing a file against its HEAD version and classifying the change into two specific categories. It lists concrete examples of what constitutes each category, making the tool's purpose unmistakable and distinguishing it from siblings like 'differentiate_type_impact'.

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

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

The description provides a clear usage context: 'Use to answer: is this PR a breaking change or a safe refactor?' This tells the agent when to invoke the tool. However, it does not explicitly mention alternatives or exclusions, which would push it to a 5.

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

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

With no annotations, the description must carry behavior. It explains why cycles matter (unpredictable initialization, tight coupling) but does not disclose output format, side effects, or limitations. The tool is likely read-only, but this is not explicitly stated.

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

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

The description is two sentences: one defining the tool's behavior and one giving a use-case question. It is concise, front-loaded, and contains no filler.

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

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

The tool is simple and the schema is clear, but no output schema exists and the description does not explain what the return value looks like. This leaves an information gap for the agent, though the purpose and prerequisites are covered.

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

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

The input schema already fully describes the single parameter (project_root) with a clear description. The tool description adds no new parameter semantics, so the baseline of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool detects circular import dependencies, with a concrete example (A imports B which imports C which imports A). It distinguishes this from sibling tools like get_dependency_graph by focusing on cycles, not the graph itself.

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

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

The description explicitly says when to use it: 'Use to answer: are there circular dependencies I need to break before refactoring?' It provides context but does not name alternatives or exclusion criteria, 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.

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 does so effectively by explaining the classification criteria: a test is skippable when the changed file contains only TypeScript type declarations or is imported via `import type`. It does not detail side effects or limitations, but for an analytical tool, this is substantial transparency.

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

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

The description is exactly three sentences: the first states the core action, the second explains the skippability criteria, and the third gives a usage example. Every sentence earns its place, with no redundant or filler content. It is front-loaded with the primary purpose.

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

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

Given the tool has only 2 parameters and no output schema, the description covers the essential aspects: what it does, how it decides, and when to use it. It does not explicitly describe the format of the returned test split, but that is implied. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description adds context on how changed_files are processed but does not add new parameter-specific semantics (e.g., format constraints or examples). It does not degrade the understanding, but it does not elevate it beyond the schema.

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

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

The description opens with a specific verb+resource pair: 'Classifies each changed file as type-only or runtime, then splits affected tests.' This clearly states what the tool does and distinguishes it from sibling tools like get_affected_tests by focusing on type-only vs runtime impact. The scope is unambiguous and actionable.

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

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

The description provides an explicit usage prompt: 'Use to answer: which tests can I skip after a type-only refactor?' This gives clear context for when to invoke the tool. However, it does not explicitly name alternatives or say when not to use it (e.g., for runtime changes), so it stops short of a full 5.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only analysis but does not explicitly state that it does not modify the project, nor does it disclose any limitations, prerequisites (like needing a fresh index), or error behavior. The description focuses on purpose and output rather than behavioral traits.

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

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

The description is two sentences, front-loaded with the core function, and adds a concrete use case and output expectation. Every word earns its place with no redundancy.

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

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

The tool has 3 parameters, no output schema, and no annotations. The description explains the output ('step-by-step import path') but does not address edge cases (e.g., no import chain exists) or prerequisites (e.g., project must be indexed via refresh_project). While sufficient for a simple tool, it leaves gaps in operational context.

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

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

Schema description coverage is 100%, with each parameter (test_file, changed_file, project_root) already well-documented. The description adds minimal semantic value, only linking changed_file to 'X' and test_file to 'Y' in the example question. This slightly enriches context but does not go beyond the schema's baseline.

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

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

The description clearly states the tool's function: 'Finds the exact import chain that connects a changed source file to a test file.' It uses a specific verb and resource, and the example question 'why does changing file X cause test Y to be affected?' distinguishes it from sibling tools that list affected tests or show dependency graphs.

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

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

The description provides clear context by explicitly saying 'Use to answer: why does changing file X cause test Y to be affected?' This indicates when to use the tool. However, it does not mention alternatives or exclusions, so it falls short of an explicit when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals the core transformation (removing function/method bodies, preserving JSDoc and declarations with line numbers), which is the essential behavioral trait. It does not mention side effects or return details, but the described behavior is clear and sufficient for basic understanding.

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

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

The description is a single, well-structured sentence that front-loads the purpose ('Generates a token-optimized representation') and efficiently conveys the mechanism. There is zero redundant or filler content, making it highly concise.

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

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

The tool is straightforward, and the description covers its transformation logic and output basis (declarations with line numbers). It does not specify the return format or side effects, but given the strong schema coverage and simple nature, the description is generally complete for an agent to select and invoke the tool.

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

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

The schema covers 100% of parameters with meaningful descriptions (file_path, project_root, include_jsdoc, include_private_members). The tool description itself adds no parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Generates a token-optimized representation'), the target resource ('a source file'), and the transformation method ('stripping function and method bodies, keeping only JSDocs and declarations with line numbers'). This is specific and distinguishes it from sibling tools, which focus on analysis or diffing rather than compact source representation.

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

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

The description implies its usage for generating a leaner view of source files for context-constrained tasks, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or references to sibling tools are provided, so the guidance is only implied.

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

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

With no annotations, the description carries the full transparency burden. It discloses that the tool outputs a command rather than executing it, which is useful. However, it does not explain behavior around edge cases (e.g., no changed files, unsupported runner), return format, or any side effects. The description is minimally transparent.

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

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

The description is a single, front-loaded sentence that wastes no words. It immediately states what the tool does and the key conditions (test runners, changed files). This is an example of effective conciseness.

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

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

Given the tool's moderate complexity, the description is functional but incomplete. It does not specify the output format (e.g., raw string versus JSON) and there is no output schema. It also lacks integration context with sibling tools. The schema covers parameter descriptions, but behavioral and output expectations are underexplained.

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

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

The input schema already provides descriptions for all three parameters (100% coverage). The tool description adds no extra semantic meaning beyond rephrasing the purpose, so it does not exceed the baseline score of 3.

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

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

The description clearly states the tool's purpose: it outputs the optimal test execution command for Jest, Vitest, or Playwright based on changed files. It names specific test runners and the input basis, distinguishing it from sibling tools that analyze test impact rather than generate commands.

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

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

The description implies usage: you provide changed files and get a command. However, it does not explicitly state when to use this tool versus alternatives like get_affected_tests, nor does it mention any prerequisites or exclusions. This is adequate but lacks clear guidance on tool selection.

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

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

With no annotations, the description carries the burden of disclosing behavior. It reveals the transitive dependency traversal through the import graph, which is a meaningful behavioral trait beyond simple reading. It lacks details on output format or error handling, but for a read-only analysis tool this is sufficient.

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

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

Two sentences, front-loaded with the core purpose, followed by a practical usage question. No wasted words.

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

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

The description covers the purpose, usage, and computation method. It does not specify the return format (e.g., array of paths), but no output schema is present and the tool is relatively simple. The absence of edge-case documentation (e.g., empty input) is a minor gap.

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

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

All three parameters have descriptions in the schema (100% coverage). The description conceptually maps to 'changed source files' but adds no additional syntax or format beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('returns'), a resource ('test files'), and the mechanism (directly or transitively through the import graph). It clearly distinguishes from siblings like get_affected_tests_by_branch by specifying input as a list of changed source files.

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

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

The description explicitly frames the use case with 'Use to answer: which tests should I run after this code change?' and defines the required input condition. It does not mention alternatives or exclusions, but provides clear contextual guidance.

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

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

With no annotations, the description carries full burden of behavioral disclosure. It reveals the internal git diff mechanism and that it returns affected test files, providing meaningful context beyond the name. However, it doesn't disclose potential errors, performance characteristics, or side effects, though as a read-only operation 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.

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

The description is two sentences, with the first stating the core operation and the second providing usage guidance. Every word earns its place, and it is immediately clear and front-loaded.

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

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

The tool is simple with two parameters and no output schema. The description explains the internal command, the return type ('affected test files'), and when to use it versus the sibling. It could mention the output format (e.g., list of paths) or error handling, but for a read-only diff tool, it is sufficiently complete.

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

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

Schema coverage is 100% with both base_branch and project_root described in the schema. The description adds no further parameter-specific semantics, only referencing the diff operation. Baseline 3 is appropriate because the schema already documents the parameters adequately.

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

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

The description clearly states the tool runs `git diff --name-only <base_branch>...HEAD` and returns affected test files, using a specific verb and resource. It also explicitly distinguishes itself from the sibling tool get_affected_tests, making the purpose unmistakable.

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

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

The description explicitly says 'Use instead of get_affected_tests when you want the server to handle the git diff automatically,' providing a direct alternative and condition for use. This offers clear guidance on when to select this tool over its sibling.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the underlying methodology (import-graph reachability from test files), which is a meaningful behavioral trait beyond the tool name. It implies a read-only analysis, though it doesn't discuss edge cases like dynamic imports, but that's acceptable for this simple tool.

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

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

The description is exactly two sentences, with the core behavior in the first sentence and a usage prompt in the second. There is no wasted wording, and the information is front-loaded.

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

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

Given the tool's moderate complexity, the description sufficiently explains what it does and when to use it. All parameters are documented in the schema, so the only missing piece is the return format (e.g., whether it returns file paths, a count, or a structure), since there is no output schema. This is a minor gap and doesn't block correct invocation.

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

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

The input schema already provides 100% description coverage for all three parameters (project_root, limit, source_dirs). The tool description adds no additional parameter-level semantics, so the baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a specific verb ('Finds') and resource ('source files not reachable from any test file through the import graph'), clearly defining its scope as completely untested code. This distinguishes it from sibling tools like get_dependency_graph or identify_unreachable_modules, which target different concepts of unreachability.

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

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

The description explicitly gives a use-case question ('which parts of the codebase have zero test coverage?'), telling the agent when to invoke it. It does not explicitly list exclusions or name alternative tools, but the context is clear enough for selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds useful context by scoping to 'direct' imports (not transitive), but it does not mention error behavior, performance characteristics, or whether any state changes occur (though 'Returns' implies read-only). This is a minimal but not rich disclosure.

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

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

The description is two sentences, front-loads the core action, and immediately provides practical use cases. Every word earns its place, with no fluff or redundancy.

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

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

For a 3-parameter read tool with full schema coverage and no output schema, the description provides enough context: it states what the tool returns and the key questions it answers. It does not describe the exact JSON/mermaid structure, but the two-direction graph return is sufficiently outlined. It could mention edge cases, but overall completeness is good.

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

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

Schema description coverage is 100%, so all three parameters already have descriptions. The tool description adds no extra parameter-level meaning beyond the schema; it only refers to 'a specific file' which is already captured in file_path. Thus the baseline of 3 applies.

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

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

The description names a specific verb ('Returns') and a specific resource ('direct import graph for a specific file'), and clarifies the two directions of the graph ('what it imports, and what imports it'). It clearly distinguishes this from sibling get_symbol_dependency_graph by emphasizing 'import graph' and 'direct'.

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

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

The description provides explicit use cases ('what depends on this file? What does this file depend on?'), giving the agent clear context for when to invoke this tool. However, it does not mention any alternatives or exclusions, such as when to prefer get_symbol_dependency_graph, so it lacks explicit when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the use of --find-renames and --ignore-all-space, which explains behavior beyond the name. However, it does not mention whether the operation is read-only or any side effects, which would be useful given the lack of annotations.

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

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

The description is three sentences: a comparison, a technical detail sentence, and a usage directive. Every sentence adds value, and the most important information is front-loaded. No fluff or redundancy.

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

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

The tool has no output schema and no annotations, so the description should ideally clarify what the tool returns. It implies the return matches get_affected_tests_by_branch ('Like...'), which supports inference, but does not explicitly state the output. The core functionality and usage context are well covered, making this only a minor gap.

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

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

The schema already has 100% coverage for all parameters, so the baseline is 3. The description adds no extra parameter-specific meaning beyond what the schema provides; the similarity_threshold is already well-documented in the schema.

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

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

The description clearly states the tool computes affected tests while handling renamed and moved files, distinguishing it from the sibling get_affected_tests_by_branch. It names the exact comparison and the specific behavior that sets it apart (rename/move handling).

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

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

Explicitly says 'Use instead of get_affected_tests_by_branch when the branch contains refactors or file moves,' providing clear when-to-use guidance and naming the alternative tool. This directly answers the selection problem.

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

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

Annotations are absent, so the description carries the burden. It adds useful behavioral context by mentioning 'bidirectional or directed' and 'mapped to individual declarations, functions, and variables,' but it does not disclose return format, edge-case behavior, or whether the operation is read-only.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the action, resource, and scope.

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

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

The tool lacks an output schema and annotations, so the description must compensate. It covers the core purpose and direction parameter, but does not specify the return structure, how to interpret the graph, or potential limitations. For a simple retrieval tool, this is adequate but with clear gaps.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by specifying the graph's granularity ('individual declarations, functions, and variables'), which complements the symbol_name parameter's semantics. However, it does not add new meaning beyond the schema for other parameters.

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

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

The description uses a specific verb 'Retrieves' and resource 'dependency graph' with a clear scope modifier 'mapped to individual declarations, functions, and variables.' This clearly distinguishes it from the sibling tool get_dependency_graph, which likely operates at a different granularity.

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

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

No guidance is provided on when to use this tool versus get_dependency_graph or other sibling tools. There is no mention of appropriate contexts, prerequisites, or exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly implies a read-only operation ('Returns') and outlines the scope of the output, but it does not mention potential performance implications, whether tests are executed, or any side effects on the project. It provides adequate but not rich behavioral context.

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

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

The description is two sentences long, with the first sentence stating what the tool returns and the second providing a direct use case. It is front-loaded with the most important information and contains no redundant or fluff wording.

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

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

For a tool with one well-specified parameter, no output schema, and no annotations, the description is reasonably complete. It conveys the purpose, key output items, and a representative question it answers. It could be improved by noting the output format or any limitations, but given the simplicity of the tool, it is adequate.

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

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

Schema description coverage is 100% as the single parameter project_root has a clear description ('Absolute path to the TypeScript project root (must contain tsconfig.json)'). The description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description explicitly states 'Returns a bird's-eye view of the project's test structure' and then specifies the exact outputs (coverage rate, most-imported source files, tests with deepest import chains). The use case is clearly framed by 'Use to answer: what is the overall test health of this project?', which differentiates it from the more granular sibling tools like get_affected_tests or get_coverage_gaps.

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

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

Provides a clear context for when to use it ('Use to answer: what is the overall test health of this project?'), but does not explicitly state when not to use it or name alternative tools. Since the sibling tools are more specialized, some implicit differentiation exists, but the absence of explicit exclusions keeps it from a 5.

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

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

No annotations are provided, so the description carries the responsibility. It discloses a key behavioral trait: automatically excludes known entry points (index.ts, main.ts, pages/, etc.), affecting results. It also qualifies findings as 'candidates' rather than guarantees, adding nuance.

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

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

The description is two concise sentences: the first states the purpose and key behavior, the second gives a direct usage question. Every word earns its place, with no filler or redundancy.

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

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

For a read-only analysis tool with three parameters and no output schema, the description covers the core context: purpose, auto-exclusion behavior, and an example query. It does not explicitly describe the return format, but that is not critical given the straightforward list-like output implied.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions entry point exclusions but does not add detail beyond what the schema already provides for parameters like limit, entry_points, and project_root.

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

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

The description clearly states the tool 'Finds source files that are never imported by any other file' with a specific verb (Finds) and resource (unreachable modules), distinguishing it from sibling tools like get_dependency_graph. It also frames the purpose as identifying 'dead code candidates safe to delete'.

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

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

The description provides clear usage context with 'Use to answer: which files in this codebase are orphaned and can be safely removed?' It does not explicitly mention when not to use or alternatives, but the intended use case is well-defined.

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

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

With no annotations provided, the description carries the full burden. It discloses the primary side effect (clearing the cached AST) and the consequence (full re-parse on next call). However, it does not mention whether this operation is reversible, requires special permissions, or returns any confirmation/error. It also leaves unclear whether the cache is in-memory or on disk. Adequate but with gaps.

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

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

Two sentences, front-loaded with the main action and then the usage context. Every word earns its place. No redundancy or filler.

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

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

The tool is simple (one parameter, no output schema). The description covers the purpose and when to use it. It doesn't describe return values, but for a cache-clear operation it's reasonable to expect no meaningful return. Could be more complete with error conditions or behavior on invalid project roots, but the schema already constrains the parameter. Overall quite complete for a straightforward refresh tool.

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

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

Schema coverage is 100% for the single parameter, and the schema already describes project_root as 'Absolute path to the TypeScript project root (must contain tsconfig.json)'. The description adds no new parameter-specific meaning beyond what the schema provides. Baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the action: 'Clears the cached AST for a project root, forcing a full re-parse on the next call.' It specifies the verb ('clears'), the resource ('cached AST for a project root'), and the effect ('forcing a full re-parse'). This distinguishes it from the sibling analysis tools, which focus on inspecting or computing rather than mutating cache state.

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

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

The description explicitly provides when-to-use guidance: 'Use after switching branches, running git pull, or adding/removing files.' This gives clear operational context. It does not explicitly call out alternatives or when not to use, but the sibling tool names and the state-changing nature imply this is a maintenance/refresh tool rather than an analysis tool.

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