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

No annotations provided, so description carries full burden. Discloses recursive behavior, depth constraint (default 3, max 6), and transitive nature. However, does not explicitly confirm read-only status, performance implications, or side effects, which would be expected for a recursive 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?

Three sentences, front-loaded with purpose, then behavioral detail, then use cases. No redundant phrases; every sentence adds value.

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

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

No output schema exists, so description should clarify what the tool returns. It mentions 'call hierarchy' and 'full chains' but not format (tree, list?). Otherwise complete for selection: depth limit, relationship to sibling, use cases.

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

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

Schema coverage is 100%, so schema already describes parameters. Description adds context about depth (walk-up, default, max) and purpose (leaf helpers to entry points), but this is marginal beyond 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?

Description clearly states the tool generates a recursive depth-N call hierarchy for a function, distinguishing it from the sibling find_usages (flat one-level refs). Specific verb 'shows' and resource 'call hierarchy' with transitive property.

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?

States specific use cases (debugging, refactor impact, verifying reachability) and explicitly complements find_usages. Lacks explicit when-not-to-use or alternatives beyond the one mentioned.

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

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

With no annotations provided, the description carries the full burden. It lists the types of checks but does not disclose whether the tool is read-only, its potential impact, or any prerequisites like permissions, leaving some behavioral ambiguity.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value without unnecessary detail.

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 performs project-wide audits with no output schema, the description does not specify the return format (e.g., file paths, line numbers, severity) which would help the AI interpret results.

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

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

The schema already provides detailed descriptions and enum values for all 5 parameters, so the description adds minimal additional meaning. The examples of 'bare except:' and 'print() calls' are also covered 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 finds code quality issues like TODO/FIXME comments, deprecated symbols, and structural patterns, which distinguishes it from sibling tools like find_usages or outline that serve different purposes.

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 recommends 'Use for project-wide audits,' providing clear context. However, it does not explicitly state when not to use it or mention alternatives among the extensive sibling list.

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

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

The description discloses the tool's behavior: it performs a one-shot operation returning a compact block with ranked symbols, source heads, graph neighbours, and test files. It implies no destructive side effects, but could explicitly state it's read-only. With no annotations, this is good but not perfect.

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

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

Two sentences with no waste: first sentence defines the output, second sentence provides usage context. Front-loaded with the core 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?

The description lists return items (ranked symbols, source heads, graph neighbours, test files) and parameter behavior. It doesn't detail pagination or limits, but as a one-shot tool it's sufficiently complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that query is split into terms by the binary, and graph controls including neighbours. This goes beyond the schema's property descriptions.

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: one-shot exploration returning ranked context and call/inheritance graph blast-radius. It distinguishes from sibling tools by explicitly offering an alternative to chaining find_usages, read_symbol, and call_tree.

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 tells when to use this tool instead of separate calls, stating it's cheaper and faster for understanding an area. This provides clear 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?

The description discloses key behavioral traits: it performs exploration (non-destructive), returns multiple sections, and warns that 'imports' and 'tests' can be 'heavy on large areas'. While it doesn't explicitly state read-only, the context implies it. No annotation contradiction exists.

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 concise (5 sentences), front-loaded with the core purpose, and each sentence adds unique value. No wasted words; structure efficiently conveys purpose, usage, and behavior.

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

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

Given no output schema, the description explains what sections are returned. It covers default behavior, optional inclusions, and performance considerations. A minor gap is the lack of return format details (e.g., JSON structure), but overall it is complete enough for a tool with two simple parameters.

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?

Input schema already describes parameters (path, include) with 100% coverage. The description adds value by explaining the default of include (['outline','changes']) and the rationale behind it, plus more detail on what each section entails. This goes beyond the schema's basic enum listing.

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: 'One-call exploration of a directory' and lists specific outputs (outline, imports, tests, changes). It distinguishes itself from sibling tools by suggesting 'Use INSTEAD OF separate outline + related_files + git log calls', making the unique value proposition explicit.

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 usage guidance: when to use this tool (instead of separate calls), when to opt into optional sections, and even references telemetry data explaining the default behavior change. This helps the agent make informed decisions about using the tool versus alternatives.

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

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

No annotations are provided, so the description must cover behavioral traits. It indicates a project-wide search but does not mention read-only nature, performance implications, or return format. Adequate for a simple find operation.

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

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

Two sentences with no filler. Front-loaded with the action and target. Every word serves a 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 no output schema, the description could mention the return format (e.g., symbols with locations). However, for a straightforward find tool, it provides sufficient context for an agent to understand its use.

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

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

The schema covers all three parameters with descriptions (100% coverage). The description adds context about what is being found but does not elaborate on parameter specifics beyond what the schema provides.

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: 'Find dead code — functions, classes, and variables with no references across the project.' It specifies both the verb and the resource, distinguishing it from siblings like find_usages.

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 includes a usage directive: 'Use for cleanup and refactoring.' It implies when to use but does not explicitly state when not to use or mention alternatives. However, the context of sibling tools provides implicit differentiation.

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

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

Despite no annotations, the description discloses key behavioral traits: semantic grouping, support for scope/kind/limit/lang filters, context_lines for surrounding code, and mode options. It also warns about cost implications for short symbols, aiding agent decision-making.

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?

Extremely concise: two sentences plus a hint. Front-loaded with the most important usage guidance. Every sentence contributes useful information without 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?

Given 7 parameters (1 required) and no output schema, the description covers all parameters sufficiently. It explains the purpose of each optional parameter and provides a usage hint. Could mention return format, but minimal 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining that context_lines 'saves follow-up read_symbol calls' and that list mode is '5-10x smaller for initial discovery.' This adds practical value.

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

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

The description clearly states the tool finds symbol references using semantic search, grouping by definitions, imports, and usages. It explicitly distinguishes itself from Grep, making its purpose specific and unambiguous.

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

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

Provides explicit guidance: 'Use INSTEAD OF Grep for finding symbol references.' Includes a concrete hint about when Grep is preferable (for short/generic symbols), giving clear context for choosing this tool vs alternatives.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It discloses the types of checks performed but does not mention whether the tool is read-only, requires project setup, or has any side effects. Important behavioral traits are missing.

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 concise sentences, no fluff. The first sentence states the action, the second gives purpose. Every word earns its place.

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

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

For a tool with no output schema and no annotations, the description covers the input semantics adequately but omits any description of the return format or structure. Given low complexity (2 params), it is adequate but not fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description lists the check types, which aligns with the enum, but does not add extra meaning about the 'module' parameter (e.g., pattern syntax, root context). No significant enhancement over 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?

Description clearly states the tool analyzes module dependencies, dependents, public API, and unused deps, specifying the verb 'analyze' and the resource. However, it does not explicitly differentiate from sibling tools like find_unused or call_tree, which share similar purposes.

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

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

The second sentence gives a high-level use case ('architecture understanding and dependency cleanup'), but there is no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. This leaves the agent without criteria for selection among related siblings.

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 provided, so description bears full burden. It explains traversal of import graph and output formats (text, json, mermaid, dot). Does not mention error handling or what happens if no path exists, but adequate for most uses.

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?

Three sentences, front-loaded with purpose and usage, no wasted words. Includes example usage in quotes and key format options efficiently.

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

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

Given 7 parameters all described in schema, description covers purpose, output format implications, and typical use cases. Minor gap: no mention of behavior when from==to or no path found, but these are edge cases. Output schema absent but not required.

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 baseline 3. Description adds context like 'all simple paths instead of just shortest' and format output types, but mostly reinforces schema. No significant new information beyond parameter names and types.

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?

Clear verb-resource pairing: 'Show the transitive dependency path(s) between two modules' and distinguishes from sibling tools like call_tree, find_usages, and module_info by focusing on dependency paths through the import graph.

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?

Explicit use cases: 'use to answer how does X depend on Y? trace coupling, or generate a dependency diagram.' Lacks when-not-to-use or alternatives, but the sibling list shows many different tools so context is sufficient.

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 provided, so description carries full burden. It discloses that it returns symbols and supports recursion, but doesn't discuss performance, side effects (likely read-only), or error cases.

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 concise sentences with key information front-loaded. No unnecessary words.

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

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

No output schema exists, and description does not specify the format or structure of the returned symbols. For a tool that returns structured data, this is a significant 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?

Schema covers all three parameters with descriptions (100% coverage). Description adds 'Supports recursive with max_depth' but doesn't provide significant additional meaning beyond what schema already offers.

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: to return all symbols in a directory, and distinguishes it from the alternative of listing and reading each file individually.

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 listing dir + reading each file', providing clear when-to-use guidance. It also mentions recursive support, but doesn't explicitly state when not to use it or list alternatives.

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

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

With no annotations, the description carries the full burden. It lists what the tool shows but does not explicitly state it is read-only, non-destructive, or describe any side effects. The user must infer it's safe, but transparency could be improved.

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: first sentence clearly states purpose and outputs; second sentence provides parameter guidance. No wasted words, front-loaded with key information.

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

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

Given no output schema, the description lists sections but does not describe output format (e.g., summary, JSON). It is sufficient for a one-parameter tool with clear purpose, but could hint at return type for completeness.

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 include parameter is fully described in the schema (100% coverage), providing enum values. The description adds value by giving usage examples ('Use ["stack"] for quick type check'), enhancing semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'START HERE for unfamiliar codebases' and lists specific outputs (project type, architecture, framework detection, quality tools, CI, directory map), distinguishing it from sibling tools like 'explore' or 'code_audit'.

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 guidance: 'START HERE for unfamiliar codebases' and gives examples for include parameter (['stack'], ['quality','ci']). It lacks explicit 'when not to use' or alternatives, but the usage context is clear.

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 provided, but the description fully covers behavior: it shows only changed hunks (read-only), requires a baseline snapshot, and implies no side effects. No contradictions.

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 concise sentences plus a required precondition line. Every sentence serves a purpose: purpose, usage guidance, prerequisite. Front-loaded with the key substitution advice.

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

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

For a simple diff viewing tool with no output schema, the description is complete. It explains input (path, context lines), output (changed hunks), and prerequisites. No missing 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 has 100% coverage for both parameters ('path' and 'context_lines' with descriptions). The description adds little beyond 'shows only changed hunks', which is already implied. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to show changed hunks instead of re-reading the whole file after edits. It uses specific verb 'show' and resource 'changed hunks', distinguishing it from re-reading the entire file.

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 re-reading whole file after edits' and provides a requirement ('call smart_read or read_for_edit BEFORE editing to create baseline snapshot'). This gives clear when-to-use and prerequisites, with implied alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the output is raw/unformatted code, supports batch, and includes optional enrichment flags. It does not mention error handling, rate limits, or idempotency, but for a read-focused tool the description is sufficiently 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 paragraph with a clear front-loaded purpose, followed by concise details on batch usage, comparison with siblings, and optional parameters. Every sentence adds essential information without 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?

Despite lacking an output schema, the description explains the return format (raw code for copy-paste). With 9 parameters and 25 sibling tools, the description provides enough context to differentiate and use the tool correctly for its intended purpose.

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 parameters have schema descriptions (100% coverage). The description adds significant value: explains that the output is meant to be used directly as old_string for the Edit tool, clarifies that 'symbols' enables batch mode (max 10), and distinguishes the purpose of include_callers, include_tests, include_changes as saving separate API calls.

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 is for preparing edits, returning raw code for use as old_string in an Edit tool. It distinguishes itself from generic Read and read_symbols, which are for reading/understanding, providing a specific verb+resource+use case.

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 advises 'Use INSTEAD OF Read when preparing an EDIT.' Contrasts with read_symbols ('Unlike read_symbols (for reading/understanding), this returns unformatted code optimized for copy-paste into Edit'). Also describes batch usage and optional enriched context parameters.

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 full burden. It only states the basic action and a performance hint ('lighter'), but does not disclose read-only nature, error behavior, or other behavioral traits.

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

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

The description is very concise with two short sentences, front-loaded with the main action and use context. No unnecessary words.

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

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

The tool has no output schema, so the description should explain return values or structure, but it does not. It also lacks details on error handling for invalid line ranges, making it incomplete for an agent.

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%, meaning the schema already describes all parameters. The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Read' and the resource 'specific line range from a file'. It provides a use case guidance ('when you know exact lines') but does not explicitly distinguish from sibling tools such as smart_read, read_section, etc.

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 includes a clear usage guideline: 'Use when you know exact lines — lighter than reading the whole file.' This implies when to use, but does not explicitly state when not to use or name alternative tools.

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

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

With no annotations, the description carries the full burden. It discloses the tool is read-only, cheap, and does not read code. It explains case-insensitivity and required heading parameter. Minor omission: no mention of error behavior if section is missing, but overall 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?

The description is concise and front-loaded with the main purpose. Every sentence adds value, including format-specific details, cost hint, and exclusions. No waste 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 description is largely complete given no output schema or annotations. It covers file types, input format, case sensitivity, cost, and provides alternatives. A minor gap is the lack of explicit information about the return format, but the purpose is clear enough.

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% and parameter descriptions in the schema are already very detailed (e.g., explaining heading types). The tool description adds usage context but does not significantly extend parameter semantics beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the tool reads sections from Markdown, YAML, JSON, or CSV files, specifying the extraction method for each format. It also distinguishes from siblings by explicitly naming alternatives (read_range, read_symbol) for 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 provides clear guidance on when to use this tool (for document/data files) and when not to (for source files). It explicitly mentions alternatives and notes that it's cheaper than reading the whole file, aiding decision-making.

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

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

No annotations are provided, so the description must carry the burden. It describes the basic action (read source code) but does not disclose dedup behavior, error handling (e.g., symbol not found), or any side effects. The parameter descriptions in the schema hint at dedup features, but the description itself is silent on behavioral nuances.

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

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

Two short, front-loaded sentences: first sentence states the core action and differentiates from whole-file reads; second sentence adds syntax support. Every word earns its place.

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

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

The description is minimal for a tool with 8 parameters. It does not explain return format, error scenarios, or how the dedup-related parameters (force, session_id) affect behavior. Given the lack of output schema, more context would be helpful.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the 'symbol' parameter supports Class.method syntax, which is not in the schema description. This extra context helps the agent use the parameter correctly.

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?

Description clearly states it reads source code of ONE specific symbol (function/method/class) and explicitly contrasts with reading the whole file. It also mentions support for Class.method syntax, making the tool's 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 'INSTEAD OF reading the whole file', guiding the agent to use this tool for targeted symbol retrieval rather than whole-file reads. It does not, however, mention when to use siblings like 'read_for_edit' or 'read_range', leaving some ambiguity.

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 present, but description covers key behavioral traits: batching behavior (saves round trips), refusal threshold (≥70% symbols) and redirection to smart_read. Does not mention error handling or performance guarantees, but sufficient for a read-only 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?

Three sentences: purpose+benefit, best-fit, alternatives. Front-loaded with core action. Every sentence adds distinct value; no redundancy or fluff.

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

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

No output schema, but tool name and display modes (full/head/tail/outline) imply return structure. Could explicitly mention output format or reference read_symbol for details. Generally complete given sibling context.

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

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

Schema coverage is 100% (all parameters described). Description adds business logic (max 10 symbols, default display mode 'auto') and usage context (example symbol names). Provides incremental value beyond 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?

Clearly states verb (batch read) and resource (multiple symbols from one file). Distinguishes from sibling read_symbol by highlighting efficiency (saves N-1 round trips).

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 specifies best-fit range (3-8 symbols), when to use simpler alternative (1-2 symbols -> read_symbol), when handler refuses (≥70% of file's symbols -> smart_read), and for edit preparation (read_for_edit).

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?

Without annotations, the description carries full behavioral burden. It discloses the tool is read-only (shows graph), what inputs it takes (a file path), and hints at processing (scoring). It does not mention any side effects or performance considerations, but the disclosed behavior is adequate for a read 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 two sentences, front-loaded with the core action, and every piece of information is relevant. No wasted words.

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

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

Given no output schema, the description sufficiently explains what the tool returns: a ranked import graph with relevance scores and categories (HIGH VALUE, MEDIUM, LOW). This is complete for an agent to understand the tool's output.

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 'path', which has a clear description. The tool description adds context ('analyze a file') but does not add new semantic details beyond the schema. 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 purpose: 'Show ranked import graph for a file'. It specifies the verb 'show', the resource 'import graph', and includes details about what is ranked (imports, importers, tests) and the scoring criteria (relevance). This distinguishes it from siblings like 'find_usages' or 'call_tree' which likely provide different views.

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 context: 'to prioritize reading' suggests the tool helps decide what to explore next. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. This is a minor gap.

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

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

No annotations are present, so the description carries full burden. It clearly describes the tool as generating a read-only report with no mention of destructive actions. While it does not explicitly state it is read-only, the nature of analytics and the sibling tools imply safety.

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 efficiently convey the tool's purpose and a key usage option. No wasted words; 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 no output schema, the description adequately explains what the report contains (specific metrics). It does not cover pagination or limits, but for a simple reporting tool with one optional parameter, this is sufficient.

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 a well-described boolean parameter. The description adds the same information as the schema's description, plus a usage suggestion. This provides marginal extra value, meeting the baseline of 3 for high schema coverage.

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

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

The description explicitly states the tool shows a token savings report with specific metrics (calls, tokens saved, per-tool breakdown, top files, cache hits). The verb 'show' and resource 'token savings report' are clear, and it naturally distinguishes from sibling tools focused on other aspects like budgets or snapshots.

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?

Guidance is provided for when to use verbose=true vs false, which helps the agent decide. However, it does not explicitly mention when not to use this tool or suggest alternatives for related tasks (e.g., session_budget, session_snapshot).

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?

The description fully discloses behavior: it is read-only, does not save tokens, and clarifies that burnFraction measures hook activity not context-window occupancy. No annotations exist to contradict this.

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

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

The description is extremely concise with only two sentences and a note, each sentence providing essential information without 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?

Given the tool is simple with one parameter and no output schema, the description fully explains what it reports (suppressed tokens, reference budget, burn fraction, denyThreshold) and clarifies a common misunderstanding, making it 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?

The description adds meaning beyond the schema by explaining that sessionId can be empty to read without filter and that it matches hook-events.jsonl ids, which enriches the schema's parameter description.

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 is a diagnostic that reports read-hook pressure for a session, distinguishing it from other tools by labeling it as 'META / info-only' and specifying it does not save tokens.

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?

It provides explicit guidance on when to use the tool ('use to decide when to tighten before a big read'), but does not explicitly mention alternatives or 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.

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

With no annotations, description carries full burden. It discloses output as a compact markdown block and clarifies the tool's role as a formatter. However, it doesn't specify whether the snapshot is stored or ephemeral, a minor gap.

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

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

Two sentences, both essential: first defines purpose and constraints, second gives usage guidance and role. 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?

Despite 6 parameters, no output schema, and no annotations, the description covers purpose, format, usage timing, and model-tool division. It is self-contained and sufficient for a formatting tool with clear parameters.

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 all 6 parameters described. The description adds minimal meaning beyond the schema, only implicitly referencing parameters via 'goal, decisions, confirmed, files, blocked, next' in the usage context. Baseline for high coverage is 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?

Description clearly states verb 'Capture', resource 'session state', and specific format 'compact markdown block (<200 tokens)'. It distinguishes from sibling tools like session_analytics and session_budget by focusing on state capture rather than analysis or budgeting.

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 explicit when-to-use instructions: 'Call before compaction, when switching direction, or periodically in long sessions.' Also explains the model-tool division: 'Model provides the facts, tool formats them.' This gives clear context for appropriate use.

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 output behavior for small vs large diffs and mentions AST symbol mapping, but does not explicitly state if the tool is read-only (though inferred).

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 efficient sentences, front-loading the key usage instruction and then detailing output. No superfluous 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 purpose, scope, and size-dependent output. It does not detail the summary format, but this is acceptable given no output schema and parameter descriptions covering the rest.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. The description adds no extra semantic value beyond what the schema already provides for 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 clearly states the tool shows changed files with AST symbol mapping, using specific verbs and resources. It also explicitly distinguishes itself from raw git diff, making its 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 instructs to 'use instead of raw git diff', providing clear context for when to use this tool over a sibling. However, it does not mention when not to use it or alternatives among other siblings.

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?

Discloses token reduction (~39%), borderline performance, and possibility of being dropped. Good behavioral context beyond default expectations, though no mention of read-only nature (no annotations to rely on).

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?

Description is slightly long but well-organized with clear sections (purpose, guidelines, heads-up). Every sentence adds value, though minor redundancy in token reduction mention.

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?

Covers purpose, usage alternatives, behavioral notes, and parameter guidance adequately. No output schema, but description doesn't need to detail return values; however, could mention that return is structured.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining that path and count tighten token savings and specifies count's default (10) and max (50), exceeding schema info.

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?

Clearly states 'Use INSTEAD OF raw git log' and describes structured commit history with category detection, file stats, author breakdown. Distinguishes from raw git log and provides filtering capabilities.

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 compares to raw git log, advises scoping with path and count for token savings, and warns about potential deprecation. Provides clear context for when to use this tool.

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 provided, so description carries full burden. It indicates the tool is a read-only replacement for read/cat, returns structured output, and is token-efficient. It doesn't fully disclose all behavioral traits (e.g., error handling, dedup behavior) but the core behavior is clear.

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 most critical information (purpose and when to use). Every sentence adds value; 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?

For a read tool with 8 parameters and no output schema, the description covers purpose, usage context, token efficiency, and references a related tool. It is sufficient for an agent to understand when and how to invoke it, though it doesn't describe the return format.

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 baseline is 3. The description adds no extra meaning beyond what the schema already provides for each parameter. It does not enrich parameter understanding.

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 it is for code files, returns code structure (classes, functions, methods with signatures and line ranges), and explicitly differentiates from raw read/cat with token savings. It also names read_symbol as a complementary tool.

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

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

Explicitly tells when to use ('Use INSTEAD OF Read/cat for code files') and when to use an alternative ('Use read_symbol() to drill into specific code'). Provides clear context for selection among siblings.

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 provided, so description carries full burden. It discloses batch operation, auto-downgrade on token limit, dedup via session_id and force, and max files. However, it doesn't explicitly state read-only nature or error handling, though the name implies reading.

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

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

One concise sentence with purpose, alternative, and key constraint (max 20). Every word is informative 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?

Covers core functionality, constraints, and parameter behaviors. Lacks explicit note on return structure format and error handling, but sufficient for a batch read tool. References sibling tool for deeper dedup details.

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%, baseline 3. Description adds value beyond schema by explaining auto-downgrade for max_tokens, dedup purpose for session_id, and bypass for force, plus references to smart_read for details.

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?

States 'Batch smart_read for multiple files at once — INSTEAD OF calling Read on each file' with specific verb and resource, and distinguishes from the alternative of calling Read individually, plus mentions max 20 files limit.

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 advises to use this tool instead of calling Read on each file, and includes a maximum file limit, providing clear when-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?

No annotations are provided, so the description must fully disclose behavior. It mentions output reduction (200 to 10-15 lines) but does not warn that executing test commands can have side effects (e.g., modifying state, running arbitrary scripts). This is a significant omission for a tool that runs user-provided commands.

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

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

The description is extremely concise: two sentences that front-load the core purpose and output, followed by a brief list of supported runners. Every word is necessary, and there is 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?

Given the absence of an output schema, the description adequately explains the output content (total/passed/failed/skipped + failure details) and the input reduction. However, it lacks details on output structure (e.g., JSON format) and error handling, which would be helpful for a complete understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds limited value beyond the schema: it lists a subset of supported runners (already in the enum) and implies auto-detection, which is already stated in the schema's runner description. No new parameter semantics are provided.

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 specifies the verb 'run tests' and the resource 'tests', and details the output format (total/passed/failed/skipped + failure details). It distinguishes this tool from sibling tools (no other test runners) and lists supported runners, 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.

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

The description implicitly guides usage by listing supported test runners (vitest, jest, etc.) and mentioning auto-detection when the runner is omitted. However, it does not explicitly state when not to use this tool or provide alternatives, though sibling tools are sufficiently distinct.

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