x402 Web Tools

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

With no annotations, the description carries the full burden and does so: it enumerates return fields (exists, verdict with its five possible values, confidence, is_retracted, best match), names the upstream data sources and their licenses, states the payment model ($0.002 USDC via x402), and clarifies that upstream errors are not charged. That is unusually rich behavioral disclosure for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and input modes are front-loaded in the first sentence, followed by return values and then provenance/cost. The sourcing and cost sentences are dense but each earns its place for a paid, external-data tool; nothing is redundant.

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

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

With no output schema and no annotations, the description must explain both behavior and returns, which it largely does via the verdict enum and is_retracted explanation. Minor gaps remain around rate limits or what 'uncertain' practically means for the caller, but the essential contract is complete.

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 every parameter is already documented, including the 'preferred if known' precedence for doi and the 'used when no DOI is given' role of title. The description restates the same precedence without adding format, matching, or fallback semantics beyond what the schema 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?

States a specific verb and resource ('Check whether a cited paper really exists') plus the motivating failure mode ('catch hallucinated or mistyped references') and the retraction dimension. This is clearly distinguishable from siblings like get_paper (fetch a paper) and search_papers (find papers).

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 invocation guidance ('Give a doi, or a title with optional year and first_author'), implying the citation-verification use case and the DOI-preferred path. It does not name alternative siblings or state when not to use it (e.g., versus get_paper when the DOI is already known to be valid), so it stops short of explicit 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?

With no annotations, the description carries the full burden and does well: it discloses the data sources (OpenAlex CC0, Crossref fallback), the $0.002 USDC x402 payment, and the notable billing rule that not-found and upstream errors are free. It omits rate limits and any auth prerequisite beyond payment.

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 identifier formats, then return fields, then sourcing/billing. The return-field enumeration is dense but each clause is informative; nothing 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?

No output schema exists, so the description compensates by enumerating the returned fields (title, authors, year, venue, DOI, counts, OA PDF, abstract, OpenAlex id, retraction flag) and it covers cost and error-billing behavior. 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 100% and the schema already names the accepted id types, but the description goes further with concrete syntactic examples (10.xxxx/..., doi.org URL, arXiv:1706.03762, W...), which reduces formatting ambiguity for the caller.

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 ('look up one scholarly work') plus the exact identifier forms it accepts, which cleanly separates it from the sibling search_papers (query-based discovery). An agent knows immediately this is a single-record retrieval keyed by ID.

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 singular 'one scholarly work' and the required id implies when to use it over search_papers, but the description never explicitly names the alternative or states when-not to use this tool. Usage is inferable rather than 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?

With no annotations, the description carries the behavioral burden, and it delivers by disclosing the return contents (status, version, tool prices, network, x402 endpoints) and the cost ('Free'). It omits any statement about side effects or auth, but for an inherently read-only diagnostic that is a minor gap.

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 tight sentences with the core purpose ('Free health check') front-loaded and the returned fields listed immediately after. No filler or redundant restatement of the 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?

There is no output schema, so the description must convey the return surface, and it does so by naming the key returned fields. The enumeration is somewhat terse ('network', 'the plain-HTTP x402 endpoints') and doesn't detail response shape, but it is adequate for a parameterless health endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema has nothing to document. The baseline for a 0-parameter tool is 4, and nothing in the description misrepresents or requires parameter explanation.

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 function ('Free health check') and enumerates what it returns (service status, version, tool prices, network, x402 endpoints), so the agent knows exactly what this endpoint provides. It does not differentiate itself from the sibling 'ping', which could plausibly serve a similar connectivity-verification role, so it lands at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Free health check' implies a diagnostic use case and the 'Free' flag hints at a no-cost call, giving implied usage guidance. However, it offers no explicit when-to-use condition, no exclusions, and no mention of how it relates to the sibling 'ping' as an alternative.

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 no annotations, the description carries the full burden and does well: it discloses that the call is paid, the exact cost ($0.001 USDC), the payment mechanism (x402), and the return payload (ok plus timestamp). It stops short of describing failure modes, e.g. what the agent sees if payment is rejected.

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 sentences with zero filler; purpose comes first, usage and cost follow. Every sentence carries information an agent needs before calling a paid endpoint.

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 zero-parameter tool with no output schema or annotations, the description supplies the essentials: purpose, return values, and the payment precondition. Minor gaps (timestamp format, error behavior on failed payment) are acceptable at this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already conveys, and it adds no misleading parameter language.

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: a paid connectivity test that returns 'ok' and a server timestamp, which is more than a tautology. It does not, however, distinguish itself from the sibling 'health' tool, which an agent will almost certainly consider alongside 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?

Gives a clear triggering context: use it to verify the x402 payment flow end to end. It omits any when-not-to-use guidance, notably that a free alternative (health) exists for plain liveness checks, so the agent must infer that distinction.

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 no annotations, the description carries the full burden and discloses important behavior: max size, conversion backend, return shape, URL safety rules by reference, failure billing exemption, and per-call cost via x402. These details go well beyond 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?

Five short, information-dense sentences with the primary action front-loaded. Each sentence contributes distinct, actionable detail (size, return, safety, billing, cost) without 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?

For a one-parameter read tool with no output schema, the description is complete: it covers the input constraint, return fields, cost model, and failure billing. The reference to read_url's safety rules is acceptable given the sibling tool is available.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'url' parameter is fully documented in the schema (100% coverage), so baseline is 3. The description adds the 10 MB limit and reiterates that the target must be public and a PDF, providing extra constraint meaning beyond 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?

States a specific verb (Fetch), resource (public PDF), transformation (convert to Markdown), and return fields. It is clearly distinguishable from sibling read_url because it targets PDFs, not generic URLs.

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 clear context and constraints for use: public PDF, max 10 MB, same safety rules as read_url, and cost. However it does not explicitly name read_url or read_url_safe as alternatives for non-PDF or unsafe URLs, so it lacks full when/when-not 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?

No annotations are provided, so the description carries the full burden and does so richly: robots.txt compliance, SSRF protections (private/loopback/metadata hosts blocked), size and time caps (3 MB / 15 s), no auth, failed reads not charged, and per-call pricing via x402. This is exactly the behavioral context an agent needs before invoking.

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 action and return payload, then constraints, alternatives, and cost, with no filler. Some clauses are telegraphic fragments ('HTML, plain text, Markdown, JSON and XML.'), but density here serves the agent rather than 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 enumerates the returned fields, and it also covers limits, auth posture, failure billing, and cost. Nothing material for a correct invocation 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% and the single 'url' parameter is fully documented in the schema, so the description adds no parameter-level meaning beyond what is already there. Baseline 3 for high coverage with no additional param guidance.

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 ('Fetch') plus resource ('public web page') and a precise statement of the output shape ('clean Markdown ... title, url, final_url, markdown, word_count'). It also distinguishes itself from the sibling read_pdf ('For PDFs use read_pdf'), so an agent can route correctly 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 when-not conditions ('Static fetch only (no JavaScript rendering)', 'no logins or paywall bypass') and names the alternative tool and the condition selecting it ('For PDFs use read_pdf'). Little is left to 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?

With no annotations, the description carries the full burden and does most of it well: it discloses the return shape (injection_check with flagged, a risk enum, and signals), the heuristic caveat, billing behavior on failure ('failed reads are not charged'), and the exact cost ($0.003 USDC via x402). It does not cover auth requirements, rate limits, or latency overhead relative to read_url.

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 dense sentences, front-loaded with the differentiating clause, followed by detection details, then caveat and cost. No filler, and the highest-value information (how it differs from read_url) comes first.

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, so describing the injection_check return object and its risk levels is exactly the right compensation, and pricing/billing behavior is covered. What is left implicit is the rest of the response payload, which is delegated entirely to the referenced sibling read_url.

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 the schema already documents it fully (100% coverage: URI format, maxLength 2048, 'Public http(s) URL to read'). The description adds no additional constraint or format guidance beyond that, 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?

Names a specific verb+resource and immediately differentiates from the sibling read_url by framing itself as 'Same as read_url plus a heuristic prompt-injection check'. The enumerated signals it detects make the added scope concrete, so an agent can distinguish it from read_url, read_pdf, or get_paper 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?

The 'Same as read_url plus...' framing makes the selection condition clear: choose this over read_url when injection screening matters. It also states the 'heuristic, not a guarantee' limitation, which helps an agent decide whether to trust the flag. It stops short of an explicit when-not-to-use statement (e.g. that the check adds latency/cost versus plain read_url).

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 no annotations, the description carries the full burden and does well: it discloses result cap ('up to 25 results'), the exact fields returned, a data caveat ('abstract ... may be null when the publisher withholds it'), source composition (OpenAlex plus Crossref for retraction notices/fallback), billing behavior ('Upstream errors are not charged'), and the x402 payment model. It stops short of rate limits, pagination beyond the limit cap, or latency expectations.

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 with purpose, then return shape, then filters, then sourcing and cost, with little redundancy. A few clauses (CC0 licensing, Crossref fallback mechanics) are marginal for tool selection, keeping 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?

With no output schema and no annotations, the description compensates well by enumerating returned fields, the abstract caveat, cost, and error-charging behavior. It is nearly complete for an agent to call the tool correctly, missing only pagination/rate-limit detail and any note on query syntax expectations.

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 every parameter including ranges and defaults, which sets the baseline at 3. The description restates the optional from_year/to_year/open_access_only filters and the result cap but adds no syntax, format, or interaction guidance (e.g. from_year > to_year handling) beyond what the schema 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 names a specific verb+resource ('Search scholarly papers') and immediately scopes it with 'OpenAlex index of 250M+ works,' which is unambiguous versus siblings like get_paper or check_citation. An agent can tell this is the free-text discovery tool without opening the 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?

Usage is implied by the verb and by the presence of from_year/to_year/open_access_only filters, and the explicit cost ('$0.005 USDC per search via x402') gives a decision-relevant signal. However, there is no explicit when-to-use/when-not guidance and no signposting toward alternatives such as get_paper for a known DOI or check_citation for citation lookup.

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 no annotations provided, the description carries the full burden and does so richly: it discloses hard limits (25 MB / 10 min, checked from the file header before transcription), rejection behavior, billing semantics (failures and no-speech files uncharged, $0.01 USDC per file via x402), and the exact model used. This is unusually complete behavioral disclosure for a tool with zero annotation coverage.

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 is front-loaded in the first clause, and every sentence carries operational information (formats, limits, rejections, billing). It is dense with parentheticals and runs long for a single paragraph, which slightly hurts scanability, but there is little wasted text.

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 4-parameter tool with no annotations and no output schema, the description covers everything an agent needs: inputs and their constraints, expected return contents (text, language, duration, timestamped segments, optional SRT/VTT), failure behavior, and cost. Nothing material is left unspecified.

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 baseline is 3, but the description adds meaning the schema does not: the url parameter must point to a direct audio file in one of the listed formats and is size/duration limited, and it corroborates the subtitles and language options. It meaningfully enriches the url semantics beyond the schema's terse 'Direct public URL of an audio file'.

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 opens with a specific verb (Transcribe) and resource (a public direct audio file URL) and immediately scopes it with accepted formats and the underlying engine. It is trivially distinguishable from siblings like read_url, read_pdf, or get_paper, which handle text/PDF/paper content rather than audio transcription.

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 when-not guidance by stating that YouTube/TikTok/Instagram and other page URLs are rejected, which steers the agent to pass only direct file URLs. It does not name an alternative sibling tool for the page-URL case, so it stops short of full routing guidance, but the conditions for correct use are clear.

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