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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds real value: it bounds what a match actually proves and rules out external calls. What's missing is the mismatch behavior (error vs. a boolean result) and the hashing basis, which matter for a verification tool with no output schema.

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: action first, then the guarantee boundary, then the cost/side-effect note. Every sentence earns its place and nothing is repeated from 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 hash check with a nested capsule object and no output schema, an agent still can't predict the return shape on success or failure, nor how the hash is computed. The scope caveats are excellent, but the operational contract is incomplete.

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?

One nested parameter, schema description coverage 0%, so the description carries the burden. It only characterizes the capsule as 'frozen' and hash-bearing; it does not tell the agent which fields are hashed, whether metadata participates, or which canonicalization is assumed — exactly the details that determine whether a supplied capsule should pass. The schema's types, enums and const hash pattern do structural work, keeping this at 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?

States a concrete verb and resource: 'Recompute the hash of a supplied frozen capsule.' An agent immediately knows this is a verification/checksum operation. It doesn't explicitly name verdict_compile_capsule as the counterpart, so sibling differentiation is only implicit through the word 'frozen'.

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 scope disclaimer ('proves internal integrity only, not source truth, SML issuance, receipt authenticity, Jev execution or payment') implies this is a narrow integrity check to run before trusting downstream claims, but it never says when to call it versus verdict_compile_capsule or verdict_status. 'No model or wallet call' hints it is a cheap, safe pre-check, but the trigger condition 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.