lazaretto

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

Goes far beyond the readOnly/idempotent hints: explains the service is free and anonymous, requires exact versions, and is fail-closed with an `unverified` bucket for anything not checked. It also spells out that `truncated: true` means omitted packages were never examined, and clarifies that `checked` counts only examined packages. No contradiction with 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?

Long but every sentence earns its place: purpose, input selection, exact-version constraint, fail-closed interpretation, and truncation handling are all material to using the tool correctly. Information is front-loaded and ordered logically. No filler or 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?

Combined with the rich output schema and annotations, this is complete: it defines all-clear conditions, explains truncation consequences, and tells the agent exactly how to recover with a follow-up call. Nothing necessary for safe, correct invocation 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?

The schema already documents both parameters fully, so the baseline is 3. The description adds real usage nuance: `lockfile` means full text of supported lockfiles, `packages` means name@version strings and is preferred when only a few deps matter or the tree won't fit in context; it also reinforces mutual exclusivity with 'never both'. This is moderately additive but partly repeats schema language.

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 an explicit verb and resource: check exactly-pinned npm dependencies against OSV/OpenSSF malicious-package advisories. The 'one call for the whole set' and exact-pinning scope signal a distinct batch security-check tool, though it does not explicitly name `scan_lockfile_deep` or describe how it differs from that sibling. Therefore very clear but not perfectly differentiated.

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 concrete selection guidance: pass `lockfile` for the whole tree or `packages` when only a few dependencies matter or the tree would not fit in context, and explicitly says never both. It also gives exclusion criteria (ranges cannot be answered) and a follow-up strategy for `truncated: true`. It doesn't name sibling tools as alternatives, so it falls just short of full cross-tool routing.

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?

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds significant behavioral detail: it makes no network call, is 'metered like scan_artifact' (indicating a cost), and detects specific threat types (tool poisoning, hidden directives, etc.). It also warns that it applies the same rules as scan_mcp_server, preventing false assurance. This goes beyond the annotations without contradicting them.

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 compact and front-loaded: first states the core purpose, then the rationale, then the input format, then the analysis scope and metering. Every sentence adds value, though it packs a lot of information into five sentences. It could be slightly more terse, but the structured flow makes it easy 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?

For a single-parameter tool with an output schema, the description covers everything needed: the input format, the local-only behavior, the detection capabilities, the metering, and the relationship to scan_mcp_server. No crucial information is missing, and the output schema handles return values.

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 documents the parameter thoroughly. The description's mention of 'a whole tools/list response, a {...} object, or a bare array' exactly mirrors the schema text, adding no new information. Baseline 3 applies because the schema carries the full semantic load.

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 starts with a clear verb and resource: 'Check tool definitions you ALREADY HOLD, with no network call to anyone.' It explicitly distinguishes from scan_mcp_server by noting it analyzes the same text but requires no network, making the tool's unique scope obvious.

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 this tool: when you already have the tool definitions locally and cannot reach the server over the network ('Most MCP servers run locally over stdio and have no endpoint... this is the only way to check them'). It also references scan_mcp_server as the counterpart, implying that server is used when network access is possible. It doesn't explicitly state 'use scan_mcp_server for network scanning,' but the context makes it 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavior: anonymity, offline verifiability, freshness semantics, fallback to unsigned identity checks, and how malware hits and unconsulted corpus states are encoded. This aligns with the openWorldHint and adds substantial context.

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 critical 'before install or paid scan' guidance, and most sentences carry important nuance. However, it is verbose and repeats the 'miss is not a verdict / absence is not a verdict' idea multiple times. A tighter structure with bullets would make the dense fallback and error semantics easier 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?

All important operational states are covered: signed verdicts, freshness, misses, fallback identity checks, malware hits as errors, and null as 'unchecked.' Since an output schema exists, the description does not need to document return shapes, but the behavioral nuances are fully explained.

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 already describes `subject`, but the description adds real meaning by enumerating the accepted forms: package identity, MCP server endpoint URL, and sha256 content hash with an optional `sha256:` prefix. It also explains how subject type affects fallback behavior, which the schema alone does not convey.

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 precise action—'Ask whether anyone has already attested an artifact'—and clearly identifies the resource. It also distinguishes itself from scan/verify siblings by telling the agent to call it 'BEFORE you install it or pay to scan it' and by noting the returned verdict can be verified offline.

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?

It gives clear when-to-use context: before installing, before paying for a scan, and for a free/anonymous check. It also warns that 'a miss is not a verdict,' which prevents misuse as a clearance check, but it does not explicitly name the scan alternatives or state when not to use this tool.

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?

Annotations are minimal (readOnlyHint false, etc.), so the description carries the burden. It discloses critical behaviors: one credit consumed per verdict (and none on error), throttling to one key per source per window, and that the key is shown once and cannot be recovered. This goes well beyond what annotations provide and is fully transparent.

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 purpose, then covers usage, throttling, and storage in a logical sequence. Every sentence provides essential information without redundancy. It is appropriately sized for the complexity of the tool.

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 output schema is present and parameters are none, the description fully covers what an agent needs: the key's behavior, how to use it, its limitations, and the one-time display. Nothing essential is missing for correct invocation and handling.

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 tool has zero parameters and schema coverage is 100% (trivially). Per the baseline for 0 params, a 4 is appropriate. The description does not need to explain parameters and adds no parameter-specific information, which is expected.

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 ('Get') and the resource ('free developer key'), with the specific scope 'for the metered tools on this server'. It also distinguishes itself from the sibling scanning/checking tools by its purpose, so there is no ambiguity about what it does.

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?

It provides clear context on when to use it (when a key is needed without leaving the session) and how to present it (X-API-Key header). It mentions throttling and the one-time nature, which informs usage frequency. It doesn't explicitly name alternatives, but the sibling tools are obviously different in function, making the usage context 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds valuable behavioral context by stating the indicator set is refreshed daily from abuse.ch and, crucially, that a miss is not a clean verdict on the artifact. This goes beyond the annotations by explaining interpretation semantics.

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 two sentences long, front-loads the core action and resource, and wastes no words. Every sentence adds value: the first establishes what the tool does, the second clarifies an important interpretation caveat. This is exemplary conciseness.

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 simple one-parameter lookup tool with a rich annotation set and an output schema (not shown but indicated), the description is complete. It covers the essential behavioral nuance (miss ≠ clean verdict) and the data freshness. Nothing an agent needs to correctly invoke the tool 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 description coverage is 100% for the single parameter (sha256), which fully documents the format and optional prefix. The description adds no additional information about the parameter, but given the high coverage, a baseline of 3 is appropriate. No extra semantic value is provided beyond the 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?

The description clearly states the verb 'Check', the resource 'SHA-256 against Lazaretto's known-bad indicator set', and adds important context about being free and anonymous. It also clarifies the meaning of a miss. However, it does not explicitly differentiate from sibling tools like scan_artifact or check_lockfile, so it falls short of a 5.

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 implies usage: you would use this to quickly check a hash against a known-bad list, and the 'free and anonymous' note hints at when this tool is appropriate. However, it does not explicitly state when to use this versus alternatives, nor does it mention any exclusions or prerequisites. The guidance is implicit rather than explicit.

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?

The description adds significant behavior beyond the annotations: it discloses that the call is metered, requires an X-API-Key with credits, offers an alternative payment method at a specific endpoint, and describes the deterministic verdict/evidence/hash return contract. It does not mention rate limits or side effects like network access, but the annotations already cover read-only/destructive/idempotent flags, so this falls just short of full transparency.

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 front-loads the core purpose, the second covers metering and payment specifics, and the third routes the agent to free alternatives. Every clause earns its place, and despite containing cost endpoints and examples, the description stays efficient with no filler or repetition.

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 complexity (metered, multi-artifact-types, payment options) and that an output schema exists for the verdict structure, the description provides the essential context: what gets scanned, what cost to expect, how to pay, and which alternatives to choose instead. It could still mention rate limits or specialized siblings like scan_mcp_server/scan_lockfile_deep, so it is just shy of fully complete.

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%: every parameter (ref, name, type, depth, content) is already documented in the schema with formats and defaults. The description adds little beyond restating that it analyzes packages/repos/skills/files and the free-check alternative. Since the schema carries the full parameter load, 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 opening sentence names a specific action ('Deterministically analyze'), a specific resource set ('package, repo, skill, or file'), and the outcome ('verdict, evidence, and a hash'). It also explicitly differentiates itself from siblings by telling the agent to use check_lockfile or known_bad_lookup for free checks, distinguishing it from those siblings at a glance.

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 explicitly states when to use this metered scan (for a full behavioral analysis with verdict and evidence) and when not to ('For checks that are always free, use check_lockfile or known_bad_lookup'). It also spells out the two payment paths (X-API-Key with credits, or x402 payment at the provided URL) and the free trial key, leaving no ambiguity about acceptable invocation conditions.

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?

Beyond the annotations, the description discloses metering (one credit per verdict, nothing for errors), the 25-package cap, lockfile-order rescanning behavior, and the continuation mechanism. It also describes what the result carries and deliberately does not carry (file-and-line evidence). None of this contradicts the provided 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?

Every sentence carries operational substance: purpose, result shape, excluded evidence, paid/free counterpart, metering, cap, continuation, and timing. It is dense without filler, though the metering and cap rules could be slightly more scannable in list form.

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 metering, cap, continuation flow, and sibling alternatives, the description provides nearly all guidance an agent needs to select and invoke it correctly. The only minor gap is the undefined behavior when both `lockfile` and `packages` are supplied, but the phrasing covers typical usage.

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. The description adds real value by explaining that repeating `lockfile` rescans the same first 25 packages and that `packages` takes name@version strings from the previous result's not_scanned.packages. The 'give this or packages' phrasing conveys the either/or intent, though it does not explicitly state the behavior if both are supplied.

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 states a specific verb and resource: behaviorally scan exactly-pinned dependencies in a lockfile and screen package code for five named threat classes. It explicitly distinguishes itself from scan_artifact (no file-and-line evidence) and check_lockfile (only name/version advisory matching), so an agent can select it unambiguously.

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?

It says when to use it ('before installing a tree you have not vetted'), when to use scan_artifact instead (for file-and-line evidence), and how it differs from the free check_lockfile. It also gives the exact continuation workflow: pass the not_scanned.packages list as `packages` instead of `lockfile`.

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?

Annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false) already signal an external side-effecting call, and the description aligns rather than contradicts. It adds substantial context beyond annotations: the tool makes an outbound network request and analyzes whatever text the server returns, the verdict is bound to a hash so a server that later changes its tools cannot inherit an old clean verdict, and the call is metered with explicit cost and endpoint details. This is rich behavioral disclosure that materially affects how an agent should use the result.

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 dense but front-loaded: the core purpose and usage trigger occupy the first sentence, followed by mechanism, detection categories, return shape, and metering. The pricing details ($0.03 USDC, endpoint path, target type) are slightly beyond what is needed for tool selection, but they are legitimate operational context for a paid tool. Every sentence earns its place; the only cost is length.

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 tool of this complexity — an outbound scanner with hash-bound verdicts — the description covers purpose, mechanism, output shape (verdict, evidence line, hash), threat categories, and cost. The output schema exists, so return values need not be fully re-explained. The only notable gap is failure behavior (unreachable servers, non-MCP endpoints, timeouts), which is minor given how much else is disclosed and the presence of structured schemas.

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% for the single required `url` parameter, so the schema already documents it and the baseline is 3. The description adds only marginal parameter context — the url is the MCP server endpoint to check before connecting — and does not give format constraints beyond what the schema presumably provides. It does not compensate or contradict, landing at the baseline.

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 and resource — "Check an MCP server BEFORE you connect to it" — then explains the mechanism (ask the server to introduce itself and list tools, analyze the returned text) and enumerates the specific threats detected (tool poisoning, secret-exfiltration parameters, cross-server shadowing, invisible unicode). This is clearly distinguished from the lockfile/attestation siblings by domain and from scan_artifact by target type, so an agent can pick it correctly without opening the 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?

"BEFORE you connect to it" gives an explicit temporal trigger for when this tool should be called, and the threat list tells the agent what kinds of servers warrant scanning. It does not, however, name when-not-to-use conditions or route to an alternative for the same task — scan_artifact is mentioned only for metering parity, not as a decision point. Clear context without exclusions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond that: it discloses it is 'Free and anonymous', details the return fields (signature validity, claims, and the 'contradicted' flag semantics), and warns about a required verification step. This goes beyond what annotations alone provide.

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 dense but efficient, front-loading the core purpose and key constraint ('WITHOUT re-scanning or paying') before explaining returns and the required follow-up. Every sentence adds value; no fluff or 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 an output schema exists (which presumably details return values), the description covers all essential context: when to use it, what it returns, a critical usage caveat (confirming claims.sub), and the free/anonymous nature. Nothing an agent needs to call it correctly 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 description coverage is 100%; the schema describes the parameter as 'The compact-JWS attestation string from a scan report.' The description adds only the nuance that the attestation may come from 'another agent (or a README, or a lockfile)', which is minor. Baseline 3 is appropriate since the schema already documents the parameter.

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 states a specific verb ('Verify') and resource ('Lazaretto scan attestation'), and immediately clarifies scope: 'WITHOUT re-scanning or paying' distinguishes it from scan_artifact. It also explains exactly what it returns, making the purpose unambiguous.

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?

Context is explicit: it's for attestations 'another agent (or a README, or a lockfile) handed you', and it explicitly says 'WITHOUT re-scanning' implying you'd use a scanning tool otherwise. It also gives a mandatory follow-up action ('You MUST still confirm...'). It doesn't name sibling alternatives by name, but the guidance is clear enough.

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