ReadFetch

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

Annotations only carry readOnlyHint/openWorldHint; the description adds substantial context beyond them: x402 payment covering the whole batch, minimum 10-page quoting, dedupe before quoting, undelivered pages not billed, batch-level billed_pages and optional credit, the 402-without-PAYMENT-SIGNATURE auth behavior, and a shared timeout budget across items. That is exactly the kind of billing/auth/failure disclosure 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?

Purpose is front-loaded in the first clause and every subsequent clause carries a fact an agent needs (billing, ordering, alternatives, auth). The sentences are long and run-on, packing several ideas each, which costs a little clarity but no filler.

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?

Covers invocation, cost model, failure semantics, result shape and ordering, and alternatives to every sibling. Although an output schema exists, the summary of returned fields is a welcome shortcut rather than wasted space.

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 adds real meaning by clarifying the billing minimum (10 pages quoted) versus the schema's minItems of 1, that URLs are deduped, and that results preserve input order. It does not explain 'fresh' or 'pipeline' beyond the schema, keeping it at a 4 rather than 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?

States a specific verb and resource ('Read a fixed list of public HTML pages in one call') and equates the per-URL output to POST /v1/text, so the agent knows exactly what it gets back. It then names the sibling for each near-miss case (readfetch_text, readfetch_map/crawl, readfetch_scrape), making it distinguishable without opening another 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: single URL → readfetch_text, discovery → readfetch_map then readfetch_crawl, JS-needed pages → readfetch_scrape. The batch-specific constraint (minimum 10 pages quoted, max 50) tells the agent when this tool is economically inappropriate too.

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/openWorldHint; the description adds real behavior beyond that — asynchronous job semantics, the exact return fields (job_id, status, pages_quoted, price_usd), the polling contract, the terminal states, and what a completed payload contains. It doesn't spell out failure/error handling or what happens if the poll never completes, which keeps it short of 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 purpose, then returns, then polling, then scope caps, then the alternative routing — a sensible priority order with no filler sentences. Minor redundancy in restating schema defaults costs it 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 an async, paid, open-world crawl with 5 params and an output schema, the description covers initiation, cost quoting, poll cadence, terminal states, scoping knobs, and sibling routing. Nothing an agent needs to invoke it 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 url, include, exclude, max_pages and max_depth are already documented with defaults and bounds. The description mostly repeats those defaults and maxima ('default 20, max 100', 'default 2, max 3') rather than adding semantics, though the wildcard note on include is a useful confirmation.

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?

Names a specific verb and resource ('Start a bounded async crawl from one seed URL') and immediately situates it among siblings: batch for a fixed list, map for URL listing, text for a single page. An agent can pick this tool over readfetch_scrape or readfetch_fetch 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?

Explicit routing rules are given for all three alternatives, plus the required follow-up call ('poll readfetch_crawl_status with that id until status is completed or failed'). It states both when to use this tool and when not to.

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 readOnly/openWorld annotations by disclosing the no-payment/no-auth access model, the enumerated status values, the incremental/growing nature of the `pages` list as results land, and the one-hour result retention window that constrains how long polling can continue.

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 key operational facts are front-loaded, but 'FREE — no payment or wallet' appears twice in near-identical form, and 'unauthenticated' repeats the same point a third time, wasting the opening of the description on redundant monetization messaging.

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 enumerates the return fields; that is mild redundancy rather than a gap. The substantive gaps are covered — retention window, stop condition, and status values — leaving nothing an agent needs in order to call it correctly 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% and the `id` description already says it comes from POST /v1/crawl, so the description's 'Pass `id` from the crawl response' is largely duplicative. It does implicitly signal that `id` is effectively required despite `required: []`, but adds no format or error-handling detail.

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 ('Poll a crawl job') and anchors it to the sibling that creates the job ('started with readfetch_crawl'), so an agent can distinguish it from readfetch_crawl without opening 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?

Gives the prerequisite (must follow readfetch_crawl), the input source ('Pass `id` from the crawl response'), and an explicit termination condition ('Stop polling when status is completed or failed'), which is exactly the when/when-not guidance a polling tool needs.

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 cover readOnlyHint and openWorldHint, and the description adds genuinely non-obvious behavior: the call is stateless and a no-change answer is still billable. It stops short of explaining what 'bounded' means for the diff or how the two hash/content inputs interact.

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?

Two short sentences, front-loaded with the core contract and finished with the cost caveat. Nothing is wasted and no sentence restates the tool name.

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 so return values needn't be described, and billing is disclosed. Still missing for a 5-parameter tool: first-call behavior with a null previous_hash, whether previous_content is needed for an added/removed diff, and the meaning of 'bounded'.

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 60%, so the schema documents timeout_s and previous_hash/previous_content while url and format are bare. The description reinforces the 'hash you hold' idea but adds no meaning for format, the null-hash first call, or how previous_content differs from previous_hash.

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 mechanism (stateless change detection via a supplied hash) and the outcome (changed/unchanged plus a bounded diff), which distinguishes it from readfetch_fetch or readfetch_text. It never names those siblings, so differentiation is inferred rather than explicit.

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?

'Send the hash you hold' implies the tool is for re-checks against a prior result, which is useful implied usage. However, it never states when to use this instead of readfetch_fetch, nor what to do on a first call when no hash exists.

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?

Discloses two things annotations don't: the call is FREE (cost is a real differentiator in this suite) and it must be bound to a prior request via X-Request-Id. readOnlyHint=false is consistent with submitting a report, so no contradiction. It stops short of saying what happens to a submitted report or whether any confirmation is returned, which for a write-flagged endpoint is the one missing behavioral beat.

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?

Roughly two sentences with the highest-value token ("FREE") front-loaded and zero filler. Every clause — cost, action, binding requirement, exclusion — carries information an agent would otherwise have to guess.

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?

All three parameters are required and there is no output schema, so the description should cover the input contract and at least gesture at what comes back. It covers binding and scope well but omits message constraints and any indication of the response, leaving an agent unable to predict the outcome of the 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 only 33% (only request_id is documented), so the description is expected to compensate. It does explain the request_id origin and implicitly maps "integration, docs or site" onto three of the four category enum values, but it says nothing about the message parameter (including the 500-character cap) or the "other" category, so the compensation is partial.

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?

Specific verb and resource: "report integration, docs or site issues for a prior call," which pins down both the action and the object. It also carves out a boundary against the paid-dispute route (/v1/claims), though it never references any of the readfetch_* siblings (fetch, crawl, scrape, etc.), so an agent gets no explicit routing contrast within the tool family.

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?

States the context of use (issues arising from a prior call in the categories integration/docs/site) and gives an explicit when-not with a named alternative: paid delivery disputes go to /v1/claims. It does not clarify the reverse direction — e.g. whether this tool is ever correct without a prior request_id — leaving the prerequisite as an inference.

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?

Although the description adds useful behavioral detail such as redirect-chain scope, max_bytes truncation, and timeout ceiling, its final sentence explicitly says POST/PUT/DELETE can change remote state despite readOnlyHint. That directly contradicts the readOnlyHint=true annotation, so the rubric requires a score of 1 despite the otherwise strong 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?

The description is dense but front-loaded, first stating the operation and return values before covering limits, redirect behavior, body choices, alternatives, and the mutation caveat. Every sentence carries actionable information.

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?

Given the output schema exists, the description need not explain return values, but it still summarizes them. It covers methods, body encoding, size limits, redirect behavior, timeout, alternatives, and the write-risk caveat, making it complete enough for an agent to invoke correctly.

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 adds useful synthesis beyond the schema: binary mode returns base64, max_bytes caps the stored body, follow_redirects and timeout_s apply across the redirect chain, and json_body versus body controls payload encoding.

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: sends an HTTP request with enumerated methods and returns status_code, response headers, and body. It clearly distinguishes the tool from readfetch_text and readfetch_pdf by naming those alternatives for HTML and PDF extraction.

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 guidance: prefer readfetch_text for readable HTML articles and readfetch_pdf for PDF text extraction. It also explains when to use json_body versus body for request payloads, which directly affects invocation 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 already declare readOnlyHint=true and openWorldHint=true, and the description adds real value on top: it emphasizes no crawling occurs and enumerates exactly which documents are fetched, so the agent knows the cost profile. It omits failure behavior (site with no robots.txt or sitemap) and the browser-fallback cost noted only in the schema.

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?

Two sentences, front-loaded with the core capability and the 'without crawling it' qualifier, then the follow-up action. No filler or restatement of the tool name.

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, so return values need not be explained, and annotations cover the safety profile. The description covers what is collected and why, leaving only edge-case behavior (empty robots.txt, partial failures) unaddressed.

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, limit, max_bytes, and timeout_s are already fully documented with ranges and defaults. The description adds no parameter-level detail such as how limit interacts with the four discovery sources, 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 ('discover') and resource ('a site's crawlable surface') and then enumerates the concrete sources parsed: robots.txt, sitemap.xml/indexes, RSS/Atom/JSON feeds, and homepage link counts. It is clearly differentiated from readfetch_crawl and readfetch_scrape by the phrase 'without crawling it'.

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 closing sentence explicitly routes the agent: 'Use the returned URLs to plan a /v1/scrape or /v1/crawl,' which positions this as the pre-flight step before those siblings. It stops short of stating when-not-to-use (e.g., a single known URL should go straight to readfetch_fetch), so it is not a full 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?

Beyond the read-only and open-world annotations, the description discloses pricing ($0.005 per document, not per page), failure billing behavior (413 above page cap is not billed), and scanned-PDF behavior (empty text can return with `billed: false` and a hint). This is unusually complete behavioral context for an agent.

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 front-loaded with the core action and then layers constraints, return shape, pricing, edge cases, and sibling alternatives in a compact paragraph. Every sentence carries operational value and there is no filler.

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?

Given the annotations, complete schema, and existing output schema, the description supplies the remaining operational context an agent needs: input selection, size/page limits, billing exceptions, and when to choose a sibling tool instead. Nothing important for correct invocation appears to be 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%, and the schema already documents mutual exclusivity, the 20 MB limit, and max_pages default/max/413 behavior. The description reinforces these constraints clearly but adds little parameter-level meaning beyond what the structured schema already provides.

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: extract text from a PDF, with a clear magic-byte check rather than Content-Type. It also distinguishes from siblings by naming readfetch_text/readfetch_scrape for HTML and readfetch_batch for many HTML URLs, not PDFs.

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 usage rules: send exactly one of `url` or `content_base64`, use the former through egress and the latter for inline bytes up to 20 MB. It also states when not to use it, routing HTML work to readfetch_text, readfetch_scrape, or readfetch_batch.

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 operational facts an agent actually needs: no payment required, plain HTTP without browser rendering (so JS-heavy pages may look different than a rendered fetch), detection of bot walls via 'challenge', and a hard 400-character cap on preview text.

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 qualifier and tool identity are front-loaded, then the returned fields, then the preview caveat with its limit. Dense but every clause carries information an agent would otherwise have to guess.

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 and annotations cover the safety profile, so the description's remaining job is scoping (free, metadata-only, no rendering, capped preview) — all of which it covers. Nothing needed to decide whether to call or to interpret the 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 description coverage is 100% with only three parameters, so the schema already documents url, timeout_s and accept_language thoroughly. The description adds no format or syntax detail about any parameter, so it neither compensates nor detracts — 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 comes back: HTTP status, content type, byte size, title, language, challenge detection. It also separates itself from content-returning siblings by noting the preview is 'not the full article' and that this is plain HTTP with no browser render.

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 'FREE — no payment or wallet' framing and 'preflight' label clearly position it as the cheap check to run before a paid/extraction call, and 'same extractor as /v1/text' implies where to go for full content. It stops short of an explicit when-to-use/when-not statement naming siblings like readfetch_text or readfetch_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?

Annotations already cover read-only and open-world behavior. On top of that, the description discloses critical operational traits: single attempt with no retries, residential egress, and a 4x price multiplier, which materially affects agent decision-making.

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 sentences, front-loaded with the core equivalence, then targeting guidance, then cost/retry caveat. Every sentence carries decision-relevant information with no waste.

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?

The output schema covers response structure, annotations cover safety and openness, and the description supplies the missing behavioral context (retry policy, cost, IP-reputation targeting). An agent has everything needed to call it correctly.

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 fully documents all 7 parameters. The description adds only that the request shape is identical to /v1/scrape, which is useful context but does not elaborate on any individual parameter.

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 action (render via residential address) and explicitly frames it as an alternative to the datacentre scrape endpoint. It distinguishes itself from sibling scrape/fetch tools by naming the exact use case: targets that block by IP reputation.

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 a clear condition for use ('For targets that block by IP reputation') and lists example vendors, plus a strong cost/caveat signal (one attempt, 4x price). It stops short of explicitly naming the sibling to use otherwise (readfetch_scrape), leaving that inference to the agent.

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 the readOnlyHint/openWorldHint annotations, it discloses per-mode latency budgets, that `fresh` bypasses cache, that `options` is deprecated in favour of `advanced`, and the edge case that bot-check or empty extractions can return billed: false with a hint. That is substantive behavioral context the agent could not infer from 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?

Front-loaded with purpose and output, then parameters and routing; nearly every clause carries information. It is dense in a single block, and the parenthetical output-field list is slightly redundant given the output schema.

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 7-parameter scrape tool with an output schema present, the description covers rendering depth, latency budget, caching, auth, deprecation, and failure modes — 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 coverage is already 100%, so the baseline is 3; the description still adds meaning by mapping mode to concrete time budgets (15/30/60 s), enumerating which knobs live in `advanced` (scroll, wait_for, js_code, headers, cookies, auth), and calling out the deprecated `options` alias.

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') and names the exact return artifacts, so it is immediately distinguishable from readfetch_fetch and readfetch_text.

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_text when JavaScript is not required; readfetch_fetch for raw HTTP/API bytes; readfetch_residential when the site blocks datacentre IPs; readfetch_screenshot for a PNG/JPEG.' Each alternative comes with the condition that selects 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?

Adds substantial context beyond the annotations: budget semantics per mode, viewport-before-navigation ordering, full_page being ignored under mode=full, billing behavior on blank/bot-check frames (billed: false plus a hint), and that payment is x402 like other routes. Annotations already cover read-only/open-world, so the remaining gap is minor (e.g., no rate limits or size caps on the returned image).

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 purpose and the crucial 'returns base64, not a URL' fact, then scope, then budget, then siblings. Dense and nearly waste-free, though the parenthetical output-field enumeration overlaps what the output schema already declares.

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 capture tool with an output schema and annotations, everything needed to call it correctly is present: scope selection, timing budget, delay guidance, billing caveats, and sibling routing. The output schema handles the return contract, so no further return documentation is required.

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 baseline is 3, but the description adds cross-parameter meaning the schema does not: width/height must be set before navigation, mode acts as a whole-call budget, and delay_ms is specifically for SPAs and lazy content. This is genuine value-add beyond the field-level descriptions.

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+resource ('Capture a public URL in headless Chromium') and immediately pins the return shape (PNG/JPEG as JSON with base64, not a hosted URL). It explicitly differentiates itself from five siblings by naming them, so an agent can route without opening another 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 branching alternatives: readfetch_text/scrape for readable text, readfetch_pdf for PDFs, readfetch_fetch for raw HTTP. Also states when to use delay_ms (SPAs, lazy media) and the scope options (viewport, full page, selector element).

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 cover read-only and open-world behavior, and the description adds genuinely useful context beyond them: no separate search API subscription is required, results are limited to titles/URLs/snippets rather than page text, and follow-up tools are required for full content. It also documents the recency filter semantics and result limit behavior.

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 front-loaded with the core action and output limitation, then provides usage routing. It is generally efficient, but some parameter detail duplicates the schema and could be trimmed without losing necessary guidance.

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, annotations, and full schema coverage, the description supplies everything an agent needs: purpose, output scope, parameter behavior, and sibling-tool routing. Nothing critical is missing for correct invocation.

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 parameter meanings are already fully documented in the schema. The description restates limit, lang, and tbs semantics, which is helpful but largely redundant; it adds examples for lang and expands tbs values, but does not add meaning beyond the structured fields.

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: run a web search. It immediately distinguishes this from full-page retrieval tools by saying it returns titles, URLs, and snippets only, not full page text.

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 explicitly routes the agent: follow with readfetch_text, readfetch_probe, or readfetch_scrape on a chosen URL. It also names alternatives for known-site tasks (readfetch_map/readfetch_crawl) and link-based tasks (readfetch_* URL tools), so when-to-use and when-to-use-something-else are clear.

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 and openWorldHint, but the description adds substantial context beyond them: the returned fields (Markdown/text, title, chars, content_sha256, billed), the missing-heading case returning HTTP 200 with empty text and available_headings for retry, and the max_chars truncation and billing implication.

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?

Four dense sentences, all front-loaded with the core action and the retry/fallback behavior before the sibling routing. No sentence is filler.

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 and annotations covering safety, the description still covers the key edge cases (missing heading, blocked HTTP, truncation) so an agent can call and recover correctly without further 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?

Schema coverage is 100%, and the description still adds useful semantics for mode (Chromium fallback only on HTTP block), max_chars default/max, and the retry-oriented behavior of heading. Most parameter detail is duplicated from the schema, but the mode and truncation explanations add real 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?

The opening sentence states a specific verb (extract) and resource (one heading or one CSS selector) and explicitly contrasts it with the whole-document alternative. An agent can distinguish it from readfetch_text/readfetch_scrape 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?

Explicitly routes the agent: 'Prefer readfetch_text for full articles; readfetch_scrape when content needs JavaScript.' It also gives the mode tradeoff (fast vs render default), so when-to-use is fully specified alongside the alternatives.

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 description carries the real behavioral burden and does so: content stripping (nav/ads/boilerplate), no JS rendering by default, one Chromium fallback on block, and a relative cost signal versus readfetch_scrape. That is material context an agent cannot infer from the schema or annotations.

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 sentences, zero filler, front-loaded with the outcome and return shape, then cost/fallback behavior, then sibling routing. Every clause carries decision-relevant information.

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, so the return-values burden is already met; the description still names the key metadata fields for orientation. For a read-only, open-world fetch tool, nothing an agent needs in order to call it correctly is absent.

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% and each parameter already has a descriptive string, so the baseline is 3. The description only restates the output format choice (Markdown vs text) and adds nothing on max_bytes, timeout_s, or accept_language beyond what the schema documents.

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') plus the concrete return payload: Markdown/text, title, author, date, site name. The parenthetical contrast with readfetch_scrape ('cheaper than') and the explicit sibling references make the boundary unmistakable.

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: use readfetch_fetch for raw status/headers/non-HTML bytes, readfetch_scrape when the article only renders after JavaScript. It also states the default operating mode (no JS) and that a single Chromium fallback occurs when plain HTTP is blocked, so the agent knows both when to pick this tool and what it will silently do.

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