Audit Package

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

Beyond readOnlyHint/openWorldHint, it discloses substantial operational context: large PyPI projects require an explicit version due to a size cap, npm versions lack publish time so recency is skipped, PyPI has no install-script check, and download counts/age/owner history are unavailable. It also frames findings as indicators not verdicts and points to the coverage field for ran/skipped checks.

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 cap description, then clearly labeled Use when / Prefer / Limits / caveat blocks; nearly every sentence carries unique information. The limits block is dense and long relative to the rest, but it is structured rather than rambling.

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 three-parameter read-only audit with an output schema present, the description covers what is checked, what is deliberately not checked, ecosystem-specific gaps, and the interpretation caveat about findings. Nothing an agent needs to call it correctly or to caveat its answer 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why an explicit `version` matters (large PyPI project documents exceed the resolution size cap) rather than just what the field is. The ecosystem/name semantics are already fully covered by the schema, so it doesn't go higher.

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 one PyPI or npm package version's supply-chain signals') and enumerates the concrete checks (OSV vulnerabilities, yanked/deprecated, install scripts, provenance, recency, repo). It explicitly differentiates itself from the sibling audit_server, so an agent can pick it 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?

Has an explicit 'Use when' clause (the user asks about a specific package/version, e.g. one a config pins) and an explicit 'Prefer another tool when' clause naming audit_server for full server checks. Both the selection and deselection conditions are stated, leaving nothing to inference.

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