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?

With no annotations, the description carries the full burden and does well: it discloses that analysis is deterministic, states the output verdicts (malicious, flagged, clear, error), mentions exact evidence and hash, and reveals metering/payment behavior. It stops short of describing rate limits or full response structure, but the core behavioral traits are covered.

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 first sentence is a bit long but front-loads the core purpose effectively. The payment and alternative-tool information is relevant and justified given the tool's metered nature, though the several payment URLs and cost details make the description denser than ideal.

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 no output schema and no annotations, the description compensates well by explaining the verdict, evidence, hash, payment requirements, and free alternatives. It could briefly mention expected response structure or error cases, but on the whole it provides enough context for an agent to call 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 documents all four parameters at 100% coverage, so the baseline is 3. The description does add some semantic context, such as 'lookup' meaning known-bad match only in the depth description, but this mostly mirrors the schema's own parameter descriptions rather than contributing substantial new meaning.

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 identifies a specific action ('deterministically analyze'), the resource type ('package, repo, skill, or file'), and the exact purpose ('malicious behavior'), listing concrete threat categories. It differentiates from siblings by explicitly stating that check_lockfile and known_bad_lookup are for always-free checks.

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 provides clear direction on when to use this tool versus alternatives, explicitly naming check_lockfile and known_bad_lookup for free checks. It also supplies practical authorization instructions: API key, wallet-based x402 payment, and a free trial key endpoint, which is unusually actionable.

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.