pkg-oracle — Dependency Trust Oracle

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It details the specific checks performed (registry existence, OSV CVE cross-reference, OpenSSF Scorecard, typosquat check against a curated list with publish age) and the possible return verdicts (ALLOW, WARN, BLOCK) with their meanings. No side effects are mentioned, but as a verification tool it is expected to be non-mutating.

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

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

The description is a single, dense paragraph where every sentence adds value: it names the tool, states when to call it, enumerates the checks, explains the verdicts, and reiterates the usage mandate. It is front-loaded with the most important usage instruction and avoids fluff.

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

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

The description is contextually complete despite the lack of an output schema. It explains the return verdicts (ALLOW/WARN/BLOCK) and their meaning, provides the use case (pre-install verification), and covers the tool's behavior comprehensively. The rich parameter schema covers the input side, and the description fills in the output/behavioral context.

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 fully documents all three parameters (name, version, ecosystem). The description does not add additional parameter-specific semantics beyond what the schema provides (e.g., 'version' is described as optional in both the schema and description). Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with specific verbs and resources: it 'checks whether the package actually exists', 'cross-references OSV.dev for known CVEs', 'pulls the package's OpenSSF Scorecard', and 'runs a Levenshtein-distance typosquat/slopsquat check'. Although there are no sibling tools to distinguish from, the purpose is unmistakable and highly specific.

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

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

The description gives explicit when-to-use guidance: 'Call this BEFORE writing any package into a manifest' and 'Always call this before running an install command for a package you have not already verified'. It also explains the context of verifying packages before they are added, making the usage conditions clear.

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