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

Annotations only mark it as non-read-only, open-world, non-destructive, non-idempotent; the description adds the materially important behavior: billing model (1 credit, only on success), key tiers and how to obtain a free key, and the exact header format required. That is the auth-and-cost context annotations cannot convey, and it is internally consistent with openWorldHint=true and readOnlyHint=false.

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?

Purpose is front-loaded, followed by the credit/auth mechanics, which is the right order for an agent that must decide whether it can call at all. Some bulk is promotional ('paid key holds 500 for $5.00 (sold on the ProofFetch home page)') and does not help invocation, though the free-key endpoint does.

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 no output schema, the description carries the return contract and does so ('cited, paragraph-addressable text with integrity hashes and a receipt'), and it covers preconditions (public URL, key required) and cost. Nothing an agent needs before calling is missing.

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 description coverage is 100%, so all three parameters (url, maxChars, idempotencyKey with its 7-day retry semantics) are already well documented in structured fields. The description adds only a redundant example URL and does not explain maxChars or idempotency behavior itself, so baseline 3 applies.

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?

Opening sentence gives a specific verb and resource plus distinctive output traits: 'Fetch a public URL and return its cited, paragraph-addressable text with integrity hashes and a receipt.' An agent knows exactly what it gets. However, it never names or contrasts with the sibling tools proof_fetch_preflight or proof_fetch_offer, so differentiation is absent.

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?

It gives useful call-context (needs an Authorization bearer key, consumes one credit, charged only on successful extraction), which is real guidance. But it never says when to choose this over proof_fetch_preflight (free, metadata + preview) or proof_fetch_offer; the agent must infer the preflight-first workflow from the input schema rather than the description.

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