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

No annotations are supplied, so the description carries the full disclosure burden. It does explain the analysis semantics (taint flow spanning files, injection detection), but says nothing about cost, file-count limits, permissions, or what happens when neither path nor files are supplied despite zero required parameters.

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

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

Three sentences, front-loaded with purpose, then routing, then a concrete invocation example. The example earns its place by showing the nested file object shape; no sentence is 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?

There is no output schema and no annotations, so the description is the only source of behavioral information, and it omits the return shape (findings structure, markdown vs json differences) and the file-count or performance envelope. Sufficient to invoke correctly, not sufficient to interpret results or anticipate cost.

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 per-parameter descriptions, so the baseline is 3. The description reinforces the files array with a concrete example, but it instructs the agent to 'pass files array with file contents' while never mentioning the path auto-discovery mode, which the schema presents as the preferred option — a mild steer toward the more verbose input mode. It also ignores the format enum.

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?

Names a specific verb and resource ('track user input flowing across module boundaries') plus the concrete vulnerability class it targets (cross-file injection). It is immediately distinguishable from the sibling analyze_dataflow, which it explicitly excludes.

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 the condition that selects the alternative: 'For single-file analysis, use analyze_dataflow instead.' This is the when/when-not/alternative pattern, resolved in one sentence with no inference required.

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 exist, so the description carries the full burden. It usefully discloses the analysis mechanism (following variable assignments rather than matching patterns), which explains result characteristics like fewer false positives on obfuscated flows. It says nothing about depth limits, what counts as a reported flow, or that analysis is static/local within a single file.

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, front-loaded with the core mechanism and immediately followed by the differentiator. No filler.

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

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

Adequate for a fairly simple two-required-parameter tool with full schema coverage, but it omits scope (single file vs project) and the boundary with analyze_cross_file_dataflow, which matters for tool selection in a 38-tool server.

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% and both enums are documented, so the standard is the baseline. The description adds conceptual value by enumerating source and sink categories that shape findings, but adds no detail about the code/format/language parameters themselves.

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 analysis: tracking user-controlled inputs (request body, URL params, form data) into dangerous sinks (SQL, eval, file ops, redirects). It also implicitly distinguishes itself from regex-based checks. However it does not distinguish itself from the sibling analyze_cross_file_dataflow, which sounds like the closest 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?

Usage is implied ('detects injection vulnerabilities that regex rules miss'), which hints that an agent should prefer this over check_code-style regex scanning. But there is no explicit when-to-use/when-not, no mention of JS/TS-only scope in the description, and no routing to analyze_cross_file_dataflow.

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 supplied, so the description carries the full burden. The audit verb and the enumerated read-only targets imply a non-destructive scan, and the cross-file scope is a genuine behavioral trait worth knowing, but the description never states that nothing is written, what permission or environment prerequisites exist, or how findings are surfaced.

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?

Front-loaded with the core purpose, followed by the sibling exclusion and then an example — a sensible information order with essentially no filler. The parenthetical file list is dense but earns its place by making the scan surface concrete.

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 annotations and no output schema, the description should carry more of the behavioral and result-shape burden. It tells the agent what to pass and what categories are checked, but says nothing about what a result looks like, whether findings include severity or file locations, or what the json format yields.

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 both parameters are documented inline, so the baseline is 3. The example audit_config({path: '.'}) usefully demonstrates that path should be the project root, but the format parameter's effect (markdown vs json) receives no added meaning beyond the schema's one-word description.

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

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

States a specific verb (audit) plus the exact resource (application config files) and enumerates the concrete artifacts checked (next.config, middleware, .env, vercel.json) and the gap classes found (missing headers, unprotected routes, exposed secrets). It explicitly contrasts itself with the sibling guardvibe_doctor, so an agent can route between them without opening either schema.

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 an explicit exclusion ("NOT the same as guardvibe_doctor which checks AI host security") and a concrete invocation example, which gives clear usage context. It does not, however, position itself against the many other audit-adjacent siblings such as full_audit, check_project, or scan_config_change, so the agent still has to infer that boundary.

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

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

With no annotations, the description must carry the full behavioral burden. 'Scan' implies a read-only inspection and the description discloses the detection categories and a specific CVE (2025-59536), which is genuinely useful context. However, it never confirms the operation is non-mutating, says nothing about what happens if a config file is missing, and does not describe what a finding or report looks like.

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: the detection scope with concrete file paths and issue categories comes first, the usage cue second. No filler, no restatement of the tool name.

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 and no annotations, but the enumerated issue categories effectively tell the agent what kinds of findings come back, and the file list scopes the behavior. The remaining gap is that the format parameter's consequence (markdown report vs JSON) is never explained, which matters for a tool whose primary product is a report.

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

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

Schema description coverage is 100% with only two self-documenting parameters (path with default '.', format enum with default markdown), so the baseline is 3. The description adds no parameter-level meaning beyond implying the default path is a project root; it never mentions that output can be JSON or markdown, which is the one parameter choice an agent would benefit from guidance on.

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 ('Scan') and a precisely bounded resource: MCP config files, with the three concrete paths (.claude/settings.json, .cursor/mcp.json, .vscode/mcp.json) enumerated, plus the four issue classes it looks for. This is far more specific than a generic 'audit' sibling like audit_config or audit_config, though it never explicitly contrasts itself with scan_host_config or scan_config_change, which an agent could plausibly confuse it with.

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?

'Use this to verify MCP configurations are safe before use' gives a clear triggering context (pre-adoption verification of MCP configs). It does not name exclusions or point to alternatives such as audit_config for broader scope or remediation_plan once issues are found, so it stops short of full routing guidance.

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

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

No annotations exist, so the description carries the full burden. It does disclose what is reported (protected vs unprotected routes, which providers are detected), which is valuable given there is no output schema. However, it says nothing about read-only/static-analysis nature, behavior when no input is supplied, or the fact that files/middleware are ignored when path is given.

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

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

Three sentences, front-loaded with purpose and then detection scope, with a compact example at the end that pays for itself by showing the exact input shape. Minor waste is the repetition of 'auth coverage' framing that the tool name already conveys.

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 annotations and no output schema, the description partially compensates by describing what the report contains. But with four params and zero required, the guidance to 'pass files array' skips the primary no-arg/`path` workflow, leaving an agent without the complete picture of how to invoke it in the simplest case.

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 schema already explains `path`, `files`, `format`, and `middleware` including the 'ignored when path is provided' rule. The description adds a concrete usage example for the files/middleware combination but omits `path` and `format` entirely, so it neither enhances nor fully mirrors 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?

States a specific verb and resource (analyze authentication coverage across Next.js App Router routes) and names the concrete capability: detecting Clerk/NextAuth/Supabase/custom auth guards and reporting protected vs unprotected routes. An agent can tell this apart from generic siblings like check_code or full_audit without opening the schema.

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 (you have route files and middleware you want analyzed) but gives no explicit when-not or alternatives among the many sibling scanners. Worse, it frames input as 'Pass files array with route file contents and middleware content,' which understates the more convenient `path` auto-discovery option documented in the schema, so guidance is partially misleading rather than absent.

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 disclosure burden. It implies a non-executing static analysis of a string and shows the caller controls output format via the example/schema, but it says nothing about how findings are produced (heuristics vs. rules), whether anything leaves the machine, or what the report contains.

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 short sentences, front-loaded with the purpose, then the alternative, then an example. The trailing example is slightly redundant given how complete the schema is, but it costs little and clarifies the call shape.

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?

All four parameters are documented and the routing to scan_file is clear, but with no output schema and no annotations the description never says what a result looks like (findings list, severities, CWEs, pass/fail). For a scanning tool whose value is its report, that is a real gap an agent must guess at.

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% (code, language enum, framework, format all documented), so baseline is 3. The description adds a small but real increment by tying 'pass code as a string' and the example call shape to the code/language pair, reinforcing that a snippet, not a path, is expected.

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 and resource ('Analyze inline code') plus concrete scope (OWASP Top 10, XSS, SQL injection, insecure patterns). It explicitly contrasts itself with scan_file, so an agent can distinguish it from that sibling without opening either schema.

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?

Gives an explicit input mode ('Pass code as a string parameter') and names the alternative with its selecting condition ('For scanning files on disk, use scan_file instead'). Nothing about when to pick this vs. a file-based scan is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return contract (allow/ask/deny verdict, blast radius, safer alternatives) and enumerates the risk categories detected. The one notable gap is that it never explicitly states the command is not executed by this tool, leaving the agent to infer that from 'analyze'.

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

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

Two sentences, both dense with information, front-loaded with the purpose and verdict semantics followed by detection categories. No filler and no repetition of the tool name.

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, so the description must explain returns, and it does by naming the verdict scale and the accompanying payload fields. It is nearly complete for a moderately simple 4-param tool; only the non-execution guarantee and the meaning of the 'ask' verdict for the caller are left implicit.

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 schema already documents command, cwd, branch, and format, making 3 the baseline. 'Context-aware risk assessment' hints that branch and cwd affect the verdict, but the description adds no format or syntax guidance 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 leads with a specific verb and resource ('Analyze a shell command for security risks') and names the timing constraint ('before execution'). This clearly separates it from siblings like check_code, check_project, or scan_staged, which operate on files or repos rather than a single command string.

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?

'Before execution' tells the agent exactly where this tool sits in a workflow, which is real usage guidance. It stops short of naming alternatives or stating when not to use it (e.g. to use check_code instead for source files), so it is clear context without 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 exist, so the description carries the full burden; it does disclose the data source (OSV database), which is genuinely useful context. However, it never states that the operation is read-only with no side effects, nor anything about network calls, rate limits, or batch size limits for the packages array.

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, zero filler, with the capability stated first and the usage trigger second. Every clause 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?

There is no output schema, and the description never indicates what comes back beyond the implication of CVEs — no mention of severity, fixed versions, or whether transitive dependencies are covered. An agent can tell what the tool does but not whether its results will answer the question it has.

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% and the nested package object documents name, version, and ecosystem with examples, so the schema does the heavy lifting. The description adds no parameter meaning beyond the schema, making the baseline 3 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 and resource: checking npm/PyPI/Go packages for known CVEs against the OSV database. That is concrete and actionable, but it does not differentiate itself from the near-identical sibling scan_dependencies, leaving an agent to guess which of the two to call.

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?

"Use this before adding new dependencies or to audit existing ones" gives two clear triggering scenarios. It stops short of naming exclusions or pointing to the obvious alternative (scan_dependencies), so it is clear context without routing.

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 disclosure burden. It implies a read-only inspection of registry metadata, but never states that nothing is modified, whether it hits the network, or how long a multi-package check takes; it also does not describe what the result contains beyond the four categories named.

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 capability statement comes first and the usage trigger second. Every clause carries information an agent needs.

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 two-parameter read-only checker with no output schema, the description covers what is inspected and when to run it. It stops short of telling the agent how to interpret or act on results (e.g. what counts as risky), which is the remaining 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 100%, so both parameters (packages list, format enum) are already fully documented in the schema, including the markdown-vs-json intent. The description adds no syntax, batching, or format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb (check) and resource (npm packages) and enumerates the four risk dimensions examined: typosquat, maintenance, adoption, deprecation. It does not distinguish itself from close siblings like scan_hallucinated_packages or check_dependencies, so an agent must infer the split.

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?

Gives an explicit trigger: 'Use this before adding new dependencies to catch suspicious or risky packages.' That is clear context for invocation, but no when-not-to-use condition and no named alternative among the many dependency-related siblings.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the outcome (a project-wide report plus a numeric security score) and implies a non-mutating analysis, but says nothing about file-count or size limits, whether it needs network access, or how large projects are handled.

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 with the capability and output stated up front and no 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?

For a two-parameter read-style tool whose schema is fully documented and whose deliverable is named, this is largely complete. The remaining gap is routing against the many overlapping scan/audit siblings, not the call mechanics.

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 both parameters — the files array with path/content and the markdown/json format enum — are fully documented in the schema. The description adds no meaning beyond that, which makes the baseline 3 correct.

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 and scope: scan multiple files across a project and produce a report with a security score. That is clear, but it never distinguishes itself from siblings like full_audit, deep_scan, or check_code, which read as overlapping capabilities.

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

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

"Use this for comprehensive security audits" hints at the appropriate context, but with 35 sibling tools including full_audit and deep_scan, the description never says which to pick or when this one is wrong. Usage is implied rather than 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?

With no annotations, the description carries the burden and does meaningful work: it discloses output structure (summary section at top), a truncation limit (top 50 findings on large projects), and an output-shaping mode. It does not state that the scan is read-only/no-write, nor anything about permissions or runtime cost, leaving some behavioral gaps for a directory-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?

Front-loads the core action, then output behavior, then the mode hint and a compact example. Every sentence is functional, though the framework enumeration and example add length that could be trimmed given the schema already lists the enum values.

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

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

No output schema exists, and the description compensates by explaining the report's shape (summary at top, truncation cap) and the executive mode. Remaining gaps are minor: what a finding entry looks like, and whether the operation is purely read-only.

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

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

Schema description coverage is 100%, so all four parameters (mode, path, format, framework) are already documented, including enums. The description only echoes the mode=executive meaning and shows an example invocation, adding little 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?

States a specific verb and resource: map security findings to compliance controls, and enumerates the supported frameworks (SOC2, PCI-DSS, HIPAA, GDPR, ISO27001, EUAIACT). The scope (scan a directory, group issues by control) is concrete. It does not explicitly contrast itself with siblings like check_project or full_audit, so it lands at 4 rather than 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?

Gives a clear usage context ('Scans a directory and groups issues by control') and a concrete trigger for a variant ('Use mode=executive for C-level summary'), plus a worked example call. It stops short of stating when-not to use it or which sibling (e.g. generate_policy, audit_config) covers adjacent needs, so no explicit alternatives.

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

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

With no annotations, the description carries the burden well: it discloses cost ('~cents per scan'), the auth requirement (ANTHROPIC_API_KEY / OPENAI_API_KEY), and the truncation behavior tied to maxBytes. It stops short of describing return structure or failure modes, but the operational context is solid.

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 tightly packed sentences, front-loaded with the distinguishing capability, then cost/model guidance, then the prerequisite. No wasted 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 an 8-param tool with full schema coverage and no output schema, the description supplies the key missing operational facts (cost, auth, model choice). Return-shape expectations are somewhat unaddressed, but the format enum covers output form adequately.

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 schema already documents all 8 parameters. The description adds model-cost tradeoff context but largely repeats what the schema conveys, so the baseline 3 applies.

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

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

States a specific verb+resource (LLM-powered deep security analysis) and enumerates exactly the vulnerability classes it targets (IDOR, business logic, race conditions, etc.). This clearly distinguishes it from pattern-matching siblings like check_code or scan_file.

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

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

The framing 'vulnerabilities that pattern-matching cannot detect' implicitly tells the agent when to reach for this instead of the pattern-based siblings, and the model guidance (haiku default vs sonnet for depth) aids selection. It doesn't explicitly name alternative tools or state when NOT to use it, keeping it short of a 5.

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

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

With no annotations, the description carries the full behavioral burden. It does well on response substance by listing exactly what the explanation contains, but says nothing about whether the tool is purely read-only, any auth or rate-limit expectations, or how the format parameter changes the payload shape beyond the enum.

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, front-loaded with the required input and immediately followed by what comes back. The trailing example is mildly redundant with the schema's own VG402 example, which keeps it from 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?

There is no output schema, so the description must convey return values — and it does, enumerating all five explanation components and noting the markdown/json format choice. What remains thin is how the optional code snippet actually alters the guidance returned.

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

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

Schema description coverage is 100%, so all three parameters are already documented in structured data. The description adds only the code-snippet rationale ('context-aware guidance') and repeats an example call whose rule ID duplicates the schema's own example — baseline 3 applies.

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

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

The description states a specific verb and resource — explaining a GuardVibe rule's remediation — and enumerates the five deliverables (risk assessment, exploit scenario, minimum fix, secure alternative, test strategy). That enumeration implicitly separates it from action-oriented siblings like fix_code and remediation_plan, though no sibling is named explicitly.

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 establishes the trigger condition (you have a rule ID and want an explanation) and the optional enrichment path (pass the code snippet for context-aware guidance). It offers no exclusions or explicit alternatives, so it stops short of a 5.

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

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

No annotations are supplied, so the description carries the full disclosure burden and only tells us the output format and that a string is returned. It does not say whether 'export' writes a file to disk or only returns the string, whether the operation is read-only, what rules/engine back the scan, or what happens on an unscannable path - all material for a scan+export tool with zero 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?

Two compact sentences with no filler; the core action and output format are front-loaded before the return-type note. Nothing repeats the title and nothing is wasted.

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?

Without an output schema, the description does its minimum duty by stating 'Returns JSON string', and the SARIF version is a useful detail. However, for a tool with no annotations and no output schema, the file-vs-string ambiguity and the lack of any scope/safety statement leave it only partially 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?

There is a single parameter whose schema description ('Directory to scan') already covers it at 100% coverage, which sets the baseline at 3. The prose adds no extra semantics such as whether the path must be absolute, whether it recurses, or how it relates to the working directory.

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 ('Scan'), resource ('a directory') and a concrete output artifact ('SARIF v2.1.0 format for CI/CD integration'), which is far more informative than a bare name restatement. It stops short of differentiating itself from the similarly-scoped sibling scan_directory, so an agent still has to guess which one produces SARIF.

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 'for CI/CD integration (GitHub, GitLab, Azure DevOps)' implies the consumption context, but the description never says when to choose this over scan_directory, full_audit, or deep_scan, nor does it state prerequisites (e.g. whether a prior scan or config is needed). Usage is inferred rather than directed.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: it returns structured edit instructions rather than applying changes, and it reports line numbers, severity, and confidence. It still doesn't state explicitly that no files are modified (read-only), nor any limits on code size or latency, so a small gap remains for a no-annotation 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?

Front-loads purpose and output shape in the first sentence, then workflow and an example. Every sentence contributes; nothing is padding.

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, so the description usefully summarizes the return value (before/after patches, line numbers, severity, confidence). Combined with 100% schema coverage, an agent has nearly everything needed; only an explicit read-only/does-not-modify-files statement 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 100%, so the schema already documents all four parameters including the format enum tradeoff (json for agent auto-fix vs markdown for human review). The description adds only a usage example with code and language, not new meaning about format or framework, so baseline 3 applies.

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

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

States a specific verb and resource ('fix_code' → get fix suggestions with before/after patches) and clarifies the input form (code as a string) and output shape (structured edit instructions with line numbers, severity, confidence). An agent can distinguish it from detection-only siblings like check_code and from the follow-up verifier verify_fix without opening the schema.

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 names the follow-up step ('Use verify_fix afterwards to confirm the fix resolved the issue'), which gives a clear workflow position. However, it does not state when to prefer fix_code over check_code, secure_this, or explain_remediation, so the initial routing decision is left 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 does substantial work: it discloses the return verdict vocabulary (PASS/FAIL/WARN), the deterministic hash, the full set of checks performed, and a mandatory follow-up chain. It omits things an agent would still want, such as whether the scan is strictly read-only and the expected runtime/cost of running all checks at once.

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?

Front-loaded with the capability list, then the critical workflow rule, then an example — a sensible ordering. Slight redundancy between 'do NOT skip any section' and 'confirm ALL sections are addressed', and the '429 rules' detail is decorative, but nothing is wasted at length.

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, so the description must carry return semantics, and it does at the verdict level (PASS/FAIL/WARN plus hash). For a tool that aggregates six analyses, it says nothing about the structure or size of the report body, which is the main remaining 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 100%, so all four parameters (path, format, skipDeps, skipSecrets) are already documented in the schema. The description only demonstrates path usage via the example and never mentions the skip flags or output format, so it adds little 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?

States a specific action (single command running ALL checks) and enumerates exactly what those checks are: code scan with 429 rules, secret detection, dependency CVEs, config audit, taint analysis, and auth coverage. An agent can tell this is the aggregate entry point rather than one of the single-purpose scanners like scan_secrets or check_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?

Very explicit about the downstream workflow: on FAIL/WARN you MUST call remediation_plan, and after fixing, verify_remediation. That is strong conditional routing. It does not, however, say when to prefer this over siblings such as deep_scan, check_project, or security_workflow, so entry-point selection is left to inference.

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 exist, so the description must carry the behavioral burden. It does disclose the key behavior that detection is based on scanning the project stack and that outputs are framework-tailored, which is valuable beyond structured fields. But it leaves critical ambiguity unresolved: whether policies are written to disk or merely returned, whether existing config files are overwritten, and what happens when detection fails.

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

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

Two sentences, front-loaded with the detection mechanism followed by the concrete deliverables. The enumeration of output types is dense but every item carries information; nothing is padding.

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 no annotations, so the description is the only source of behavioral detail. It does well on what artifacts are produced, but omits side-effect semantics (write vs. return), error behavior on unrecognized stacks, and scope of the directory scan required for a two-parameter generation 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% with only two parameters, both documented in the schema (path as project root, format enum with default). The description adds no syntax, constraints, or meaning beyond that, so the baseline 3 applies.

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

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

Uses a specific verb ('generate tailored security policies') plus the mechanism (auto-detect stack) and enumerates the concrete artifacts produced: CSP headers, CORS, RLS policies, rate limiting, security headers. An agent knows exactly what it gets; however, it never contrasts itself with close siblings like policy_check or remediation_plan.

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 statement of when to use this versus policy_check (which presumably validates existing policies) or full_audit/remediation_plan. The only usage signal is implicit: you pass a project root and get policies, so the reader must infer the scenario themselves.

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 exist, so the description carries the full burden. It does disclose the return shape ('Returns actionable guidance with code examples'), which is valuable, but it never clarifies that this is a static knowledge-base lookup rather than an inspection of the caller's repository — a materially ambiguous point given fifteen scan_* siblings that do operate on 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?

Three short sentences, generously front-loaded with the purpose and coverage scope before the return-value note. No filler and no redundancy with the schema.

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 reference lookup with no output schema and no annotations, this covers the what, the topical breadth, and the response format. The one real gap is whether the answer considers the caller's actual codebase or is purely generic reference material.

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 'topic' parameter already carries a strong enumerated example list, so the schema does the heavy lifting. The description broadens the framing to 'topic, framework, or vulnerability type,' which adds a little taxonomic guidance but no syntax, casing, or granularity advice beyond the examples.

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 ('Get') and resource ('security best practices and remediation guidance'), then enumerates the exact scope: OWASP Top 10, framework-specific hardening for Next.js/Supabase/Stripe, and secure coding patterns. Against a sibling set dominated by scan_*/check_*/audit_* tools, this reads unmistakably as a static reference lookup rather than a scanner.

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 usage context ('for a specific topic, framework, or vulnerability type') but never states when to prefer it over near-neighbors like explain_remediation or remediation_plan, which plausibly overlap on remediation guidance. An agent can infer this is the lookup step, but no explicit routing rule or exclusion is 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?

No annotations are provided, so the description carries the full behavioral burden. “Check” implies a read-only diagnostic, and scope-specific scanning behavior is described, but the description does not explicitly confirm that no files are modified or state permission/read-access requirements for host-level scans.

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?

Front-loads the security purpose, follows with a sibling comparison, then scope guidance and a compact example. No wasted sentences.

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, sibling distinction, scope selection, and an example for a moderately complex diagnostic tool. Since there is no output schema, it could say more about what the diagnostic returns, but the core invocation guidance is 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%, so all three parameters are already documented. The description reinforces scope semantics and provides a usage example, but adds no parameter meaning 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?

States a specific verb and resource set: checking AI host security across MCP configurations, hooks, base URL hijacking, and environment variable exposure. It clearly distinguishes itself from audit_config, but does not differentiate from closer-sounding siblings like audit_mcp_config or scan_host_config.

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 this is NOT audit_config and gives concrete guidance on scope selection: project by default, host to include shell profiles and global AI configs. It lacks guidance on when to prefer this over overlapping siblings such as audit_mcp_config or scan_host_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 carries the full burden. It implicitly signals a read-only validation and describes output shape (pass/fail plus per-control findings), but omits CI-critical behavior such as what happens when .guardviberc is absent or malformed, and whether a failing check surfaces a non-zero exit 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?

Four sentences, front-loaded with the purpose and then usage, validation scope, and return shape — no filler. The middle enumeration of validated rule types is slightly list-like but each item is informative.

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 no annotations, the description does the necessary work of stating the return value (pass/fail with detailed findings per control) and the config source. Remaining gaps — missing-config handling and CI exit-code behavior — are minor but real for a gate used in pipelines.

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 both `path` and `format` are already documented with defaults and an enum. The description only indirectly touches these (the .guardviberc reference relates to `path`) and adds no new semantics, so baseline 3 applies.

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

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

States a specific verb and resource — check a project against compliance policies defined in .guardviberc — and enumerates what is validated (custom frameworks, severity thresholds, required controls, risk exceptions). That is far more specific than the sibling compliance_report or full_audit, though it never names those siblings to draw the boundary explicitly.

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?

Gives two concrete invocation contexts: CI/CD security gates and pre-release compliance verification. This is clear usage guidance, but there are no exclusions or explicit pointers to alternatives (e.g., when to prefer compliance_report or full_audit instead).

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 exist, so the description carries the burden and does well: it discloses the return shape (ordered steps for all 6 named sections with specific tool calls and actions), the mandatory-completion behavior, and the format-driven output. It omits permission/side-effect details, but as a plan generator that is minor.

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?

Front-loads the core purpose, the sequencing precondition, and the return content, with a concrete example at the end. Slightly repetitive with two MUST statements about section completeness, but every sentence carries routing or behavioral 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?

No output schema exists, yet the description explains what the result contains (ordered steps across the 6 sections with tool calls) and how format affects it, which is enough for an agent to call it correctly. Permission and error behavior remain unstated.

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 only 2 optional parameters, so the schema already documents path and format (including the enum and default). The description's example call ({path: '.'}) and format note add marginal value but no new semantics; baseline 3 applies.

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

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

States a specific verb (Generate) and resource (section-by-section remediation plan) with its source (full_audit results) and enumerates the exact 6 sections produced. This clearly differentiates it from siblings like explain_remediation and 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?

Gives an explicit trigger condition: must be called after full_audit when verdict is FAIL or WARN, plus the constraint that all sections must be completed. It does not name alternative sibling tools (e.g. explain_remediation) or state when not to use it, so it falls short of the top mark.

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 does disclose the analysis outputs and uses 'recommends' and 'lists' to imply a read-only advisory operation rather than a mutating one, but it never states that no files are modified, whether a git repository is required, or whether the analysis is expensive/slow for large repos.

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 the core purpose first and the deliverables after. The parenthetical area list (auth, payments, PII, admin, API, infrastructure) is dense but each item earns its place by telling the agent what the scan covers.

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 no annotations, the description must carry more weight. It partially compensates by enumerating what the analysis reports, but it does not describe the shape of the result, the guard-mode concept it references, or how the recommended fixes relate to the fix_code/remediation_plan siblings.

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

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

Schema description coverage is 100% with only two simple parameters ('path' as repository root, 'format' enum with default), so the schema already does the work. The description adds nothing about path expectations (absolute vs relative, monorepo roots) or when to choose JSON over markdown, 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?

States a specific verb and resource ('Analyze a repository's overall security posture') and enumerates the concrete artifacts produced (sensitive-area map, high-risk workflows, guard-mode recommendation, priority fixes). This clearly reads as an aggregate/overview analysis rather than a single-target scan like scan_secrets or check_dependencies, though it never names a sibling explicitly.

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 'overall security posture' framing implies this is a high-level entry point rather than a targeted check, which is enough to distinguish it in spirit from scan_file or check_code. However, with near-identical siblings like full_audit, deep_scan, and security_workflow present, the description gives no explicit when-to-use or when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses diff-only scanning semantics, the three output surfaces (Check Runs, PR comments, inline annotations) and severity-based blocking. It omits whether the tool mutates anything, what permissions/CI auth it needs, and how blocking is signalled to the caller.

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 short sentences, front-loaded with purpose, then scope, then output and gating. No filler and every clause carries information the agent needs.

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

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

No output schema exists, and the description covers the return surfaces well enough to act on; all five parameters are schema-documented. What is missing for a CI-integrated mutation-adjacent tool is auth/permission expectations and how the blocking outcome is reported.

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% and both enums are documented there, so the baseline is 3. The description reinforces diff_only and fail_on conceptually ('diff-only mode', 'severity gating to block PRs') but adds no format or semantics beyond the schema, and its 'scans only changed lines' phrasing slightly oversimplifies diff_only=false.

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 and resource ('Review a pull request for security issues') and scopes the work to changed lines, which distinguishes it from repo-wide siblings like full_audit, check_project and audit_config. It does not explicitly name the sibling it replaces, 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?

Usage is implied by 'pull request' plus 'diff-only mode', which signals a PR-scoped review, but the description never says when to choose this over scan_staged, scan_changed_files, check_code or full_audit, nor when not to use it. The reader must infer the routing decision.

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 and does explain the key behavioral trait: diff-aware mode is on by default and reports only findings on newly-added lines, with instructions to set diff_aware:false for whole-file scanning. It does not state the read-only/non-destructive nature of the scan or any prerequisites such as needing a git repository, which is a minor gap for an unannotated 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 short sentences, each doing distinct work: scope, use cases, then default behavior with the opt-out. The scoping constraint is front-loaded and nothing is redundant.

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 four-parameter scan tool with no output schema and no annotations, the description covers purpose, usage context, default behavior, and roughly what is returned. It lacks any safety/read-only statement and repository prerequisite, which would complete the picture given the annotation 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 100%, so all four parameters are already documented. The description adds a few examples for 'base' (branch, commit, HEAD~N) and clarifies the diff_aware default, but mostly restates what the schema provides; baseline 3 applies.

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

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

The description states a specific verb ('scan') applied to a well-scoped resource ('only files that have changed since a given git ref'), so the purpose is unambiguous. However, it never names or contrasts with the closest sibling, scan_staged, which also targets uncommitted changes, leaving the boundary to be inferred.

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 supplies concrete use cases ('PR checks, pre-push hooks, and incremental CI'), giving the agent clear when-to-use context. It gives no explicit when-not-to-use or 'use X instead' alternatives, so it falls short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the detection scope and that the operation is a comparison, but it omits whether the tool is read-only, whether it writes anything, whether it requires repository context, and what kind of response it produces.

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 a compact, readable list of detection categories. Every element contributes to the tool's purpose, 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?

The description adequately covers the tool's purpose and detection surface, and the schema fully documents the four parameters. However, with no annotations and no output schema, it should say more about usage boundaries, read-only behavior, and/or expected result shape to be fully complete for an agent.

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

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

Schema coverage is 100%, so before, after, format, and file_path are already documented in the schema. The description does not add any parameter-level meaning beyond what the schema provides, 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 gives a specific verb and resource: 'Compare before/after versions of a config file to detect security downgrades.' It also enumerates concrete detection categories (CORS relaxation, CSP weakening, HSTS removal, etc.), making the tool's scope clear. It does not explicitly differentiate itself from close siblings such as audit_config or scan_changed_files.

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

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

The before/after comparison framing implies when the tool is appropriate, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent can infer that this tool applies to versioned config comparisons, but must still guess against siblings like audit_config or scan_host_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?

With no annotations, the description carries the full burden; it does disclose that the file is read directly and that lookups go to the OSV database, which implies an outbound network call and a read-only posture. It says nothing about permissions, rate limits, size limits, or whether results are cached, and never clarifies that nothing is modified on disk.

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 short sentences: what it does, what it reads, and when to use it. No filler and the core action is front-loaded in the first clause.

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 no annotations, so the description should say more about what comes back (CVE ids, severity, affected packages) or about network/auth requirements. The format parameter hints at output shape but the content of a finding is never described.

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 manifest_path and the format enum are already documented; the description adds only a slightly broader format list (adding package-lock.json) and does not explain path resolution or how the markdown vs json choice affects downstream parsing. Baseline 3 is appropriate when 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?

States a concrete verb+resource chain: parse a lockfile/manifest and check dependencies for CVEs via OSV, with the supported file types enumerated. An agent immediately knows what it does, but the description never differentiates it from close siblings such as check_dependencies, check_package_health, or scan_directory, which sound near-identical.

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?

Gives explicit temporal triggers: after installing dependencies, during CI, or when auditing existing projects. However, it offers no when-not conditions and never names an alternative tool, so an agent facing both scan_dependencies and check_dependencies has no routing rule.

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

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

With no annotations, the description carries the full burden. It helpfully discloses that it reads files from the filesystem, returns a security score and findings, and may truncate results for large projects, but it does not clarify permissions, side effects, or whether any files are modified.

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 the core action, followed by concise usage, return, truncation, and example information. Every sentence serves a purpose and there is no unnecessary 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 no output schema, the description gives a useful return overview: security score (A-F), findings, possible truncation, and where to check top files in JSON output. It is mostly complete, though a bit more detail on findings structure would help.

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 schema already explains path, format, exclude, baseline, and recursive. The description adds an example path and notes fileRanking in JSON output, but does not add meaning to the other parameters 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 states a specific verb and resource: scanning all files in a directory for security vulnerabilities. It is clear what the tool does, though it does not explicitly name sibling alternatives such as scan_file or check_project to sharpen the 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?

Usage is implied by 'Pass a directory path' and the example, but there are no explicit when-to-use versus when-not-to-use guidelines and no mention of alternatives like scan_file for single files or check_project for whole-project checks.

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

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

With no annotations the description must carry the behavioral load, and it does disclose that the tool reads the file itself and what the 'agent' format contract contains (finding, exact edit, confidence, verify step). It omits any mention of output for the other formats and of side effects, but for a read-only-looking scan tool this is solid disclosure.

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

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

Three tight sentences plus an example; the core action and scope come first, the alternative second, and the format payoff last. Nothing is redundant.

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

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

No output schema exists, and the description covers the most consequential return case ('agent' format) with enough detail to call correctly. It leaves markdown/json outputs undescribed, a minor gap for a two-parameter 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 the baseline is 3; the description goes further by explaining the semantic value of the 'agent' enum value (machine-actionable contract with exact edits and confidence) beyond the schema's own wording, plus a concrete usage example.

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 and resource ('Scan a single file on disk by path for security vulnerabilities') and makes the scope explicit ('single file', 'by path'), which cleanly separates it from scan_directory and full_audit without opening any schema.

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 routes inline snippets to check_code and clarifies that the caller passes a path rather than code. That is a clear when/when-not split, though it does not distinguish against the many other scan_* siblings (scan_staged, scan_secrets, deep_scan).

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

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

With no annotations, the description carries the full load and does so: it discloses the default-on network call, graceful degradation to offline, which checks run in each mode, and what each signal means (404 = definitive hallucination, new low-download = slopsquat pattern). The network/determinism tradeoff is the key behavioral trait an agent needs before calling.

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?

Front-loaded with the purpose, then structured as OFFLINE / ONLINE blocks with the opt-out instruction last — easy to scan. Slightly dense with marketing flavor ('supply-chain seam', parenthetical asides), but no sentence is redundant.

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, and the description says what is flagged but not the shape of findings or severity levels; the schema's guardvibe.slopscan.v1 hint partially covers this. For a 3-param, zero-required scan tool it is otherwise complete enough to invoke 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 the baseline is 3; the description earns an extra point by explaining the consequence of `online` (registry truth vs deterministic phantom+typosquat checks) and by noting the json output is versioned for agents. `path` and `format` remain schema-only.

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?

A concrete verb ('Detect') plus a specific resource ('AI-hallucinated and slopsquatted packages in a repo'), with the phantom-import and typosquat/404/new-package signatures spelled out. The 'supply-chain seam commodity SCA misses' line separates it cleanly from the generic dependency scanners 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?

Gives clear operating context — run on AI-generated code at PR time, before `npm install` — and states the online:false alternative for air-gapped runs. It stops short of naming sibling tools (e.g. scan_dependencies, check_dependencies) that an agent might otherwise pick, so the routing 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?

No annotations are provided, so the description carries the full burden, and it does disclose the concrete categories of checks performed, including a named CVE. It still omits whether the tool is strictly read-only, whether it touches or writes any config, permission requirements, and any runtime/performance characteristics for host-scope scans.

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

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

Two sentences, front-loaded with the security-issue inventory before the scope escalation note, with no filler. Slightly list-heavy, but every item conveys a distinct check the agent could not otherwise infer.

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?

Three optional parameters, no annotations, and no output schema, so the description must carry more weight than it does. It covers what is scanned and scope escalation, but says nothing about the return shape beyond the `format` param and omits the `full` scope, leaving meaningful gaps for a security-scanning 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% and both enums are documented in the schema, so the baseline is 3. The description reinforces the project-vs-host distinction for `scope`, but never mentions the third enum value `full` (home dir) or the `format` parameter, so it adds only partial value 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?

States a specific verb and resource ('Scan host environment for AI security issues') and enumerates the exact issues covered: API base URL hijacking (CVE-2026-21852), credential exposure in shell profiles, .env leaks, and env var sniffing. This clearly separates it from broad scanners like scan_secrets or full_audit, though it never names a sibling to reinforce the 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 second sentence gives real escalation guidance: project scope checks .env files, and scope=host adds shell profiles and global AI configs. However, it never says when to prefer this over scan_secrets, audit_config, or scan_config_change, nor when not to run it, leaving the sibling-routing decision to inference.

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 behavioral burden. It usefully discloses detection scope (entropy heuristics, vendor key patterns, .env exposure, .gitignore gaps) and that findings include line numbers plus remediation steps, but it never states that the operation is read-only/non-mutating, whether it traverses ignored or binary files, or how it behaves on very large trees.

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

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

Three sentences, front-loaded with purpose, then detection coverage, then return shape. Every sentence contributes and nothing is padded.

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 compensates by describing the return payload (findings with exact line numbers and remediation steps). Detection scope is well covered; the remaining gap is the lack of any read-only/side-effect statement and no mention of scan limits or skip rules.

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% and all three parameters (path, format, recursive) are documented in the schema, including the enum semantics. The description adds no parameter-level information beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Scan files and directories for leaked secrets') and enumerates the detection classes, so the agent knows exactly what it does. It fails to distinguish itself from close siblings such as scan_secrets_history, scan_staged, or scan_file, leaving ambiguity about which secret-scanning entry point to pick.

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, and no mention of alternatives despite several overlapping siblings (scan_secrets_history, scan_staged, scan_changed_files). Usage is only implied by the word 'scan'.

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

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

With no annotations, the description carries the full load, and it does disclose a real behavioral trait: findings are labeled 'active' vs 'removed' and 'removed' implies rotation is needed. That is genuinely useful output semantics. It omits what an agent would want to know for an unannotated tool — whether it's read-only (implied but unstated), cost/runtime on large repos, and that the default max_commits=100 truncates the scan.

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, front-loaded with the core action, followed by the differentiating detail and the finding classification. No filler or redundancy.

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

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

Adequate for a simple read-only, three-parameter tool with a fully documented schema: the agent knows what it does and what findings look like. It stops short of routing the agent among the many sibling scan tools and doesn't note the commit-cap limitation, so it's viable but not complete for a crowded tool family.

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

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

Schema coverage is 100% with all three parameters documented, including the enum for format and the default of 100 commits, so the schema does the work. The description adds no parameter-level detail such as what the path must point to or the consequences of raising max_commits. Baseline 3 applies.

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

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

Specific verb+resource ("Scan git history for leaked secrets") with an explicit scope statement that it finds secrets "committed in the past — even if they were later removed." That scope cleanly separates it from the sibling scan_secrets (working-tree scan) without needing to name it.

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?

Usage is strongly implied by "in the past — even if they were later removed," so an agent can infer this is the history counterpart to a current-code scan. But no sibling is named and there is no explicit when-not guidance (e.g., use scan_secrets for the working tree, or that the default 100-commit cap limits coverage).

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses that no input is needed, that staged files are read automatically, and that diff awareness defaults to true, but it does not state whether the scan is read-only, what the output contains, or any repo/permission constraints.

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 short and front-loaded with the core action and timing. The only minor inefficiency is that 'before committing' and 'before every commit' restate the same timing 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?

Given the low-complexity schema and no output schema, the description gives enough for an agent to invoke it correctly. It could say more about the return shape or the format parameter, but the schema covers those details adequately.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions diff_aware behavior, but this largely repeats the schema's own explanation and does not add syntax, defaults, or edge-case guidance beyond 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?

States a specific verb and resource: scanning git-staged files for security vulnerabilities. The scope ('git-staged files', 'before committing') clearly separates it from sibling tools that scan directories, changed files, dependencies, or full projects.

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 to run it before every commit, giving a clear usage occasion. It does not name alternatives or exclusion cases, such as when to prefer scan_changed_files or full_audit instead.

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

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

With no annotations, the description carries the full burden and does so well: deterministic, no LLM, no network, plus the three verdicts and what each implies (NO_MOD proceeds unchanged, HEAVY_MOD surfaces but never invents answers). It omits any mention of latency/limits or how rules are configured, which keeps it just short of the top.

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?

Front-loaded with the core action, then behavior, then example — a logical order with no filler. It is a dense single paragraph, though, and the parenthetical framework/attack-surface lists add bulk that could be tightened.

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

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

No output schema exists, and the description compensates by enumerating the return shape (verdict + intent summary + numbered [rule-id] requirements + rewrite directive). Combined with the verdict semantics and detection scope, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so the baseline is 3; the description adds value by showing a concrete example invocation and emphasizing that raw_prompt is the verbatim pre-code prompt to be analyzed, clarifying the intended input beyond the schema's 'verbatim' note.

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?

Opens with a specific verb and resource ('analyze a raw coding prompt BEFORE any code is written') and states the concrete return ('structured enhancement directive'). It explicitly distinguishes itself from the sibling scan/check tools by being pre-generation rather than post-hoc 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?

'Call this with the user's prompt before generating code; prevents vulnerabilities before code generation instead of scanning after' names both the trigger and the alternative it replaces. The example call anchors the usage in a concrete scenario.

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 exist, so the description carries the full burden, and it does: it discloses that candidate edits are re-scanned and rolled back if they don't resolve the issue or introduce a new one, that the tool does not write files itself, and what the response contains. It also defines the status vocabulary (clean|secured|partial|no_autofix) and the meaning of remaining[] and proofTest, which are exactly the behaviors an agent could not infer.

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 core purpose and the alternative-route are front-loaded, then return shape, then required workflow, then an example — a sensible ordering. It is dense but slightly overstuffed: the return shape and the 'write fixedCode to disk' instruction overlap, and the example adds little given a 100%-covered schema.

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, so the description must describe the return payload, and it does in detail: status enum, fixedCode, applied[], remaining[], definitionOfDone, proofTest. Combined with rollback semantics and the disk-write convention, an agent has everything needed to invoke and act on 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 description coverage is 100%, so both required parameters and the two optional ones are already documented; the description adds only an example call with code and language. It does not explain how framework or filePath change analysis behavior beyond what the schema states, so this sits at the baseline appropriate when 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 opens with a specific verb chain (scan, apply verified fixes, return verified code plus a definition-of-done gate) applied to a concrete resource: vulnerabilities in code. It explicitly names the sibling combination it supersedes (fix_code+verify_fix), so an agent can distinguish it without opening any schema.

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 gives an explicit selection rule — 'Prefer this over fix_code+verify_fix when you want a guarantee the fix landed — not just a suggestion' — plus a post-call workflow: write fixedCode to disk, gate completion on definitionOfDone.passed, and treat remaining[] as manual work. When-to-use, when-to-prefer-an-alternative, and what to do next are all stated.

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 usefully discloses the data source ('stored locally in .guardvibe/stats.json'), which implies a read of prior scan history rather than a live scan, but it never states that the call is read-only, what happens when no stats file exists yet, or whether prior scans are a prerequisite.

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 short sentences, front-loaded with the output content, then the use case, then the storage detail. The middle sentence is slightly promotional but still carries usage signal, so there is little 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?

With no output schema and no annotations, the description does name the three categories of returned data and the storage location, which is close to sufficient for a read-only reporting tool. The main remaining gap is the empty-state / prerequisite condition (stats only exist after prior scans).

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% and both enums (format, period) are documented in the schema, so the baseline is 3. The description adds nothing about how 'period' interacts with cumulative totals or what 'path' means relative to the stats file location.

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 ('Show') plus three concrete resources: cumulative security statistics, grade trend, and vulnerability fix progress, scoped to 'this project'. That is enough to distinguish it from action-oriented siblings like full_audit or fix_code, though it does not explicitly contrast with reporting siblings such as compliance_report or repo_security_posture.

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?

'Use this to demonstrate the value of GuardVibe security scanning over time' gives a use case, but it is framed as a motivation rather than a decision rule. There is no when-not guidance and no named alternative among the many reporting/audit siblings, so the agent must infer whether this or compliance_report/repo_security_posture fits.

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 does disclose the return shape (an ordered tool sequence with parameters), which tells the agent this is advisory. However, it never states that it performs no scanning itself, whether the recommendation is static or state-dependent, or what happens if the agent deviates from the sequence — the things an agent most needs to know for a router 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 short sentences: what it returns, when to use it, and a concrete example — front-loaded with zero waste. The example earns its place by demonstrating invocation, not padding.

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 router with a fully documented enum and no output schema, the description is nearly sufficient — the agent knows what it gets back and when to ask. The remaining gap is that its advisory, non-executing nature and the presence of the direct-execution siblings are implied rather than stated.

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 `task` parameter has 100% schema description coverage including a 12-value enum with per-value parenthetical guidance, so the schema already does the heavy lifting. The description adds an illustrative valid value ('pre_commit') and the framing 'your current task', but contributes no semantics beyond the enum documentation.

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 and resource ('Get the recommended GuardVibe tool sequence') and explicitly names the payload: which tools, in what order, with what parameters. This cleanly distinguishes it from the ~38 sibling scanning/fixing tools, which do the actual work rather than route.

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?

'Use this when unsure which tool to use' gives a clear positive trigger, and the example call shows the invocation shape. It stops short of an exclusion (e.g. 'skip this if you already know the right tool'), so an agent must infer that it is a fallback rather than a mandatory first step for every request.

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 exist, so the description carries the full burden. It does useful work by disclosing the three possible outcomes ('fixed', 'still_vulnerable', 'new_issues') and the fact that it re-scans rather than trusting prior results, but it never says whether the scan is read-only, what permissions or cost/latency are involved, or what 'details' contain.

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 short sentences with the purpose, mechanism, and return values front-loaded in that order. No filler, though the final sentence listing statuses could be tightened.

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 annotations and no output schema, the description covers purpose and outcome vocabulary but omits the sibling disambiguation (verify_remediation) and any statement about side effects or return detail structure. Adequate but with visible gaps.

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

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

Schema description coverage is 100%, so the four parameters are already documented in the schema and the baseline is 3. The description reinforces that ruleId targets the vulnerability and that code should be the post-fix version, but adds nothing about filePath or language 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 uses a specific verb ('Verify') with a concrete resource ('a specific security fix') and states the mechanism (re-scan of updated code, matched by rule ID). It is clear on its own, but it does not distinguish itself from the closely named sibling verify_remediation, leaving ambiguity for an agent choosing between the two.

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?

Usage is implied: call this after applying a fix to confirm the vulnerability is gone. There is no explicit when-to-use/when-not guidance and no mention of the overlapping sibling verify_remediation, so an agent must infer the routing decision 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?

With no annotations provided, the description carries the full burden and does well: it discloses that a fresh audit is executed (a non-trivial side effect), that a before-snapshot is compared, that skipped sections are flagged, and that 'complete' is withheld unless everything is addressed. It omits cost/runtime and whether the tool writes anything to disk, which keeps it below 5.

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?

Front-loaded with the purpose and the mandatory-call rule before the mechanics, and almost every sentence adds information. The trailing example is somewhat redundant given 100% schema coverage and three short parameters, costing a bit of tightness.

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

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

No output schema exists, and the description partially compensates by describing what the result conveys (skipped-section flags, refusal of 'complete' status). It does not sketch the actual return shape or the format parameter's effect, leaving a small gap for a verification 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 baseline is 3, but the description adds real meaning: it explains that before_hash may be supplied 'or let it re-run', clarifying the consequence of omitting an optional parameter beyond the schema's terse 'for tracking' note. The example call reinforces which keys matter.

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 and resource: 'Compare before/after audit results to verify ALL sections were addressed', which is clearly distinct from full_audit and remediation_plan. It does not, however, differentiate itself from the close sibling verify_fix, which an agent could easily confuse with this tool.

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

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

'MUST be called after completing remediation to confirm success' gives an unambiguous trigger condition, and 'Pass the before audit hash or let it re-run' resolves the optionality decision. It stops short of naming when-not-to-use cases or pointing at verify_fix/explain_remediation as alternatives.

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