Privi Verify

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds a material behavioral fact not in the structured data: the call is metered and paid per invocation via x402. It also discloses the shape of the result (ordered events + integrity check). It stops short of describing pagination or what the integrity verdict looks like on failure.

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 sentences, no filler, and the primary payload (ordered history plus integrity check) is front-loaded ahead of the billing note.

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?

With no output schema, the description carries the burden of describing the return and does so (ordered events, fingerprints, chain integrity), and it flags the payment requirement. What is missing is any hint about result size, ordering guarantees, or error behavior.

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?

There is one required parameter with 100% schema description coverage, so the schema already carries the semantics. The description only alludes to it via 'for a lot' and adds no format, validation, or naming guidance 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?

States a specific verb+resource: returns a lot's full ordered event history with per-event fingerprints plus a whole-chain integrity check. That is clearly distinguishable from privi_record_event and privi_lookup_fingerprint, though it does not explicitly name privi_verify_lot, which sounds like the nearest sibling.

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 the usage context (you want the complete ordered history and a chain-level integrity verdict), but gives no explicit when-to-use guidance, no exclusions, and no comparison against privi_verify_lot, whose scope may overlap.

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 annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds that the lookup is free, which is useful behavioral context, but it does not explain return format or any constraints around the existence check.

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 a single efficient sentence with the core existence-check action front-loaded. It contains no redundant or wasted phrasing.

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 read-only lookup with no output schema, the description is nearly complete: it communicates the existence-check purpose and that the lookup is free. A minor gap is that it does not explicitly state the return shape, such as a boolean result.

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%, and the schema already documents the single required fingerprint parameter as a 64-character hex SHA-256 value. The description adds source context (label, certificate, or document), but does not add syntax or format details 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 states a specific verb and resource: checking whether a record fingerprint exists in Privi. It clearly distinguishes a lookup/existence check from sibling tools such as verify_lot or chain_of_custody.

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 useful context that the fingerprint may come from a label, certificate, or document, and notes that the lookup is free. However, it does not explicitly say when to use this versus sibling tools like privi_verify_lot or privi_chain_of_custody.

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 and openWorldHint=false, so the safety profile is covered. The description adds that this returns pricing and payment-process information, but says nothing about whether prices are current, region-specific, or tied to account state.

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?

A single well-formed sentence with the resource and returned content front-loaded. Nothing redundant or padded.

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?

With an output schema present, the description need not enumerate return fields, and with no parameters there is no input ambiguity. It is sufficient for a simple informational tool, though a hint about when pricing is worth consulting would round it out.

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 takes zero parameters, so the schema baseline of 4 applies. There is no parameter behavior for the description to clarify.

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 gives a specific verb ('List') and names the exact content: Privi Verify tools, their costs, and payment mechanics. It is clearly distinguishable from siblings like privi_verify_lot or privi_record_event, though it does not explicitly name them.

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?

Usage is only implied: an agent would infer to call this when cost or payment information is needed. There is no explicit statement of when to use it, when not to, or how it relates to the other Privi tools.

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 annotations only declaring the safe-ish write profile, the description adds substantive context: Bearer auth via PRIVI_WRITE_KEYS and the PRIVI_ALLOW_LOCAL_WRITES=1 gate for stdio. It stops short of saying what appending does to the lot's status (e.g. a 'recalled' event) or whether duplicate events are allowed.

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?

Three tight sentences, front-loaded with the core action and audience, then the auth prerequisites. Every sentence carries information; no padding or repetition of the schema.

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 7-parameter mutation tool with no output schema, the definition omits the return value and any effect on downstream state (chain of custody, lot verification). Auth and audience are covered, but an agent still lacks a full behavioral picture before writing.

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 86%, so the schema already explains lot_code, event_type, location, actor, and the optional fields. The description adds no syntax, format, or enum guidance beyond that, so the baseline 3 applies.

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?

'Append an event to a lot's history' names a specific verb and resource, which reads clearly as a write operation distinct from read-oriented siblings like privi_verify_lot and privi_chain_of_custody. It does not explicitly name or contrast with any sibling though, so an agent must infer the boundary.

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 '(manufacturers only)' qualifier and the PRIVI_WRITE_KEYS requirement give real gating context, but there is no explicit when-to-use guidance and no routing against the other privi_* tools. Usage is implied rather than stated.

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 and openWorldHint=false, covering the safety and scope profile. The description adds important behavioral context beyond annotations: the tool is paid per call via x402, and it clarifies what the verification checks (product, custody events, recall status, record integrity). It does not detail payment mechanics or error behavior, but the cost disclosure is significant.

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 sentences, front-loaded with the operation and its scope, followed by the payment requirement. No filler or repetition; every clause earns its place.

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 read-only tool with one required parameter and no output schema, the description gives a good sense of what is verified and notes the x402 payment model. It stops short of describing the exact return structure or differentiating from sibling tools, but the core context is sufficient for an agent to invoke it 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% for the single required parameter lot_code, which the schema already describes as 'Lot or batch code to verify.' The description mentions 'a lot' but adds no format, constraints, or validation details beyond the schema. Baseline 3 applies when the schema fully documents parameters.

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: 'Verify a lot.' It also enumerates the verification scope (product, first/latest custody events, recall status, record history integrity), so the agent knows exactly what operation is performed. However, it does not distinguish this tool from siblings such as privi_chain_of_custody or privi_lookup_fingerprint.

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?

No when-to-use guidance, prerequisites, or alternative tools are mentioned. The description implies usage when a lot code needs verification, but it does not say when to choose this over privi_chain_of_custody, privi_lookup_fingerprint, or the other siblings. 'Paid per call via x402' is a cost notice, not usage guidance.

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