ProofFetch — Cited Web Evidence

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.

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond that: pricing tiers, free extraction limits, payment mechanisms, and the idempotency-key requirement for cited text. Some of that detail is dense and arguably more about the evidence endpoint than this offer tool, but it still adds behavioral value.

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 core purpose is front-loaded, but the pricing sentence is a dense run-on that mixes card packs, per-page pricing, and Stripe MPP calls. 'Example arguments: {}' adds little for a zero-parameter tool, so the paragraph could be tightened.

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 does enough by explaining that the tool returns the offer and request schema without purchasing, and by summarizing the pricing tiers. It does not describe the shape of the returned offer/schema in detail, but for a simple informational tool it covers the essential context.

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 tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description includes 'Example arguments: {}', which is redundant but confirms the no-argument nature of the call.

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 a specific verb and resource: it returns the offer and request schema without buying. It implicitly distinguishes itself from the evidence-fetching sibling by emphasizing 'without buying,' but it does not name or explicitly contrast with proof_fetch_evidence or proof_fetch_preflight.

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 phrase 'without buying' implies this is the informational/pre-purchase tool, which gives some usage context. However, there are no explicit instructions about when to choose this over proof_fetch_evidence or proof_fetch_preflight, and no stated exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond that: it bounds the preview to roughly 1,000 characters with short pages returned whole, states no payment is involved, and explicitly warns 'not a safety guarantee', which prevents the agent from over-trusting the result.

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 cost framing ('Free:') is front-loaded and the sentence packs the return contract efficiently, with a compact example at the end. The parenthetical aside about short pages is slightly clunky but still informative rather than redundant.

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 does the necessary work of enumerating what is returned: fetchability, provenance, hashes, injection indicators, and a text preview. What it leaves out is how failures are surfaced (e.g., an unreachable or blocked URL) and whether the preview is truncated by maxChars, which matters for a tool whose name implies a pre-check gate.

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 coverage is 100%, so both parameters are already documented, including the maxLength and min/max bounds on maxChars. The description restates the preview limit (which the schema also notes) and gives one example call, but adds no new semantics such as how maxChars interacts with the free preview cap. Baseline 3 is appropriate.

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 specific verb and resource ('checks a public URL') and enumerates what comes back: fetchability, provenance, hashes, injection indicators, and a text preview. An agent can tell it is a non-destructive inspection tool, though it never names the siblings proof_fetch_evidence or proof_fetch_offer to draw the free/paid line explicitly.

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?

'Free' and the name 'preflight' imply this is the cheap check before a paid fetch, and 'No payment or purchase' reinforces that, but the description never says when to use it instead of proof_fetch_evidence or proof_fetch_offer. Usage is inferable rather than stated.

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