lazaretto

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

With no annotations provided, the description carries the full burden. It discloses that the tool is free and anonymous, and explains fail-closed behavior: 'anything that could not be checked is returned in `unverified`, so an empty `malicious` list is an all-clear only when `unverified` is empty too.' This provides key behavioral context beyond a simple mutation warning. It does not contradict any annotations, as none exist.

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 three sentences, each purposeful and informative. The first sentence fronts the core purpose. No redundant or vague language exists. Every sentence earns its place, making it highly efficient for an AI agent to parse.

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 (one required parameter, no output schema), the description adequately covers usage context and output semantics. It explains fail-closed behavior and the meaning of the 'unverified' list, giving agents enough information to interpret results. However, without an output schema, a more explicit listing of return fields (e.g., 'malicious', 'unverified') would improve completeness.

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 schema covers 100% of parameters (only 'lockfile') with a clear description. The description adds value by specifying the accepted formats: 'Accepts the contents of a package-lock.json, yarn.lock, or pnpm-lock.yaml.' This clarifies that the input must be the full text, not a path or URL, which is not explicit in the schema. Since schema coverage is high, baseline is 3, and the description provides meaningful extra detail, earning a 4.

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 purpose: 'Check every EXACTLY-PINNED dependency in a lockfile against published malicious-package advisories (OSV/OpenSSF).' It specifies the verb 'check', the resource 'dependencies in a lockfile', and the scope 'malicious-package advisories'. This distinguishes it from siblings like 'known_bad_lookup' and 'scan_artifact', which target individual packages or artifacts rather than lockfile trees.

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 explains when to use the tool: 'Free, anonymous, one call for the whole tree.' It also clarifies a limitation: 'Only exact versions can be answered: a range like ^5.0.0 has no definitive answer.' This implies that users should only use this tool for lockfiles with pinned versions. However, it does not explicitly contrast with sibling tools, missing a direct 'when not to use' statement.

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

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

With no annotations provided, the description carries full burden and excellently discloses behavior: the set is refreshed daily, the lookup is free and anonymous, and a miss does not imply a clean verdict. No contradictions.

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, consisting of two sentences that front-load the essential action and limitation. Every sentence adds value, and there is no extraneous information.

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 single parameter, no output schema, and clear explanation of behavior and limitations, the description is fully complete for an agent to select and invoke the 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?

The input schema already fully describes the sha256 parameter (64 hex chars, optional prefix). The description does not add additional parameter semantics beyond what the schema provides, so 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 clearly states the action ('Check a SHA-256 against Lazaretto's known-bad indicator set') and distinguishes itself from sibling tools like check_lockfile and scan_artifact by focusing specifically on hash lookups against a curated indicator set.

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 mentions that the tool is free and anonymous and clarifies the meaning of a miss ('not a clean verdict'). However, it does not explicitly specify when to use this tool versus alternatives like scan_artifact, which might provide broader analysis.

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

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

No annotations provided, but description fully covers behavioral aspects: deterministic analysis, credit consumption, required header, and output format (verdict, evidence, hash). No contradictions.

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?

Two focused sentences plus credit purchase info. Front-loaded with main purpose. No wasted words.

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 no output schema, description adequately describes return values. Covers all parameters, required header, and credit system. Complete for a scanning tool.

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 covers 100% of parameters with descriptions. Description adds value by clarifying ref omission for inline type and content requirement. Explains depth enum values beyond schema.

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?

Clearly states the tool analyzes artifacts for malicious behavior and returns a verdict. Distinguishes from sibling 'known_bad_lookup' by noting it as a free alternative.

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?

Provides explicit context on prepaid credits and suggests known_bad_lookup for free checks. Lacks explicit 'when not to use' but alternative is clear.

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

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 clearly states the tool is free and anonymous, does not rescan, returns specific outputs (signature validity, claims, contradicted flag), and explains the meaning of 'contradicted'. This is rich behavioral context that goes beyond what one would expect, covering side effects, return values, and logical behavior.

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 front-loaded with the core action and then expands with essential context. It is slightly longer than the minimum but every sentence earns its place: the 'free and anonymous' note, return-value summary, and security caveat all add value. Structure is logical and easy to parse. A 5 would require even tighter phrasing with no redundancy.

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 has only one parameter, no annotations, and no output schema, the description does a solid job of explaining return values and prerequisites. It clearly states what the function returns and even explains the 'contradicted' flag. However, it leaves some ambiguity about the exact shape of the return (e.g., is 'valid' a boolean? how are claims nested?). A tiny bit more detail on return structure would make it complete, but as-is it is quite comprehensive.

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 schema has 100% coverage for the single parameter 'attestation', so the description does not need to add much for the parameter itself. The description adds context about where attestations come from (another agent, README, lockfile) and underscores the need to cross-check claims.sub, but it does not elaborate on the compact-JWS format beyond the schema. This is adequate but not exceptional, so a 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 opens with a specific verb ('Verify') and a specific resource ('Lazaretto scan attestation'), immediately clarifying the action. It also distinguishes itself from sibling tools by explicitly stating 'WITHOUT re-scanning or paying', which differentiates it from scan_artifact. This makes the tool's purpose unmistakable and well-scoped.

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 clear context for when to use this tool: when handed an attestation by another agent, README, or lockfile. It also provides an important caution ('You MUST still confirm the artifact... matches claims.sub'), which is a usage guideline. However, it does not explicitly name alternative tools (e.g., scan_artifact) or state when to avoid this tool, so it misses the 'when-not' dimension that would earn a 5.

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