owp_run_verification

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds a key detail: 'The tool never retries an indeterminate commit,' which is valuable transparency. However, it does not disclose whether the tool is read-only or mutating, nor any prerequisites or side effects. Given the absence of annotations, this is a moderate disclosure, but not comprehensive.

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 only two sentences long, front-loaded with the purpose and followed by the non-retry behavior. It is concise, technically accurate, and contains no filler or redundancy. Every sentence adds value.

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?

Considering the tool has three parameters, an output schema, and no annotations, the description is moderately complete. It clearly defines the operation parameter and a key behavior, but leaves 'ledger' and 'payload' undefined. While the output schema covers return values, the missing parameter documentation and lack of guidance on when to use this over similar verification tools makes it only partially 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?

The description explains the 'operation' parameter by listing its allowed values, which is helpful. But it provides no explanation for 'ledger' or 'payload', and the input-schema has no descriptions (schema coverage 0%). Since two of three parameters remain completely undocumented, the description only partially compensates for the schema's lack of details, and it should have explained all parameters.

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

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

The description clearly states the tool runs exactly one explicit verification operation, listing the allowed operation values (commit_arm, prepare_decision, commit_decision) and the version scope (v0.2, v0.3, v0.5). This distinguishes it from sibling tools like owp_verify_signature or owp_verify_work_order, making the purpose specific and 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?

The description provides clear context for when to use the tool: it runs the specified operations. However, it does not explicitly mention when not to use it or list alternative tools for other verification tasks. Since the allowed operations are explicit, the usage context is clear, but exclusions are absent, so it earns a 4 rather than a 5.

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