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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's job is to add context beyond safety. It provides a specific rule list and the AST-precision claim, which is a meaningful behavioral trait. No contradiction with annotations.

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

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

Two efficient sentences with zero fluff. The action is front-loaded, the rule list is compact, and the precision advantage is stated in a short addendum. 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 adequately explains what the tool does but omits any mention of output format or return behavior. Given there is no output schema, a brief note about the type of findings returned would be helpful, though the single-parameter schema and clear purpose make it minimally 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 input schema has 100% description coverage for the single 'path' parameter, which is fully documented. The description adds nothing about the parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the verb (run), the resource (all built-in tree-sitter anti-pattern rules), and lists concrete examples (empty catch, await-in-loop, etc.). The phrase 'AST-precise — no regex false positives' differentiates it from regex-based scanners, distinguishing it from siblings such as semgrep_scan or secret_scan.

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 makes the tool's purpose obvious but does not explicitly state when to use it versus alternatives, nor does it name any sibling tools or exclusion conditions. An agent can infer usage from the rule list, but the guidance is implied rather than explicit.

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 already declare read-only, idempotent, and non-destructive behavior, which covers the safety profile. The description adds valuable behavioral context about how matching works (against real syntax trees, avoiding matches in strings/comments) and the syntax for variables, which goes beyond the 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?

Three efficient sentences: definition, behavioral advantage, and syntax example. Zero fluff, critical information is front-loaded, and the example is illustrative without being verbose.

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

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

For a read-only search tool with annotations covering safety, the description adequately explains the matching semantics and pattern syntax. It does not specify the return format or mention installation prerequisites, but these are minor gaps given the tool's simplicity and the presence of annotations.

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

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

Schema description coverage is 67% (only 'pattern' has a description). The main description adds explanation for the pattern parameter (the $VAR/$$$ syntax) and provides an example, which enriches understanding beyond the schema. Path and lang are not elaborated, but the pattern syntax is the most nuanced parameter.

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

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

Description clearly states it is a structural search on ASTs via ast-grep, explicitly distinguishing from text search ('not text'). The example pattern and explanation of matching against syntax trees make the tool's purpose and scope 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 gives clear context that this is for structural matching, implying use for AST-aware searches rather than text. However, it does not explicitly name alternative tools (e.g., 'search') or state when not to use it, so it falls short of providing explicit 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?

The description provides useful behavioral context beyond annotations: it runs 'every scanner, every engine,' produces 'scored and correlated' results, and includes 'trend versus last run' implying stateful comparisons. However, it does not disclose the destructive nature indicated by annotations (destructiveHint: true) nor any side effects, prerequisites, or performance implications. The description adds some value but does not fully contextualize the operation's impact.

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 at two sentences, front-loading the core purpose and enumerating the scope efficiently. The list of scanners is dense but effective, and the final sentence reinforces the tool's role as the definitive audit. No wasted words, though it could be slightly more compact by trimming redundant emphasis.

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 complex tool with no output schema, the description adequately communicates the breadth of coverage but omits crucial details: what 'trend versus last run' entails (e.g., previous run required), the nature of the destructive hint, and the expected output format. The description covers the 'what' but not the 'how' of results or side effects, leaving gaps for an agent to infer.

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 single parameter 'path' is fully documented in the schema ('Absolute path to the repository root'), achieving 100% schema coverage. The description adds no additional semantic meaning about the parameter, so the baseline score of 3 is appropriate—the schema handles parameter documentation 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 states a precise, comprehensive purpose: 'Complete end-to-end audit' enumerating specific scanners (Security, AST, secrets, CVEs, IaC, dead code, complexity, test gaps) and explicitly distinguishes itself from siblings by claiming to be 'the single call that tells an agent everything about a codebase.' It clearly differentiates from the many specialized tools in the sibling list.

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 clearly communicates when to use the tool—when a comprehensive, all-encompassing audit is needed—by framing it as the 'single call' that replaces individual scans. However, it does not explicitly mention alternatives or provide exclusionary guidance (e.g., 'use security_scan if you only need security checks'), leaving some inference to the agent.

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

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

Annotations already indicate destructive behavior (destructiveHint=true). The description adds that the tool autonomously iterates until a target score is reached and performs 'safe-fix' actions, which gives some additional behavioral context beyond the annotation. However, it does not detail what constitutes a safe-fix, potential side effects, or whether changes are reversible, so it only partially discloses behavior.

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

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

The description is a single, succinct sentence that front-loads the core concept ('Autonomous self-healing') and clearly outlines the process flow with an arrow sequence. There is zero fluff, and every chunk of the description conveys essential information about the tool's behavior. This is an excellent model of 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?

Despite being a complex, destructive, autonomous tool with three parameters and no output schema, the description provides minimal context. It does not explain what a safe-fix entails, how the score is computed, whether it modifies files in the repository, or what happens if maxIterations is exceeded. For an agent to safely invoke this tool, more operational details are necessary, making the description incomplete.

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 references 'target score' and 'iterate', which loosely map to targetScore and maxIterations parameters. This adds some meaning beyond the schema, where only path has a descriptive comment. However, it does not explicitly explain these parameters, their defaults, or how they interact. With schema coverage at 33%, the description should provide more details but only hints at them.

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

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

The description states a clear purpose: autonomous self-healing through a defined cycle of diagnose, safe-fix, re-score, and iterate. This implies both diagnosis and correction, distinguishing it from sibling tools like full_diagnose which likely focuses on diagnosis alone. However, it could be more explicit about the resource (code repository) and the exact actions taken during fixing.

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

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

The description provides no guidance on when to use this tool versus alternatives like full_diagnose or verify_all. It does not mention conditions, prerequisites, or scenarios where this tool is preferable. An agent is left to infer usage from the name and partial description, which is insufficient.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a performance claim ('Rust-based, roughly 25× faster than ESLint') which is not behavioral but gives context. It does not describe side effects or output, but those are not required given the low-risk nature and existing 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 a single, efficient sentence with no filler. It front-loads the core purpose and adds a relevant performance note. While it omits usage guidance, that is a separate dimension; as a concise statement of intent, it is well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema) and annotations that cover read-only/idempotent behavior, the description is adequate but minimal. It lacks any mention of when to use it or how it relates to sibling check tools, which leaves an agent with incomplete context for tool selection.

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 fully documents the only parameter 'path' as 'Absolute path to the repository root' (100% coverage). The description adds no additional parameter semantics, so it meets the baseline but does not enhance understanding 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 performs 'Biome lint and format check', specifying a concrete verb ('check') and resource (Biome). It also adds a performance comparison to ESLint, but does not explicitly contrast it with sibling tools like 'code_quality' or 'standards_check', which could be confused for similar checks.

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

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

There is no guidance on when to use this tool versus the many sibling tools. The description does not mention prerequisites, exclusions, or alternative tools for different scenarios (e.g., security scanning vs. linting). An agent has to infer its applicability from the name alone.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond these by setting expectations about the output size (~150 tokens) and its nature as a snapshot, which helps the agent anticipate the format. No contradiction with annotations is present.

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, compact sentence that conveys purpose and usage in under 20 words. It is front-loaded with the key phrase 'repo snapshot' and the qualifier 'fast orientation', with no filler or repetition.

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 a single parameter and no output schema, the description is complete enough: it tells the agent what it does, why to use it, and what to expect in terms of output size. The only minor gap is that the exact contents of the snapshot are not specified, but that is acceptable for a simple cheatsheet 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 input schema provides a full description for the 'path' parameter, including its meaning ('Absolute path to the repository root'), so schema coverage is 100%. The tool description does not add anything about the parameter, but the schema already tells the agent everything needed. 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 tool produces a '~150 token repo snapshot' for 'fast orientation', which conveys its purpose as a quick codebase overview. It distinguishes itself by emphasizing speed and orientation in an unfamiliar codebase, though it doesn't explicitly contrast with deep-analysis siblings like full_diagnose or audit_360.

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: 'Fast orientation for an agent entering an unfamiliar codebase' tells the agent exactly when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the full exclusion 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is safe and non-modifying. The description adds the specific focus of the scan, which is useful context beyond annotations. However, it does not describe output format, performance, or any other behavioral aspect beyond the scan scope, so it does not significantly enrich the safety profile already provided.

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 leads with the tool's purpose and promptly lists the concrete checks. Every piece of information earns its place, with no filler or redundancy. The front-loaded action and scope make it immediately graspable.

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 single parameter and no output schema, the description covers the essential purpose and the specific issues it detects. It lacks any mention of the return format or interpretation of results, but since it's a read-only scan and the checks are explicitly listed, an agent can reason about its use. The absence of usage guidance relative to siblings is the primary gap, but the description itself is fairly complete for a straightforward scan 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 only parameter, 'path', is fully described in the schema as 'Absolute path to the repository root' (100% schema description coverage). The description does not add any additional meaning about the parameter, such as constraints or usage nuances. Baseline of 3 is appropriate when the schema already covers the parameter.

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

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

The description clearly identifies the tool as a 'code quality scan' and enumerates the specific checks it performs (empty catch blocks, console.log, @ts-ignore, any types, TODO debt, oversized files). This is a specific verb ('scan') plus resource ('code quality') with distinct scope, and the list of checks differentiates it from siblings like security_scan or type_coverage.

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 the many siblings. With dozens of similar scan tools (biome_check, verify_all, full_diagnose, etc.), the description offers no context about when this one is appropriate, when it is not, or what alternatives exist. It merely states what it does, leaving the agent to infer when to pick 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description correctly avoids repeating those. It adds valuable behavioral context by explaining the classification output and the default behavior when run ids are omitted.

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 concise sentences with no wasted words. The core purpose is front-loaded, followed by the output detail and the default usage hint—all in a logical order.

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 4-parameter tool with no output schema, the description conveys the essential behavior: comparison of metrics, classification of results, and default run selection. It covers the key aspects an agent needs to invoke it correctly, though it doesn't detail response structure or error handling—minor gaps given the tool's simplicity.

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 only 25% (only path has a description), yet the description clarifies the meaning of run ids (toRunId, fromRunId) by explaining their optionality and default behavior, and implicitly defines 'tool' by referencing 'a tool'. This compensates well for the sparse schema 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?

Description clearly states a specific verb (compare) and resource (recorded runs) with the additional detail that it classifies each metric as better, worse, or unchanged. This distinguishes it from sibling tools like list_reports or audit_360.

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 on omitting run ids to default to the two most recent runs, and frames the use case as proving codebase improvement. While it doesn't name alternative tools or exclusions, the purpose is distinct enough that an agent can infer when 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that by explaining the significance of cyclomatic complexity (drives minimum tests required) and cognitive complexity (nesting-weighted readability cost), which helps the agent interpret results. It doesn't contradict 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 two sentences with zero fluff. It leads with the core function, then explains the two metrics succinctly. Every word adds value, and the structure is front-loaded with the main 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?

For a read-only analysis tool with one parameter and no output schema, the description adequately conveys what it measures and the meaning of the metrics. It doesn't specify the exact return format, but 'per-function' implies a structured result. Annotations cover safety, and the tool is simple enough that an agent can call it correctly with the given information.

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

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

The schema provides 100% coverage for the single 'path' parameter with a clear description ('Absolute path to the repository root'). The tool description adds nothing about the parameter, so it doesn't exceed the baseline of 3 for high schema coverage. No enrichment beyond the schema is 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 states that the tool analyzes per-function cyclomatic and cognitive complexity, specifying what each metric means. It has a specific verb (analyzes) and resource (complexity), and it distinguishes itself from generic code quality tools by focusing on these two metrics. However, it doesn't explicitly differentiate from siblings like code_quality or test_coverage, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or alternative tools. With many siblings (code_quality, test_coverage, etc.), an agent has no indication of when complexity analysis is the right choice.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context about the tool's purpose—transparency into the validation layer—which helps the agent understand the intent and expected output. No contradiction with annotations.

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

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

Two sentences with zero fluff. The action is front-loaded ('Show exactly which findings...') and the rationale follows immediately. 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 read-only tool with one parameter and no output schema, the description is fairly complete. It conveys what the tool does and why. However, it does not specify the format or granularity of the output (e.g., how many findings, structured vs. textual), which could leave slight ambiguity for an agent expecting precise output shape.

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 single parameter 'path' is already fully described in the schema (100% coverage). The tool description adds no additional meaning or usage details about the parameter, so the baseline score 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 states a specific verb ('Show') and resource ('which findings were rejected as false positives'), and explains the rationale ('verify ARGUS's own accuracy'). This clearly distinguishes it from sibling tools like verify_all or audit_360, which focus on different aspects of analysis.

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 a use case (verifying the validation layer's accuracy) but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or preconditions. Usage context is implied rather than explicit.

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 already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds value by specifying the return content: severity breakdown and critical vulnerabilities with fixed versions, which is useful behavioral context beyond the schema.

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

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

Two concise sentences, front-loaded with purpose and output details. No filler or redundant phrasing.

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 single-parameter tool with no output schema, the description sufficiently communicates what the agent can expect in return. It doesn't mention potential runtime length or external network dependencies, but these are minor for a read-only scan. Overall, complete enough for correct invocation.

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

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

The only parameter (path) is fully documented in the schema with a clear description ('Absolute path to the repository root'). Schema coverage is 100%, so the description adds no additional parameter guidance, which is the baseline 3 for this dimension.

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 scans for known CVEs in the dependency tree using Trivy, and identifies the key output (severity breakdown and critical vulnerabilities with fixed versions). This distinguishes it from sibling security tools like secret_scan and semgrep_scan.

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 indicates the tool targets dependency tree CVEs via Trivy, but does not explicitly state when to prefer this over overlapping siblings like dependency_risk or security_scan. No exclusions or alternative conditions are given, leaving the decision heuristic to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail beyond annotations by listing exactly what the analysis detects (orphan files, unused exports, etc.) and its coverage of whole modules. This enriches the agent's understanding of scope without contradicting any annotation.

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 detection types, and adds a distinguishing comparative statement. Every word carries meaning with 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?

Given the single-parameter schema, read-only annotations, and no output schema, the description adequately covers the tool's function and scope. It might benefit from mentioning the output format (e.g., list of dead code locations), but this is not critical since the tool is clearly an analysis utility and the annotations cover safety. Overall complete for practical 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?

Schema description coverage is 100% for the single 'path' parameter, which is fully documented as 'Absolute path to the repository root'. The description adds no extra parameter information, so it does not go 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 clearly states the tool's verb (detect) and resource (dead code), enumerates specific detection types (orphan files, unused exports, unused dependencies, unreachable code, commented-out blocks, duplicate files), and explicitly contrasts with per-symbol analysis, distinguishing it from the sibling dead_exports. No ambiguity.

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 for comprehensive dead code detection and notes it catches whole dead modules that per-symbol analysis misses, providing some context for choosing this over alternatives. However, it does not explicitly state when to use this tool vs. dead_exports or other siblings, nor does it give exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by explaining the impact (bundle size, maintenance cost) and clarifies the scope (exports). No contradiction with annotations.

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

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

A single, front-loaded sentence with zero waste. It immediately states the action and result, then adds the rationale, making it efficient and easy to scan.

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) and annotations cover safety. However, the description lacks any mention of limitations or what the output looks like, and it does not differentiate from the similar 'dead_code' sibling, leaving some contextual ambiguity.

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 the single 'path' parameter with 100% coverage. The description adds no additional meaning beyond the schema, so 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?

States a specific verb+resource: 'Find exported symbols not imported anywhere' and explains the consequence (dead code that increases bundle size and maintenance cost). This clearly distinguishes it from the broader 'dead_code' sibling by focusing specifically on exports.

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

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

The description provides no guidance on when to use this tool versus alternatives such as the sibling 'dead_code' or other analysis tools. It implies its purpose but does not mention any selection criteria 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds specifics about what the tool examines (outdated deps, lock file presence, risky patterns), which is additional behavioral context beyond the annotations. However, it does not mention any potential side effects like network calls, authorization requirements, or performance implications—though these are unlikely for a read-only analysis. Overall, it adds modest value over the 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 a single, well-structured sentence that leads with the verb and resource, then enumerates the specific checks. There is no filler or redundancy; every phrase earns its place. The structure is efficient and front-loaded with the core purpose.

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

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

Given the tool has no output schema, the description should indicate what the tool returns or how the results are presented. It only states what it analyses, not what the agent can expect in the response (e.g., a report, a risk score, a list of issues). This is a notable gap for completeness. The tool is simple with one parameter, so it does not need extensive context, but the lack of output clarification prevents a higher score.

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 single parameter 'path' is fully documented in the schema with a clear description ('Absolute path to the repository root'). Schema description coverage is 100%, so the baseline is 3. The tool description adds no additional meaning regarding parameter formatting, constraints, or usage examples, so no credit beyond baseline is warranted.

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 'Analyse' and the resource 'package.json', then lists three specific focus areas (outdated dependencies, missing lock files, known risky patterns). It distinguishes itself from sibling tools like cve_scan and secret_scan by explicitly scoping to dependency risk, so an agent can easily tell them apart.

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

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

The description provides no guidance on when to use this tool over its many siblings such as security_scan, risk_assess, or audit_360. There is no mention of use cases, exclusions, or alternatives. An agent must infer that this tool is dependency-specific, but nothing explicitly says 'use this for package dependency analysis' or contrasts it with broader security scans.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat them. It adds behavioral context by specifying the exact engine list (ast-grep, semgrep, gitleaks, trivy, biome, ripgrep, fd) and that it covers installation guidance for missing ones—details beyond the annotations that help an agent understand the tool's scope.

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

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

A single, tightly worded sentence that front-loads the core purpose (availability check) and then specifies the engine list and installation guidance. No filler, no repetition, and every phrase carries meaning.

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 parameterless, read-only status tool with no output schema, the description fully captures what an agent needs: the exact scope (which engines) and what it will receive (availability plus install steps). There are no missing behavior or input considerations.

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

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

The tool has zero parameters, making schema coverage trivially 100%. The description correctly implies no inputs are needed, and the baseline for zero-param tools is 4. There is no parameter detail to miss; the description aligns with the empty input schema.

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

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

The description states an explicit verb ('which ... are available') and a specific resource (analysis engines on this machine), listing the exact engines covered. It clearly differentiates itself from the numerous scanning tools in the sibling list by focusing on engine availability and installation, not scanning results.

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?

Though it does not explicitly name alternatives or exclusions, the description makes the use case unambiguous: to check installed engines and obtain installation instructions. Given the tool's self-contained nature and zero parameters, an agent can readily infer when to invoke it, even without naming 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?

The description adds behavioral context beyond the readOnlyHint and idempotentHint annotations by explaining the ranking logic and which exports are prioritized. This enhances the agent's understanding of the tool's output and purpose, though it does not disclose details like execution time or edge 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?

The description is two sentences with zero filler. The core purpose is front-loaded, and the ranking detail is appended in a compact, actionable way. Every phrase 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 read-only, single-parameter tool with no output schema, the description fully covers what an agent needs to call it correctly: it specifies the input (repository root), the output behavior (ranked untested exports), and the ranking criteria. Nothing essential is missing.

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

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

The schema fully documents the single 'path' parameter with a clear description ('Absolute path to the repository root'), and the tool description adds no further parameter-specific meaning. With 100% schema coverage, the baseline of 3 is appropriate, as the description does not need to compensate for missing schema information.

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 ('Find'), a precise resource ('every exported symbol with no reference in any test file'), and a distinguishing feature ('ranked by risk'). This clearly differentiates it from siblings like test_coverage, dead_exports, and gap_analysis, which likely address broader or different concerns.

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 when to use the tool: to identify untested exports with priority given to risky categories (async, security-adjacent, API-layer). However, it does not explicitly state when NOT to use it or contrast it with specific alternatives, leaving some inference to the agent.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description need not restate safety. It does add that the tool runs multiple diagnostic categories, which is useful context about its scope. However, it does not disclose potential performance costs, output size, or any side effects beyond what annotations imply, so it only modestly extends the behavioral profile.

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, efficient sentence that lists the tool's components. It is front-loads the key term 'complete codebase diagnosis' and then enumerates specifics. There is no fluff, though it could be slightly more explicit about the action (e.g., 'runs all scanners and analyzes').

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

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

Given the tool's complexity (aggregating many scanners) and absence of an output schema, the description is notably incomplete. It does not mention what the result looks like, whether it produces a report or scores, potential runtime, or any warnings. It also lacks any rationale for when to use this full diagnosis over more targeted tools, leaving the agent without sufficient context for a safe and effective 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 only parameter 'path' is fully described in the schema as 'Absolute path to the repository root', achieving 100% schema description coverage. The tool description adds no additional semantic detail about how the path is used or any constraints, so it does not improve on the schema.

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

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

The description clearly states it performs a complete codebase diagnosis and enumerates specific components: quantum scoring, git hotspots, dead exports, type coverage. This gives a good sense of scope and differentiates it from more targeted siblings. However, 'all scanners' is somewhat generic and the overall purpose could be more explicit about what 'diagnosis' entails.

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

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

There is no guidance on when to use this tool versus alternatives like auto_diagnose or specific scanners. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer when this comprehensive tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scope of analysis (which structural items are checked) but does not disclose additional behavioral traits like how results are presented, whether a missing path causes errors, or performance characteristics. This is adequate but not rich.

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 lists the detection targets without any wasted words. It is appropriately brief and easy to parse.

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

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

For a tool with one parameter and no output schema, the description should explain what the agent receives as a result. It does not mention return format or how to interpret findings. It also lacks usage guidance relative to similar tools. These gaps make it adequate but incomplete for an agent to fully anticipate the tool's behavior.

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

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

Schema coverage is 100% and the single parameter 'path' has a clear description ('Absolute path to the repository root'). The tool description adds nothing about the parameter, so the schema carries the full burden. This meets the baseline but does not exceed it.

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 a specific action ('Structural gap detection') and enumerates the concrete items it checks (CI/CD, linter, TypeScript config, README, test scripts). This distinguishes it from sibling diagnostic tools like security_scan or dead_code, and leaves no ambiguity about its scope.

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

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

The description provides no guidance on when to use this tool versus alternatives such as verify_all, full_diagnose, or auto_diagnose. It does not state when this tool is preferred or when to avoid it, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It goes beyond annotations by disclosing the output structure (arrange/act/assert) and the presence of TODOs for human-only assertions, which gives the agent expectations about what the tool returns. This is valuable context not present in the structured metadata.

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, tightly constructed sentence. It front-loads the verb and resource, then adds the key behavioral detail (arrange/act/assert and TODOs) without any filler. Every phrase contributes meaning, and it is appropriately sized for a tool of this simplicity.

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 compensates by describing the generated scaffold's structure and the TODOs, which is sufficient for an agent to know what to expect. It does not cover error handling or edge cases, but for a read-only, idempotent scaffolding tool this is not critical. The information needed to call it correctly (params and purpose) is complete, so a 4 is justified.

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

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

Schema description coverage is 100%, so each parameter (file, path, exportName) already has a description. The tool description adds little about parameter usage—it does not explain relationships between parameters or provide format examples. It slightly reinforces that exportName is the specific export to test, but that information is already in the schema. Baseline of 3 is appropriate since 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 ('Generate') and identifies a concrete resource ('runnable Vitest scaffold') for a targeted input ('a specific untested export'). It clearly separates from sibling tools like find_untested or test_coverage, but does not explicitly name an alternative or contrast with them, so it stops short of a 5.

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

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

It states the intended context: when you have a specific untested export and want a scaffold. This implies when to use it, but it does not provide explicit negative guidance ('use X instead') or mention any alternatives among the many sibling tools. The phrase 'specific untested export' narrows applicability sufficiently to be useful, but lacks an explicit when-not-to-use clause.

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 already cover read-only, idempotent, and non-destructive behavior. The description adds the time window and risk interpretation but does not describe the return format, limits, or any edge-case behavior. It does not contradict 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 extremely concise—two sentences with the main purpose front-loaded, followed by a brief interpretation and a contextual note. Zero filler, every sentence 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 covers the core functionality but omits the output format (e.g., list of file paths, counts, sorting), which an agent may need to consume the result. Given the tool's simplicity and single documented parameter, it is minimally adequate but not comprehensive.

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 single parameter 'path' is fully documented in the schema with 'Absolute path to the repository root' (100% coverage). The description adds no additional parameter details, which is acceptable given the schema already carries the semantics.

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

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

The description clearly states the tool identifies files changed most frequently in the last 90 days, with an explicit interpretation (high churn = high risk). It specifies the metric, time frame, and resource (files in a repo), distinguishing it from generic analysis siblings.

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 a use case (identify high-churn files) and mentions SonarQube's limitation, but does not explicitly state when to use this tool versus sibling alternatives or when not to use it. No direct exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by specifying what the tool returns (function, references, imports) and its role in verification, which goes beyond the annotations without contradicting them.

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

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

Two sentences deliver both the operational definition and the usage timing. The actionable instruction is front-loaded, and there is no redundant wording 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?

For a read-only verification tool with no output schema, the description is sufficient. It tells the agent what to expect (returns) and when to use it. A more detailed return structure would be nice, but it is not essential given the tool's simplicity and the annotation coverage.

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 all three parameters have descriptive comments (path, file, line) that fully explain their purpose. The description does not add additional meaning beyond the schema, so the baseline score 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 states a specific verb ('ground'), the resource ('a specific finding in real code'), and details the return payload (enclosing function, referencing files, imports). It clearly differentiates this tool from the long sibling list by focusing on verification of a single finding, not analysis or scanning.

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 gives an explicit when-to-use directive: 'Use this BEFORE acting on any finding to confirm it is real.' This is strong guidance, though it does not explicitly name alternatives or conditions when not to use it. Still, the instruction is clear and actionable.

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 already declare readOnlyHint=true and destructiveHint=false; the description adds context about the scanning scope and Trivy but does not disclose additional behavioral traits beyond what annotations convey. It is consistent with annotations, showing no contradiction.

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 no waste: the first front-loads the core purpose and technology, the second lists concrete examples. Every element earns its place 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?

For a tool with a single parameter and strong annotations, the description adequately conveys what it scans and where to point it. However, it does not describe the output format or any operational prerequisites, though these are minor gaps given the tool's simplicity.

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's only parameter, 'path', is fully described as 'Absolute path to the repository root'. The tool description does not add any additional meaning to this parameter, so the baseline of 3 applies given 100% schema description 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 a specific verb (scanning) and resource (infrastructure-as-code) across AWS, Azure, GCP, Kubernetes, and Docker, and lists concrete misconfiguration types like public S3 buckets and wildcard IAM policies. This distinguishes it from sibling scanners like secret_scan and cve_scan.

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

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

The description provides no guidance on when to use this tool versus other security scanners, nor does it mention any prerequisites, exclusions, or alternative tools. An agent would have to infer usage from the description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is well covered. The description adds the scope (per repository) and the subject (false-positive patterns learned by ARGUS), which is mildly useful. It doesn't describe output format or ordering, but that's less critical for a listing tool with strong 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 a single, clear sentence with no wasted words. It front-loads the action and subject effectively.

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 read-only listing tool with one well-documented parameter and strong annotations, the description is adequate. It could benefit from mentioning what the output contains (e.g., pattern IDs, suppression rules) but this is a minor gap given the available annotations and schema.

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 the parameter (path) with a description, so the description doesn't need to add much. The tool description implies the path is the repository root, which aligns with the schema. Baseline 3 is appropriate as the schema handles the meaning.

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 list false-positive patterns learned by ARGUS for a repository. The verb 'List' and resource 'false-positive patterns' are specific, and it distinguishes itself from related tools like learn_false_positive (which likely learns patterns) and memory_scan/memory_get (general memory). However, it doesn't explicitly name siblings to differentiate, dropping from a 5.

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

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

The description implies the tool is for viewing learned patterns, but it doesn't explicitly state when to use it versus alternatives like learn_false_positive for adding patterns. The context is clear, but no exclusions or alternative selection criteria are given.

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 declare destructiveHint=true, and the description adds valuable context beyond that: it specifies the storage location (.argus/learned.json), the persistent suppression effect on future runs, and the benefit (precision improves with use). This goes beyond the bare destructive flag, though it does not address reversibility or duplicate handling. No contradiction with annotations.

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

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

Two concise sentences that lead with the primary purpose, then provide the behavioral outcome. No fluff, every clause adds value. The structure is ideal for an agent scanning the definition.

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 core behavior required to invoke the tool correctly: what it does, where it stores data, and the long-term effect. Missing details like idempotency or what happens on repeated submissions are not critical for basic usage, and the absence of an output schema is acceptable for a mutation tool. Overall, it is complete enough for a typical call.

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 75% of parameters with descriptions (path, reason, category), but the 'file' parameter lacks a description in both schema and tool description. The description does not elaborate on parameter relationships or format, so it adds little beyond the schema. Baseline 3 applies given high schema coverage.

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

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

The description clearly states the specific action (teach ARGUS that a finding is a false positive) and the resource (ARGUS). It also explains the persistent effect (remembered in .argus/learned.json and suppressed on future runs), which distinguishes it from sibling tools that analyze or report findings. Unlike ambiguous verbs like 'process', it is precise 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 implies the use case: when you want to teach ARGUS a false positive pattern. It does not explicitly compare against siblings like ground_finding or learned_patterns, but the purpose is clear enough for an agent to infer when to invoke it. It lacks an explicit 'when not to use', but the context is straightforward.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about persistence — every scan is stored to .argus/runs/ as JSON, Markdown, and HTML — which orients the agent to where data lives without contradicting the read-only annotations. It does not disclose richer behavior (e.g., ordering or pagination), but for a read-only listing the annotations carry the main burden.

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 the core listing purpose front-loaded and the return fields specified up front. The second sentence adds the persistence-location context without redundancy relative to the schema or annotations. Efficient and well-structured, though the storage detail is slightly tangential to the tool's call semantics.

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

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

This is a low-complexity tool: 2 parameters (1 required), no nested objects, no output schema, and strong annotations. The description states the return fields, so the absence of an output schema is not a gap. It is complete enough for an agent to call correctly, with the only minor omission being explicit guidance on which sibling to prefer for related operations.

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%: path is documented as the absolute repository root and tool as a filter with an example. The description mentions 'tool' as one of the returned fields, which parallels the filter concept but adds no new parameter information beyond the schema. Per the baseline for full schema coverage, a 3 is appropriate.

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

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

The description uses a specific verb-resource pair ('List every recorded ARGUS run for this repository') and enumerates the exact returned fields (run id, tool, date, git commit), making the operation unambiguous. It is clearly a pure enumeration, distinct from analysis operations. However, it does not explicitly name sibling differentiators such as compare_reports or open_dashboard, so sibling distinction is implicit rather than stated.

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 purpose statement implies the usage — call this when you want to enumerate all recorded runs for a repository. But no explicit alternatives or exclusion conditions are given. With roughly five dozen siblings including compare_reports, open_dashboard, and track_run, explicit routing would materially help an agent select between them.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds the 'cross-session context' rationale but does not disclose behaviors like handling of missing keys, multiple matches, or the effect of combining 'key' and 'search'. Given the rich annotations, the description meets a minimal bar without contradiction.

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

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

A single sentence that front-loads the core action ('Recall stored values') and efficiently conveys the two entry points. It does not waste words, though the brevity forces omission of essential details. The structure is clean, but the content is too sparse to be highly effective.

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

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

With no output schema and 0% schema description coverage, the description carries the full burden of explaining usage. It does not cover the namespace parameter, the semantics of key versus search, return behavior when no match is found, or how results are formatted. The annotations cover safety, but not operational completeness, leaving a significant gap for an agent to call this correctly.

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

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

Schema description coverage is 0%, meaning the description must compensate. It only hints at 'key or search term', leaving 'namespace' entirely unexplained. It does not clarify parameter types, defaults, interactions (e.g., what happens if both key and search are provided), or expected format. This is insufficient for a tool with 3 optional parameters and no output 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 states the verb 'Recall' and resource 'stored values', and specifies two access mechanisms ('by key or search term'). This clearly identifies the function without being a tautology, but it does not explicitly differentiate from sibling tools like 'search' or 'memory_scan' — the name and mention of 'stored values' suffice to infer the memory scope.

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

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

The phrase 'Used for cross-session context' gives a use case but does not explain when to choose this over alternatives (e.g., 'search', 'memory_scan', or 'rag_retrieve'). It implies the tool addresses persistent memory recall, but no explicit when-to-use or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety. It adds value by specifying exactly which code patterns are flagged, but it does not describe output format, performance implications, or how findings are reported—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 a single, front-loaded sentence that states purpose and specifics without waste. Every word contributes meaning, making it efficient and easy to parse.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the core functionality adequately. It does not explicitly state the return format, but for a scan tool, results are implied as a report of leaks, which most agents would assume. Overall it is sufficiently complete for a focused scan utility.

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 the lone parameter 'path' already has a descriptive schema description ('Absolute path to the repository root'). The tool description adds no additional parameter semantics, so it sits at the baseline of 3 for high-coverage schemas.

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 ('Detect') and a clear resource ('memory leaks'), enumerating concrete examples (addEventListener without cleanup, useEffect without return, setInterval without clearInterval) that make the tool's purpose unambiguous and distinguish it from sibling scan tools like dead_code or security_scan.

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 tool's purpose is self-evident from the description, so an agent can infer when to use it (any memory leak concern). However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5, but the clarity of the scope provides sufficient context for most scenarios.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds that the value persists across sessions, which implies persistent mutation, but does not disclose whether existing keys are overwritten or the exact side effects. Since annotations cover the mutation flag, the description adds modest context beyond them.

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. The primary function is front-loaded, and the usage guidance follows immediately. 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 tool is simple (3 params, no output schema), and the description covers the core purpose. However, given the 0% parameter coverage, it leaves the namespace parameter unexplained and does not mention overwrite behavior. An agent could likely infer enough to call it, but the description is not fully self-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 description coverage is 0%, so the description must compensate. It only references 'key-value pair' and does not explain the parameters, especially the optional 'namespace' field. The schema provides types and constraints, but the description adds no additional meaning about parameter semantics.

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

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

The description clearly states the verb 'persist' and the resource 'key-value pair' stored in a specific location (.argus/memory/). It also mentions cross-session persistence, which distinguishes it from in-memory or ephemeral tools. The purpose is unambiguous and specific.

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 gives context for when to use it ('track scores, decisions, or context between runs') but does not explicitly exclude alternatives or mention sibling tools like memory_get. It implies usage but lacks explicit when-not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds that it returns a path, which is a read-only behavior, but does not explain how 'latest' is determined or what happens if no dashboard exists. It provides minimal extra behavioral context beyond the 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 a single concise sentence that front-loads the core purpose. It is not padded with unnecessary details. However, it could have included a brief note on the 'tool' parameter without losing conciseness, so it earns a 4 rather than a 5.

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 return value (a path) and the use case, but it omits any explanation of the optional 'tool' parameter, how it influences the result, or what values are valid (e.g., tool names). With no output schema, the agent needs more guidance on both parameters and potential error conditions, making this incomplete for a 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?

Schema description coverage is 50%: only 'path' is explained ('Absolute path to the repository root'). The optional 'tool' parameter has no description, and the description text only says 'for a tool' without clarifying how it is specified or what values are expected. The description fails to compensate for the missing schema documentation of 'tool', leaving the agent guessing about its purpose and valid inputs.

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

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

The description states a specific verb+resource: it returns the filesystem path to the latest visual HTML dashboard. It distinguishes from siblings like list_reports (which likely lists dashboards) by focusing on retrieving the path of the latest one for a given tool. The phrase 'ready to open in a browser or attach to a PR' adds practical context without ambiguity.

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 when to use it ('ready to open in a browser or attach to a PR') but does not explicitly mention alternatives or when not to use it. There is no reference to sibling tools like list_reports or compare_reports, leaving the agent to infer the appropriate context from the purpose alone.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it states the result is reproducible ('same codebase always gives same score') and mentions confidence weighting, which implies a confidence output. These details go beyond the annotations and help an agent anticipate behavior.

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

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

The description is two short sentences with no fluff. It front-loads the core purpose (scoring), then states the grading scale and reproducibility. Every sentence earns its place, and the structure is clear and efficient.

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 simple input (one well-documented path) and strong annotations, the description covers the essential invocation details. It explains the output scale and reproducibility. It could be more complete by listing the 10 dimensions or how confidence weighting is reported, but for an agent deciding to call it, the current description 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 for the single 'path' parameter is 100%, so the baseline is 3. The description does not enrich the parameter meaning beyond saying it gives a score; the schema already explains 'path' as an absolute path to the repo root. No additional parameter-specific detail is provided, so it stays at 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 computes a '10-dimension weighted codebase score' and assigns a grade on an S/A/B/C/D/F scale, which specifies the verb, resource, and output format. It is distinct from generic 'analyze' tools, but it does not explicitly differentiate from similar scoring siblings like code_quality or complexity, so it misses the top mark.

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 gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or contrast with any sibling tools (e.g., verify_all, code_quality). An agent has to infer from the name and output that it is for overall scoring, but no explicit usage context is provided.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds meaningful behavioral detail: the retrieval mechanism (local BM25), the guarantee of no API calls or data egress, and the return format (full code windows with line numbers). These go beyond the annotations and help an agent understand what happens without attempting a call. No contradiction.

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 concise sentences with zero filler. The first sentence states purpose and method, the second clarifies constraints (local, no API), and the third explains output value. Everything earns its place, and the key scoping 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?

For a retrieval tool with no output schema and simple parameters, the description is complete enough: it tells the agent what it returns (code windows with line numbers) and the key constraint (local only). It doesn't mention error behavior or edge cases, but given the simplicity and the annotations, nothing critical is missing.

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

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

Schema description coverage is 67% (path and query described, topK undocumented). The description does not explain any parameters further; it only refers to 'code chunks' generally. The schema already provides constraints for topK (default 8, min 1, max 20), and path/query are well-described, so the description adds no extra semantic value 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 states a specific verb (retrieve) and resource (most relevant code chunks for a question), and immediately contrasts itself with API/embedding-based approaches. It also specifies the output (full code windows with line numbers), making it distinct from generic search tools. While it doesn't name a sibling explicitly, the 'no API calls' and 'local BM25' clearly differentiate from any cloud retrieval alternative.

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 when to use it (when you need local, private retrieval) by highlighting no data leaves the machine, but it does not explicitly state when to prefer this over other tools like `search` or `ground_finding`. There is no mention of alternatives or exclusion conditions, so guidance is only implicit.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: it reviews ONLY added lines and lists concrete check categories (secrets, empty catches, @ts-ignore, XSS sinks, disabled TLS, await-in-loop). No contradiction with annotations.

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

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

Three sentences, front-loaded with the primary purpose, followed by the scoping constraint and check list. Zero wasted words; the check list is compact and informative without over-elongating.

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?

Complete for purpose and scope, but two gaps remain: there is no output schema, so the description carries the burden of explaining the return format and doesn't; and the 'new secrets' flagging overlaps with the secret_scan sibling without disambiguation, leaving an agent to guess which tool to invoke.

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 and path documented, so baseline is 3. The description reinforces the base=HEAD default (uncommitted changes) and the diff target semantics, but adds little meaning beyond what the schema already 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?

States a specific verb+resource ('Diff-aware code review' of uncommitted changes or branch comparison). Clear scope: reviews only ADDED lines. However, it doesn't explicitly differentiate from the overlapping secret_scan/security_scan siblings that also flag security issues like 'new secrets'.

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 clear context for when to use: 'uncommitted changes or a branch comparison'. But no explicit when-not guidance or alternative routing despite several overlapping security/scan siblings. The 'way a human reviewer reads a PR' framing implies usage but doesn't exclude tool boundaries.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: the output is an execution-mode classification (Full Autonomy / Mixed / Structured) with a human gate count, clarifying what 'risk assessment' concretely produces. Consistent with annotations (no contradiction).

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 tight sentences, zero waste. Purpose is front-loaded, and the second sentence states the return value efficiently. 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 states inputs (path, task via 'planned task') and outputs (execution mode, human gate count), which is adequate for calling. However, it never explains what the '4 dimensions' are, what 'human gate count' represents, or how this differs from gap_analysis/full_diagnose. With no output schema present, the description carries the full burden for return semantics, and those semantics stay vague.

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

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

Schema coverage is 50%: 'path' is documented but 'task' is not. The description's phrase 'planned task' implicitly maps to the task parameter, but it doesn't elaborate the '4 dimensions' that presumably drive the assessment, nor does it clarify task format. It partially compensates for the uncovered task parameter but leaves meaning to inference.

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 a specific purpose: '4-dimension risk assessment for a planned task' and what it returns (execution mode + human gate count). It's unambiguous about the tool's function, but it doesn't differentiate from several similar analysis siblings like gap_analysis, full_diagnose, or audit_360 — an agent would struggle to know which to pick for a given scenario.

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

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

No guidance is given on when to use this tool versus alternatives. Given the large sibling set full of overlapping analysis tools (gap_analysis, full_diagnose, audit_360, dependency_risk), the absence of any 'use this when...' or 'for X use Y instead' guidance is a notable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds feature context (regex, context lines, file type filtering) and a performance claim, but does not disclose any other behavioral aspects such as recursion behavior, result limits, or return format. Given the annotations cover the critical safety traits, this is adequate but not exceptional.

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 brief and front-loaded with the core purpose. The sentence '32× faster than grep' is a performance claim that does not aid tool invocation and could be omitted, but it is not verbose enough to detract significantly. Overall, it is concise and to the point.

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, idempotent search tool with no output schema, the description covers the main capabilities. However, it lacks details that could affect an agent's call, such as whether the search is recursive, whether results are limited, or how output is structured. Given the existence of sibling tools and the need to select the right one, some usage context would improve completeness, but it is not critically incomplete.

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 only 25%, with just 'path' having a description. The description compensates by implying the semantics of the other parameters: 'regex' maps to pattern, 'context lines' to context, and 'file type filtering' to fileType. This adds meaning to otherwise undocumented parameters, earning a 4 rather than a lower score.

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 identifies the tool as a codebase search tool using ripgrep, stating the verb 'search' and resource 'codebase'. It lists key features (regex, context, file type filtering). However, it does not explicitly differentiate from sibling tools like ast_search, which also searches code but at the AST level, so it gets a 4 rather than a 5.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions or contexts where another tool would be more appropriate. The usage is only implied by the name and title, but there is no explicit guidance for an agent deciding between this and ast_search or other search-related 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond that by explaining the effect of includeHistory on scanning every commit and the persistence of secrets in history, which is not stated in the 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 two sentences, front-loading the core purpose and then a focused, meaningful usage note. Every word adds value; there is 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?

For a read-only scan tool with no output schema, the description covers the essential function and the key parameter nuance. It lacks explicit information about the return format or that it produces a report of findings, but these are inferable from the tool type and the read-only annotation, so the gap is minor.

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 both path and includeHistory (100% coverage). The tool description adds extra semantic value for includeHistory by explaining why scanning history matters, which is more than the schema's 'Scan full git history' phrase. It does not add anything for path, but the schema description is sufficient.

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 ('detection') and resource ('secrets via gitleaks'), with the method ('entropy-based') making it clear what kind of scanning this is. This differentiates it from sibling tools like cve_scan or semgrep_scan, which target different categories of issues.

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 instructs when to set includeHistory=true and explains the rationale (secrets in history remain exploitable), which is direct usage guidance. However, it does not explicitly compare to alternative scanning tools or state when not to use it, leaving some implicit inference for sibling 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it emphasizes 'false-positive filtering' indicating results are curated, and lists the scan categories, which informs the agent of the tool's thoroughness and focus. This goes beyond the structured 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 a single, dense sentence that front-loads the core purpose ('Deep security scan') and then lists the specific vulnerability categories. It avoids fluff and all content is informative. While the list is long, it is justified for a security scan tool. The structure is efficient and effective.

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

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

For a tool with a single parameter and no output schema, the description covers what the tool scans but does not specify the return format (e.g., whether it outputs a report, a list of findings, or a pass/fail result). Since there is no output schema, this missing detail could affect an agent's expectation of the tool's response. The description is reasonably complete but leaves this important 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% for the single parameter 'path', and the schema already describes it as the absolute path to the repository root. The description adds no additional parameter semantics, such as accepted formats or edge cases. Given the baseline of 3 when schema fully documents parameters, this score 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 performs a deep security scan and enumerates specific vulnerability categories (secrets, injection, XSS, SQLi, etc.). It conveys the verb (scan) and resource (repository), making the purpose unambiguous. However, it does not explicitly differentiate from security-focused siblings like semgrep_scan or secret_scan, relying on the vulnerability list to imply distinction.

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 for a thorough security review with false-positive filtering, but it does not provide explicit when-to-use or when-not-to-use guidance nor name alternatives. An agent could infer this is the default deep-scan tool, but there is no direct routing like 'for more specific scans use X'. This leaves the guidance implicit rather than explicit.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds 'CWE mapping' as a behavioral trait, which is useful, but it omits any mention of prerequisites (e.g., Semgrep installation), output format, or performance implications. The added value is modest relative to the annotation coverage.

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

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

The description is a single sentence that front-loads the core purpose and then provides the config list. There is no fluff, and every word serves function. This is appropriately concise and well-structured.

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

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

With no output schema and complex scanning behavior, the description omits crucial details: what the tool returns (results, severity, CWE identifiers), any dependencies, and how to interpret outputs. The config list is helpful but insufficient for an agent to confidently use the tool in a real workflow.

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

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

Schema description coverage is 50% (only 'path' is described). The description compensates for the undocumented 'config' parameter by listing acceptable values (p/owasp-top-ten, etc.), which adds meaning beyond the schema. However, it doesn't explain what 'auto' means or how to specify multiple configs, leaving some ambiguity.

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 'Semgrep rule-pack scanning with CWE mapping' which clearly identifies the tool's verb and resource. It lists specific configuration names, distinguishing it from generic scanning tools. However, it does not explicitly contrast with siblings like security_scan or secret_scan, leaving some ambiguity about which scanner to choose.

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

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

The description provides no guidance on when to use this tool versus alternatives. Sibling tools such as security_scan, secret_scan, and cve_scan exist, but no filters or conditions are given to select this one. The agent is left to infer usage from the tool name and config 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is well-covered. The description adds meaningful behavioral context by specifying the output format (scored checklist with pass/fail per rule), which is not in annotations. However, it doesn't disclose details like whether results are aggregated or how scoring works, but the annotations handle the critical safety profile.

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 standards checked and immediately gives the output format. Every word contributes to understanding the tool's function, with no filler or repetition.

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 parameter and read-only, idempotent annotations, the description covers the core purpose and output. While it doesn't explain how to interpret the scoring or whether the checklist is exhaustive, those details are not essential for a basic call. The description is sufficient for an agent to correctly select and invoke it.

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 description coverage is 100%, and the single 'path' parameter is fully documented in the schema. The description does not add any additional meaning about the parameter beyond what is already in the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool checks against specific, well-known standards (OWASP Top 10, SOLID, 12-Factor, Clean Architecture) and specifies it produces a scored checklist with pass/fail per rule. This distinguishes it from security-only siblings like security_scan or semgrep_scan, which focus on security vulnerabilities rather than broad architectural principles.

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 (checking code against multiple standards) but does not explicitly state when to choose this over alternatives like code_quality or verify_all. While the purpose is clear, there is no guidance on exclusions or conditions that would favor this tool over others, nor any mention of prerequisites like needing a repository path.

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 already declare readOnlyHint=true and idempotentHint=true, establishing the safety profile. The description adds real behavioral context beyond those: parallel multi-agent execution, an internal critique loop, and deduplication/false-positive filtering — traits an agent needs to know before invoking a heavy analysis. Nothing contradicts the annotations. It does not mention runtime cost or output shape, but the added behavioral color earns a 4.

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

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

A single dense sentence that front-loads the core action (multi-agent parallel scan) before the qualifiers, and packs the covered domains and processing traits compactly. Slightly heavy with the colon-list plus trailing clause, but no wasted words and the most important information leads.

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?

Adequate for a moderate-complexity read-only tool: domains, parallelism, and output processing are covered. However, with no output schema present, the description should hint at the return format or the relationship to the other comprehensive siblings (verify_all, full_diagnose, audit_360, critique_report), and it does neither. For a heavyweight multi-agent scan, that is a meaningful omission.

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%: the single required `path` parameter is fully documented as the absolute path to the repository root. The description adds no parameter syntax or format detail, but none is needed for a single well-documented path argument. Baseline 3 applies since the schema carries the full semantic load.

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 a specific composite action — a multi-agent parallel scan covering security, quality, memory, testing, and gaps, with dedup and false-positive filtering. Clear on what it does and the domains it spans. However, it does not differentiate from the sibling comprehensive tools (verify_all, full_diagnose, audit_360), which appear to serve an overlapping combine-everything role.

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

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

There is no when-to-use or when-not-to-use guidance. With a long list of targeted siblings (security_scan, memory_scan, code_quality, test_coverage, gap_analysis) plus other aggregate tools (verify_all, full_diagnose, audit_360), an agent has no basis for choosing swarm_intel over a targeted scan or over a competing all-in-one. The implicit cue that this is the one-stop exhaustive scan is not stated explicitly.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds specific metrics it computes, which is useful context beyond the annotations. However, it does not disclose output format, pagination, or any other behavioral details, and since annotations cover the core traits, a score of 3 is appropriate.

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

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

The description is a single concise sentence that front-loads the purpose ('Test coverage analysis') and follows with specific metrics. There is no wasted verbiage, and it is efficiently structured for quick comprehension.

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 what the tool returns. It does not mention the output format or contents, leaving a gap. Given the simplicity of the tool (1 param) and available annotations, some return-value information is expected but missing, making it incomplete for an agent to fully understand the tool's behavior.

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

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

The single parameter 'path' is fully documented in the schema with 'Absolute path to the repository root', yielding 100% schema description coverage. The description does not add any additional semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool performs test coverage analysis and lists specific metrics (test/source ratio, assertion-free tests, skipped tests), which differentiates it from siblings like type_coverage and find_untested. However, it does not explicitly mention what the tool returns or how it differs from other analysis tools beyond these metrics, so it stops short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives. The description implies it is for test coverage analysis, but does not state when to prefer this over type_coverage or find_untested. The sibling list includes many related analysis tools, and the description provides no exclusions or selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, so the agent knows it's safe and side-effect free. The description adds that reasoning is 'structured' and involves decomposition and exploration, which provides some behavioral context but doesn't disclose return values or internal processes. No contradiction with annotations.

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

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

The description is a single concise sentence that front-loads the core purpose and lists key actions. It avoids filler and is appropriately sized for a simple internal-reasoning tool, but it could include a bit more detail without becoming verbose.

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

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

There is no output schema, and the description does not clarify what the agent receives after calling the tool (e.g., a reasoning summary or just an acknowledgment). The roles of the steps and context parameters are also left ambiguous. For a tool that assists reasoning, this lack of return and parameter context 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 description coverage is 0%, and the description does not explain any of the three parameters (problem, steps, context). While names and types are somewhat self-explanatory, the description adds nothing about how steps or context influence the reasoning process. With zero coverage, the description should compensate, but it does not.

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 performs structured chain-of-thought reasoning and lists specific actions (decompose, explore, conclude). It implicitly distinguishes from sibling analysis tools that run concrete checks (e.g., security_scan, code_quality) by focusing on internal reasoning. However, it doesn't specify the output or how it assists, leaving a slight ambiguity.

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 explicit guidance is given on when to use this tool versus the many sibling tools. It does not mention that it should be used for logical reasoning before invoking analysis tools, nor does it provide any exclusion criteria or alternatives. Given the large toolset, this is a notable 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?

Annotations already indicate readOnlyHint=false and destructiveHint=true. The description adds that it writes to a file and returns a delta, providing some behavioral context beyond annotations. However, it does not disclose whether it overwrites or appends, nor does it mention prerequisites like the file's existence. Given annotations, the description adds moderate value.

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 zero redundancy. The primary action and output are front-loaded, and the second sentence adds context without waste. 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 one parameter and no output schema, the description covers the essential behavior (what it writes, what it returns). Minor gaps such as handling of missing history file or error cases are not addressed, but these are not critical for a simple tool. The description is largely complete.

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

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

Schema description coverage is 100% for the single 'path' parameter, so the baseline is 3. The description does not elaborate on the parameter beyond what the schema already provides, offering no additional meaning or usage detail.

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 ('Record') and resource ('.argus/history.json'), and explains the output (delta versus previous run). It distinguishes itself from siblings by emphasizing the trend-line aspect, though it doesn't explicitly name an alternative to differentiate from.

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 ('Turns ARGUS from a snapshot into a trend line') which signals when it's appropriate, but it does not explicitly state when not to use it or mention alternative tools. There is no guidance on exclusions or alternative choices.

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 already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by naming the specific checks performed and the output of a 'strictness score', which is useful behavioral context beyond the 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 a single, front-loaded sentence with zero redundancy. Every word contributes to defining the tool's purpose 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?

Given the tool's simplicity (one parameter, read-only, no output schema) the description is largely complete. It explains what is audited and mentions a 'strictness score', though it does not specify the exact output format or how to interpret the score, which 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?

The schema fully describes the single 'path' parameter with 100% coverage ('Absolute path to the repository root'). The description adds no additional detail about the parameter, so the baseline of 3 applies as the schema carries the burden.

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 performs a TypeScript type safety audit, specifically enumerating 'any usage, @ts-ignore, type assertions, strictness score'. This is a specific verb (audit) and resource (TypeScript code) that distinguishes it from siblings like test_coverage or security_scan.

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 for checking type safety but provides no explicit guidance on when to select this tool over siblings. There are no alternatives mentioned or exclusions given; the purpose is clear enough to infer but not explicitly routed.

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 already set destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that. It adds the detail of capturing output, which is useful, but does not disclose other behavioral traits like side effects on the filesystem or required permissions. Since annotations cover the destructive nature, the description meets the baseline without adding significant extra value.

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

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

The description is a single sentence that is front-loaded with the action ('Run build, lint, and test suite') and immediately states the return format. Every word earns its place, with no filler or repetition.

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 parameter and no output schema, the description states the input and the high-level return, which is adequate but not exhaustive. It does not specify the exact output structure (e.g., JSON vs plain text), whether it is synchronous, or potential timeouts. Given the lack of output schema, more detail about the return value would improve 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 schema describes the path parameter fully as 'Absolute path to the repository root' with 100% coverage. The description does not add any nuance beyond that, relying entirely on the schema. This meets the baseline for fully documented 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 specific actions: run build, lint, and test suite. It also describes the return format as pass/fail per check with captured output. This distinguishes it from siblings like biome_check (lint) or test_coverage (tests) by bundling all three checks.

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

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

The description provides no guidance on when to use this tool versus alternatives such as verify_layers or full_diagnose. There is no mention of when it should be used, when it should not be used, or any exclusions. Agents must infer its role as a comprehensive check from the name and content.

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 already declare destructiveHint=true, so the agent knows this could have side effects. The description adds context by listing the gates and stating that blocking gates must pass for a SHIP verdict, which clarifies the decision logic. However, it does not disclose that running these gates (e.g., build, tests) may modify the repository or require network access, nor does it mention any side effects beyond the verdict. Since annotations carry the safety profile, the description adds moderate but not comprehensive 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, both front-loaded and information-dense. It lists the gates, distinguishes blocking gates, and states the return verdict without any filler or repetition. Every sentence adds value and there is no 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?

For a tool with one parameter, no output schema, and a straightforward verdict, the description is mostly complete. It specifies the exact gates and their blocking behavior, and tells the agent what the verdict is (SHIP or HOLD). It could improve by noting whether the non-blocking gates (lint, CVEs) still appear in the output or if there is additional detail beyond the verdict, but given the simplicity, 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?

The schema covers the single 'path' parameter fully (100% coverage) with a description of its meaning and constraints. The description adds no additional nuance about the parameter—it does not specify expected path formats, whether it should be a local path, or any edge cases. The schema does the heavy lifting, 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 tool runs six verification gates and returns a verdict, with specific gate names (type check, lint, build, tests, secret scan, dependency CVEs). The verb 'verify' is paired with the resource 'layers', making the purpose unambiguous. However, it does not explicitly distinguish itself from the sibling tool 'verify_all', which likely performs a similar comprehensive check, so it loses a point for lack of sibling differentiation.

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 says what the tool does but gives no guidance on when to use it versus alternatives like 'verify_all', 'security_scan', or 'full_diagnose'. It does not mention any conditions, prerequisites, or trade-offs that would help an agent decide between this and other verification tools. There are no exclusions or alternative routing hints.

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