Privi Ledger

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

Annotations already declare readOnlyHint and a closed-world scope, so the safety profile is covered. The description adds two useful behavioral facts beyond the annotations: an auth requirement (organization API key) and that only the current version of each record is returned.

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 short sentences, purpose first, then the access constraint. No filler, no restatement of the tool name, and the most decision-relevant information leads.

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 read-only single-param list tool with full schema coverage and annotations covering safety, the description says enough to invoke it correctly. It stops short of noting return shape or pagination, though no output schema exists, so that gap is minor.

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 single optional parameter is already documented ('One use case; omit for all'). The description adds no syntax, ID format, or filter semantics beyond the schema, 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?

States the resource (the agency's AI use case inventory) and scopes it to 'the current version of each record', which implicitly distinguishes it from version-history or export siblings. However, the verb is nominal/implicit and no sibling (e.g. gov_ai_inventory_export or gov_ai_inventory_check) is named to sharpen 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 prerequisite 'Requires the organization API key' is a genuine usage condition, but there is no guidance on when to choose this over gov_ai_inventory_check, gov_ai_inventory_export, or gov_ai_usecase_save. Usage is only implied by the purpose 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds a genuinely useful behavioral trait beyond the annotations: 'Requires the organization API key,' an auth prerequisite an agent must satisfy. It does not describe the return shape, but with no output schema and read-only annotations that is a minor gap.

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?

It is a single dense sentence, but the purpose is front-loaded ('Flags what an OMB M-25-21 review would flag before you submit') before the enumeration of checks. The eight-item risk-practice list is long yet each item is substantive, so it 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 zero-parameter, no-output-schema validator, the description covers the domain (OMB M-25-21), the trigger (pre-submission), the exact checks, and the auth requirement. It stops short of describing the response format (pass/fail vs issue list), the only meaningful omission.

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 is trivially complete and the baseline of 4 applies. There is no parameter surface for the description to explain or compensate for.

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 names a specific action (flags review-blocking issues) and enumerates exactly what it checks: missing required fields, PII without a PIA, and high-impact AI missing minimum risk practices or an active activity log. This is far more specific than the sibling gov_ai_inventory (listing) or gov_ai_inventory_export, so an agent can route 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?

The phrase 'before you submit' clearly frames when to use it as a pre-submission gate. However, it names no alternative tool (e.g., gov_ai_inventory_export to inspect raw data) and states no exclusions, so the routing guidance is contextual 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?

With annotations present the bar is lower, and the description still adds real context beyond them: it discloses the auth prerequisite (organization API key) and the side effect that a SHA-256 is sealed on the Privi blockchain, which explains why readOnlyHint is false despite the word 'export'. It does not describe pagination, rate limits, or what happens when re-exporting, but the key 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?

Effectively one dense sentence plus a short prerequisite clause; the core deliverable (CSV export) is front-loaded and nothing is wasted. Slightly long but every clause earns its place by describing format, publishing target, and sealing.

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 no-output-schema tool, the description adequately covers what is returned (a CSV for public publishing), where it is meant to go, its integrity guarantee, and the auth requirement. Sibling differentiation and any error/failure behavior are the remaining gaps.

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% and there is only one parameter, so the schema already documents include_withheld and its effect. The description adds nothing about parameters, so the baseline of 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?

The description names a specific verb and resource — exporting a machine-readable CSV of publicly releasable AI use cases — and adds the sealing mechanism and intended publishing destination (agency.gov/ai). Without the sibling context an agent can still tell exactly what is produced, though it never explicitly contrasts itself with gov_ai_verify_export or gov_ai_inventory.

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 implied via the stated purpose ('for publishing at agency.gov/ai') and the prerequisite 'Requires the organization API key'. There is no explicit when-to-use vs the sibling verify/inventory tools, so an agent must infer routing from the surrounding tool list.

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 cover the safety profile (mutation, non-destructive, idempotent), and the description adds genuinely useful context beyond them: every change creates a new version, writes go to a tamper-evident 'ai-inventory' log, and an API key is required. Slight tension with idempotentHint=true, since 'every change creates a new version' implies repeated identical calls could still mint new versions, but a no-op call arguably is not a change, so this is not a hard contradiction.

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, zero waste, and the core action is front-loaded before the audit/auth details. 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?

For a mutation tool with full annotation coverage, a fully documented nested schema, and no output schema, the description supplies the missing behavioral context (versioning, audit log, auth). What remains absent is return-value/pagination behavior, which is minor here since no output schema exists and the call semantics are self-contained.

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%, including a detailed nested use_case object, so the schema already carries the parameter burden. The description adds only the log-stream name context and no syntax or format detail beyond the schema, making baseline 3 correct.

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: 'Add or update an entry in your agency's AI use case inventory (OMB M-25-21)'. This clearly distinguishes the write operation from the read-oriented siblings gov_ai_inventory / gov_ai_inventory_check / gov_ai_inventory_export, though it never names any sibling explicitly.

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 a real prerequisite ('Requires the organization API key') and hints at versioning behavior, but gives no explicit when-to-use guidance versus the other gov_ai_inventory tools or when merge should be preferred. Usage context is implied rather than spelled out.

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 readOnlyHint annotation, the description adds critical behavioral context: it specifies the output (returning its on-chain seal) and practical constraints (

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 definition is highly concise, front-loading the verification goal, detailing the specific return type, and concluding with essential operational information (cost and key requirements. Every sentence 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?

Despite lacking an output schema, the description is complete by explicitly stating what the tool returns: 'its on-chain seal.' This addresses the functionality and constraints thoroughly for a single-input, read-only verification 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?

Although the schema provides 100% coverage, the description reinforces the parameter's meaning by clarifying that the `csv_text` must be 'exactly what the agency exported from Privi Ledger.' This adds vital context about the required input state.

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 specific action (Check/Verify) and the resource (published AI inventory file). It specifies the condition for the check (exactly what was exported from Privi Ledger) and distinguishes itself by focusing on returning the on-chain seal, differentiating it from general inventory tools.

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?

While it does not explicitly name sibling tools, its highly specific purpose—verifying the authenticity and obtaining the on-chain seal—provides a very strong guideline for when this tool should be used, implicitly guiding the agent away from general inventory operations.

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 the non-obvious cost signal ('Free'), which is genuine behavioral context not in the annotations, but says nothing about batching limits, per-item error handling, or unknown-name behavior. With annotations carrying safety, a 3 is appropriate.

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 tight sentences with zero filler; the action is front-loaded and the category enumeration is the most information-dense part of the definition. Nothing could be removed without losing meaning.

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 one-parameter, no-output-schema reader, the description covers input intent and the set of possible classification results, which effectively conveys the return vocabulary. It does not state whether one label comes back per input algorithm or an aggregate is returned, a minor remaining gap.

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 single 'algorithms' array parameter is documented with format hints and examples ('RSA-2048', 'ECDHE-RSA-AES256-GCM', 'X25519MLKEM768'). The description lists output classes rather than adding input-format meaning, so baseline 3 is correct when the schema does the heavy lifting.

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 ('Classify') and resource ('cryptographic algorithms') and enumerates the exact output categories (quantum-vulnerable, post-quantum, hybrid, symmetric/hash, unknown) with representative algorithms. There is no overlapping sibling, so an agent can unambiguously identify what this tool 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?

No when-to-use guidance, no prerequisites, and no named alternatives. The only directive-style statement is 'Free,' which is a cost note rather than usage context. The agent must infer from the purpose alone that this is the right tool for qualifying algorithm names.

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 declare readOnly=false, idempotent=false, destructive=false, openWorld=true, and the description adds meaningful context beyond them: the operation seals a SHA-256 hash on the Privi blockchain (explaining the non-read-only nature) and requires an organization API key. It does not address repeat-call behavior or failure modes when the org is not onboarded.

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 front-loaded sentence carries the purpose, audience, output format, sealing behavior, and auth requirement with no filler. 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?

With no output schema, no parameters, and annotations covering the safety profile, the description supplies the remaining essentials: what is exported, in what format, for whom, and the auth and write side-effect. It stops short of describing response structure or prerequisites (e.g., needing a completed plan), but is nearly complete for a zero-argument export.

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 baseline is 4 and there is no parameter semantics for the description to compensate for. Nothing in the description misleads about inputs.

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 (export) and a well-defined resource (cryptographic inventory/CBOM plus migration plan), along with the output format and the blockchain sealing step. It does not explicitly distinguish itself from close siblings such as gov_pqc_verify_export or gov_pqc_inventory, though the CBOM framing separates it from gov_ai_inventory_export.

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 audience ('for OMB, the CIO or auditors') implies a compliance-reporting use case, which is useful context. However, there is no explicit when-to-use guidance or routing versus alternatives like gov_pqc_verify_export or ledger_report_pdf, so selection is left to inference.

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 usefully adds the authentication requirement (organization API key), but says nothing about result size, pagination, or what the inventory contains.

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 short sentences, front-loaded with the resource and scope, and the auth prerequisite is compact. No filler, though nothing beyond the bare minimum is offered.

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 read-only inventory tool with no output schema, the description does not describe what the inventory returns (systems, algorithms, quantum-vulnerability status) or whether results are paginated. Adequate given annotations cover safety, but incomplete for a tool whose output shape is undefined.

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 single optional parameter is already documented as 'One system; omit for all'. The description adds no syntax or scoping detail beyond that, so the schema does the heavy lifting and 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?

States a clear verb+resource: retrieving the current cryptographic inventory of the organization's systems. It does not distinguish itself from adjacent siblings such as gov_pqc_classify, gov_pqc_plan, or gov_pqc_export, which an agent must infer from the names alone.

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 a precondition (organization API key required) but no explicit when-to-use or when-not-to-use guidance relative to gov_pqc_classify, gov_pqc_plan, or gov_pqc_export. Usage is only implied by the tool name and scope.

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 still adds real value by stating the API-key requirement and by disclosing the ranking logic (HVA/high-impact/long-lived data first, key establishment before signatures) and the deadlines applied. It stops short of saying whether this is computed live, whether it is deterministic, or how large the result can be.

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?

One dense sentence, front-loaded with the artifact name, followed by the auth prerequisite — nothing is wasted and no filler. It is long, but every clause (ranking rules, deadlines, findings types) carries information an agent would otherwise have to guess.

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 it does list the returned elements well (ranking, deadline, recommended replacement, metrics, findings). It omits result shape, size, and whether an empty or non-onboarded org returns an error, which matters for a report tool with no parameters to narrow scope.

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 zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the tool is parameterless by scoping everything to the caller's organization.

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 artifact (a prioritized migration plan) and enumerates what it contains: ranked assets, deadlines, NIST replacements, progress metrics, and findings. That is far more than a restatement of the title. It doesn't explicitly distinguish itself from siblings like gov_pqc_inventory or gov_pqc_classify, so ranking vs. listing vs. labeling is left to inference.

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 content implies usage (you call this when you want a prioritized remediation roadmap rather than raw inventory), and 'Requires the organization API key' is a stated prerequisite. However, no alternative tool is named and no condition is given for choosing this over gov_pqc_inventory, gov_pqc_classify, or gov_pqc_export.

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?

Goes well beyond the annotations: it discloses that every change creates a new version, that writes go to a tamper-evident 'pqc-inventory' log, and that an organization API key is required. These are meaningful operational facts (versioning, audit trail, auth) not derivable from readOnlyHint/idempotentHint.

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?

Four short sentences, front-loaded with the core action and followed by behavior and prerequisites. No filler, though the scanner/agent sentence is somewhat loose and could be merged.

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?

No output schema exists, but the description covers the mutation semantics, versioning, logging, and auth needs, while the schema fully specifies the nested system record. Nothing essential for a correct call appears 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 both parameters (actor, system) are already fully documented, including the nested asset fields and the fact that the inventory is replaced. The description only adds the 'one system' scoping and the actor types, which the schema already covers.

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 ('Record the cryptographic inventory (CBOM) of one system') with the domain purpose (post-quantum migration). An agent can distinguish this write from read/export siblings like gov_pqc_inventory and gov_pqc_export, though no sibling is named explicitly.

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?

'Scanners and agents can submit results directly' gives a caller profile, and the API-key requirement sets a precondition. However, it never says when to use this versus gov_pqc_inventory or gov_pqc_plan, nor any exclusions, so guidance is implied 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the return value (an on-chain seal) and the auth requirement ('no key needed'), which an agent needs to know it can call this without credentials. It stops short of describing failure behavior or rate limits.

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 tight sentences: the verification action and its guarantee come first, followed by the cost/auth note. No filler, no repetition, everything front-loaded.

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 one-param verification tool with no output schema, the description supplies the key missing piece by stating it returns the on-chain seal. Combined with the readOnly annotation and the auth note, an agent has enough to call it correctly; only edge-case behavior on a failed verification is unstated.

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% and the single 'document' param is already documented as 'exactly as exported'. The description's 'exactly what was exported' phrasing reinforces the integrity expectation but adds little syntactic or structural detail beyond the schema. 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?

States a specific verb (Check/Verify) plus the exact resources (CBOM and migration-plan document) and the guarantee being verified (exactly what was exported from Privi Ledger). This differentiates it from the many siblings (gov_pqc_export, gov_ai_verify_export, gov_pqc_plan) by naming the artifact type and the source ledger.

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: you call it on a document that was exported from Privi Ledger. There is no explicit when-to-use/when-not, no mention of the related export step that produces the input, and no contrast with gov_ai_verify_export despite it being a near-twin. 'Free; no key needed' is a helpful gate but not routing guidance.

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 the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), so the description's added value is the semantic consequence of the signature parameter (proven vs merely declared) and the auth requirement. It does not disclose error behavior or whether re-binding an already-bound wallet is a no-op, but the annotation coverage lowers the bar.

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 action and purpose, then the signature distinction, then the auth prerequisite. No filler 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 5-parameter mutation tool with no output schema and no enums, the description covers purpose, prerequisite, and the key behavioral distinction, while the schema handles the stream_id/label/challenge_id scoping. It could say more about failure modes or what is returned, but nothing essential to 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?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining what the signature parameter actually accomplishes in the domain (proof vs declaration and why checkers care), which is meaning the schema's mechanical '65-byte hex signature' text 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?

States a specific verb and resource ('bind the wallet to your organization's Privi Passport') plus the outcome it enables ('transactions pass KYA checks'), and its 'Step 2' framing plus the bind/unbind sibling names let an agent place it precisely in the KYA family.

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?

Gives clear conditions for the two modes ('with a wallet signature the binding is proven; without one it is only declared (most checkers require proven)') and states the prerequisite 'Requires the organization API key'. It stops short of explicitly naming kya_challenge as the prerequisite call or ruling out alternatives, but the context for when to call it 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?

Annotations declare readOnlyHint=false and idempotentHint=false, which the description reinforces by describing a fresh, transient artifact rather than a pure read. It adds real behavioral detail the annotations cannot convey: a 30-minute TTL, the signing standard (EIP-191), and the organization API key requirement. It does not say whether re-calling invalidates prior challenges, so it is not 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?

A single compact sentence with the step number and purpose front-loaded, followed by the signing format, TTL, and auth requirement. Every clause adds information; nothing is redundant with the title.

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 one-parameter tool with no output schema, the description conveys the essential contract: a message is returned, it must be signed with the given wallet, and it expires in 30 minutes. It could go one step further and tell the agent to pass the signed message to kya_bind_wallet, but the flow is largely reconstructable.

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% and the single parameter 'address' is documented as '0x wallet address your agent controls'. The description only echoes this with 'with that wallet', adding no format, network, or validation detail beyond the schema. Baseline 3 applies when the schema carries the full parameter burden.

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 — 'get a message to sign with that wallet' — plus the exact cryptographic standard (EIP-191 personal_sign) and the framing 'Step 1 of binding a wallet to your Privi Passport'. That framing cleanly separates it from the adjacent kya_bind_wallet sibling 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?

Gives clear context: this is the first step in the wallet-binding flow, it requires the organization API key, and the output is only valid for 30 minutes. It falls short of explicitly naming kya_bind_wallet as the mandatory follow-up step, so the agent must infer the sequencing from 'Step 1'.

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 still adds real value by disclosing the allow/deny-with-reasons output, a Privi-signed attestation valid 60 minutes that is cacheable, and the zero cost. It does not explain how the organization key is transmitted (header vs. param) or any rate limits.

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-loads the core question (is this wallet operated by an audited AI agent, and how trustworthy is it right now?) before the mechanical details, and every sentence carries information. Slightly dense with the attestation/validity/logging clause stacked at the end, but no filler.

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 correctly carries the burden of describing the return (allow/deny with reasons, cacheable 60-minute attestation), which is exactly what an agent needs. Annotations cover the read-only profile, and 100% schema coverage handles the inputs; only the grade scale and how min_grade/min_score interact are left unstated.

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 baseline is 3: address, purpose, min_grade, min_score and require_signed are all documented in the schema itself. The description only lightly reinforces this (purpose is 'recorded in your log if you send your key') and introduces an organization-key concept that is not a schema parameter, so it adds little beyond what the schema already provides.

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?

Names a specific verb (check) and resource (a wallet's AI-agent status / Privi Passport), and states concretely what is returned: allow/deny with reasons plus a signed attestation. This distinguishes it from sibling tools like kya_bind_wallet, kya_wallets and passport_verify, which bind, list, or verify passports rather than resolve a wallet to a trust decision.

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?

Explicitly names the callers/contexts it serves (chains, DeFi protocols, exchanges, stablecoin issuers, x402 facilitators) and notes it is free and can be logged by sending an organization key. It stops short of naming alternatives such as passport_verify or stating when a check is unnecessary, so the routing guidance is clear but not exhaustive.

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 destructiveHint=true, idempotentHint=true, and non-readonly, so the safety profile is covered. The description adds real value beyond them by disclosing the downstream consequence ('KYA checks deny it immediately') and the auth requirement (organization API key).

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 short, front-loaded sentences with zero filler: action first, consequence second, prerequisite last. Every sentence 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 destructive, credential-gated mutation with no output schema, the description covers the action, the enforcement effect, and the auth requirement. It is largely complete, though a note on whether the wallet can be re-bound or what happens to existing KYA records would close the remaining gap.

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 address parameter, so the schema already documents the input fully. The description adds no format or constraint detail about the address beyond what the schema provides, making the baseline 3 correct.

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 ('Remove a wallet from your Passport') and is the clear inverse of the sibling kya_bind_wallet, so an agent can tell them apart without opening a 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?

It names the triggering scenario ('rotated or compromised key') and the prerequisite ('Requires the organization API key'), giving clear context for when to reach for this tool. It stops short of naming alternatives or explicit when-not conditions, so it does not reach a 5.

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 known. The description adds the organization API key prerequisite, which is useful auth context. It does not discuss pagination, ordering, or return format, so it clears the lowered bar but is not rich.

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 short sentences with no wasted words, and the resource is front-loaded. The fragment style is minimal but functional rather than confusing.

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 zero-parameter, read-only tool with annotations covering safety and no output schema, the description supplies the core purpose and the API-key requirement. It omits listing scope and pagination details, but the tool is simple enough that these gaps are minor.

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, so the baseline is 4 per the rules. There are no parameters for the description to add meaning to beyond the schema already showing an empty input object.

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 names the resource (wallets bound to the organization) and includes the returned attribute (how each was proven). Although it lacks an explicit verb like 'list', the plural 'Wallets' and title make the read-only listing intent clear. It does not differentiate itself from siblings such as kya_check.

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?

There is no when-to-use guidance beyond the API key requirement. It does not tell the agent when to call this versus kya_check, kya_bind_wallet, kya_unbind_wallet, or other KYA siblings.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), but the description adds two traits not in structured data: the cost model ('Paid per call via x402') and the privacy guarantee that raw actions are not exposed. It stops short of stating failure modes (e.g. behavior on an empty or missing stream) or rate limits.

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 core purpose, then the enumerated outputs, the privacy boundary, and the cost note. With no output schema, the field enumeration earns its place rather than padding.

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 usefully documents the returned fields, the non-disclosure boundary, and the per-call payment — enough for an agent to call it correctly. It is slightly thin on edge-case behavior (tampered vs intact output shape, empty streams), which keeps it from a 5.

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% with only org_id and stream_id, both documented in the schema itself (including the 'stream_id is usually the agent's name' hint). The description adds no extra parameter meaning beyond linking the call to 'an agent's action log', 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?

States a specific verb+resource ('Check whether an agent's action log is intact') and enumerates exactly what is inspected: entry count, time span, action/failure counts, head hash, and where the chain broke. The clause 'Does not reveal the actions themselves' implicitly distinguishes it from the action-revealing sibling ledger_read_stream, so an agent can separate the two 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?

Usage is only implied — an agent can infer this is for integrity verification after actions are recorded, but there is no explicit 'use this when...' framing and no sibling alternative (e.g. ledger_read_stream, ledger_verify_report) is named as the choice for a different need. The privacy clause hints at a boundary but does not state the routing condition.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description usefully adds that the tool returns only existence and timestamp, not action contents, and that it is free — real behavioral value beyond the 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?

Three short sentences, no waste, with the core purpose front-loaded and the caveats (no contents, free) trailing succinctly.

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 read tool with no output schema, the description tells the agent what is confirmed and what is not revealed, which is nearly everything needed. Minor gap: no explicit statement of failure behavior when the entry is absent.

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%, with entry_hash fully documented (64-character hex returned at record time). The description adds nothing about the parameter, so the baseline of 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?

States a specific verb (confirm) and resource (action receipt in the ledger) plus the returned fact (when it was recorded). It hints at its read-only inspection role, but never names a sibling like ledger_record_action or ledger_verify_report to differentiate itself explicitly.

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 phrase 'Reveals no action contents. Free.' implies when this is preferable to a content-reading tool, but it never names an alternative or states a condition for choosing it. Usage is implied rather than prescribed.

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 mark this non-read-only, open-world, non-idempotent, and explicitly not destructive, but say nothing about what actually happens. The description supplies the missing behavior: the report hash is anchored on the Privi blockchain and is tamper-evident, and an organization API key is mandatory. It is consistent with readOnlyHint=false rather than contradicting it, though the cost/latency of anchoring is unstated.

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 front-loaded paragraph: deliverable first, then report contents, then the integrity guarantee, then the auth requirement. The parenthetical list of use cases is dense but each item is a real reason to call it. Nothing is padding, though the sentence is long and could be split.

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?

There is no output schema, so the description carries the burden of telling the agent what comes back, and it does: section-by-section contents plus the blockchain hash that makes the artifact defensible. Auth, time window, and scope filtering are all accounted for, and the report artifact need not be described further.

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%, and each parameter already carries its own ISO 8601 format hint and omit-behavior (since = all history, until = now, streams = all). The description adds only the loose phrase 'for a period', which it already conveys via the schema. 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?

States a specific deliverable (an audit-ready compliance report) and enumerates exactly what it contains: actions by type, failures, human approvals, log integrity, on-chain status, findings. That is far more than a restated name. It stops short of distinguishing itself from close siblings like ledger_report_pdf or ledger_read_stream, which an agent may equally plausibly pick.

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?

Gives concrete consumption contexts (SOC 2 evidence, security questionnaires, AI-regulation record keeping) and states a hard prerequisite ('Requires the organization API key'). It never names an alternative tool or a when-not condition, so the agent must infer the boundary with ledger_report_pdf and ledger_read_stream.

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 (write, non-idempotent, non-destructive), the description discloses what actually happens: terms are recorded in the caller's log, confirmed in the counterparty's log, and the matched pair is sealed on-chain. It also notes the API key requirement, which is important authorization context not present in 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?

Three tight sentences, front-loaded with the core action and effects before the prerequisites. Every sentence contributes necessary information with no waste.

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 multi-step write operation with no output schema, the description covers purpose, effects, authorization, and the prerequisite read step. It could be slightly more complete by noting failure modes or the result of sealing, but it 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 coverage is 100%, so the schema already documents all three parameters with clear descriptions. The description adds only an indirect hint that handshake_id comes from the inbox, without expanding on stream_id or actor semantics, so the baseline score of 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?

The description states a specific verb (accept) and resource (handshake) scoped to the caller's organization, and describes the concrete effects: recording terms, confirming in the other log, sealing on the Privi chain. This clearly distinguishes it from sibling tools like ledger_handshake_offer and ledger_handshake_reject.

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 explicitly directs the agent to read terms first with ledger_handshake_inbox, establishing a prerequisite. It does not name the alternative actions (e.g., reject) or state when not to accept, leaving some inference to the agent.

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 useful context beyond annotations: the ordering ('newest first'), the included fields ('terms and status'), and the API-key requirement. It still omits pagination or result limits, which are relevant for an inbox-style listing.

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 tightly written sentences with no filler. The core content and ordering are front-loaded, and the API-key requirement is appended as a clear prerequisite.

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 zero-parameter, read-only list tool with annotations covering safety and no output schema, the description is largely complete: it states what is returned, the ordering, and the auth requirement. It would be stronger with a note about pagination or result-size limits, but no critical information is missing for correct invocation.

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 there are no parameter semantics for the description to clarify. Per the baseline for zero-parameter tools, a 4 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 identifies the resource (handshakes sent to and from the organization) and scope (inbox view, newest first, with terms and status). It clearly separates this from action-oriented siblings like ledger_handshake_offer or ledger_handshake_accept, but does not explicitly name alternatives or use a direct verb such as 'list'.

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 a prerequisite ('Requires your organization API key') but no explicit guidance on when to use this inbox versus sibling tools such as ledger_handshake_verify or ledger_handshake_accept. Usage is only implied by the inbox framing.

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 only give the boolean profile (not read-only, not idempotent, not destructive, closed-world), so the description carries extra weight and delivers: it states the record is written to your log immediately, becomes a matched pair on acceptance, and is sealed on the Privi chain, plus the auth requirement and the counterparty's Privi dependency. What it does not cover is failure/expiry behavior or reversibility if the counterparty never responds.

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 sentences, front-loaded with the what and how, then the prerequisites. Dense but every sentence carries information; nothing is padding. Slightly long for the core purpose but justified by the multi-step nature of the operation.

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 an 8-parameter mutation with no output schema and a full schema description coverage, the description supplies the missing lifecycle context (immediate local record, eventual matched pair on acceptance, on-chain sealing) and the auth/handshake prerequisites. It is missing only the failure/expiry path and what identifier the caller receives, which are minor given the rich schema.

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 all eight parameters are already documented in the schema, setting the baseline at 3. The description adds only light context, sketching the kinds of dealings (payment, data transfer, delivery, agreement) that map to action_type and details, without adding syntax or format 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?

The description gives a specific verb and resource: 'Start a Privi Handshake: a two-sided record of a dealing with another company's agent.' It explains the narrow scope (payment, data transfer, delivery, agreement) and the outcome. It never names the sibling tools that complete or inspect the flow (ledger_handshake_accept, ledger_handshake_inbox), so an agent must infer the routing from the concept rather than an explicit sibling reference.

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 implied rather than stated: the description covers the sequence ('when the other company accepts, both logs hold matching entries') and the prerequisites (your organization API key; the other company must also use Privi Ledger). However, it does not say when to prefer this over ledger_record_action for a one-sided entry, nor does it name any alternative tool. Adequate context, no 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 declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds two things annotations cannot: the rejection is externally visible in the counterparty's log, and an organization API key is required. It stops short of saying what happens to the local handshake state or what a repeat call does, which matters given idempotentHint=false.

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, both front-loaded with the action and then the key constraint and auth requirement. Every clause carries information an agent needs; nothing is padding.

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 one-required-param mutation with no output schema and a full set of annotations, the description covers scope, side effect visibility, and auth. The remaining gap is what the caller gets back and how the handshake's state changes, which is minor given annotations already signal the safety profile.

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 both parameters (handshake_id format 'hs_...', and the shared reason) are already documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 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?

States a specific verb (reject) and resource (handshake addressed to your organization), and adds the consequence that the other company's log records the rejection. It is clearly distinguishable in intent from the sibling ledger_handshake_accept, though it never names that sibling to sharpen the contrast.

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 phrase 'addressed to your organization' scopes which handshakes this applies to, which implies usage. But there is no explicit when-to-use versus when-to-accept guidance and no mention of the sibling ledger_handshake_accept as the alternative path.

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 safety is covered, and the description adds genuinely new behavioral facts: it is free, it is a public check, and it never reveals the terms (a privacy guarantee). It stops short of describing failure modes for an unknown or malformed handshake ID.

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 compact sentences, front-loaded with what is checked and followed by the privacy and cost traits. No filler and no restatement of the title.

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 usefully compensates by enumerating the returned fields and the explicit non-return (terms), and annotations cover the read-only profile. Slightly incomplete only in that invalid-ID or not-found behavior is unstated.

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?

Only one parameter and schema coverage is 100% ('hs_... handshake ID'), so the schema fully documents the input. The description adds no format or sourcing detail beyond it, which is the baseline-3 case when the schema does the heavy lifting.

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 (public check/verify) and resource (a handshake), and enumerates exactly what is verified: both companies, status, existence of both matching log entries, and the on-chain seal. This is clearly distinguishable from the sibling mutation tools (ledger_handshake_offer/accept/reject) without opening any 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?

Gives situational context ('useful for disputes and audits') and notes it is free and public, which implies when to reach for it. It does not, however, name an alternative or state when NOT to use it versus siblings like ledger_check_receipt or ledger_verify_report, leaving the routing choice to inference.

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 a genuine operational constraint (organization API key required), but says nothing about pagination, result size limits, or scoping 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?

Two short sentences, no filler, with the core action front-loaded and the prerequisite immediately after. 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?

With no output schema and zero parameters, the description carries most of the burden and does indicate the payload contents ('entry counts') plus the auth requirement. It could still note whether results are paginated or org-scoped, which is the only remaining gap.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading parameter claims are made.

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 ('List your organization's streams') and adds a distinguishing detail ('with entry counts') that separates it from the read-oriented sibling ledger_read_stream. It stops short of naming or contrasting with siblings explicitly, so it is clear but not fully 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?

The prerequisite 'Requires the organization API key' is a real usage condition an agent must satisfy before calling. However, there is no guidance on when to choose this listing tool over ledger_read_stream or the other ledger_* siblings, leaving selection to inference.

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 safety is covered. The description adds meaningful context beyond the annotations by disclosing the auth requirement (organization API key) and the exact data surfaced, which is the useful behavioral detail here.

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 short sentences, front-loaded with the returned data and followed by the auth constraint; nothing is wasted. Slightly less crisp because the first sentence is a bare noun list rather than an action statement.

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 and no parameters, the description must carry the return-value burden, and it does so by naming plan, usage, limit, and renewal date plus the auth requirement. Adequate for a simple read tool, though it could note that usage/limit are month-scoped quantities.

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 there is nothing to disambiguate and the baseline is 4. The description correctly adds no param detail because none exists.

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 enumerates the specific data returned: plan, entries used this month, the limit, and the Pro renewal date. An agent can tell it apart from ledger_pricing (pricing) and ledger_upgrade_pro (mutation), though the action verb is only implied by the noun list rather than stated.

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 implied (check your current plan/usage) and a prerequisite is given ('Requires your organization API key'), but there is no explicit when-to-use, when-not, or routing to alternatives like ledger_pricing or ledger_upgrade_pro.

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 safety and scope are covered structurally. The description adds genuinely new behavioral context: the response is a catalog of tools with their costs plus instructions for obtaining an organization key, which tells the agent this is the pricing/onboarding resource rather than a data-access tool.

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 front-loaded sentence that names the three things the call returns (tool list, costs, org-key guidance) with 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?

With no parameters and an output schema present, the description only needs to say what the call is for and what category of information it returns, which it does. The absence of any explicit when-to-use framing is the only remaining gap for this simple zero-arg lookup.

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 per the rubric the baseline is 4; there is no argument surface for the description to explain or for the schema to leave ambiguous.

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?

Specific verb ("List") plus a clearly bounded resource (Privi Ledger tools with pricing and org-key guidance). No sibling covers pricing or onboarding, so the agent can route here without inspecting other schemas, though the description never explicitly contrasts itself with e.g. ledger_list_streams.

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 implied by the content (call this to find out what the Ledger tools cost and how to obtain an organization key), which effectively signals an onboarding/pricing lookup. However, there is no explicit when-to-use statement, no prerequisites, and no exclusion telling the agent not to use it for cataloging streams or receipts.

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 safety is covered; the description adds real value by disclosing the auth requirement (organization API key), the deterministic oldest-first ordering, and that the whole stream is integrity-checked. It stops short of explaining what the integrity check yields or how pagination behaves.

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 front-loaded sentence with two clauses, both of which carry information (scope/ordering and auth prerequisite). No filler or restatement of the tool name.

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 should hint at the return shape, and it does signal that an integrity check accompanies the entries. Combined with 100% schema coverage and annotations covering the safety profile, an agent has nearly everything needed; only pagination behavior and the integrity result format are left implicit.

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 limit, after_seq, and stream_id are already documented in the schema. The description's 'oldest first' wording lightly reinforces after_seq's cursor semantics but adds no syntax or format detail beyond the schema. 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?

States a specific verb and resource (read entries in a stream) plus the ordering guarantee (oldest first) and an integrity-check behavior. It is distinguishable from ledger_list_streams (which lists streams, not entries), though no sibling is named explicitly.

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 supplies a prerequisite ('Requires the organization API key') but gives no guidance on when to pick this over ledger_audit_stream or other read paths, and no exclusion conditions. Usage is implied by the read-entries framing 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description stays consistent while adding real value: 'tamper-evident log' conveys immutability, the return of an entry_hash receipt tells the agent how to verify the write, and the API-key requirement flags auth. It stops short of covering rate limits or what happens on conflicting appends.

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, with the operation front-loaded ahead of the return-value and auth notes. Every clause carries 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?

For a 7-parameter write tool with no output schema, the description covers the core operation, the return shape (entry with entry_hash receipt), and the auth requirement, while the schema carries the field-level detail. Minor gaps remain around append conflicts or idempotency semantics, but the essentials are present.

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 every parameter (including enums for outcome and action_type and the 16 KB details limit) is already documented in the schema. The description adds no parameter-level meaning beyond that baseline, so a 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 gives a specific verb and resource ('Append an action to the organization's tamper-evident log') and even characterizes the return ('entry_hash receipt'). This clearly reads as a write/append operation, implicitly distinguishing it from the read/verify/handshake siblings, though no sibling is named explicitly.

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?

There is no when-to-use guidance, no when-not conditions, and no named alternatives among the many ledger_* siblings. The only prerequisite offered is 'Requires the organization API key,' which is an auth constraint rather than usage 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 only cover the safety profile (readOnly, not open-world), and the description adds genuinely new behavioral detail: three delivery channels (base64 pdf_base64, embedded PDF resource, and a /reports/<report_id>.pdf URL) plus an explicit auth requirement ('Requires the organization API key'). With no output schema, this return-format disclosure carries real weight.

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 tight sentences: identity/audience front-loaded, then the return mechanics and auth prerequisite. Nothing is redundant and there is no filler.

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 read tool with no output schema, the description covers what is returned and what credentials are needed, which is most of what an agent needs. It stops short of describing error conditions (e.g., unsealed or missing report) or whether the org key is passed as a header vs. query parameter.

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 single parameter already documents that report_id comes from ledger_compliance_report, so the description adds no new parameter meaning beyond what structured data provides. 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?

The description names a concrete artifact (a finished PDF of a sealed compliance report) and its audience, so an agent knows exactly what comes back. It does not, however, contrast itself with ledger_compliance_report (which produces the report) or ledger_verify_report, leaving sibling differentiation to inference.

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: the report is 'for auditors and customers' and report_id comes from ledger_compliance_report, which hints at the sequencing. There is no explicit statement of when to call this instead of ledger_compliance_report, nor any failure/'report not sealed yet' guidance.

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 confirm a non-idempotent write, and the description adds genuinely useful behavior beyond them: the API key is displayed only once and must be stored, and the free plan carries a monthly entry limit with all tools included. It doesn't address what happens on duplicate organization names, but the destructive/side-effect profile is otherwise well 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?

Three tight sentences that front-load the core action and outcome, then plan terms, then the alternative tool. Every sentence carries distinct information with no filler.

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 compensates by telling the agent exactly what it receives (an API key, displayed once) and the plan constraints. Nothing material for correct invocation or post-call handling 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% and the single parameter's meaning ("Your company or project name") is already documented in the schema. The description adds no further naming constraints or format guidance, 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?

States a specific verb+resource (create a Privi Ledger organization) plus the outcome (API key), and names the free plan explicitly. It clearly differentiates from ledger_upgrade_pro, which it identifies as the upgrade path rather than a competing signup route.

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 key needed to sign up" tells the agent this is the unauthenticated entry point, and "Upgrade any time with ledger_upgrade_pro" routes the agent to the alternative for plan changes. It stops short of explicitly stating when not to call it (e.g. if an org already exists), leaving one inference to the agent.

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 non-readOnly, openWorld, and non-idempotent, and the description is consistent with them ('Each call adds 30 days'). It adds genuinely new context beyond structure: the payment rail (USDC on Base via x402), the cost model, and the API-key requirement. It stops short of stating reversibility or what happens if payment fails, which would matter for a paid mutation.

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 tight sentences, front-loaded with the core action and price, then the cumulative effect and the prerequisite. Every clause earns its place; nothing is repeated.

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 parameters and no output schema, the description covers what an agent needs: what is bought, for how long, at what cost, via what payment rail, and what credential is required. It could go slightly further on failure/retry behavior for a paid call, but the essentials are present.

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 leaves nothing to document and the baseline is 4. The description correctly adds no param details and instead explains the implicit inputs (organization API key, payment).

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 combination: buying 30 days of Privi Ledger Pro (unlimited entries) for an organization. It also quantifies the effect of each call ('Each call adds 30 days'), which no sibling like ledger_pricing or ledger_signup duplicates, so an agent can distinguish it immediately.

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?

Conveys an implied use case (upgrade when you want Pro) and a prerequisite ('Requires your organization API key'), but never names when to choose this over ledger_pricing or ledger_signup, nor when not to call it. Usage is inferable 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, so safety is covered; the description adds genuinely new operational context by stating it is free and requires no key, which matters for an agent deciding whether to invoke it. It does not, however, disclose cost-free side effects, rate limits, or failure 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?

One tight sentence: the core action leads, the three sub-checks follow, and the cost/auth caveat closes. Every clause carries information; no filler.

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 explaining what the agent gets back, and it says nothing about the result shape (e.g., a validity verdict, which check failed, failure reasons). The nested report object with additionalProperties=true is also left unelaborated. Adequate but with a real gap for a verification tool whose value is in its verdict.

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% and the single parameter already documents that it is the 'report' object exactly as received from ledger_compliance_report. The description adds nothing beyond that, so 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?

States a specific verb (verify/check) and resource (compliance report), then enumerates the three concrete checks performed: hash recomputation, issuer confirmation, and blockchain anchor lookup. It is clear what the tool does, but it never distinguishes itself from the near-identical sibling ledger_check_receipt, so an agent must guess which of the two to pick.

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?

"Free; no key needed" gives useful preconditions, but there is no statement of when to use this versus ledger_check_receipt or ledger_audit_stream, and no exclusions or prerequisites beyond cost. Usage is only implied by the tool's purpose.

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 only cover readOnlyHint and openWorldHint; the description adds meaningful non-annotation context (pricing is free, an optional org API key causes the decision to be written to a tamper-evident due-diligence log). These are real behavioral traits beyond the safety hints, though rate limits or failure modes are unmentioned.

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 sentences with no filler; the core decision purpose is front-loaded and pricing/logging details follow. It is tight, but the logging clause is slightly compressed and could be clearer about auth requirements.

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 with no output schema, the description does supply the return shape ('returning the reasons') and notes the free tier. It is complete enough to invoke correctly, though it does not describe whether reasons are codes or prose.

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 every parameter is already documented in the schema. The description adds little beyond a loose reference to 'your minimums' covering min_grade/min_score, 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?

States a specific verb and outcome: an allow/deny decision that verifies a Privi Passport against caller-supplied minimums. It clearly separates itself from the sibling passport_verify by framing the call as a pre-transaction gate that returns reasons rather than a raw verification.

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 phrase 'before transacting with another AI agent' gives a clear trigger condition, so the agent knows when to reach for this tool. It stops short of naming passport_verify as the alternative for plain verification, so the routing guidance is implicit rather than exhaustive.

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 only cover the safety profile (readOnlyHint false, openWorldHint true, idempotentHint false, destructiveHint false). The description adds material operational context the annotations cannot convey: a 30-day validity window, an authentication requirement (organization API key), and a pay-per-call path via x402. That is exactly the extra behavior an agent needs before invoking a non-idempotent, metered mutation.

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 definition and purpose, then layers in verification routing, validity, and pricing in a logical order. It is dense and multi-clause but each clause carries decision-relevant information; only the enumeration of scoring inputs is arguably expendable.

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 usefully characterizes the returned artifact (a signed credential scored 0-1000, graded A-E, valid 30 days) and the billing/auth context. It does not say what identifier or fields come back on issuance, which would have closed the last gap for a tool with no output schema.

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% and the single parameter (stream_id) is fully documented in the schema itself ('Issue for one agent (stream). Omit for the whole organization'). The description echoes the agent-vs-organization scope but adds no syntax or format detail beyond that, so the 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?

States a specific verb and resource ('Issue a Privi Passport') and immediately defines the artifact as a signed, on-chain-anchored trust credential, including its scoring model and grade range. It explicitly routes the agent to the verification siblings (passport_verify / passport_gate), so it is distinguishable from them 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?

Gives clear context for use: issue the credential to show counterparties, who verify it free via passport_verify / passport_gate. It also states prerequisites (organization API key) and cost conditions (free on Pro/enterprise, paid per passport on free plans via x402). It does not state when not to issue, but the intended scenario is unambiguous.

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 safety is covered. The description adds value beyond that by disclosing the returned fields and, importantly, the organization API key requirement, which is a real operational precondition not present in the 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?

Two short sentences with no filler. The payload description is front-loaded and the auth constraint follows immediately, so nothing needs to be skimmed past.

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 usefully names the fields a caller will receive (score, grade, expiry, revocation) plus the auth requirement, which is what an agent needs to call it confidently. Only a brief note on ordering or pagination is absent, which is minor for a no-arg list 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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-related that the description needs to explain, and it avoids inventing nonexistent arguments.

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 resource and scope: "Your organization's issued passports," which clearly separates it from siblings like passport_verify or passport_issue. It also enumerates the returned fields (score, grade, expiry, revocation). It stops short of explicitly naming a sibling alternative, so it doesn't reach the top band.

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 implied by the read-only listing nature of the tool, and the auth prerequisite is stated, but there is no explicit when-to-use/when-not guidance or routing to related tools such as passport_verify or passport_revoke. An agent can infer the purpose but gets no decision rules.

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 destructiveHint annotation, the description adds two critical behavioral traits: 'Verifiers see it immediately' (synchronization/visibility) and 'Requires the organization API key' (prerequisite authentication requirement). These add significant operational 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 highly concise, packing necessary operational information—action, scenario, real-time effect, and authorization requirement—into three tightly worded sentences.

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 high schema coverage and the destructive nature of the tool, the description is complete. It answers the 'what,' 'why,' 'how to authorize,' and 'what happens next' questions for the agent.

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%, meaning the input schema already documents the parameters thoroughly. The description provides high-level context but does not add specific semantic meaning to the passport_id or reason fields beyond what the schema already provides.

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 explicitly states the function (Revoke one of your passports), names the specific resource, and is clearly distinct from sibling tools like passport_issue or passport_list.

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 scenarios for usage, such as when an 'agent was retired or compromised,' which acts as a strong conditional usage guideline. It implies the intent clearly without needing an explicit 'when-not' clause.

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 genuinely new behavioral context: it is free, needs no API key, performs a live re-score at call time, and catches post-issue tampering. It does not describe latency, rate limits, or what happens on a failed 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?

Front-loaded with the action and its purpose, followed by a compact list of the checks performed and a short "Free; no key needed" tag. The long clause chain is dense but every element (each verification step) carries information; minor tightening is possible but nothing is wasted.

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?

No output schema exists, so the description must carry the return-value burden, and enumerating the five checks implicitly tells the agent what the result will report on. Safety is covered by annotations. What is missing is the shape of the response (per-check booleans, overall verdict) and failure behavior, but the enumeration makes the tool callable as-is.

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% and both parameters (passport, passport_id) are documented in the schema itself, including the "pp_... ID, or omit and pass the passport document" alternative. The description adds no parameter-level detail beyond this, so 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?

Specific verb (check/verify) applied to a specific resource (Privi Passport), and it enumerates exactly what is verified: signature, content integrity, expiry/revocation, chain anchor, and a live re-score. This is clearly distinguishable from the sibling passport_issue, passport_revoke, passport_list, and passport_gate without opening any 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?

"Check an AI agent's Privi Passport before trusting it" gives a clear usage context (pre-trust verification). It does not name an alternative or state any when-not-to-use condition, so it falls short of the explicit routing seen in top-tier definitions.

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