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

The annotations already convey readOnly, idempotent, and non-destructive behavior, but the description adds meaningful non-obvious details: it computes a canonical hash, does not fetch the source, does not generate secrets, does not sign or pay, and leaves source/facilitator capacity unchecked. These details go well beyond the annotation flags and reduce the chance of an agent misusing the 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?

Three tight sentences front-load the core action, then list critical non-actions and a residual limitation. Every sentence earns its place, with no redundant phrasing or marketing 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 side-effect-free preparation tool with strong annotations, the description covers purpose, safety, and limitations well. It lacks an explicit statement of return values or next steps, which is notable because there is no output schema, but the intended outputs — hash, payment/client requirements, and storage readiness — are reasonably inferable from the verbs.

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 does not explain the sources or requireAllSources parameters or how they affect the preparation result. Schema description coverage is only 50%, and the main 'sources' parameter lacks a top-level description; the tool description does not compensate. An agent must rely almost entirely on the schema and x-allowed-hosts for parameter meaning.

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 explicit actions: validate input, compute a canonical hash, and read payment/client requirements and receipt storage readiness. It also distinguishes itself from siblings by listing what it does not do — fetches no source, generates no secret, signs and pays nothing. This gives an agent a precise, resource-specific purpose beyond the generic title.

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 implies this is a read-only preparation step before a citation evidence purchase retry, and it lists exclusions such as no source fetching, no signing/paying, and unchecked capacity. However, it never explicitly says when to use this tool versus validate_evidence_request or another sibling, nor does it name alternatives. Selection logic is largely left to inference.

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