Scrapling x402 Data Store

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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the payment semantics and does so well: price range, two-step 'call without payment to get the exact x402 price, then retry', and instant download. It does not state failure/refund behavior if payment is rejected, which keeps it below 5. No contradiction: the read-only hint refers to data, not the payment side effect.

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 tight sentences, price and paid status front-loaded, followed by use condition, output, and the payment protocol. 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?

With no output schema, the description still specifies the return formats and that all records come back, and it fully explains the paid invocation flow. Minor gap: no mention of size limits or what happens on payment failure.

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 67%, and the description compensates by naming all four output formats and explaining the api_key vs x402 payment alternative that the api_key parameter description only hints at. dataset_id provenance is already in the schema, so this adds real value on top.

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 ('buy a dataset'), the price band, and the exact scope ('every row of a dataset at once'), which cleanly separates it from preview_dataset (partial) and scrape_url (manual paging). An agent can pick it 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?

Gives a clear selection condition ('when you want every row at once instead of scraping pages yourself') and points to list_datasets for pricing. It does not explicitly say when to prefer preview_dataset or scrape_url, so sibling routing is only partly covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavior beyond that: the data is delayed ~30 minutes and free versus paid, which tells the agent when this data is or isn't fresh enough. It stops short of any rate-limit or refresh-cadence detail.

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, zero filler, with the most decision-relevant fact (FREE) front-loaded. The alternative and its price are packed into the final clause without redundancy.

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

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

With no output schema, the description carries the return-value burden and does so by listing price, market cap and 24h change. Combined with the freshness caveat and the routing to lookup_coin, an agent has everything needed to decide and call 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?

The tool takes zero parameters, so per the baseline there are no parameter semantics to document. The description usefully confirms the zero-argument nature by implying a fixed top-10 scope, though it adds nothing more about invocation.

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 (snapshot of the top 10 coins) plus the exact fields returned (price, market cap, 24h change), and explicitly contrasts with the sibling lookup_coin for broader coverage. An agent can distinguish it from lookup_coin 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?

Names the alternative (lookup_coin) and the exact condition that selects it: any of 500 coins with more fields, at $0.002. It also signals this is the free tier, giving a clear cost-based reason to prefer it for the top-10 case.

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?

readOnlyHint=true and openWorldHint=false already establish the safety profile, so the description adds real value beyond annotations: it flags the free tier, the fixed top-5 result cap, and the cost of the paid filtering path. It doesn't describe the shape of a returned yield entry, but the ranked-APY framing and the fixed cap cover most operational 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?

Three short sentences, with the most decision-relevant fact (FREE) front-loaded. Every sentence earns its place: what it returns, how it is ranked, and where to go for filtering.

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 parameterless, read-only, no-output-schema tool, the description adequately conveys the bounded result set (top 5, ranked) and the escape hatch for richer queries. Only the exact fields of each yield entry are unspecified, a minor gap for a simple ranked list.

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 is 4 and there is no parameter syntax for the description to clarify. It correctly signals parameterlessness by directing any filtering need to lookup_yields.

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, resource, and scope: the top 5 DeFi yields ranked by risk-adjusted APY. It explicitly distinguishes itself from the sibling tool lookup_yields by noting it is the free, unfiltered counterpart. An agent can route between the two 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?

It names the alternative (lookup_yields) and the exact condition that selects it: filtering by chain/token. The price of the alternative ($0.003) is included so the agent can weigh cost. This is explicit when-to-use-this-vs-that 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?

Annotations already establish readOnlyHint and a closed-world catalog, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is free, it surfaces row counts, freshness and prices, and it explicitly discloses the paid tier and its prices. It does not describe pagination or result size limits, but for a listing tool the added value is solid.

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?

A single dense sentence with the cost qualifier front-loaded ('FREE.') and no filler. The enumeration is long but each category earns its place by telling the agent what coverage to expect.

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 carries the return-value burden, and it does so by naming the entry-level fields (row counts, freshness, full price) and the paid entries with prices. It stops short of describing the exact shape, but an agent has enough to decide whether to call it.

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 about arguments. The description appropriately spends its words on the payload instead.

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 (lists) and resource (every live auto-refreshed feed) and enumerates the covered categories (crypto, DeFi, Polymarket, stocks, new pools, token risk) with what each entry carries. The free-vs-paid framing also separates it from the single-lookup siblings, so an agent can tell what it will get 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?

The leading 'FREE.' and the mention of 'paid single-lookup tools and their prices' imply this is the discovery/entry point before calling buy_dataset or a lookup_* tool, but no explicit when-to-use or when-not-to-use statement is given. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond that: the call is free, returns only a few sample rows (not full data), emits JSON, and discloses the pricing tiers for the paid siblings ($0.01–$4.99). It omits pagination/result-size limits, which 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?

Front-loaded with the two most decision-relevant facts (FREE, Use first), followed by one dense sentence. The parenthetical pricing inventory is somewhat run-on, but every element (field list, sample-row caveat, output format) earns its place for a discovery 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 and no parameters, the description carries the full burden and discharges it: it enumerates the return fields, notes that only sample rows are included, gives the output format, and explains the cost structure that motivates the downstream siblings. Nothing an agent needs to call this 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering inputs are needed and instead spends its budget on return-field semantics, which is the right trade-off.

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 (list) and resource (every dataset for sale), then enumerates the exact returned fields (id, title, category, row count, field names, created_at, sample rows, USDC price). Combined with 'Use first', an agent can place it ahead of buy_dataset/preview_dataset 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?

'FREE. Use first.' gives clear, actionable context that this is the entry-point call before the paid siblings. It stops short of naming buy_dataset/preview_dataset or stating when NOT to use it, but the intended ordering is unambiguous.

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 establish this is a read-only, non-open-world call, so the safety profile is covered. The description adds genuinely new behavioral context: the $0.002 USDC cost, the prepaid-key vs x402-per-call payment paths, and the no-charge-on-error policy. It does not cover rate limits or latency.

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, cost front-loaded, then the use case, then the error/pricing caveat. Every clause carries information an agent needs and nothing is padded.

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 compensates by enumerating the returned metrics in place of one, and it covers cost, payment paths, and error semantics. An agent has enough to call it correctly; only minor operational details such as response shape/formatting are unstated.

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 (q, api_key) are already fully documented in the schema, including accepted symbol/id/name forms and the x402 payment mechanism. The description adds no parameter-level detail beyond that, which matches the baseline 3 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 specific verb (lookup) and resource (one coin) and enumerates exactly what comes back: live price, market cap, volume, 1h/24h/7d change, distance from ATH. It does not explicitly distinguish itself from similarly named siblings like lookup_token_risk or lookup_polymarket, but the returned-field list makes the purpose unambiguous.

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?

"Use when you need one coin's live price..." gives a clear triggering condition, and "Unknown coin = error, no charge" sets an expectation for failure behavior. No explicit when-not-to-use or named alternative is given, so it falls short of a 5.

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

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

With readOnlyHint and openWorldHint already declared, the description adds genuinely useful context beyond annotations: a per-call price ($0.003 USDC) and a result cap (top 10). It does not mention behavior on zero matches or latency, but the cost and cap disclosures are meaningful additions.

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?

A single sentence that front-loads the critical pricing fact and then lists returned fields. Very little waste, though it is a fragment that could name its action verb more explicitly.

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, and the description compensates by enumerating the return fields and the top-10 cap, while annotations cover the safety profile and the schema covers both params. Payment mechanics (api_key vs x402) are left to the schema, which handles them adequately.

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 q and api_key are fully documented in the schema, and the baseline is 3. The description restates keyword matching but adds no syntax, formatting, or matching-rule detail 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 resource (Polymarket markets) and the exact payload returned (YES probability, 1h/24h/7d odds change, volume, liquidity, top 10). It is distinguishable from siblings like lookup_coin or lookup_yields, though it is phrased as a noun fragment rather than an explicit verb+resource statement.

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?

There is no guidance on when to choose this tool over the free siblings (free_crypto_top10, free_defi_top_yields) or how to phrase the keyword. Usage is only implied by the keyword-matching phrasing; no exclusions or prerequisites are stated.

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=false, so the safety profile is covered. The description adds genuinely useful context the annotations lack: it is a paid call ($0.003 USDC) and it lists what data is returned. It does not disclose rate limits, error behavior, or payment fallback beyond what the schema mentions.

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 fragments, front-loading cost then purpose, with zero filler. Every clause (price, scope, returned fields) earns its place.

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

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

For a two-parameter read-only tool with no output schema, the description covers what is returned and the pricing model. However, it leaves pool_id format unspecified and omits sibling routing, so an agent has enough to invoke it but not enough to confidently choose it over lookup_yields.

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 50%: api_key is documented in the schema, but pool_id has no schema description. The description partially compensates by clarifying that the id is a DefiLlama pool id, yet provides no format or example, and says nothing about api_key or payment beyond the cost header.

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 (lookup) and resource (one DeFi yield pool by DefiLlama pool id), and enumerates the returned fields (APY base/reward/30d mean, TVL, IL risk, risk score). It is distinguishable from lookup_yields by the singular 'one pool by id' framing, though it never names siblings explicitly.

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

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

The description gives no when-to-use guidance or exclusions; in particular it does not contrast itself with lookup_yields or free_defi_top_yields, which an agent must choose between. The only cue is implicit: you need a DefiLlama pool id, which narrows applicability but is not stated as 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?

Annotations already declare the operation as a read-only, closed-world lookup, so the safety profile is covered. The description adds a genuinely useful trait — the $0.002 USDC paid call — but says nothing about rate limits, data freshness, or what happens when payment/credits are absent.

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 terse fragments, cost first then payload, with zero filler. Every clause conveys an actionable fact.

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 correctly enumerates the returned fields, which is the key piece of missing context, and the schema handles auth/payment. Only usage routing and data-source/freshness notes are 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 description coverage is 100%: 'q' is documented as a DefiLlama slug/name with an example, and 'api_key' explains the prepaid vs x402 payment path. The description adds nothing about parameters, 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?

The description names a specific resource and its exact payload: one DeFi protocol's TVL, 1d/7d change, category, chains and market cap. This inherently separates it from lookup_coin, lookup_pool and lookup_yields, though it never names those siblings explicitly.

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

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

There is no guidance on when to choose this over lookup_coin, lookup_pool, lookup_yields or the free_* variants, and no stated prerequisites or failure conditions. The agent must infer routing purely from the resource noun.

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 cover readOnlyHint/openWorldHint; the description adds material behavioral context the agent would otherwise lack: the $0.005 USDC cost, the prepaid-key vs per-call x402 payment path, and the cached-scan-or-live-GoPlus data source. It stops short of noting latency or rate limits for live scans, and there is a mild tension between openWorldHint=false and pulling live external data.

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?

A single tight sentence that front-loads the price and the use case, then lists the checks. Every clause carries information; 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?

There is no output schema, so the description carries the burden of describing results, and it does name the headline return value (0-100 risk score) and the individual check dimensions. It does not describe the response structure or how cached vs live results differ, which leaves a small gap.

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 (address, api_key) are already fully documented in the schema, including the x402 payment mechanism. The description adds no syntax or format detail beyond what the schema provides, 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 (token risk lookup) scoped to Base tokens, and enumerates exactly what is checked: honeypot, cannot-sell, hidden owner, mintable, buy/sell tax, plus a 0-100 risk score. This distinguishes it cleanly from siblings like lookup_coin, lookup_pool, and lookup_protocol.

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?

"Use before buying a Base token" gives clear, actionable timing context for when the agent should invoke it. It does not name an alternative or state when-not-to-use, but the pre-purchase framing is unambiguous.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond annotations: the payment mechanism ($0.003 USDC via x402, or prepaid api_key) and the ranking methodology. It does not discuss failure modes if neither chain nor token is supplied.

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 tightly packed sentences with the price and output shape front-loaded; every clause earns its place. The 'PAID $0.003 USDC.' fragment is terse but effective as a lead.

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

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

With no output schema, the description carries the return-value burden and does so by specifying top 10, ranking method, and risk score. Payment and credential path are covered. Only edge behavior (no chain and no token, empty results) 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 coverage is 100%, so the baseline is 3, but the description meaningfully extends it by stating the at-least-one-of constraint on chain/token, which the schema does not enforce. The api_key/payment parameter is left to the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (DeFi yields), scope (top 10), and ranking criterion (risk-adjusted APY with a 0-100 risk score). The price prefix makes it distinguishable from the free sibling free_defi_top_yields, though the description never names that sibling explicitly.

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

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

Adds the constraint 'Give at least one of chain or token,' which is real operational guidance not present in the schema (required is empty). However, it gives no when-to-use guidance against the free siblings that appear to cover similar ground, leaving the agent to infer why it should pay $0.003.

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 cover safety (readOnlyHint, openWorldHint=false); the description goes well beyond them by disclosing the cost model (free), the sampling cap (up to 10 rows, never more than half the dataset), the exact price field returned, and the JSON output format. An agent knows exactly what calling it costs and yields.

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 tight sentences with no waste, front-loaded with the cost signal ('FREE') and the routing instruction before the return-value detail. Every clause earns its place.

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

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

With no output schema, the description fully compensates by enumerating the return payload and its bounds. For a one-parameter read-only preview tool, nothing needed to call 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?

There is a single parameter with 100% schema description coverage ('Id from list_datasets'), so the schema already carries the semantics. The description adds no extra format or sourcing detail beyond that, which is the baseline case for high 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?

States a specific verb (preview) and resource (dataset) and enumerates exactly what is returned: up to 10 rows, field names, total row count, created_at, and the exact USDC price. This clearly distinguishes it from list_datasets (enumeration) and buy_dataset (purchase).

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 says 'Use before buy_dataset to check a dataset fits your task', naming the sibling alternative and the condition that selects this tool. The 'FREE' lead-in further signals it is the zero-cost pre-purchase step.

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, the description discloses the paid nature (from $0.001 USDC), per-tier pricing, the auth model (optional prepaid api_key vs per-call x402 via _meta['x402/payment']), and the two-step payment protocol (call without payment to get the price, then retry with payment). This is unusually rich behavioral context for a network-fetching 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?

Front-loads the two most decision-relevant facts (paid, and the use case), then sequences tier options and the payment flow. Dense but every sentence carries information an agent needs; 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?

No output schema exists, and the description compensates by describing the return format, so an agent knows what comes back. Combined with the cost, tier, and payment-flow coverage, nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 75%, and the description meaningfully compensates for the bare enum values by explaining each tier's semantics, relative cost, and appropriate use case, plus the role of api_key vs x402 payment. The url and css_selector parameters are already covered by schema descriptions, so the added value centers on the tier enum, which is exactly where the schema was thin.

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 (scrape/fetch) and resource (one specific web page) and further specifies the output shape (clean Markdown, JSON-LD, HTML tables, links). The resource is unambiguously distinct from the dataset-oriented siblings (buy_dataset, list_datasets, preview_dataset), so an agent can route 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?

Gives an explicit when-to-use trigger ('current content of one specific web page') and detailed guidance for choosing among tiers based on page characteristics (cached copy vs normal page vs JavaScript/Cloudflare). It does not state when NOT to use the tool or route to a sibling alternative, so it falls short of a 5.

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