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

No annotations provided; description mentions security gap checks but does not disclose if the tool is read-only or has side effects. Some transparency but incomplete.

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 well-structured sentences plus an example. Front-loaded with purpose, no wasted words.

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

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

Given schema richness (100% covered params) and no output schema, description explains what files and checks are performed. Adequate but could mention output format implications.

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

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

Schema coverage is 100%, so baseline 3. Description adds example usage but does not provide extra meaning beyond what the schema already documents.

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 audits application config files (next.config, middleware, .env, vercel.json) for cross-file security gaps, and distinguishes from guardvibe_doctor.

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

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

Explicitly says 'NOT the same as guardvibe_doctor' and provides an example invocation, helping the agent decide when to use this tool.

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

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

No annotations provided; description implies read-only scanning but does not explicitly confirm non-destructiveness, side effects, or security considerations. Adequate but incomplete.

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 covering purpose, target files, issues, and usage guidance with no unnecessary words.

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

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

Lacks details on return values or behavior when issues are found; no output schema provided. For a scanning tool with no annotations, more context is needed.

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?

Both parameters are fully described in the input schema; the description adds no additional meaning beyond what the schema provides. Baseline score 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?

Clearly defines scanning MCP config files for specific security issues (malicious hooks, suspicious servers, etc.), distinguishing from sibling tools like 'audit_config' that may target different configs.

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

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

Explicitly states when to use ('verify MCP configurations are safe before use'), but lacks explicit when-not-to-use or comparison with alternative tools like 'audit_config'.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It states the tool analyzes code for vulnerabilities, implying a read-only operation, but does not explicitly mention whether it modifies anything, requires network access, or has other side effects. While not misleading, it lacks depth.

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: main purpose, usage guideline, and example. Front-loaded with the core function, no extraneous words. Efficient 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?

Given the simplicity of the tool (analyze code), the description covers the essential: what it does, how to use it, and distinguishes from a sibling. No output schema is provided, but the example implies return of a security analysis. It could mention the output format more explicitly, but overall complete.

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

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

Schema coverage is 100%, but the description adds value by explaining the purpose of the 'format' parameter (markdown vs json) and providing an example that contextualizes the parameters. This goes beyond the schema definitions.

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 analyzes inline code for security vulnerabilities, listing specific categories (OWASP Top 10, XSS, SQL injection). It distinguishes itself from the sibling tool 'scan_file' which scans files on disk, making the purpose unambiguous.

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

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

Explicit instructions: pass code as a string parameter, use 'scan_file' for files on disk. Includes an example call with parameters, providing clear guidance on when and how to use the tool.

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

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

In the absence of annotations, the description fully discloses the tool's behavior: it returns a verdict with blast radius, safer alternatives, and risk assessment. It is a read-only analysis tool with no destructive side effects, as implied by the analysis nature.

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 three sentences, front-loading the core purpose in the first sentence and listing outputs and risk types efficiently without extraneous information.

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

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

Despite no output schema, the description thoroughly explains return values (allow/ask/deny verdict, blast radius, safer alternatives, context-aware risk assessment) and enumerates detected risks, providing complete context for an analysis tool.

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

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

Schema coverage is 100%, so parameters are already described. The description adds no further detail on the optional parameters (cwd, branch, format) beyond what the schema provides, meeting the 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 analyzes a shell command for security risks before execution, listing specific risk types. It distinguishes itself from sibling tools focused on files, dependencies, or secrets by being command-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 implies use before running a command ('before execution') but does not explicitly state when not to use it or provide direct alternatives among the many sibling security 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?

No annotations are provided, so the description carries full burden. It discloses that the tool checks for typosquat risk, maintenance status, adoption metrics, and deprecation, implying a read-only operation. It does not mention any destructive behavior or limitations beyond the checks listed.

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: the first states the tool's function, the second provides usage guidance. No unnecessary words, front-loaded with purpose, 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?

No output schema is provided, but the description explains the types of metrics returned and the output format options. For a check tool, it covers the necessary context about what is checked and the possible outputs. The presence of similar sibling tools doesn't detract from 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?

Schema coverage is 100% with good parameter descriptions. The description adds value by specifying the types of checks performed (typosquat risk, maintenance, adoption, deprecation) and the output formats (markdown for humans, json for agents), which augments 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 checks npm packages for specific risks (typosquat, maintenance, adoption, deprecation). It uses a specific verb 'Check' and resource 'npm packages', and differs from sibling tools like check_dependencies or scan_dependencies which are broader.

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 advises using this tool before adding new dependencies to catch suspicious packages, providing clear context. It does not mention when not to use or alternatives, but the guidance is sufficient.

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

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

No annotations provided, so description carries full burden. It discloses truncation to top 50 for large projects, a summary section at top, and different modes. This is adequate behavioral context for safe invocation.

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 plus an example, no extraneous information. Front-loaded with key purpose and frameworks, then details. 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?

Covers purpose, behavior (truncation), output structure (summary), modes, and provides an example. No output schema, but return format is implicitly described. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for mode ('C-level summary') and an example, but does not significantly expand on schema descriptions. Appropriate 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 uses specific verb 'map' and clearly identifies the resource: security findings to compliance controls. It lists supported frameworks (SOC2, PCI-DSS, etc.) and distinguishes from sibling scanning tools by focusing on compliance mapping rather than general 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?

States when to use: mapping security findings to compliance frameworks. Provides mode choices (executive for C-level) and an example. Does not explicitly state when not to use or contrast with siblings, but the context is clear enough.

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

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

No annotations are provided, so the description must convey behavioral traits. It mentions the return format (JSON string) but does not state whether the operation is read-only, what side effects occur, or any rate limits. Given the tool's simplicity, the description is adequate but lacks details beyond the basic action.

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 efficiently conveys the tool's purpose, output format, and context. Every word earns its place with no redundancy.

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

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

For a tool with a single input parameter and a simple output (JSON string), the description covers purpose, input, and output. No output schema exists, but the return format is specified. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% (the only parameter 'path' is described in the schema as 'Directory to scan'). The description does not add additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate since 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 states the verb 'scan and export', the resource 'directory', and the output format 'SARIF v2.1.0'. It also specifies the context (CI/CD integration for GitHub, GitLab, Azure DevOps), which distinguishes it from sibling tools like scan_directory that likely do not produce SARIF format.

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 is intended for CI/CD integration, providing context for when to use it. However, it does not explicitly exclude alternative tools or mention when not to use it. For a simple tool, this is clear enough but could be more 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?

Given no annotations, the description discloses that it returns structured edit instructions with line numbers, severity, and confidence. It also mentions before/after patches. This covers the essential output behavior. However, it does not discuss any side effects, permissions, or limitations (e.g., whether it modifies the input code).

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: two sentences and an example. It front-loads the core action and output, and every sentence adds value. No redundancy.

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

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

For a 4-parameter tool without output schema or annotations, the description covers purpose, usage hint, output structure, and follow-up tool. It is sufficient for an agent to understand how to use it. Minor gap: no mention of asynchronous behavior or failure modes, but not critical for this 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?

All 4 parameters are described in the input schema (100% coverage). The description adds little beyond restating the schema; it mentions 'vulnerable code' and provides an example but does not clarify nuances like the purpose of 'framework' or 'format' beyond the schema's own descriptions.

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

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

The description clearly states it takes vulnerable code and returns fix suggestions with before/after patches. The verb 'fix' and resource 'code' are specific. However, it does not explicitly differentiate from sibling tools like check_code or verify_fix, leaving some ambiguity about when to use this tool over others.

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

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

The description provides a clear use case ('vulnerable code') and suggests to use verify_fix afterwards. It also gives an example. However, it does not specify when not to use this tool or describe prerequisites beyond the required parameters.

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

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

With no annotations, the description carries the burden. It reveals the tool returns ordered steps for six specific sections with tool calls and actions, and emphasizes mandatory completion. It does not explicitly state side effects (read-only), but the planning nature implies no destructive actions. This adds context beyond what annotations would provide.

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 plus an example, all front-loaded with the core purpose and key usage rule. Every sentence adds value with no fluff. Highly 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 no output schema, the description adequately describes the output as ordered steps for all six sections with specific tool calls. It also sets context by linking to full_audit verdicts. Could be more detailed on failure modes or edge cases, but sufficient for an AI to use 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 coverage is 100%, and the description only provides an example usage with path. It adds no new meaning beyond the schema's descriptions for path and format. Baseline score of 3 is appropriate as the description neither enhances nor detracts.

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 generates a mandatory section-by-section remediation plan from full_audit results, specifically after a FAIL or WARN verdict. It lists the six sections and emphasizes completeness, distinguishing it from siblings like full_audit or verify_remediation.

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

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

Explicitly states when to use: MUST be called after full_audit when verdict is FAIL or WARN. Also provides a constraint: AI assistants MUST complete every section. This gives clear guidance and exclusions, meeting all 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?

No annotations provided, but description explains the tool analyzes and recommends (no mutation implied). However, it does not disclose if the tool modifies the repository, requires specific permissions, or has rate limits.

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. First sentence states the core purpose, second lists key outputs. No wasted words, front-loaded with essential information.

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

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

For a tool with two simple parameters and no output schema, the description adequately states what it maps, identifies, and recommends. However, it does not describe the return format beyond the format parameter, nor explain 'guard mode' or how priority fixes are presented.

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 100% with clear descriptions for both parameters. Description adds context about what the tool examines (sensitive areas list) but does not provide additional details about the parameters beyond what schema includes.

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 starts with a clear verb+resource ('Analyze a repository's overall security posture') and lists specific outputs (maps sensitive areas, identifies high-risk workflows, recommends guard mode, priority fixes). It distinguishes from siblings like 'deep_scan' and 'compliance_report' which have different scopes.

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 on when to use this tool versus alternatives. Does not mention prerequisites, when-not-to-use, or contrast with sibling tools like 'deep_scan' or 'compliance_report'.

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

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

Without annotations, the description carries the full burden of behavioral disclosure. It discloses that it uses diff-only mode, supports multiple output formats, and enables severity gating. However, it does not mention required permissions (e.g., write access to post comments) or whether it modifies any state. The description is adequate but not comprehensive.

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

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

The description is very concise: two sentences that cover the essential aspects without unnecessary details. Every sentence adds value, and the most critical information (purpose and key features) is front-loaded.

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

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

Given the complexity (5 parameters, no output schema), the description covers core functionality: diff-only scanning, output formats, and severity gating. It omits the structure of the returned findings, which would be helpful for an agent, but the description still provides sufficient context for invoking the tool correctly.

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

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

The input schema has 100% parameter description coverage, so the schema already documents parameter meanings. The description reiterates high-level concepts like 'diff-only mode' and output formats but does not add new meaning beyond the schema's parameter descriptions. Thus, it provides marginal additional value.

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

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

The description clearly states the tool's purpose: reviewing a pull request for security issues. It specifies the diff-only mode, output formats, and severity gating, which are distinguishing features. This differentiates it from siblings like 'scan_changed_files' which may not have the same output integration.

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

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

The description explicitly says 'Review a pull request for security issues,' which provides clear usage context. However, it does not mention when not to use this tool or suggest alternative tools for different scenarios, such as full scans of the repository. The context is clear but lacks 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?

No annotations are provided, so the description carries the full burden. It states that the tool reads files from the filesystem (access behavior), returns security scores and findings, and mentions truncation. However, it does not disclose whether the tool is entirely non-destructive, any authentication or permissions required, or other side effects like network access or rate limits.

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

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

The description is three sentences including an example. It is front-loaded with the main purpose, and every sentence serves a purpose: stating action, explaining input and behavior, noting truncation, and giving an example. No waste.

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 5 parameters and no output schema, the description covers the key output features (security score A-F, findings, fileRanking) but does not enumerate all possible result fields. It provides enough context for basic usage but could be more complete regarding error handling or structure of findings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with an example usage and a note about fileRanking for truncated results, but does not provide additional semantics beyond what the schema already offers for parameters like recursive, exclude, format, and 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 'Scan all files in a directory on disk for security vulnerabilities', which is a specific verb+resource action. This distinguishes it from sibling tools like 'scan_file' (single file) and 'scan_dependencies' (dependencies).

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 usage context: 'Pass a directory path — reads files from filesystem' and notes that results may be truncated for large projects, suggesting when to check fileRanking. However, it does not explicitly guide when to use this tool vs alternatives like scanning individual files or dependency 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?

No annotations provided, so the description carries the burden. It discloses that the tool reads the file itself and describes output formats, but lacks details on side effects, permissions, or error handling. Some context is added but not comprehensive.

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 front-loaded purpose. No wasted words; the example at the end aids understanding.

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 2-parameter tool with no output schema, the description covers purpose, usage, param semantics, and behavioral context. Minor omission of error handling but overall adequate.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by explaining the 'agent' format in detail (structured contract) and providing an example call, which goes 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 scans a single file for security vulnerabilities and distinguishes itself from sibling tool 'check_code' for inline snippets. The verb 'scan' and resource 'file on disk' are 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 explicitly tells when to use this tool (scan file paths) and when not to (use 'check_code' for inline code snippets). It provides a clear alternative.

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

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

With no annotations provided, the description carries the full burden. It details both offline and online behaviors, including graceful degradation when offline. However, it does not explicitly state the tool is read-only or mention any permissions or side effects, but the nature of scanning is implied.

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 somewhat lengthy but well-structured with clear sections for offline and online modes. It front-loads the core purpose and provides necessary detail without excessive verbiage. Could be slightly more concise.

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

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

Given the three parameters are fully described in the schema and there is no output schema, the description adequately covers the tool's behavior, modes, and recommended usage. It provides sufficient context for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the offline parameter's effect but adds no new meaning beyond the schema's parameter descriptions. No additional value is provided for the other parameters.

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

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

The description clearly states the tool detects AI-hallucinated and slopsquatted packages, specifying both deterministic offline detection and opt-in online registry checks. It distinguishes itself from sibling SCA tools by calling out what 'SCA misses' and targeting AI-generated code.

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

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

Explicitly advises running on AI-generated code at PR time before 'npm install', and provides guidance on when to use offline mode ('air-gapped') or online mode. This clearly tells the agent when to invoke this tool over alternatives.

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

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

No annotations provided. Description discloses marking findings as 'active' or 'removed' and need for rotation, but lacks details on permissions, performance impact, or side effects. Adequate but not comprehensive.

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 are concise and front-loaded with the core action. No unnecessary words.

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

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

Description explains the output classification (active/removed) but does not detail the output format beyond schema enum values. With no output schema, a bit more detail on return structure would improve completeness, but overall adequate.

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

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

Schema coverage is 100%; description adds no extra meaning to parameters beyond schema definitions. Baseline score of 3 is appropriate.

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

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

Clearly states the tool scans git history for leaked secrets, including those later removed. Distinguishes from sibling tools like 'scan_secrets' by specifying historical 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?

Description implies this is for historical scanning vs current scanning but does not explicitly state when to use or alternatives. No 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?

No annotations provided, so description carries full burden. Discloses automated staged file reading, diff-aware default behavior, and output format options. Does not mention that it is read-only or requires a git repository, but these are reasonable assumptions for a scanning tool.

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

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

Three sentences with zero waste: purpose, usage guidance, and behavioral note. Front-loaded with the essential verb and resource, efficient and scannable.

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

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

Covers all essential aspects given the tool's simplicity: what, when, how to customize. Lacks mention of prerequisite git repository or potential error states, but these are minor omissions for a focused 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?

Schema coverage is 100%, baseline 3. Description adds value by explaining format options as 'human-readable' vs 'machine-readable' and clarifying the diff_aware trade-off. This goes beyond the 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?

The description clearly states the tool scans git-staged files for security vulnerabilities, with a specific verb and resource. It distinguishes from sibling tools like scan_file or scan_directory by targeting only staged files, and explicitly ties its use to the pre-commit workflow.

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

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

Explicitly recommends running before every commit, giving clear context. Does not explicitly exclude alternative tools, but the staged file focus is a natural differentiator. Could mention when not to use, but the guidance is sufficient 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?

With no annotations, the description fully details behavioral traits: deterministic, no LLM, no network, triage verdicts, detection of stack and attack surfaces, matching against GuardVibe rule set, and output contents. It also clarifies that it never invents answers.

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 front-loaded with purpose and structured with specific details. It is moderately concise; each sentence adds value, though it could be slightly shorter.

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 no output schema, the description thoroughly explains the return structure (verdict, intent, numbered requirements, rewrite directive) and behavior. It is complete for an agent to understand invocation and expected results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (e.g., 'verbatim' for raw_prompt, 'if the client has it' for context) and an example, but this does not significantly extend beyond the 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?

The description clearly states the tool's action (analyze a raw coding prompt), the resource (prompt), and the outcome (structured enhancement directive). It distinguishes itself from sibling tools by focusing on pre-code generation security, with specific verdicts NO_MOD, LIGHT_MOD, HEAVY_MOD.

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 to 'Call this with the user's prompt before generating code' and contrasts with post-generation scanning. It provides an example but lacks explicit statements about when not to use it, though the context of sibling tools implies alternatives.

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

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

Despite no annotations, the description comprehensively discloses behavior: scanning, applying verifiable fixes, re-scanning, rollback on failure, and the return structure. It also specifies post-invocation actions like writing fixedCode and checking definitionOfDone.passed.

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 fairly long but well-organized, with the main idea front-loaded, followed by details, and an example. Each sentence adds value, though some trimming could improve conciseness.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is highly complete: it explains the algorithm, return format, and post-invocation steps. It leaves no major gaps for an AI agent to act 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 coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; it mentions 'code' and 'language' in the example but does not elaborate on 'framework' or 'filePath' beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Close the loop on vulnerabilities in code: scan, apply only the fixes that verifiably land...' and explicitly distinguishes it from siblings like fix_code+verify_fix, making it specific and actionable.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Prefer this over fix_code+verify_fix when you want a guarantee the fix landed — not just a suggestion.' It also implies context for use.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return type (tools, order, parameters) and gives an example, but does not mention side effects, permissions, or limitations. It is adequate but lacks deeper 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?

Two sentences plus an example, no unnecessary words. Front-loaded with the core purpose and usage. Highly concise.

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

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

Given the tool is an orchestrator without an output schema, the description adequately explains what it returns and when to use it. It could optionally describe the output format, but the current level 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?

The input schema covers the single parameter 'task' with 100% coverage, including detailed enum descriptions. The description adds a usage example but no additional semantic meaning 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 it returns a recommended tool sequence (tools, order, parameters) for the given task. This distinguishes it from sibling tools like analyze_dataflow or check_code, which are individual tools.

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

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

Explicitly tells the agent to 'Use this when unsure which tool to use,' providing a clear usage context. It does not list alternatives or exclusions, but the guidance is sufficient.

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

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

No annotations are present, so the description bears full behavioral disclosure. It states the return statuses ('fixed', 'still_vulnerable', 'new_issues') but does not mention side effects, permissions, idempotency, or whether the tool is read-only. This adequate but lacks depth.

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, no unnecessary words. First sentence states the main purpose; second explains behavior and output. Every word adds value; extremely 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?

Given 4 parameters, no output schema, and no annotations, the description covers input and output well. It explains the verification process and return statuses. However, it omits behavioral details like whether it modifies state or requires previous fix application, and lacks usage context like when to choose this over sibling tools.

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

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

Schema coverage is 100% (all parameters described), providing a baseline of 3. The description adds beyond the schema by clarifying that 'ruleId' targets a specific vulnerability and that 'filePath' is for context-aware analysis, which is not detailed in the schema. This adds meaningful context.

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 verifies a specific security fix by re-scanning code against a rule ID. This distinguishes it from sibling tools like 'fix_code' (applies fix) or 'remediation_plan' (plans). The verb 'verify' and noun 'fix' are specific and unambiguous.

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

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

The description implies usage after applying a fix ('after applying the fix') but does not explicitly state when to use versus alternatives like 'explain_remediation' or 'check_code'. No exclusion criteria or alternative tool suggestions are provided, leaving context 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?

With no annotations, the description discloses key behaviors: runs a fresh audit, compares snapshots, flags skipped sections, and refuses to return 'complete' unless all are addressed. This is good transparency, though side effects like permissions are missing.

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

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

Description is concise: three sentences plus an example. Every sentence serves a purpose, no redundancy, and key 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?

No output schema exists, but the description hints at return values ('flags skipped sections', 'complete' status). For a relatively simple verification tool, this provides adequate context, though explicit output structure is not detailed.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining that 'before_hash' is for tracking and can be omitted to re-run, and provides an example usage. This clarifies optionality and usage beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare before/after audit results to verify ALL sections were addressed.' It uses specific verbs and resources, and distinguishes itself from sibling tools like 'full_audit' by emphasizing post-remediation verification.

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

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

Explicitly states when to use: 'MUST be called after completing remediation to confirm success.' Provides details like passing a before hash or letting it re-run. However, no explicit when-not-to-use or alternative tools are mentioned.

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