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

The annotations already cover safety because the tool is read-only, idempotent, open-world, and non-destructive. The description adds value beyond that: it explains the three possible outcomes, warns that 'unknown is not clean' and that 'no matches is not proof of safety', and discloses that cache misses send package identities and versions to OSV. This is genuine behavioral context an agent could not infer from the 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 definition is front-loaded with purpose, then input forms, then outcome semantics, then the privacy note. Every sentence carries information, so nothing is redundant with the schema or annotations.

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?

An output schema exists, so the description does not need to explain return values. Still, the definition covers batch limits, input modes, outcome interpretation, and outbound data disclosure, which is everything needed to call this single-parameter, open-world tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining that identity can be supplied in two alternative shapes—ecosystem or packageManager plus name and exact version, or a purl—which the flat schema does not make explicit, and by restating the exact-version and batching rule. It could still clarify which identity fields are required in each mode.

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 definition opens with a specific verb and resource: checking installed package versions against OSV advisories, plus a hard batch bound of 100. That is enough for an agent to tell it apart from sibling lookups such as get_cve (single advisory) and list_ecosystems (enumeration).

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 definition gives clear positive guidance on how to invoke the tool: supply 'ecosystem or packageManager plus name and exact version, or a Package URL'. It also states an explicit prohibition against sending raw files, source code, or secrets. It does not name sibling tools or say when to prefer get_cve, so it falls short of full alternative routing.

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