Verify a record against the published procedure

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

Adds critical behavioral detail beyond the read-only/idempotent annotations: every check returns verified, failed, or not_checkable; there is no overall boolean because it would mask non-checkable results; a signature with an unheld key is not checkable and never verified; missing rules_version makes guarded transitions not_checkable rather than verified. These are non-obvious semantics the 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?

The description is dense but every sentence earns its place: first sentence defines the procedure, second gives usage context, third maps input modes to usage, and the final two sentences disclose edge-case behaviors. Perfectly front-loaded and free of fluff.

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 having no output schema, the description explains the per-check outcomes, the intentional omission of an overall boolean, and the conditional behavior of guarded transitions based on rules_version. For a complex seven-step verification tool, this provides a complete mental model without needing to inspect additional structured fields.

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 already covers all four parameters, so baseline is 3. The description adds value by clarifying the selection semantics: transaction_id verifies 'this server's record of one transaction,' object_ids verifies 'part of it,' and objects verifies 'a bundle somebody handed you.' It also explains the rules_version parameter's effect on guarded transitions. This goes beyond the schema's literal field definitions.

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

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

The description opens with a specific verb and resource: 'Run the seven-step verification procedure over a set of objects,' then enumerates the seven steps (content hashes, signatures, purpose, version chains, event-chain continuity, guarded transitions, determination follow-through, and non-checkable items). This clearly distinguishes it from sibling verify_mandate, which has a different object of verification.

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

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

Explicitly instructs when to use the tool: 'Use it on your own record before relying on it, and on anything a counterparty sends you.' It also maps input modes to scenarios: transaction_id for the server's record, object_ids for partial records, and objects for counterparty-supplied bundles. This gives clear, actionable guidance on selecting the right input.

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