Agent Data Tools: Web, documents and search

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

Goes well beyond the annotations: it discloses the $0.001 USDC/x402 charge per successful call, prepaid-credit alternative via /credits, that failed calls are free, and that 25 calls are free up front. Crucially it explains WHY readOnlyHint and idempotentHint are false (repeat calls re-charge), turning an apparently odd annotation set into predictable 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?

Purpose and return contents are front-loaded before the payment mechanics, and each clause is informative. The pricing paragraph is somewhat sprawling for a one-word lookup tool, but every sentence carries non-redundant information about cost or free-tier behavior.

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 no output schema, the description compensates by enumerating the returned fields (definitions by part of speech, examples, link, attribution). Combined with cost, auth path, free-tier, and side-effect disclosure, an agent has everything needed to call it correctly and predict the billing outcome.

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?

Only one parameter and schema coverage is 100%, so the schema already documents 'word' fully. The description adds no format constraints (case, phrases, multi-word input), 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+resource ('Definitions of an English word from Wiktionary') and specifies the return shape: grouped by part of speech, example sentences, page link, attribution. The named source (Wiktionary) distinguishes it from the sibling 'wikipedia' tool without needing the schema opened.

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 clear use contexts ('writing help, vocabulary, translation checks and word games'), which is more than most definitions offer. It does not, however, name a when-not condition or point at the natural alternative (wikipedia) for encyclopedic word lookups, so the routing guidance is incomplete.

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?

Exceptionally transparent: explains the $0.002 x402/credits cost, 25 free calls, 2 MiB input and 20k/100k char limits, and which failures are uncharged. Critically, it explains WHY annotations show readOnlyHint=false and idempotentHint=false (repeated calls are re-charged), turning an otherwise confusing annotation set into a coherent, disclosed cost model.

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 core capability and constraints, then handles cost last. It is dense but nearly every sentence carries operative information (limits, exclusions, billing, failure behavior). Slightly long, but no filler sentences to cut.

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, return values need not be described; the description instead covers the things that matter for a paid, open-world read tool — input size, output caps, exclusions, and billing/failure semantics — leaving no operational question open.

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 nonetheless adds meaning beyond the schema by clarifying that 'section' is an exact visible HTML ID and that URL fragments do not select a section, plus the default/max output sizes.

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?

Opens with a specific verb+resource ('Read public static HTML, Markdown or plain text') and enumerates exactly what is extracted (code, tables, links, heading IDs, alt text, provenance). The explicit 'static' + 'No JavaScript rendering' wording implicitly separates it from the sibling extract_rendered, so an agent can route between them without opening schemas.

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?

Provides a clear use case ('Use to read docs or articles into context') and rules out several cases: no JS rendering, no auth, no paywalls. It stops short of naming the alternative tool (extract_rendered) for those excluded cases, so the routing is implied rather than explicit.

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 annotations: a 15-second network-settle wait, no outside side effects, a $0.01 x402/prepaid-credit charge per successful call, no charge on failures, and a direct explanation of why readOnlyHint and idempotentHint are false (repeat calls re-charge). This is exactly the kind of disclosure annotations cannot carry.

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 core differentiator and the when-to-use rule, then the cost caveat. Generally efficient, though the payment explanation runs long and 'it only reads or computes' slightly restates 'side effects: none'.

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?

No output schema, but the description points to '/extract' for output shape and covers cost, scope limits (public, no login), timing, and failure behavior — everything an agent needs to call it correctly and predict the charge.

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, section, and maxChars are already fully documented, including the enum and the 500-100000 range. The description adds no parameter-level meaning, 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+resource and immediately distinguishes itself from the sibling 'extract' by explaining the browser-rendering difference and the payoff (JS-built pages return text instead of an empty shell). An agent can select it 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 an explicit trigger condition ('Use when /extract returns EXTRACTION_EMPTY or too little text for a page you can read in a browser'), names the alternative tool, and implicitly bounds scope with 'Public pages only; no login.'

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 annotations: it discloses the x402 per-call cost ($0.002 USDC), prepaid-credit alternative, the 25 free calls, that failed calls are never charged, and explains WHY readOnlyHint/idempotentHint are false (repeating a call charges again) – resolving what would otherwise look like a contradiction. It also discloses size/count caps and leniency with real-world feeds.

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 purpose and return shape in the first sentence, then layers limits, usage, and billing. Every sentence carries information, but the billing paragraph is dense and runs long, which slightly dilutes 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?

No output schema exists, yet the description fully enumerates return fields and their formats (ISO 8601 dates, plain-text summary). For a two-parameter read tool with non-obvious billing semantics, the description covers everything an agent needs 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 already documents both parameters, making 3 the baseline. The description adds the operational note that feeds are limited to 2 MB, but otherwise largely restates the schema's 1-50 item limit without adding format or syntax 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 (read) and resource (RSS 2.0/RSS 1.0/Atom feed) and enumerates exactly what it returns (title, link, description, items with title/link/date/summary/author/id). This clearly differentiates it from siblings like extract, url_meta, sitemap and pdf_text, which don't parse feeds.

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 guidance: 'Use to follow news, blogs, release notes or podcasts without scraping pages.' It also notes non-feed pages return 422 uncharged. It does not name a sibling alternative for the scraping case, so it stops just short of a full when/when-not/alternative treatment.

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?

Excellent disclosure beyond the annotations: it explains the per-call $0.003 cost, x402/credits payment paths, why the tool is deliberately not marked read-only or idempotent (repeat calls re-charge), that failed calls are never charged, and the 25 free calls. This actively justifies the readOnlyHint=false and idempotentHint=false flags.

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 and use cases are front-loaded well, but the payment/x402 paragraph is dense and lengthy relative to the tool's simplicity. Every sentence is somewhat relevant, yet the billing explanation could be tightened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still lists the return fields (title, authors, year, venue, citation count, DOI link, abstract), states the result cap, and covers billing, free tier, and failure behavior. An agent has everything needed to call it and anticipate cost.

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 query, fromYear, and limit are already fully documented in the schema. The description only restates 'fromYear filter' and 'up to 20 results,' adding no syntax, format, or semantic detail beyond the structured fields. 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 (Search) plus resource (scholarly literature across journals, conferences, preprints and books) and enumerates the returned fields. It is immediately distinguishable from siblings like dictionary, wikipedia, or extract.

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 concrete use cases: research agents, literature reviews, fact-checking against published work, and DOI lookup. It does not explicitly name an alternative sibling or state when-not to use it, but the research/search framing is clear enough to route correctly.

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?

With annotations present, the description goes well beyond them: it explains the 10 MB limit, the 200-page and maxChars caps, the failure modes that are never charged, the $0.005 x402/credits cost, the 25 free calls, and explicitly reconciles the annotations by stating why it is not marked read-only or idempotent (repeat calls re-charge). This is exactly the extra 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?

Front-loaded with purpose, then parameters, failure modes, use cases, and the payment model. It is dense and the pricing explanation is long, but every sentence carries operative information an agent needs (cost per call, free tier, failure behavior), so little is wasted.

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?

There is no output schema, but the description fully describes the return shape (text page by page plus title, author, page count, character counts), and it covers cost, limits, and failure semantics. An agent has everything needed to invoke 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 baseline is 3, but the description adds meaning beyond the schema: a 10 MB file-size ceiling that appears nowhere in the schema, plus reinforcement of the page/character caps and defaults. It doesn't add syntax or format nuance beyond that, so it sits just above 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?

The description states a specific verb and resource ('Download a public PDF ... return its text page by page') and enumerates the returned fields (title, author, page count, character counts). This distinguishes it from sibling text-extraction tools like extract and extract_rendered by scoping it to PDF inputs and paginated text output.

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 clear when-to-use context ('read papers, invoices, reports and manuals into an agent's context') and enumerates failure cases (scanned PDFs without a text layer, encrypted files, non-PDF URLs). It stops short of naming a specific alternative tool for non-PDF or rendered content, so it is clear but not fully routing.

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 annotations by disclosing the cost model ($0.02 in USDC on Base via x402, or prepaid credits when an API key from /credits is present), that failed calls are never charged, and the 4000 px cap. Crucially it explains *why* readOnlyHint and idempotentHint are false—repeating a call re-charges—turning a potentially confusing annotation set into a coherent story.

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 capability and return payload in the first sentence, then layers usage and billing. The payment sentence is long and detail-dense, but given the unusual x402 billing it earns its place; only minor trimming is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully specifies the return payload (base64 JPEG, final URL, HTTP status, page title) and the viewport/height constraints. Combined with the billing and side-effect disclosure, an agent has everything needed to call and interpret this 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 the schema already documents url and fullPage. The description restates the 1280 px width and the 4000 px fullPage height cap, adding mild corroboration but no new syntax or format detail (e.g., fullPage is typed as string, not boolean). Baseline 3 applies when the schema does the heavy lifting.

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 ('Render any public web page in a real headless Chrome browser') and specifies exactly what comes back: a JPEG screenshot (1280 px wide, base64) plus final URL, HTTP status and page title. This clearly separates it from text-oriented siblings like extract, extract_rendered and url_meta.

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 concrete use cases ('visual checks, page previews, monitoring and feeding pages to vision models') and implicitly scopes itself to *public* pages. However, it never names an alternative such as extract_rendered for when an agent only needs rendered text, so the when-to-use-this-vs-sibling guidance is contextual rather than explicit.

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 annotations declare readOnlyHint=false and idempotentHint=false, and the description explains precisely why: every successful call costs $0.002, so repeats are charged again, and failed calls are never charged. It adds limits (512 KiB expanded, 1000 entries), gzip support, the 25-free-call allowance, and payment rails (x402 USDC on Base or prepaid credits via API key) — no contradiction with 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?

Front-loaded with purpose, then limits, then behavioral/payment disclosure. It is unusually long, but nearly every sentence carries a distinct, decision-relevant fact (billing, non-charging of failures, free tier); slight compression would still help.

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-shape detail is not needed. The description covers limits, filtering/pagination, failure and billing semantics, and sibling relationships — 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 baseline is 3; the description goes beyond it by framing the parameters as substring filtering and pagination behavior and by stating the global caps (512 KiB, 1000 entries) that bound what the parameters can return. It doesn't restate per-parameter ranges, but it adds usable context.

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 names a specific verb+resource ('Read one public XML sitemap or sitemap index') and states what it returns ('structured URLs and source-reported dates'). It also explicitly carves itself off from sibling behaviors with 'Does not crawl pages or follow child sitemaps' and routes to /extract.

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 a concrete when-to-use ('Use to find which pages of a docs site to read before calling /extract') plus explicit when-nots ('Does not crawl pages or follow child sitemaps'). An agent knows exactly where this fits relative to extract, feed, and url_meta.

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?

With annotations only flagging readOnlyHint=false, idempotentHint=false and destructiveHint=false, the description explains the surprising reason: each successful call costs $0.01 via x402/card credits, so repeats charge again, while failed calls are never charged. It also confirms no outside side effects and what processing happens (fetch, strip boilerplate, LLM summarize) — real context beyond 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?

Purpose and output are front-loaded, followed by usage then side-effect/payment caveats, so nothing critical is buried. The pricing sentences are dense and slightly verbose, but each one resolves a genuine ambiguity about why the tool is not read-only or idempotent.

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 single-parameter tool with no output schema, the description still specifies the return shape (summary + 3-6 key points) and fully covers the non-obvious cost/permission model. Nothing an agent needs to decide whether and how to call it 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?

Only one parameter, and schema description coverage is 100% ('Absolute http(s) URL of the page to summarize'), so the schema already carries the semantics. The description adds no format or constraint detail beyond it, matching the baseline for a fully-covered 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 precise verb (summarize) and input (URL), and defines the exact output: a short summary plus three to six key points. This output shape implicitly distinguishes it from siblings like extract and extract_rendered that return raw content, and url_meta that returns metadata rather than prose.

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 concrete use contexts ('research, news triage, link previews and deciding whether a page is worth reading in full'), which is clear positive guidance. It stops short of explicitly naming alternatives (e.g. use extract when you need the full text), so no exclusion-based routing is provided.

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 annotations declare readOnlyHint=false and idempotentHint=false, which would otherwise look contradictory for a metadata fetcher; the description explicitly explains the reason (each successful call is charged via x402/credits, so repeats cost again, while failed calls are free). It also discloses hard limits (512 KB max, no JavaScript execution) and the 25-free-call quota — none of which the annotations 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?

It is front-loaded: capability and returned fields first, then use cases, then side effects and payment. Every sentence carries non-redundant information, though the payment/quota passage is dense enough that the whole definition runs long for a one-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still details what is returned, the 512 KB/no-JS limits, absence of external side effects, and the pricing/quota model that explains the unusual annotations. An agent has everything needed to call it correctly and predict the cost.

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?

There is a single parameter with 100% schema description coverage ('Absolute public http(s) URL of the page'), so the schema already carries the semantics. The description adds no syntax or format detail beyond that, which is the baseline-3 case for full coverage.

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 ('Fetch a public web page's head') and then enumerates the exact payload it returns (title, description, OG/Twitter-card fields, favicon, theme colour, etc.), so an agent can distinguish it from generic siblings like extract or extract_rendered at a glance.

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 concrete use cases ('build link previews, label citations or check how a URL will unfurl before sharing it'), which tells the agent when this is the right tool. It does not explicitly name an alternative sibling (e.g. extract or screenshot) or state when not to use it, so it stops short of full routing guidance.

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?

It goes well beyond the annotations by disclosing cost ($0.001 USDC on Base via x402, or prepaid card credits with an API key), the 25 free calls, and that failed calls are never charged. Crucially it explains WHY readOnlyHint and idempotentHint are false - repeating a call recharges - turning an otherwise confusing annotation set into a coherent story.

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 and return contents are front-loaded in the first sentence, and every subsequent sentence carries required information (payment mechanism, failure behavior, free tier). The pricing detail is dense and somewhat lengthy, but it is not padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the burden of describing the return value (title, extract, description, thumbnail, URL) and does so fully, plus it covers the commercial and failure semantics. An agent has everything needed to call this 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 description coverage is 100%, so both parameters are already documented in the schema and the baseline is 3. The phrase 'any language edition' adds a little framing for lang, but no syntax, defaults or format detail beyond what the schema supplies.

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 resource (Wikipedia article) and enumerates the returned fields (title, one-paragraph extract, description, thumbnail, page URL), which is far more than a tautology. It is clear what the tool does, but it never names or contrasts a sibling (e.g. extract, url_meta, dictionary), so the differentiation is implicit rather than stated.

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 positive use case - 'ground an agent's answer in a quick, citable fact sheet' - which signals intent. However, there is no when-not guidance and no mention of when a competing sibling (extract, url_meta, summarize) would be the better choice, leaving selection largely to inference.

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