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

Annotations only supply readOnlyHint and openWorldHint; the description adds the material missing context — x402 payment covering the whole batch, a 10-page minimum quote, dedup and a 50-URL cap, per-page billing where undelivered pages are not billed, and optional credit for unused pages. The one gap is that the 10-page minimum price floor sits oddly against a schema that allows a single URL, leaving the cost of a 1-page request ambiguous.

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?

Dense and mostly front-loaded, but it opens with payment prerequisites rather than the tool's purpose, pushing 'Read a fixed list of public HTML pages' into the middle. The closing '402 without PAYMENT-SIGNATURE' partially restates the opening payment sentence, a minor redundancy in an otherwise information-rich block.

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 paid batch tool the description covers prerequisites, billing model, ordering, per-item and batch-level return fields, and sibling alternatives — an output schema also exists, so field naming assistance is supplementary rather than load-bearing. The only uncertainty left is the practical interaction between the 10-page quote minimum and the schema's minItems of 1.

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 a 3 is the floor; the description earns above that by explaining batch-level semantics that the schema cannot — URLs are deduped before quoting, the batch has a minimum quoted size, and a shared time budget applies across items. It does not re-explain format/pipeline, which the schema already documents well.

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 a specific verb and resource — 'Read a fixed list of public HTML pages in one call' — and anchors it to existing semantics ('the same article extraction as POST /v1/text for each URL'). It also explicitly separates itself from readfetch_text (single URL), readfetch_map/readfetch_crawl (discovery and traversal), and readfetch_scrape (JS required).

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 explicit routing rules: use this for a fixed list, readfetch_text for one URL, map+crawl to discover and walk a site, scrape when JavaScript is required, and pipeline='render' when a probe reported challenge:true. It also states the prerequisite (funded Base USDC wallet plus a signing client or proxy) and the failure mode (402 on direct calls).

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 only declare readOnlyHint and openWorldHint; the description adds material behavior the annotations cannot express: a funded Base USDC wallet is required, direct calls without a signing client terminate at 402, and the accepted auth paths (readfetch-client, @readfetch/client, @readfetch/mcp-x402-proxy) are named. It further discloses the async lifecycle (job_id, status=queued, pages_quoted, price_usd) and that completed jobs carry per-page url and Markdown in the status payload.

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?

Dense but purposeful, with no filler sentences and a clean progression from prerequisites to action to follow-up to alternatives. The main structural flaw is ordering: the payment preamble occupies the opening position that should belong to the purpose statement, delaying the one-line "what it does" until the second sentence.

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 paid, asynchronous, open-world crawl tool, the description covers the prerequisite (funded wallet), failure mode (402), lifecycle and polling, and sibling routing. Return fields are also summarized even though an output schema exists, so an agent has everything needed to call, pay for, and complete the workflow.

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 five parameters are already documented structurally, and the description largely restates what the schema says (max_pages default 20 / max 100, max_depth default 2 / max 3, include/exclude as prefix filters with * wildcard). The one genuinely additive note is that quoted page count drives up-front payment, but that is framed as billing behavior rather than parameter meaning, so the baseline 3 holds.

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?

"Start a bounded async crawl from one seed URL" gives a specific verb (start), resource (crawl), execution model (async) and scope constraint (bounded, one seed). It is immediately distinguishable from readfetch_text (single page), readfetch_map (URL listing only) and readfetch_batch (fixed list), which the description names directly.

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?

Explicit routing rules: prefer readfetch_batch for a fixed URL list, readfetch_map to list URLs without fetching bodies, readfetch_text for a single page. It also gives the follow-up protocol — poll readfetch_crawl_status with the returned job_id until complete or failed — so the agent knows both when to enter and when to exit this workflow.

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 flag readOnlyHint and openWorldHint, but the description adds genuinely useful facts: no payment or wallet required, it is unauthenticated, pages grow incrementally as results land, and results are retained only one hour after completion. The retention window and the growing-result behavior are exactly the kind of operational context annotations cannot convey.

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 main sentence is front-loaded and well ordered (purpose, auth, input, return, termination, retention), but 'FREE — no payment or wallet' appears twice in near-identical form, wasting space on a repeated claim.

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 simple polling tool with an output schema, annotations, and full schema coverage, the description covers everything an agent needs: when to call it, what to pass, how to interpret status, when to stop, and how long results persist.

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% and there is a single required parameter. The description's 'Pass `id` from the crawl response' merely repeats what the schema already says, adding no format or edge-case detail beyond it, so the baseline of 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?

The description states a specific verb and resource — poll a crawl job started with readfetch_crawl — and names the companion tool so an agent can tell it apart from readfetch_crawl (which starts jobs) and the other siblings. It also enumerates what comes back (job_id, status, counts, pages).

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 the selection context (only for jobs already started with readfetch_crawl), tells the agent to pass the id from that response, and specifies the termination condition: stop when status is complete or failed. It does not discuss failure recovery or what to do on repeated failed polls, so it stops short of a 5.

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 only say readOnlyHint and openWorldHint, so the description carries the cost model and does it well: it discloses that calls are paid, that a no-op still bills when text was delivered, that unsigned calls stop at 402, and that state is client-side so nothing is stored server-side. The only gap is that it doesn't say how long a baseline hash stays valid or what errors look like, but with an output schema present that omission is minor.

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?

Dense but each sentence carries load; the billing and client requirement, the statelessness model, the parameter interaction, and the sibling routing are all necessary. Deducting one point because it opens with the payment/signing prerequisite rather than the tool's core purpose, so the key verb+resource is not front-loaded.

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 an output schema present, the description needn't explain return shapes, and it doesn't. What remains — prerequisites, cost behavior, baseline flow, parameter combinations, and alternatives — is fully covered, and all five parameters are documented in the schema, so an agent has everything needed to call this correctly on the first try.

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 the baseline is 3. The description goes beyond the per-field text by explaining the interaction between parameters: previous_hash alone yields a change boolean without a diff, while adding previous_content is required to get added/removed/diff, and format must match how prior content was built. That cross-parameter semantics is genuine added value.

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: "Stateless change detection on readable page text", and pins down the mechanism (fetch URL, compare to hash or prior content, return changed/unchanged plus optional diff). It explicitly distinguishes itself from readfetch_fetch, readfetch_text, and readfetch_probe, so an agent can route without opening a schema.

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?

Gives explicit when-to-use and when-not-to-use guidance: "Prefer readfetch_text when you need the full article once; readfetch_probe (free) for a short preview and content_sha256 before spending on text." It also prescribes the first-call workflow (omit previous_hash to establish a baseline) and the hash-only vs hash+content choice.

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 only declare readOnlyHint=false and openWorldHint=false; the description adds the non-obvious cost signal (FREE) and the binding requirement to a prior request_id, which affects whether the call can succeed at all. It does not say what happens after submission (confirmation, ticket ID, side effects), so it stops short of full behavioral disclosure.

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 short clauses with no filler; the cost hook and purpose are front-loaded, followed by the binding requirement and then the exclusion. Every sentence earns its place.

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 3-required-param write tool with full schema coverage and no output schema, the description supplies the prerequisite, the free-cost signal, and the boundary against claims. The only gap is post-submission behavior, which is minor given the annotations and complete 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?

Schema description coverage is 100%, including the category enum values and the 500-char limit, so the schema already carries parameter meaning. The description only reinforces that request_id comes from the X-Request-Id header and repeats the billing exclusion, adding little beyond the schema 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 specific verb and resource: report integration/docs/site issues for a prior call. It also names the thing it is not (paid delivery disputes go to /v1/claims), so an agent can route correctly without opening any schema, and it is unambiguous against the read-only data-retrieval siblings.

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?

Gives the precondition for use (requires a request_id from a prior call's X-Request-Id) and an explicit exclusion with a named alternative ('Paid delivery disputes use /v1/claims, not this tool'). This is exactly the when/when-not/alternative pattern.

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 only supply readOnlyHint=true and openWorldHint=true, and the description adds substantial behavior the agent could not infer: a paid route requiring a funded Base USDC wallet, the 402 stop condition, the required signing client/proxy, redirect-chain timeout semantics, and max_bytes truncation. It also explicitly warns that POST/PUT/DELETE can mutate remote state despite readOnlyHint, which corrects a potentially misleading annotation rather than contradicting it. This is exactly the extra context the behavioral dimension is meant to reward.

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?

Dense and essentially waste-free: every sentence carries either a precondition, a parameter hint, or a sibling routing rule, appropriate for a 9-parameter tool. The weakness is ordering — the core 'send an HTTP request' statement arrives after two sentences of wallet/proxy prerequisites, so the front-loaded element is setup friction rather than the tool's action.

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 general-purpose egress fetch tool with 9 parameters, a full schema, and an output schema, the description covers the critical unknowns: payment/auth prerequisites, the 402 failure mode, mutation risk on non-GET methods, and sibling routing. Return values are briefly summarized even though the output schema carries them. Minor gaps remain around rate limits, header restrictions, and egress/geo behavior, but nothing an agent needs to invoke the tool correctly 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 coverage is 100%, so the baseline is 3; the description still earns above baseline by giving selection guidance between the two overlapping body parameters ('use json_body for JSON POST/PUT payloads; use body for raw bytes or strings'). It also frames timeout_s and follow_redirects as applying to the full redirect chain and binary:true as a base64 switch, reinforcing the practical effect of each parameter. It adds meaning but does not fully document headers or the 2083-char URL limit, which the schema already covers.

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 names a specific verb and resource: send an HTTP request across all six methods through egress and return status_code, response headers, and body. It also distinguishes itself from two siblings (readfetch_text for readable HTML articles, readfetch_pdf for PDF text), so an agent can route correctly. The main statement of purpose is buried behind two sentences of payment/setup preamble, which slightly blunts the front-loading.

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 explicit routing advice: prefer readfetch_text for readable HTML articles and readfetch_pdf for PDF extraction rather than raw bytes. It also tells the agent that direct calls without a signing client will stop at 402, which is actionable context for when a call will fail. It stops short of naming when a completely different sibling (e.g. readfetch_scrape or readfetch_crawl) is preferable over a raw fetch.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the monetization model: a funded Base USDC wallet is required on paid routes, a signing client or @readfetch/mcp-x402-proxy is needed, and unsigned direct calls fail at 402. It also notes the 95 s edge ceiling and that the browser fallback shares the timeout budget. It stops short of describing failure modes for unreachable sites or how robots/documents errors surface, so not a 5.

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 purpose sentence is dense but front-loaded with the core capability, and the workflow/alternative instructions follow logically. The opening payment/wallet preamble consumes the highest-attention position before the tool's function is stated, which costs a point.

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 read-only, open-world, four-parameter tool with full schema coverage and a declared output schema, the description supplies everything an agent still needs: payment/auth prerequisites, the 402 failure condition, the timeout ceiling, what is returned, and which sibling to call next. No material gap remains.

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 four parameters (url, limit, max_bytes, timeout_s) are already documented with defaults and bounds. The description adds no parameter-level meaning of its own and does not explain how limit interacts with the collected sitemap/feed URL pool, 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?

States a precise verb and resource: "Discover a site's crawlable surface without crawling it", then enumerates the exact artifacts produced (robots.txt rules, sitemap URLs, RSS/Atom/JSON feeds, link counts). The negation "without crawling it" and the instruction not to re-run readfetch_map on each returned URL cleanly separate it from readfetch_crawl.

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?

Explicit downstream routing: use returned URLs to plan readfetch_scrape, readfetch_batch, or readfetch_crawl. Also gives a pre-condition alternative ("Prefer readfetch_probe on one URL before paying for bodies") and an anti-pattern (do not call readfetch_map per URL), so both when-to-use and when-not-to-use are covered.

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=true and openWorldHint=true, and the description confirms 'Read-only server-side'. Beyond that it adds genuinely useful context beyond annotations: the 402-without-signing-client behavior, $0.005 per-document pricing, 413 unbilled over-cap behavior, and empty-text-with-hint for scanned PDFs. Missing detail on return shape and pagination limits it to a 3 rather than higher.

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?

Information-dense and front-loaded with the payment prerequisite and the pair-selection rule, then the billing and limit caveats. Well organized, but the single dense paragraph packs unrelated concerns (auth, limits, billing, sibling routing) together without clear separation, slightly hurting scannability.

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?

Complete for a paid extraction endpoint: it covers input alternatives with size limits, output fields (pages, markdown, title, metadata), billing semantics, edge cases (scanned PDFs, over-cap 413), and sibling routing. An agent has everything needed to call it correctly and interpret the response.

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 four parameters are documented in the schema itself, making the baseline 3. The description mostly restates the schema's size caps (20 MB egress, 1 MiB body with base64 expansion) and max_pages defaults, adding little new meaning beyond what structured fields already say.

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 ('Extract text from a PDF') and adds a concrete acceptance rule ('%PDF- magic, not Content-Type') that distinguishes it from generic fetch/scrape. The sibling comparison in the final sentences makes it unambiguous which tool handles PDF extraction vs HTML.

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?

Explicit routing guidance: 'Prefer readfetch_text or readfetch_scrape for HTML articles; readfetch_fetch for raw PDF bytes without extraction; readfetch_batch for many HTML URLs, not PDFs.' It also states the input-selection rule ('Send exactly one of url or content_base64') and the payment prerequisite for calls.

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 only declare readOnlyHint and openWorldHint; the description adds real substance beyond them — free/no wallet, plain HTTP only with no browser render, a 400-character preview produced by the same extractor as readfetch_text, and a timeout budget shared across redirects. The main omitted behavior is redirect handling details and any rate limiting, which keeps it from a 5.

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?

Front-loaded with the cost model and the core purpose, with the escalation path at the end. Dense and information-rich, though the bold markup and stacked parentheticals make it read more like a sales blurb than a spec — a slightly leaner phrasing would earn a 5.

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?

An output schema exists, yet the description still names the key response fields and the preview semantics, which is what an agent needs to decide whether to follow up with a paid call. Combined with the routing rules and transport limitation, nothing material is missing for a 3-parameter read-only probe.

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, timeout_s, accept_language) are already documented, including the note that timeout_s does not carry over to a follow-up paid call. The description adds no parameter-level meaning beyond the schema, so the 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?

States a specific verb and resource ("Free preflight on a URL") and enumerates exactly what it returns: HTTP status, content type, byte size, title, language, bot-wall flag. It is clearly distinguishable from the paid readfetch_* siblings it names.

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?

Explicit routing guidance: use this instead of readfetch_text when choosing a route or estimating size, and on `challenge: true` escalate to readfetch_scrape then readfetch_residential rather than readfetch_text. Both the when and the when-not are spelled out.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: paid routes need a funded Base USDC wallet, unsigned calls fail with 402, there are no retries ('one attempt'), and the price is four times scrape. The target category (DataDome, PerimeterX, Cloudflare, AWS WAF) tells the agent what success looks like.

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?

Front-loads the payment prerequisite and routing guidance, and each sentence carries a distinct fact. The 'cover it honestly' aside is editorial padding that could be trimmed, and the prerequisite/proxy sentence is dense enough to slow scanning.

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?

Output schema and annotations handle return shape and safety, so the description only needs cost, auth, failure modes, and routing; it covers all four. An agent could call this correctly and predict the 402 and no-retry behavior from the text alone.

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 every parameter and nested option is already documented. The description adds only the framing that request and response are identical to /v1/scrape, which is useful but no substitute for parameter-level detail. 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?

States a specific resource and a distinguishing mechanism: 'Identical request and response to /v1/scrape, but the render leaves through a residential address instead of the datacentre.' That single clause separates it from readfetch_scrape without requiring the agent to open either schema.

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?

Explicit when-to-use and when-not: 'Prefer readfetch_scrape when datacentre egress works; use readfetch_residential only after readfetch_scrape fails or readfetch_probe reports a persistent challenge.' It names both sibling alternatives and the exact condition that selects this one.

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 only declare readOnlyHint and openWorldHint, so the payment precondition, the 402 failure mode, and the billing semantics (a 'billed' field, with billed: false on bot checks or empty extractions) are genuine added value that the agent could not infer. It stops short of covering rate limits or retry/backoff behavior, so it is not a full 5.

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?

Dense but nearly every clause carries load, and the sibling routing is compressed into one comparison sentence. The one structural flaw is front-loading the wallet/402 prerequisite ahead of the actual purpose statement, so an agent skimming the first sentence learns the payment gate before what the tool 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 an output schema present, the description need not describe return fields, and it still names the key response fields (status_code, title, billed, links). For a 6-parameter, outbound-network tool it covers the payment gate, mode budgets, advanced controls, and alternative tools.

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 the 3 baseline is already met; the description goes further by grouping the advanced knobs ('scroll, wait_for, js_code, headers, cookies, and auth') and by flagging that `options` is deprecated but shares the `advanced` shape, which prevents a wrong-field 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?

States a specific verb and resource ('Load a public URL in headless Chromium') plus the exact output shapes ('Markdown, plain text, or HTML'), which is enough for an agent to distinguish it from readfetch_fetch or readfetch_text without opening a schema.

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?

Explicitly routes away from this tool with named alternatives and conditions: readfetch_text when JavaScript is not required, readfetch_fetch for raw HTTP/API bytes, readfetch_residential when datacentre IPs are blocked, readfetch_screenshot for images. It also states the prerequisite (a funded Base USDC wallet plus a signing client) and the failure mode (402) of not meeting it.

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?

Beyond readOnlyHint/openWorldHint it discloses payment mechanics (funded Base USDC wallet, 402 without a signing client), the fact that page JavaScript runs and there is no ad blocker, that the call is a GET-and-render with no form POST, and that bot-check or blank frames can still bill as false with a hint. This is exactly the kind of operational context annotations cannot express.

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 block is dense but mostly earns its words; however, it opens with billing/auth mechanics rather than the tool's purpose, burying 'Screenshot a public URL' in the middle. It also restates schema defaults (1280x800, 3840x2160) and output fields that the schema and output schema already declare.

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 an 8-parameter, open-world rendering tool, the definition covers cost/auth prerequisites, capture scope semantics, timeout behavior, and failure modes (bot checks, billed:false with hint). With an output schema present, it correctly does not need to explain return structure in depth.

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 the schema already documents every parameter and the baseline is 3. The description adds real guidance on top: mode is framed as a whole-call time budget, mode=full overrides full_page, and 'raise delay_ms or use mode=full for slow SPAs and lazy media' is operational advice not present in 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 states a concrete verb and resource: 'Screenshot a public URL in headless Chromium ... return PNG or JPEG in JSON.' It also enumerates the return fields and explicitly names the sibling tools it is not (readfetch_text, readfetch_scrape, readfetch_pdf, readfetch_fetch), so an agent can distinguish it without opening any schema.

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 explicit routing rules: 'Prefer readfetch_text or readfetch_scrape for extractable text; readfetch_pdf for PDF files; readfetch_fetch for raw HTTP without rendering.' It also states in-scope capture modes (viewport, full page, single selector) and when to raise delay_ms, so both selection and configuration decisions are covered.

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?

Goes well beyond the supplied readOnlyHint/openWorldHint annotations: it discloses the paid-route prerequisite (funded Base USDC wallet), the required signing client/proxy, and the concrete failure mode (calls stop at 402 without one). It also caps expectations on the payload (snippets only, not page text), which shapes downstream planning.

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 content is dense and each clause is relevant, but front-loading is inverted: the first two sentences are payment/proxy logistics rather than the tool's action, and the final paragraph compresses parameter details, alternatives, and multi-tool routing into one long run-on block. It could be restructured to lead with what the tool does and push payment prerequisites later.

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 an output schema present, the return shape need not be spelled out, and the description still usefully summarizes it. Auth/payment requirements, failure mode, and successor-tool routing are all covered; only cost/latency or rate-limit expectations are left unstated for a paid, open-world call.

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 the schema already documents query, limit, lang and tbs. The description restates the same facts (limit 1–20 default 5, tbs h/d/w/m/y, lang locale examples) without adding format rules, interaction notes, or edge cases beyond what the structured fields carry.

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+resource ("Run a web search") and immediately bounds the output scope ("titles, URLs, and snippets only — not full page text"), which is exactly what separates it from the readfetch_scrape/text siblings. An agent can identify this as the discovery step without opening any schema.

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?

Explicit routing: follow with readfetch_text/probe/scrape on a chosen URL, use readfetch_map/crawl when the site is already known, and use readfetch_* URL tools when a link exists. It names both the successor tools and the conditions that select them, so no inference is required.

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?

The description goes well past the readOnlyHint/openWorldHint annotations: it discloses the paid-route prerequisite (funded Base USDC wallet plus a signing client or proxy), that unsigned calls stop at 402, and the notable edge-case behavior that a missing heading still returns HTTP 200 with empty text plus available_headings. The one thing left implicit is anything about rate limits or billing magnitude beyond the 'billed' field name.

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?

Almost every sentence carries load — the payment precondition, the one-of parameter rule, the empty-result recovery, and the sibling routing are all things an agent needs. The only structural weakness is that it opens with an auth wall rather than the tool's purpose, so the core verb arrives second.

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 read-only extraction tool with a full output schema, six well-documented parameters, and two enums, the description covers purpose, routing, preconditions, failure modes, and truncation. Nothing an agent needs in order to call it correctly or interpret an empty result 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 coverage is already 100%, so the baseline is 3, but the description adds decision-level meaning: mode is framed as when Chromium is engaged ('when the page blocks HTTP') and max_chars as a truncation ceiling with a usable default. Those are marginal restatements of schema text rather than new syntax, keeping it below a 5.

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 names a specific verb and resource ('Extract one heading or one CSS selector from a public page instead of the whole document') and scopes it tightly against grabbing a whole document. It also names the sibling tools it is not, so an agent can separate it from readfetch_text and readfetch_scrape without opening a schema.

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 explicit routing: 'Prefer readfetch_text for full articles; readfetch_scrape when content needs JavaScript,' plus a rule for choosing between the two required-one-of parameters ('use selector when the section has no stable heading text'). There is even a recovery path when the heading is absent — retry using the returned available_headings.

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 only declare readOnlyHint and openWorldHint; the description adds the billing/auth precondition (funded USDC wallet, signing client or proxy, 402 on direct calls), the no-JS-by-default behavior with a single Chromium fallback, and the relative cost versus readfetch_scrape. Those are material facts an agent cannot derive from the structured fields.

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?

Dense and free of filler, but the first two sentences are payment preamble placed ahead of what the tool actually does, delaying the purpose statement. The routing guidance at the end is well placed; only the ordering keeps it from a 5.

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?

Output schema exists, so return values need no explanation, and all five parameters are fully described in the schema. The description fills the remaining gaps an agent needs: auth/payment requirement, cost relative to siblings, retry-capable fallback behavior, and when to choose each alternative tool.

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 url, format, max_bytes, timeout_s and accept_language are already documented with defaults and bounds. The description only echoes the format choice ('Markdown or plain text') and adds no syntax, units or interaction detail beyond the schema, 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?

States a specific verb and resource ('Fetch a public URL and return its main readable content as Markdown or plain text'), plus the returned metadata (title, author, published date, site name) and boilerplate stripping. It explicitly separates itself from readfetch_fetch (raw bytes/headers) and readfetch_scrape (JS-dependent articles), so an agent can pick the right sibling without opening any schema.

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?

Gives explicit routing rules: prefer readfetch_fetch for raw status, headers or non-HTML bytes; use readfetch_scrape when the article only appears after JavaScript runs. It also flags the prerequisite that paid routes need a funded Base USDC wallet and a signing client, and that unsigned direct calls terminate at 402.

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