Security Audit

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by naming the actual audit mechanisms (npm audit, cargo audit, pip-audit, composer audit, govulncheck), which implies external tool invocation and potential network access. It also highlights a cautionary timing rule. No contradiction with annotations.

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

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

The description is concise and well-structured. It front-loads the primary purpose, includes a critical usage note, and provides three clear example queries. Every sentence contributes to understanding the tool's function and usage. The use of a bold 'CRITICAL' callout adds emphasis without 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?

Given the tool's simplicity (two optional parameters) and thorough annotations, the description covers the essential aspects: purpose, trigger timing, and example usage. It does not describe the return format in detail (no output schema), but the examples imply a list of CVEs/vulnerabilities, which is reasonable for a scan tool. It could mention potential runtime or network dependencies, but those are not critical given the read-only annotations.

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

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

The input schema already provides a description for both parameters (project and directory) with 100% coverage. The description adds no additional parameter-specific semantics beyond what the schema offers. The examples illustrate usage but do not clarify parameter behavior further. Thus the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource combination: 'Scan projects for known security vulnerabilities (CVEs)', clearly stating the tool's core function. It names the underlying audit tools (npm audit, etc.), which adds specificity. However, it does not explicitly differentiate itself from sibling tools such as depsonar_cve or depsonar_live_cve, which likely also deal with CVEs, so it misses the sibling-distinguishing criterion.

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

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

The description provides a clear trigger for when to use the tool: 'CRITICAL: Run this after any CVE announcement (e.g. Svelte CVE-2026-22775, devalue DoS).' This gives explicit contextual guidance. It also includes example user queries, helping an agent recognize valid use cases. However, it does not specify when NOT to use it or point to alternative sibling tools, so it stops short of full exclusions/alternatives.

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