check_dependencies

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

The annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that by naming the specific checks performed, the OSV.dev data source, and the 'direct dependencies' scope, which clarifies that transitive dependencies are not the focus. No contradiction with annotations exists.

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

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

The description is tight and front-loaded: the opening sentence states the purpose and scope, followed by a minimal Args block. There is no filler or repetition of schema details, and 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?

With a single optional parameter, rich annotations, and an output schema available, the description covers everything needed for correct invocation. It explains what the tool checks, the dependency scope, and the path semantics without over-explaining return values that the output schema already documents.

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

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

Schema description coverage is 0%, so the description must clarify the only parameter, path. It does: 'Project root. Defaults to the client's workspace root.' This resolves the schema's opaque default null and gives the agent enough semantic grounding to invoke the tool correctly.

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

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

States a specific verb ('check') and resource ('direct npm/PyPI dependencies'), and enumerates the exact threat categories it covers: hallucinated packages, typosquats, suspiciously new packages, and known vulnerabilities via OSV.dev. This scope clearly differentiates it from broader siblings like scan_project without needing to inspect them.

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

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

The description implies usage context via 'direct npm/PyPI dependencies' and the optional path argument, but it never explicitly states when to prefer this tool over siblings like scan_project or scan_snippet. There are no exclusions or alternative routing guidance, so the agent must infer applicability from the scope wording alone.

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