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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by disclosing it never fakes proofs, routes physical proofs honestly, and does not handle payment. These are meaningful behavioral guarantees that go beyond the annotations and build trust in the tool's 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?

The description is three sentences with some promotional phrases like 'no oracle, no judge' that add little value. It is front-loaded with the primary action, but the second and third sentences contain extra context that could be more succinct. The structure is adequate but not tight.

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 a full output schema and complete parameter descriptions, the description's job is to provide the high-level context. It covers the tool's purpose, scope (digital vs physical), and the payment model. An agent can correctly invoke it without missing critical information, though error handling is left to the output schema.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description highlights the proofUri parameter by discussing machine-checkability but does not add further meaning to workId, standard, or definitionId. It provides context but no new parameter-level 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?

The description clearly states the tool verifies that a proof URI is machine-checkable and provides the path to obtaining a signed certificate. It differentiates from physical proof handling and clarifies it does not execute payment, making the purpose concrete. Slight ambiguity remains in whether it returns a certificate or instructions, but 'validates and instructs' resolves this.

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 explicitly states 'Digital claims only' and notes physical proof is routed to human review, establishing when not to use it. It also clarifies the tool is for validation/instruction and that the caller pays, implying this is a pre-payment step. While it does not name sibling tools, the division of labor is clear.

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