Privi

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

Annotations already declare destructive=true, readOnly=false, idempotent=true. The description adds genuinely useful context beyond that: the auth requirement ('Requires the organization API key') and the capability constraint ('Your key cannot approve, only cancel'), plus the distinction between withdrawing a request versus revoking an unused approval.

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 the parenthetical nuance, then the key constraint. 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?

For a single-parameter destructive mutation with no output schema, the description covers the operation, the auth requirement, and the key's inability to approve. It is nearly complete; a note on irreversibility or post-cancel state would close the remaining gap, though destructiveHint already signals the risk.

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 description coverage is 100% ('apr_... ID' is documented in the schema), so the schema carries the burden. The description adds no format or syntax detail for approval_id, making this a baseline 3.

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 ('Withdraw an approval request (or revoke an approval not yet used)') and clarifies the dual semantic of cancel vs revoke. It does not explicitly name a sibling alternative, but the action is unambiguous enough that an agent can distinguish it from approval_* readers like approval_status.

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 action (withdraw/revoke a pending or unused approval) and the constraint 'Your key cannot approve, only cancel' narrows the intent. However, no explicit when-not condition or named alternative (e.g. how to approve instead) is provided, leaving routing partly 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 genuinely useful non-annotation context: the auth requirement ("Requires the organization API key") and the default sort order (newest first), which the schema does not express.

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, zero filler, with the resource and ordering front-loaded. Nothing to trim, though it is terse to the point of omitting useful routing detail.

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 list tool with no output schema, the description covers purpose, ordering, and auth. It leaves return shape, pagination/limits, and scoping (organization-only vs. personal) unspecified, which an agent may need.

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 status parameter already enumerates its accepted values (pending, approved, denied, expired or cancelled). The description adds nothing about the filter, 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?

"Your organization's approval requests, newest first" states a clear resource (approval requests) plus ordering, and the tool name supplies the list verb. It does not, however, differentiate itself from the sibling approval_status or approval_wait, which an agent could plausibly confuse with a listing call.

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 and no mention of alternatives. With approval_status and approval_wait in the sibling set, the agent gets no signal about which one to reach for when it wants approvals versus a single request's state.

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 (readOnly=false, destructive=false, idempotent=false). The description adds real context beyond them: an organization API key is required, the threshold creates an approval request, and the mandate's principal must sign with their wallet before the agent can spend. It doesn't note reversibility or interaction with existing requests, hence not a 5.

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 dense sentence that front-loads the core action (pause mandate_spend for humans on large payments) before the mechanics. Slightly long but 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 only 2 fully-documented params, no output schema, and annotations present, the description supplies the missing behavioral pieces: auth requirement, the approval-request mechanism, and who signs. Adequate for calling the tool correctly; minor gaps remain around policy removal and idempotency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents stream_id ('*' for all) and approve_over_usdc (omit to remove the rule). The description reinforces the threshold concept but adds no syntax or format detail beyond the schema. 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+resource: configuring a live-approval threshold that makes mandate_spend require human sign-off for large payments. It names the affected sibling (mandate_spend) and the exact mechanism, letting an agent distinguish it from approval_list/approval_request/approval_status which operate on the runtime flow rather than the policy.

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 conveys the scenario (large payments need a human) and ties the tool to mandate_spend, so usage is implied. However, it gives no explicit when-to-use vs alternatives and never states when to avoid setting a policy or how it interacts with the other approval_* tools.

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

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

Goes well beyond the annotations (which only declare it is a non-read-only, non-destructive, non-idempotent mutation). It discloses the return value (approve_url), that the human signs with their wallet at no cost and with no transaction, the authorization boundary (only the named wallet decides; the API key can only cancel), and the auth prerequisite (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?

Four tight sentences, front-loaded with what the tool does and what it returns, followed by the next-step routing and the authorization/auth constraints. No sentence is 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 nine-parameter mutation with no output schema, the description covers what the agent gets back (approve_url), how to proceed (approval_wait or channel watch), who can decide, and the auth requirement. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all nine parameters including approver_wallet and mandate_id. The description reinforces the authorization model ('only the named wallet can decide') but adds no syntax or format detail beyond what the schema provides, 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 (ask/request) and resource (human approval of an action), and explicitly distinguishes itself from the sibling approval_wait by naming it as the follow-up step. An agent can tell this is the initiation tool rather than the polling or cancel tool.

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?

Routes the agent forward: 'Your agent then calls approval_wait, or watches your live channel for approval.approved.' It also clarifies who may act (only the named wallet decides; your API key can only cancel). It does not explicitly state when NOT to use this versus approval_policy_set, but the workflow context is strong.

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 real context beyond that: the exact set of terminal and non-terminal states, the fact that a human wallet signature is attached once a decision is made, and that the call incurs no cost. Error/not-found behavior for a bad ID is not 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?

Two short sentences: the core purpose and return shape first, then the cost note. No filler, no restating of the title, and 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 one-parameter read-only tool with annotations covering safety, this is nearly complete. Because there is no output schema, the description usefully describes the return (state values plus signature), which is the main burden it needed to carry; only invalid-ID and freshness/timing behavior are unaddressed.

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 approval_id parameter is documented there as an 'apr_... ID', so the baseline is 3. The description adds no syntax, format, or lookup semantics beyond what the schema already states.

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 (an approval request) and the exact information returned: its status, enumerated as pending/approved/denied/expired/cancelled, plus the wallet signature. That enumeration clearly separates it from approval_wait (which presumably blocks) and approval_list, though neither 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?

No when-to-use guidance is given. An agent must infer that this is a non-blocking point-in-time check, and nothing in the text explains when to prefer it over approval_wait or approval_list. Only the trailing 'Free.' hints at a selection factor (cost).

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?

Read-only annotations already cover the safety profile, and the description adds real value beyond them: blocking semantics, the retry-on-pending pattern, an implicit cost note ('Free'), and the sense that a timeout is not a failure. It doesn't say what status values can be returned or what happens to the approval on timeout.

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 clauses, all front-loaded with the blocking behavior first, then the return contract, then the retry rule. Every clause earns its place; nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the burden of describing the return and does so ('returns the current status'). It omits the set of possible status values and any note about whether a timed-out wait loses the approval, which is the only meaningful gap for a two-parameter blocking tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so timeout_s and approval_id are already fully documented in the schema. The description only echoes the timeout concept ('or timeout_s passes') without adding format or edge-case meaning, 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 (block/wait) and the exact resource (the human's approval decision), and contrasts implicitly with the non-blocking siblings approval_status/approval_list. An agent can tell immediately this is the blocking variant.

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 operating context (block until decision or timeout) and an explicit retry rule ('if still pending, call again'). It does not name the non-blocking alternative (approval_status) or state when *not* to block, so it stops short of full 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 establish readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context: the key algorithms, that the keys are public and intended for offline signature verification, and that the endpoint is free. It does not cover auth requirements or rate limits, but with annotations present this is a solid contribution.

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, front-loaded with the resource and algorithm details, then the action, then pricing. 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 zero-parameter, read-only key retrieval tool with an output schema and readOnlyHint/openWorldHint annotations, the description supplies everything an agent needs: what the keys are, their algorithms, the intended use, and cost. No critical 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?

The tool takes zero parameters, so the 4 baseline applies. The schema has no properties and the description adds no parameter details because none exist.

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 as Privi's public signing keys and names the exact algorithms (Ed25519, ML-DSA-87), so an agent knows what the tool provides. It does not use an explicit retrieval verb or mention sibling tools like fortress_tpi_*, so it is clear but not fully differentiated from the broader fortress 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?

It gives a concrete use case—'Pin these to verify Privi signatures offline'—which tells the agent when to call it. It does not name alternatives or exclusions, so it falls short of the 5-level 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?

Adds real behavior beyond the annotations: single-use consumption, refusal when unauthorized, and an organization API key requirement. Annotations only say readOnly=false and idempotent=false; the single-use and auth semantics are the valuable additions. It does not say what happens to the action's result or failure modes beyond refusal.

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 clauses, zero filler, and the core semantics (consume, single use, auth requirement) are front-loaded. 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 non-idempotent mutating tool with no output schema, the description covers the key operational facts an agent needs: it consumes a one-time right, requires authorization and an org API key, and will be refused otherwise. It leaves the identity of the underlying action and the post-consumption outcome 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 parameter (request_id, 'tpi_... ID') is already documented in the schema. The description adds no syntax, format, or sourcing hint for the ID, 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 ('consume') and resource ('two-person authorization right') and clarifies the tool executes a previously-authorized action rather than creating or inspecting one. It does not explicitly name the sibling it must follow (fortress_tpi_request / approval_request), so it stops short of full differentiation.

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?

'Right before performing the action' and 'refused unless authorized' imply the precondition (an authorization must already exist), which is useful sequencing guidance. However, no alternative sibling is named and no explicit when-not-to-use is given, so the agent must infer the workflow from the family of tpi_* tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description contributes the API-key requirement, which the annotations do not convey, but says nothing about result size, pagination, or ordering for a list operation.

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 the resource identified first and the auth constraint second; no filler. The opening fragment is terse to the point of being a label rather than a sentence, but nothing wastes space.

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 no output schema, the definition covers what the resource is and the auth needed. It omits anything about the shape or volume of results and gives no way to place it among the five fortress_tpi_* siblings.

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 and the schema is empty, so there are no parameter semantics to document. Baseline 4 applies; 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?

The description names a specific resource ('two-person requests') scoped to the organization, but supplies no verb of its own – it is a noun fragment that only implies listing via the title. It does not distinguish itself from siblings like fortress_tpi_request, fortress_tpi_status, or fortress_tpi_execute.

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 only guidance is a prerequisite ('Requires the organization API key'), which is useful but is auth info rather than usage routing. There is no statement of when to call this versus fortress_tpi_status or fortress_tpi_request, and 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?

The annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description usefully adds the organization-API-key auth requirement. It still does not say whether re-defining a policy with an existing name replaces or merges with the prior one, which for an idempotent write tool would be the most valuable remaining detail.

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 tool's purpose, then the auth prerequisite. No filler, 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 required and annotations carrying the mutation/idempotency profile, the description covers purpose, parameter meaning, and auth. It remains slightly short on lifecycle behavior — namely overwrite vs. create semantics for a policy name that already exists.

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 each parameter documented (including the 2..officers bound on 'required'). The description restates the meaning of officer_wallets and required but adds no syntax or constraint detail beyond the schema, 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 gives a specific verb and resource (define a Two-Person Integrity policy) plus the two governing attributes (approver set, required approval count), so the agent knows exactly what this tool configures. It does not, however, differentiate itself from the closely named sibling approval_policy_set, leaving a real ambiguity unaddressed.

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?

'Requires the organization API key' is a genuine prerequisite that tells the agent a credential is needed. Beyond that, there is no when-to-use guidance and no indication of how this differs from approval_policy_set or the other fortress_tpi_* tools, 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 only declare the generic safety/behavioral hints (non-read-only, non-idempotent), so the description earns credit for disclosing the auth requirement (organization API key), the human-in-the-loop signing mechanism, and the returned approve_url — none of which appear in structured fields. It stops short of describing failure modes (e.g. expired requests, rejected signatures), which keeps it from a 5.

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: what it does, what it returns, and the workflow gate, all front-loaded. Nothing is redundant with the schema or annotations.

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 non-idempotent mutation tool with no output schema, the definition still supplies the return shape (approve_url), the authorization prerequisite, and the surrounding call sequence. An agent has everything needed to invoke it and act on the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (policy, stream_id, summary, details, hours) is already documented in the schema, including ranges and defaults. The description adds no syntax, format, or naming guidance beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Ask officers to authorize a sensitive action under a two-person policy') that an agent can distinguish from approval_request and fortress_tpi_execute. The return value (approve_url) and the policy scope are named explicitly, so the tool's role in the TPI flow is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit gating condition ('Do not act until fortress_tpi_status shows authorized') and names the correct next tool (fortress_tpi_execute). It routes the agent across siblings both before and after this call, which is exactly what the usage dimension asks for.

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 only readOnlyHint and openWorldHint; the description adds genuinely new context by listing the terminal states (pending, authorized, vetoed, expired, executed) and that the approver identity is returned, which is the return-value behavior an agent needs. It also flags cost ('Free'), which annotations do not convey.

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 front-loaded sentence that leads with the resource and status set, then adds the approver payload and cost note. No filler or repetition 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?

No output schema exists, and the description supplies the expected return content (status enum plus approver) for a simple read-only lookup with one documented parameter. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single request_id parameter documented as a 'tpi_... ID', so the schema carries the semantics. The description only implies the input is one 'two-person request' without adding format or lookup detail, 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?

Names a specific verb (status) and resource (two-person request), and enumerates the possible states, so an agent can tell it apart from fortress_tpi_list or fortress_tpi_execute. It never explicitly names those siblings or states that it operates on a single request_id, so differentiation is inferable 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?

There is no when-to-use guidance, no prerequisites, and no alternatives named; the agent must infer from the name that this is the check-before-execute call. The only practical guidance offered is the cost note 'Free', which is useful but not 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 declare a non-read-only, non-destructive, non-idempotent mutation, and the description adds substantial context beyond them: the kill switch behavior, tamper-evident call logging, rate-limiting, optional Passport gating, the public-HTTPS upstream constraint, and the org-API-key auth requirement. This is rich disclosure of effects and prerequisites for a mutation 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?

Front-loaded with the core action, then the value proposition, then prerequisites; nearly every sentence carries information. It is dense but slightly overstuffed, stacking many features into one long second sentence.

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 describing what is returned (HTTP and WebSocket URLs) and by covering auth, constraints, and side effects. It stops short of explaining how the guard/min_score/rate options interact, but an agent has enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each of the five params (name, guard, min_score, rate_per_min, upstream_url) is already fully documented in the schema. The description adds no parameter-level meaning beyond a general reference to 'rate-limits callers,' 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 resource: 'Put your MCP server behind Privi,' and elaborates the concrete artifacts produced (HTTP + WebSocket URLs) plus the value-add (rate-limiting, metering, logging). It is clearly a creation tool, though it never names the sibling it differs from (e.g. gateway_delete, gateway_set_guard, gateway_info), leaving differentiation to the obvious name prefix.

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 create framing and by the stated prerequisites ('Upstream must be public HTTPS. Requires the organization API key'), but there is no explicit when-to-use versus when-not guidance or reference to gateway_set_guard/gateway_delete for subsequent lifecycle changes.

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 destructive=true and idempotent=true, but the description adds real value beyond them: URLs stop working immediately, and gateway history is retained in the log. That clarifies what is and isn't destroyed, plus the org-API-key auth requirement. It doesn't say whether the gateway can be re-enabled or what the response 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?

Three short sentences, front-loaded with the core action, then effect, then prerequisite. Every sentence carries distinct information with no repetition or 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 one-parameter tool with no output schema and rich annotations, the description covers effect, data retention, and auth. It could go one step further and state whether the disable is reversible or how the tool relates to gateway_create, but nothing critical 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 description coverage is 100% for the single gw_id parameter ("gw_... ID"), so the schema already carries the semantics. The description adds no format, prefix, or lookup guidance beyond what the schema provides, 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?

The description gives a clear verb+resource ("Turn a gateway off") and its operational effect, so an agent can tell it apart from gateway_create/gateway_info/gateway_list at a glance. It stops short of explicitly naming a sibling it must not be confused with, and the framing as "turn off" rather than "delete" is left for the reader to reconcile with the tool name.

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?

"Requires the organization API key" is a useful precondition, but the description offers no when-to-use vs when-not guidance and never points to any sibling (e.g. gateway_set_guard, gateway_create). Usage is only implied by the destructive effect described.

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, and the description still adds real context: the call is 'Free' (no credit cost) and it enumerates the returned fields. It does not say whether the gateway must exist or what happens on an unknown gw_id, but the added cost and content disclosure is meaningful.

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 that front-loads the core purpose and appends the field list and the 'Free' qualifier without padding. 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?

There is no output schema, so enumerating the returned fields (forwarding target, Passport requirement, rate limit, call counts) is exactly the right compensation. The only gaps are error behavior and the boundary versus gateway_list/gateway_stats, which is a minor omission for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% — the single parameter gw_id is documented as a 'gw_... ID' in the schema — so the schema carries the burden. The description adds nothing about the identifier's format or lookup semantics, making the baseline 3 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: it returns a gateway's public description, enumerated as forwarding target, Passport requirement, rate limit, and call counts. However it never distinguishes itself from the closely related siblings gateway_list and gateway_stats, so an agent must infer the boundary itself.

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 required gw_id and the 'public description' framing suggest fetching metadata for one known gateway. No explicit when-to-use, when-not, or alternative (e.g. gateway_list for enumeration, gateway_stats for metrics) is named, so the agent must guess.

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 auth context (organization API key) and organizational scope, but says nothing about pagination, result limits, or return format.

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 scope before the auth prerequisite. There is no filler, though the first sentence is close to 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 zero-parameter, read-only list with no output schema, the description conveys the scope and authentication need. It could say more about the return shape or pagination, but the tool's simplicity makes that a minor 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?

There are no parameters, so the baseline is 4. The description adds no parameter detail, which is appropriate since none exist.

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 name and description together make clear this retrieves the organization's gateways. It stops short of 5 because the description uses a noun phrase rather than an explicit verb like 'list all' and does not name gateway_info to sharpen the one-vs-many distinction.

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 states a prerequisite ('Requires the organization API key') but gives no when-to-use guidance or alternative tools. The agent must infer from the name gateway_list that this is the list-all variant, with no explicit comparison to siblings such as gateway_info.

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 none of the annotations declaring what is actually mutated, the description carries that burden well: it specifies the exact write location (result._meta['privi/guard']), the semantic difference of block (injected results are replaced with an error before agents see them), the billing model (one Guard check per result, free allowance then credits), and the auth requirement. That is materially more than readOnlyHint=false / destructiveHint=false convey.

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 compact sentences, front-loaded with the core action, then modes, then cost and auth. The middle clause packs both mode behaviors into one long sentence, which slightly hurts scannability, but 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?

No output schema exists, and the description compensates by naming the result._meta key and the error-substitution behavior of block mode. It leaves 'off' mode and any gateway existence/permission prerequisites unstated, so it is strong but not fully closed.

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, but the description goes further by defining the observable behavior of each mode value rather than restating the enum 'off | tag | block'. It adds nothing for gw_id beyond the schema's 'gw_... ID', and notably omits any explanation of 'off'.

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 ('Turn Privi Guard on for every tool result that passes through your gateway') and immediately differentiates the two operating modes. It is clearly distinct from sibling gateway_* tools such as gateway_create, gateway_info, or gateway_stats, which deal with gateway lifecycle and metrics rather than guard configuration.

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 explains the selection criteria between the tag and block modes and states a hard prerequisite ('Requires the organization API key'), which is real usage context. It does not address the third schema mode value ('off'), nor when you would prefer Guard over other result-inspection tools like guard_check or scan_*, so there is no explicit alternative 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 already establish a safe read-only, non-open-world operation. The description adds useful behavioral context: it reports tool/day usage plus monthly quota and requires an organization API key. It does not cover pagination or return format, so not a 5.

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 returned metrics and followed by the access prerequisite. No redundant or filler language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with annotations and no output schema, the description supplies the metric list, scope, quota inclusion, and auth requirement. Nothing material is missing for correct selection or 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?

Schema coverage is 100%, so the gw_id parameter is already documented as a 'gw_... ID'. The description reinforces that the parameter selects 'one of your gateways,' but adds no format or selection detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States exactly what is returned—calls, errors, denials, x402 payment prompts, per tool and per day, plus monthly quota—for a specified gateway. The metric/scope phrase clearly distinguishes it from gateway_info, gateway_list, and guard_balance.

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 gateway scope and 'Requires the organization API key' establish when it is usable, but there is no explicit alternative routing such as 'use gateway_info for metadata.' Usage is implied rather than fully guided.

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 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?

Goes beyond annotations by naming the auth requirement ('Requires the organization API key') and the on-chain anchoring side effect (SHA-256 sealed on Base until Privi mainnet), which explains why readOnlyHint is false despite the CSV output being a read. It stops short of describing seal failure behavior, chain latency, or cost.

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 what is produced before the sealing and auth notes; no filler sentences. The second clause stacks a parenthetical chain caveat that makes the sentence slightly dense, 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?

With no output schema, the description carries the return-value burden and does so: CSV format, contents (public use cases), and the seal that proves the file unaltered. The auth prerequisite is stated and the sole optional parameter is schema-documented.

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 param include_withheld already documents its effect ('internal copy'). The description adds nothing about that parameter, 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 resource: exporting a machine-readable CSV of 'publicly releasable' AI use cases, with an on-chain SHA-256 seal. The 'publicly releasable' scoping distinguishes it in spirit from gov_ai_inventory, but the description never names the sibling it complements/excludes, so differentiation is left implicit.

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 via the parenthetical 'for publishing at agency.gov/ai'. There is no explicit when-to-use vs. gov_ai_inventory, gov_ai_verify_export, or gov_pqc_export, and no statement about when not to export or how the withheld-copy variant differs.

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 readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the agent already knows this is a non-read, externally-reaching, non-idempotent call. The description adds valuable context the annotations don't: the seal is written to Base until the Privi mainnet, an organization API key is required, and the call is effectively an attestation-producing submission. It stops short of saying repeated calls create new seals or listing failure modes, so not a 5.

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 sentence that front-loads what is exported and for whom, then tucks the sealing detail and auth requirement in trailing clauses. No filler, 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 params and no output schema, the description covers the essentials: contents of the export, destination of the seal, chain caveat, audience and auth. It omits what the agent should do to verify the resulting seal (e.g., gov_pqc_verify_export) and any precondition such as an existing inventory, 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?

Zero parameters, so the baseline is 4. The description still adds an operational requirement outside the schema: an organization API key must be supplied at the transport/auth level, which the empty input schema cannot express.

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: export the full CBOM plus migration plan as a single JSON document, sealed with SHA-256 on chain. This is clearly distinguished from plain read tools like gov_pqc_inventory by the sealing behavior, but the description never mentions the closely-named siblings gov_pqc_verify_export or gov_ai_inventory_export, leaving the agent to infer the difference.

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?

Names the intended audiences (OMB, CIO, auditors), which implies the compliance/attestation use case, but gives no explicit when-to-use versus when-to-call gov_pqc_verify_export or the raw inventory/plan tools. No prerequisites or exclusions beyond the API key requirement.

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 readOnlyHint=true and openWorldHint=false, so the safe read-only nature is covered. The description adds the auth requirement ('Needs the organization key') and the exact data scope (monthly free checks, prepaid credits), which is useful context 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?

Two short sentences: the first states what is returned, the second states the prerequisite. It is front-loaded and every word carries 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?

For a no-parameter, read-only tool with no output schema, the description tells the agent what data is returned and what credential is needed. Annotations carry the safety profile, so nothing critical for 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?

With zero parameters, the schema is empty and the baseline is 4. The description adds meaningful invocation context by stating that an organization key is required, even though that key is not represented as a parameter in 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 names the specific resource it returns ('free checks left this month and your prepaid credits') but omits an explicit verb like 'get' or 'return'. It still distinguishes the tool from siblings such as guard_check and guard_buy_credits by focusing on balance information rather than checks or purchases.

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 guidance on when to use this tool instead of guard_check, guard_buy_credits, or guard_pricing. The phrase 'Needs the organization key' is a prerequisite, not a routing condition or alternative comparison.

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 a non-read-only, non-idempotent, open-world operation, and the description adds genuinely new context: the funding rail (USDC on Base via x402), that credits never expire, that they apply after the free monthly allowance, and that an organization key is required. It does not contradict the annotations ('Buy' is consistent with readOnlyHint=false) and usefully surfaces the auth prerequisite.

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 with the core action front-loaded, followed by the operational details (expiration, allowance, auth). Every clause carries information; there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter purchase tool with no output schema, the description covers the payment method, authentication requirement, credit lifetime, and when credits are consumed. It could state what a successful purchase returns or debits, but the essential calling context is 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% and the single 'pack' enum is fully documented with prices (1k/10k/100k in USDC) in the schema itself. The description adds no parameter detail beyond what the schema provides, 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 and resource ('Buy prepaid Privi Guard checks') plus the payment rail ('USDC on Base via x402'), so an agent immediately understands this is a credit-purchase operation distinct from guard_check or guard_balance. It does not explicitly name a sibling to avoid, keeping it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line 'used after the free monthly allowance' implies the condition under which purchase is needed, giving an implicit when-to-use. There is no explicit when-not guidance and no routing to alternatives such as guard_pricing or guard_balance, so usage remains inferred 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 only declare readOnly/idempotent/closed-world, so the description carries the interesting load and does so: it discloses the return vocabulary (allow/warn/block), the findings, the redacted copy, an on-chain-anchored Ed25519 receipt, the non-storage guarantee, and the pricing model (free 1,000/month with org key, else 1 cent USDC via x402). These are concrete behavioral traits an agent can't derive from 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?

Front-loads the purpose in the first sentence, then the return contract, then the trust/privacy and pricing facts, with no filler sentences. The one-sentence pricing/x402 tail is dense but still earns its place for a paid tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully compensates by explaining the return values (allow/warn/block, findings, redacted copy, signed receipt). Combined with the parameter docs and annotation-covered safety profile, an agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the enum for direction plus the source label are fully documented in the schema, so a baseline of 3 applies. The description reinforces the inbound/outbound semantics but adds no syntax, format, or constraint detail beyond what the schema already states.

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 ('Check content for prompt injection ... or leaked secrets and personal data') and adds the preconditions 'before an agent acts on it or sends it'. It does not name its closest sibling guard_check_many (the batch variant), so the boundary with that sibling is left to inference, but the core purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context via the inbound/outbound framing: check untrusted content coming in before acting on it, check content going out before sending it. No explicit when-not or alternative-tool routing (e.g. use guard_check_many for multiple texts, or guard_receipt to fetch a receipt later), so it stops short of 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 cover the read-only/idempotent/closed-world profile, and the description adds substantial extra context they don't convey: per-item billing against allowance or credits, per-item receipts, the 50-item cap, and the organization-key auth requirement. These are exactly the operational facts an agent needs before invoking.

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, zero filler, with the batch scope and cap front-loaded before secondary details like billing and auth. 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?

Covers the operational essentials (cap, billing, auth) for a batch-check tool and the schema fully documents the input shape. With no output schema, it could optionally say what each check returns beyond 'receipt,' but nothing critical for 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 description coverage is 100%: the items array format (text, direction, source) is fully documented in the schema itself. The description adds no syntax or format detail beyond that, and the per-item billing note is behavioral rather than parameter semantics, 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 resource with explicit batch scope: 'Check up to 50 texts in one call.' The batch framing clearly separates it from the singular guard_check sibling, though it never names that sibling explicitly, so it falls short of full sibling differentiation.

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 a concrete usage context ('for example every tool result in a step'), which tells the agent when this tool fits. It does not, however, state when to prefer the single-check sibling guard_check or any exclusions, so no explicit alternative 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 already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, sandboxed read. The description adds the useful fact that the tool is 'Free', but does not clarify what 'checks' means or whether this returns static content versus live account data. With annotations covering the safety profile, 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?

One compact sentence with no filler, and the key content areas are front-loaded. It is arguably too terse given the ambiguity of 'checks', but nothing in it 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?

An output schema exists, so the description is not obligated to explain return values, and a parameterless read tool has a small contract to document. The remaining gap is the vague phrase 'what Privi Guard checks', which an agent must resolve by calling the tool, but overall it is complete enough.

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 beyond what an empty schema already communicates. Baseline of 4 applies for a parameterless tool.

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 (Privi Guard pricing information) and enumerates the three content areas it covers: what Guard checks, what it costs, and how receipts work. That is clearer than the bare name 'guard_pricing'. It does not, however, differentiate itself from the sibling guard_receipt or ledger_pricing, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus the many adjacent pricing/receipt tools such as ledger_pricing, guard_receipt, or guard_balance. The description only states what the tool contains, not the condition under which an agent should reach for it.

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 genuine value beyond that: it discloses that verification covers signature validity and Merkle inclusion in an anchored log, and that the operation is free and open to any holder of the id. It stops short of describing the verification verdict or failure modes.

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 sentence that front-loads the verb and resource, then layers the verification scope, ending with the access/cost note. No filler and nothing redundant.

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 some burden for explaining what a caller gets back. It gestures at this by naming what is checked (signature validity, Merkle proof) but never states the shape or meaning of the result, such as a valid/invalid verdict or failure reasons. Adequate but with a clear gap for a 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?

Schema description coverage is 100% – the single check_id parameter is documented as 'gc_... id from a guard_check receipt'. The description adds no syntax or format detail beyond that, so the schema does the heavy lifting. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (verify) and resource (a Privi Guard receipt), then decomposes what is verified: the signed body, signature validity, and the Merkle proof into the anchored transparency log. It is much more informative than a bare name restatement. It does not, however, distinguish itself from adjacent siblings such as guard_check or ledger_check_receipt, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Free; anyone holding the id can verify it' implies the precondition (you need the gc_... id) and the cost, which is useful framing. But there is no explicit when-to-use guidance and no routing against alternatives like guard_check (create the receipt) or ledger_check_receipt. Usage is implied rather than stated.

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

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

Annotations already declare 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?

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: exactly what property is proven (append-only, no edit/removal/reorder), the standard it conforms to (RFC 9162), and the absence of cost ('Free'). It stops short of describing the returned proof format or verification 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 tight clauses with the core guarantee front-loaded and no redundant restatement of the name. The trailing 'Free.' is terse but earns its place by surfacing a cost signal an agent would otherwise have to discover.

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 proof endpoint with two params at full schema coverage and no output schema, the description covers what is proven and the cost. The remaining gap is the shape of the returned proof, which an agent may still want, but nothing critical to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with 'first' documented as the older signed tree size and 'second' as the newer size, omitting for latest. The description's 'two signed tree heads' corroborates this but adds no syntax, ordering, or edge-case detail 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?

The description states a specific cryptographic artifact and its semantics: a proof that the log only grew between two signed tree heads, with the concrete guarantees (nothing edited, removed, or reordered) and the RFC 9162 reference. It implicitly distinguishes this from the sibling ledger_inclusion_proof by describing append-only consistency rather than membership, but it never names that alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use, no prerequisites (e.g., that you need two recorded tree heads), and no routing to alternatives such as ledger_tree_head to obtain the heads or ledger_inclusion_proof for membership. Only the 'Free' hint signals anything about cost.

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 goes further by disclosing the auth requirement ("Requires the organization API key"), the signing algorithms (Ed25519 and ML-DSA-87), and the fact that the package is self-contained and verifiable offline. It does not mention rate limits, size limits, or whether export is logged/notified, keeping it short of a 5.

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 dense sentences with zero filler: the verb and resource are front-loaded, the enumerated bundle contents follow, and the second sentence carries the verification path and auth prerequisite. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, non-destructive read tool with annotations covering the safety profile and no output schema to explain, the description supplies the missing pieces: what the artifact contains, how to verify it offline, and that an org API key is required. Only the origin/selection of stream_id is 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?

Only one parameter (stream_id) with 100% schema description coverage, so the schema already documents it. The description adds nothing about where to obtain a stream_id (e.g. ledger_list_streams) or what a stream represents, 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 ("Export") and a precisely enumerated resource: every entry, hash chain, RFC 9162 inclusion proof, signed tree head, on-chain checkpoint and keys. This level of content specification clearly distinguishes it from siblings such as ledger_report_pdf, ledger_compliance_report and ledger_inclusion_proof.

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 a clear use context ("for auditors, courts or air-gapped systems") and points to the offline verification path via verify_bundle.py. It does not, however, state when an agent should prefer this over sibling artifacts like ledger_report_pdf or ledger_compliance_report, so routing among near-neighbors 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?

Beyond annotations, the description discloses cross-organization side effects: recording the same terms in your log, confirming in the other company's log, and sealing the matched pair on chain. It also states an auth requirement. It does not cover failure behavior or result shape, but annotations already declare the mutation and idempotency profile.

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 action is front-loaded, followed by the side effects, auth requirement, and prerequisite in compact sentences. Every sentence adds useful 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?

For a complex mutation that spans local logs, another organization's log, and on-chain sealing, the description covers the side effects and prerequisite well. It does not describe the return value or failure states, and there is no output schema to fill that gap, so it is strong but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains handshake_id, stream_id, and actor. The description adds context about accepting terms addressed to your organization but does not add parameter-level meaning 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 names a specific verb and resource ('Accept a handshake') and explains the resulting effects: recording terms in both logs and sealing the matched pair on chain. It also distinguishes the read-before-accept workflow by naming ledger_handshake_inbox.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear prerequisite: read the terms first with ledger_handshake_inbox. It also states the organization API key requirement. It does not explicitly discuss when not to use it versus siblings such as reject or verify, so it falls short of a full 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 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?

Beyond the annotations, the description explains that the entry is recorded in the caller's log immediately and only becomes a sealed matching pair after the other company accepts. It also discloses the organization API key requirement, the counterparty prerequisite, and the on-chain Base sealing behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the action and resource, then explains the two-sided lifecycle and prerequisites without filler. Every sentence contributes useful context for selecting and understanding the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation with no output schema, the description covers the workflow, prerequisites, and sealing behavior well. It could say more about the immediate return value or offer state after creation, but the core operational context is 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 the schema already documents each parameter. The description adds context about the overall handshake but does not add parameter-level meaning beyond what the schema provides, making the baseline score 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 states a specific verb and resource: "Start a Privi Handshake." It explains that this is a two-sided record of a dealing and gives concrete examples such as payment, data transfer, delivery, and agreement. This distinguishes it from ledger_record_action and from the accept/reject/verify handshake siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: use it to start a two-sided record with another company's agent, and the counterparty must also use Privi Ledger. It does not explicitly name alternatives such as ledger_record_action for unilateral records or ledger_handshake_accept for the responding side, 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 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 safe-read profile is covered. The description adds genuinely new behavioral context: the proof is verifiable offline against the signed tree head, it reveals no entry contents (a privacy guarantee), and it is free. That goes beyond what the annotations convey.

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/fragments with zero waste, front-loaded with the core purpose. The privacy and cost facts are appended efficiently rather than 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 read-only proof tool with no output schema, the description covers what is returned (a Merkle audit path), how it can be used (offline verification against the signed tree head), and the privacy/cost profile. What is missing is how the agent obtains the required entry_hash or how it routes to verification siblings, but the core calling information is 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 both entry_hash ('64-hex entry_hash (an action receipt)') and tree_size ('omit for latest') are already fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: a 'Merkle audit path proving an entry is in Privi's append-only transparency log (RFC 9162)'. An agent immediately knows this returns an inclusion proof, not a consistency proof or a receipt check. However it never names the adjacent sibling (ledger_consistency_proof) that could be confused with it, so the differentiation is implicit rather than explicit.

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, when-not-to-use, or alternative routing is given. The description notes offline verifiability and cost, but says nothing about when an agent should call this versus ledger_check_receipt, ledger_consistency_proof, or ledger_tree_head. The only usage hint ('omit for latest') lives in the schema, not the description.

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 readOnlyHint and openWorldHint=false, so safety and scope are covered; the description adds real value beyond that by disclosing the signing schemes (Ed25519 and ML-DSA-87), periodic on-chain anchoring on Base, and that use is free (no credit cost). It does not mention freshness/caching behavior of the head, but the added operational context is substantial.

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 identifies the resource first, then adds the technical qualifiers (RFC 9162, algorithms, anchoring) and the cost note. No filler or redundant restatement of the name or 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 input parameters and no output schema, the description carries the burden of explaining what comes back, and it does describe the semantic content of the result (Merkle root, signatures, anchoring). It stops short of indicating the response shape (e.g., whether tree size, timestamp, or signature fields are included), which would help an agent consume it.

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. Nothing in the description contradicts or complicates the empty schema, and it correctly implies the call needs no 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?

Names the exact resource returned ('the latest signed tree head' being an RFC 9162 Merkle root over all log entries) so an agent knows this is a snapshot of the log's current root. It lacks any explicit contrast with closely related siblings like ledger_consistency_proof or ledger_inclusion_proof, which also deal with Merkle state.

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 infers it should call this when it needs the current log root to verify proofs or checkpoints. There is no statement of when to prefer it over ledger_consistency_proof, ledger_inclusion_proof, or ledger_check_receipt, and no prerequisites or follow-up 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 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, so the safety profile is covered; the description adds useful non-annotation context (cost, no API key required, which chain the anchor lives on, and the mainnet caveat). One mild tension: openWorldHint=false while the description says it 'checks the anchor on chain (Base)', which implies an external network lookup — worth noting though not a hard contradiction for a read-only vendor-infrastructure verification. It does not describe what a failure verdict looks like.

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 compact sentence front-loads the purpose, then lists the three sub-checks and ends with the cost/auth caveat. No redundant restatement of the title or name, and every clause carries distinct 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?

The description covers the 'what' and the operational constraints well, but with no output schema the agent gets no sense of the return shape — whether a plain verified/not-verified flag, per-stage results (hash, issuer, anchor), or failure reasons. For a verification tool whose entire value is the verdict, that is a meaningful 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% and the single parameter is documented as 'the report object exactly as received from ledger_compliance_report', which already supplies the key guidance. The description adds no further insight into the report object's fields or how mismatches are treated, so it sits at the schema-covered baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb ('Check that ... is unaltered') and enumerates the three concrete operations performed: hash recomputation, issuer confirmation, and on-chain anchor check. The resource and its provenance (a report from Privi Ledger) are clear. It stops short of naming the closest sibling candidates (ledger_report_pdf, ledger_check_receipt), so differentiation 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 statement that the tool is 'Free; no key needed' plus the hash/issuer/anchor framing implies it is a post-hoc verification step on a report you already hold, and the schema points back to ledger_compliance_report. However, there is no explicit 'use this when X, use Y instead' guidance against siblings such as ledger_check_receipt or ledger_report_pdf, so the agent must infer the routing.

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