Tanod Finance

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds substantial context beyond that: the exact list and date basis, false-negative caveat, compliance limitations, verification link, latency, price, and free-tier limit. Nothing contradicts the 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-loads the core purpose and alternatives, then packs caveats, limits, and pricing into a single dense paragraph. Every sentence carries operational information, though the result is long and could be more scannable.

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

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

Given the tool's screening complexity, single-address schema, existing output schema, and safety annotations, the description covers scope, alternatives, limitations, timing, cost, and verification guidance. It omits nothing material for correct selection or invocation.

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

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

Schema covers the address parameter at 100% with a description and pattern. The description adds matching semantics: EVM/bech32 addresses match case-insensitively while base58 BTC, TRX, and other formats must be provided exactly as listed, useful for correct input formatting. It does not restate the schema's length/pattern constraints.

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: screen one crypto address against the US OFAC SDN digital-currency list. It explicitly names the sibling tools check_sanctions_batch and check_address_poisoning and distinguishes single-address vs lookalike use cases, so an agent can select it 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?

Explicitly routes to alternatives: use check_sanctions_batch for up to 1,000 addresses and check_address_poisoning for lookalikes. It also states scope (OFAC SDN digital-currency addresses only), that a non-match does not clear, and that this is not legal advice or full compliance.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: bounded reads (12 RPC calls), a `coverage` field, per-window counted/estimated/lower_bound semantics, the yield definition (USD paid / market cap now, not annualized), error handling (404 not_reward_token, 422 not charged), 5-minute caching, latency bounds, pricing, free-tier quota, and a prompt-injection warning about untrusted text.

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

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

The core question and outputs are front-loaded in the first two sentences, followed by operational detail. It is dense but nearly every sentence carries actionable information; only a light overlap with the title keeps it from a 5.

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

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

An output schema exists, so return-value explanation is not strictly needed, yet the description still characterizes the result states, windows, and yield basis. Combined with error codes, latency, caching, and quota, an agent has everything required to call and interpret the tool 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% for the single `mint` parameter, so the schema already documents the base58 mint address and its constraints. 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 and resource – returns whether a Solana reward token still pays holders – and enumerates the concrete outputs (PAYING/STALE/NEVER, last payout, 7d/30d payouts and yield). It explicitly distinguishes itself from the closest sibling (check_solana_token_safety for rug risk), so an agent can route 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 tool for a related but different question ('For rug risk use check_solana_token_safety'), which gives clear routing context. It implies when the tool applies (assessing whether a reward token still pays) but does not lay out explicit when-not conditions, 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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: indicative-not-oracle caveat, the USDC cross-check pricing method, the 30s pool read cadence, error handling (failed coin in `errors`, 502/422 outcomes), no-charge behavior for failures, latency, price, and free-tier rate limits. This is a genuinely rich behavioral disclosure.

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

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

Front-loaded with the core purpose and well organized, but the asset list is repeated across the title and both first sentences, and pricing/latency/limits are packed densely. Slightly redundant but every sentence carries operational value.

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

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

Complete for a zero-required-param read tool: purpose, alternative, error/status mapping, cost, and rate limits are all present, and an output schema exists to cover return values. 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 description coverage is 100% and the schema already documents coins, case-insensitivity, omit-for-all default, and the 422 unknown-coin behavior. The description largely restates this, so the baseline 3 is appropriate — it adds no syntax or semantics 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+resource ('Check stablecoin peg') and enumerates the exact assets covered (USDC, USDT, DAI, USDe, PYUSD) and the source (Ethereum Uniswap V3 pools). It explicitly names and routes away from the sibling get_stablecoin_supply, so an agent can distinguish 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?

Provides an explicit alternative with its selecting condition: 'For supply by chain use get_stablecoin_supply,' which contrasts against this peg-check scope. The purpose sentence itself makes the when-to-use obvious (checking peg status). This matches the high-bar pattern of naming the sibling to use instead.

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 readOnly/idempotent/non-destructive, but the description goes well beyond them: 60 s cache TTL, 422 on bad input with no charge, 0.3-2 s latency, USD 0.003 price, 10 free reads per IP per UTC day, and a docs link. Unusual amount of operational context.

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 comparison in the first sentence, then constraints, then operational details. Dense and slightly run-on with pricing/caching/docs packed together, but each sentence carries actionable information.

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

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

With an output schema present, annotations covering the safety profile, and 100% schema coverage, the description only needs to add constraints and operational context — which it does (venue intersection, volume gating, caching, error/pricing). Nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: min_volume_usd must be satisfied on both venues (not just one) and unmatched symbols surface in symbols_not_found. Useful clarification of cross-venue filtering behavior.

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 (compare) and resource (perpetual funding rates) and names both venues in scope (Hyperliquid vs dYdX v4). It also distinguishes itself from the sibling rank_funding_carry, so an agent can route between them 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?

Explicitly routes the five-venue/fee-net-of-fees case to rank_funding_carry, and states the comparison constraint (only assets listed on both venues). It does not mention get_funding_rates or get_perp_markets, leaving a small gap in sibling 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?

Annotations already declare read-only, idempotent, non-destructive behavior, yet the description adds substantial operational context beyond them: 15 s cache, the 65,000 gas-unit assumption (not measured), Solana lamport fees plus new-token-account rent, per-chain error handling with failing chains listed last, 502 on all-fail, 422 on bad input, latency 1-5 s, price, and free tier. This is unusually rich disclosure.

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

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

Front-loaded with purpose and the sibling alternative before dense operational detail. Every sentence carries information, though the pricing/error/latency block is packed tightly and reads as a spec dump rather than prose.

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-format explanation is unnecessary; the description still covers error semantics, caching, cost, rate limits, and performance. For a 3-param read-only comparison tool, nothing an agent needs 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?

Schema description coverage is 100%, so the schema already documents token, amount (including that it is informational only), and chains. The description adds only the Solana lamport/rent detail, which is not a parameter concern. 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 specific verb (compare) plus resource (USDC/USDT transfer fees) and enumerates the exact chains covered. It explicitly distinguishes itself from the sibling check_stablecoin_peg by naming it as the tool for peg status, so an agent can route correctly 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 tool and the condition that selects it ('For peg status use check_stablecoin_peg'), and clarifies the default scope (all six chains). When-to-use and when-to-use-something-else are both 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?

Goes well beyond the annotations (which only cover read-only/idempotent safety) by disclosing bad-input behavior (422, not charged), latency (<0.2 s), price and the 10-free-calls-per-IP-per-UTC-day quota, and an accuracy caveat that holiday rules are library-modelled and should be confirmed with an official source for legal/payroll use.

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 the mode split are front-loaded, and most information earns its place. It is dense and includes some boilerplate (pricing, docs URL) and re-explains return values the output schema already carries, so it is not maximally tight.

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

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

With an output schema present and 100% parameter coverage, the description only needs to frame behavior, and it does: both modes, inclusion semantics, supported date ranges (20 years; 1990-2100 with a country), error code, cost, and a legal caveat.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds value by grouping which parameters apply to which mode (end/include_start/include_end for count; days/weekend/country/subdivision for add) and flags that weekends are configurable and a country adds its public holidays.

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 two specific operations with verb+resource: count business days between two dates, or add working days. It distinguishes itself from the sibling get_public_holidays by naming it and explaining the relationship (this tool uses the holiday data, that tool lists 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?

Explains when to use each mode (count vs add) with the Excel NETWORKDAYS/WORKDAY analogies and routes to get_public_holidays for the holiday list. It does not compare against other date siblings (convert_time, cron_next_runs, expand_rrule), so the routing is clear but not exhaustive.

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

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

Beyond the read-only and idempotent annotations, the description adds substantial behavioral context: one value per day from an hourly cache, typical latency under 0.1s, 503 behavior when cache is stale or absent, attribution requirements, pricing, and a free-call limit. These details tell an agent exactly what to expect at runtime.

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

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

The description is front-loaded with purpose and usage, and most sentences carry operational value such as cache behavior, pricing, and limits. It is somewhat repetitive between the first sentence and the 'Returns...' sentence, but the repetition does not obscure the most important information.

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

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

Given the simple parameterless interface, the existing annotations, and an output schema, the description is complete for correct selection and invocation. It covers return content, cache and error behavior, attribution requirements, cost, rate limits, and an alternative tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not need to compensate for any schema gaps.

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 verb: 'Get the crypto Fear & Greed Index,' and specifies the exact returned fields (value 0-100, label, 7-day history). It also distinguishes the tool from a sibling by directing agents to get_local_crypto_premiums for a different use case.

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

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

It explicitly routes agents to an alternative for local exchange premiums and provides clear usage boundaries, including that the data is informational only and not investment advice. It also states the cache-freshness limit and the 503 condition when data is unavailable or older than 3 days.

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 readOnly/idempotent annotations, the description discloses that the data comes from one allow-listed pool rather than an exchange feed, that DEX prices can differ from CEX, that a swap-less candle repeats the prior close, and that the last candle is still forming. It also covers failure modes (422 before payment, 503 warming_up/rpc_unavailable not charged) and 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?

Purpose is front-loaded, followed by the alternative, then data provenance, caveats and operational details. It is dense and long, but nearly every sentence carries distinct information; 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 an output schema present and rich annotations, the description need not explain return values, and it still covers provenance, caveats, error/payment semantics, latency and pricing. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so pair, limit (with per-interval lookback caps) and interval are already fully documented in the schema. The description restates the intervals and that a bad pair/interval/limit yields a 422, but adds little parameter meaning beyond what the schema provides, so the baseline 3 holds.

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

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

States a specific verb and resource (get OHLCV price candles) and pins the exact scope: ETH (WETH/USDC) or BTC (cbBTC/USDC) in USDC from Uniswap v3 on Base. It explicitly distinguishes itself from the sibling get_token_price, so an agent can route 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 route explicitly ('For the oracle price now use get_token_price') and makes the use case (historical/forming candles vs. spot oracle) clear. There is no explicit when-not-to-use or statement about which other price siblings to prefer, but the context is strong.

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?

Going well past the annotations (readOnly/idempotent/openWorld/non-destructive), it discloses the cache's refresh cadence, that as_of exposes staleness, that only the top-25 chains are covered, exact failure modes (422 with suggestions on unknown names, 503 on missing/stale cache) and that failures are not charged. It adds latency, price, and free-tier quota, which no structured field carries.

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 the alternative, then behavioral and pricing details in descending priority. Dense but every clause carries operational information; it is on the long side but not padded with restated schema content.

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-shape explanation is unnecessary, and the description covers everything else an agent needs: input combinations, caching semantics, error behavior, cost, quota, and a docs link. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by explaining the combination semantics (one, both, or neither) and what each combination yields. It does not restate the limit bounds or slug examples, which the schema already handles.

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 (Get) and resource (DEX volume by protocol and chain), and explicitly routes the adjacent need elsewhere: 'For TVL use get_protocol_tvl.' It also enumerates the four output shapes (a DEX's chains, a chain's largest DEXs, a DEX on a chain, market total), so an agent can tell it apart from siblings 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?

Clear usage rules: give protocol, chain, both or neither, and it names the alternative tool for TVL. It also flags the cache-only nature so an agent knows not to expect live data. It does not, however, differentiate from other DEX-volume-adjacent siblings such as get_dex_price_candles, leaving some sibling routing 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: cached (never live, refreshed every few hours), wallet provenance (exchanges' published/labelled wallets), what a rise means, exact symbol matching, and error behavior (422 unknown asset/exchange, 503 missing/stale cache, neither charged). This is exactly the extra transparency the bar rewards.

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 purpose and alternative before the operational detail; the pricing/free-tier/docs tail is dense but each sentence carries information. Slightly long, but nothing is wasted for an agent deciding and invoking correctly.

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

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

Complete for a 3-param cached-reader with an output schema: purpose, return shape, cache freshness, matching rules, error codes, latency, pricing and docs link are all present, so an agent knows what to expect and how to recover from failures.

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 asset, days and exchanges. The description adds meaning beyond it: symbols matched exactly ('WBTC is not BTC'), the semantics of a rise, and what the history window represents, though it does not restate per-parameter formats.

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 ('how much of a coin sits on centralised exchanges and whether it is flowing in or out') and explicitly names the sibling to avoid: 'For DEX volume use get_dex_volume.' An agent can distinguish it from get_dex_volume, get_protocol_tvl and similar reserve/flow tools 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?

Explicit when-to-use ('judge selling pressure or check reserves before depositing') plus a named alternative with its condition ('For DEX volume use get_dex_volume'). Also notes the prerequisite-ish paywall/free-tier limits, which shape whether to call it at all.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description goes well beyond them: 422 vs 5xx error semantics, that failed calls are not charged, latency expectations (under 0.1 s, up to 10 s on refresh), pricing (USD 0.001) and a free tier of 10 calls per IP per UTC day. It also discloses provenance (ECB euro reference rates, Tanod-computed cross rates) and a licensing disclaimer.

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 alternative in the first two sentences, then attaches operational facts. The licensing/attribution and 'not for transactions' clauses are somewhat boilerplate for a paid reference-rate API but are justified by the data source, so the length is defensible rather than 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?

An output schema exists, so return values need no explanation. Everything an agent needs to call it correctly — required param semantics, date window, error-and-billing behavior, latency, pricing, and the sibling alternative — is present.

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 documents base/date/symbols and the baseline is 3. The description adds real semantic value about the base parameter — non-EUR bases are cross rates computed by Tanod rather than raw ECB figures — plus a corroborating note that older dates are rejected, which is slightly more than the schema alone conveys.

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 ('foreign-exchange reference rates for a base currency') and explicitly distinguishes itself from the sibling get_live_fx_rates by naming that alternative for live on-chain rates. 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?

Gives an explicit when-to-use-elsewhere rule: 'For live on-chain rates use get_live_fx_rates.' It also names the conditions that produce failures (unknown currency, older dates → 422; ECB outage → 5xx), so the agent knows the boundaries of correct invocation.

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 (readOnly/idempotent/non-destructive) by disclosing caching (20 s), latency (2-6 s typical, 25 s max), pricing (USD 0.01), a free quota (10 reads/IP/UTC day), error behavior (404 for no pool, 422 for bad address, not charged), heuristic USD sizing, and a prompt-injection warning about untrusted page/on-chain text.

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

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

Front-loads the purpose and the price-alternative routing, then packs operational facts efficiently. It is dense and delivered as one long run-on paragraph, which makes scanning for the paying/latency/quota facts harder than a short bulleted list would.

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?

Although an output schema exists and return values need not be described, the description still covers the scan-coverage caveat, latency, cost, quota and error handling. Nothing an agent needs to call it correctly and interpret the 'coverage' field 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%, so the schema already documents mint, limit ('newest first, 1 to 100') and min_usd ('high value over a short scan can return no trades'). The description largely restates ordering and adds no new syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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 ('Who is buying this Solana token? Recent large trades: big buys, sells and swaps by mint') and scopes it to a single token mint. It also distinguishes itself from the sibling get_solana_token_price by redirecting price queries there, so an agent can route correctly without opening a schema.

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

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

Explicitly names an alternative for the price use case ('For the price use get_solana_token_price') and defines the selection constraint ('Size-based only, no wallet is labelled'). It does not, however, contrast against other trade/volume siblings such as get_large_token_trades or get_dex_volume, so when-not conditions are only partially 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 readOnly/idempotent/non-destructive, and the description goes well beyond them: 30 s cache, 422 on bad address or oversized window (and not charged), 3-6 s typical / 25 s max latency, USD 0.01 price, free-tier limit, and honest limitations (misses trades outside top 3 pools, heuristic amounts, no wallet labels). This is the level of disclosure that actually changes how an agent calls the 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-loaded with purpose, then alternatives, then return shape, then caveats — a sensible order. It is a single dense block that packs in a lot (latency, price, cache, error codes), which is justified by the tool's complexity but borders on overloaded.

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

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

For a read tool with a full output schema, this covers everything an agent needs: routing, return fields, data-quality caveats, error behavior, latency, cost, and a docs link. Nothing material 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 every parameter already carries its own description, including the Base 60 / Ethereum 240 window rationale and min_usd semantics. The description largely restates those constraints rather than adding new parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Recent large trades: big buys and sells on Base or Ethereum') and names exactly which sibling covers the Solana case and which covers quoting. An agent can distinguish this from get_large_solana_token_trades and get_swap_quote without opening any schema.

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

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

Explicit routing: 'For Solana use get_large_solana_token_trades; for a quote at your size use get_swap_quote.' It also implies when-not via the size-based-only caveat, so the agent knows this tool won't help for small or wallet-attributed flows.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing snapshot freshness ('refreshed about every 5 minutes' with as_of/stale fields), protocol/chain coverage, that APY excludes rewards, error semantics (422 on bad input, not charged), latency (<1s), price, and free-tier limits. These are exactly the behavioral traits an agent needs for planning and budgeting.

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 usage, then return shape, then operational constraints in a logical order. It is dense but nearly every sentence is actionable; only the pricing/free-tier/docs boilerplate edges toward padding, and the title duplicated in the opening 'chainpeek:' prefix is slight 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 an output schema present, return values need not be re-explained, and annotations already cover the safety profile. The description fills the remaining gaps an agent needs: when to use it, coverage, data freshness, reward exclusion, error behavior, and cost, making it complete for a zero-required-param query 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 all six parameters (view, limit, assets, chains, protocols, min_tvl_usd) including enums and defaults. The description echoes the best_stablecoin view and the stablecoin set but adds no syntax, format, or interaction detail beyond what is already structured. Baseline 3 applies when the schema carries the load.

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 (current lending supply and borrow APY) with named protocols (Aave V3, Compound V3, Morpho) and explicitly distinguishes itself from siblings by naming get_protocol_tvl and get_funding_rates as the tools for adjacent data. An agent can separate this from every other yield/DeFi tool in the sibling list 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?

Front-loads the trigger condition ('Use when an agent must choose where to lend or borrow') and then explicitly routes two adjacent needs elsewhere ('For protocol TVL use get_protocol_tvl; for perp funding use get_funding_rates'). Both when-to-use and when-not-to-use are stated, leaving nothing 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?

Despite readOnlyHint/idempotentHint being present, the description adds substantial context annotations cannot carry: 15 s pool cache, 60 s exchange cache with stale data retained up to 300 s, as_of/age_s meaning fetch age not venue age, venue_timestamp null, thin/errors reporting, 503 exchange_unavailable and 422 for unknown pair (both uncharged), typical 2–4 s latency, $0.002 price and a 10-call/day free tier.

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 decision-relevant usage and alternative, and nearly every clause carries operational fact (caching, error codes, pricing). It is dense and symbol-heavy (thin, stale, age_s, gap_pct) and long, which slows parsing, but little is actually 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?

With an output schema present the description needn't enumerate returns, yet it still names the key fields (bid/ask/mid, deviation_pct, exchange_quotes, exchange_gaps/gap_pct) and covers failure modes, latency, cost and freshness. Nothing an agent needs to invoke it correctly or interpret results 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%, so the schema already documents pairs format, supported set, exchange-only vs on-chain pairs, and amount_usd's role in the thin threshold. The description largely restates that pair coverage (USDCHF/EURGBP/EURJPY exchange-only, USDCAD also on-chain) rather than adding new syntax or defaults, so baseline 3 applies.

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

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

The opening sentence states a specific verb and resource — live on-chain FX rates for eight named currencies vs USD, plus exchange quotes for eight pairs — and explicitly distinguishes the not-ECB variant from the sibling get_fx_rates. An agent can select 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?

It gives an explicit use condition ("Use when an agent needs on-chain ... not ECB") and routes the excluded cases — ECB fix or a past date — to get_fx_rates by name. It also warns the quotes are indicative and not dealable arbitrage, which constrains how the output may be used.

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

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

Annotations already cover readOnly/idempotent/non-destructive safety, but the description goes well beyond them: data provenance (public tickers, Chainlink, ECB/BCRA FX), 30s cache, typical (<0.5 s) vs worst-case (~10 s) latency, error semantics ('failed venue in errors', all-fail = 503 and not charged), and the ~0.5% noise floor. This is unusually rich operational disclosure.

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

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

Front-loaded with the use case and alternative before any mechanics, and each clause carries distinct information. It is long and packs billing/legal/docs lines into the same block, which slightly dilutes scannability, but there is little true 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?

An output schema exists so return-value structure need not be explained, and the description still covers scope (assets, countries), failure behavior, latency, cost and rate limits. 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?

Schema description coverage is 100% and both params are documented with allowed values and defaults in the schema itself. The description only restates that both are optional and default to all, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource+scope: it measures the local-exchange premium (kimchi/USDT) versus global price, and explicitly names the sibling get_crypto_fear_greed_index as the alternative for global sentiment. An agent can distinguish it from the many other crypto tools 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?

It states the triggering need ('when an agent needs to gauge local demand for crypto') and routes the agent away to a named alternative ('For global sentiment use get_crypto_fear_greed_index'). That is explicit when-to-use plus an exclusion.

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

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

Annotations already cover readOnly/idempotent/openWorld, and the description adds substantial context beyond them: explicit non-coverage (VIX, equity indices, gold land in `not_included`), null commodities with `not_configured` when no EIA key, failure handling (`sources_failed` with null section, 503 when all fail and not charged), latency (under 0.2s cached, up to ~30s on the slow Treasury feed), price and free-tier limits.

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 scope are front-loaded in the first sentence, followed by inclusion/exclusion, failure semantics, and operational facts. It is dense and mostly earns its length, though the licence/source attributions and docs/pricing sentence add bulk that could be trimmed for a fast-selecting agent.

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

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

With an output schema present, the description need not explain return shapes, and it instead covers everything else an agent needs: scope, exclusions, degraded-source behavior, latency, cost, and free-tier limits. Nothing material for 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to clarify. The description correctly implies a no-argument call, and there is no gap to compensate for.

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 ('get/return one macro snapshot') and enumerates exactly what the snapshot contains: US Treasury par yield curve with spreads, ECB euro rates, a dollar-index proxy, EFFR/SOFR, WTI/Brent/Henry Hub. It also explicitly distinguishes itself from the sibling treasury_yield_curve, so an agent can route without opening another schema.

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

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

Gives a clear when-to-use ('needs the rates backdrop before a market decision') and names one alternative for a specific case ('For the Treasury curve on a past date use treasury_yield_curve'). It does not, however, address the FX-focused siblings (get_fx_rates, get_live_fx_rates) or other market-data tools, so when-not coverage is partial.

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 readOnly/idempotent annotations it discloses charge semantics (unknown account charged, bad-id 422 and failed RPC 503 not charged), the fact that pool delegations are excluded from locked_near, untrusted-string handling, finality/RPC, latency, price and a per-IP free quota. This is unusually rich behavioral context that the annotations alone would not 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?

Purpose and scope are front-loaded before the operational and error details, and virtually every sentence carries distinct information. It is dense and long, with slight redundancy between the opening summary and the 'Returns a NEAR account's...' clause, keeping it off a perfect 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?

Despite an output schema existing, the description covers what an agent needs to call it correctly: error outcomes, charging behavior, latency, pricing, rate limits, and the security caveat about untrusted on-chain strings. Nothing material is left for the agent to infer.

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 format of account_id is already documented. The description still adds meaning about how inputs are interpreted: an unknown account yields exists=false (and is charged) while a syntactically bad id is a 422, which goes beyond the schema's format contract.

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 + resource ('Get a NEAR account') with the exact returned fields enumerated (balance, staked NEAR, storage, access keys, contract deployed). It explicitly distinguishes itself from the EVM path by routing to get_portfolio, and the sibling list contains no other NEAR-account tool, so scope is 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?

It names an explicit alternative with the selecting condition ('For EVM balances use get_portfolio') and notes the boundary 'no history'. It does not name a tool to use for historical data or state further when-not conditions, so it stops short of a full 5.

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

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

Annotations already declare read-only/idempotent/non-destructive, yet the description adds substantial context beyond them: cached (never live), refresh cadence, `as_of` staleness signal, 422 with suggestions for unknown protocols, 503 for missing/stale cache, neither charged, sub-1s latency, price and free tier.

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 what the tool does before the error/caching/pricing clauses, and each clause carries real information. It is dense and slightly run-on, but not 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?

An output schema exists, so return values need not be described. The description still covers caching semantics, error modes, latency, and cost, leaving nothing an agent needs in order 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 coverage is 100% and the single `protocol` parameter already documents name/slug and parent-summing behavior. The description largely repeats this (including the 422-on-unknown note), adding little beyond the schema; baseline 3 is appropriate.

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 (get a protocol's fees and revenue) and explicitly routes the sibling case away: 'For TVL use get_protocol_tvl.' An agent can distinguish this from the nearest sibling 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 (get_protocol_tvl) and the condition that selects it, and labels the tool 'Informational only.' No coverage of when not to use it beyond the TVL case, but the critical routing decision is 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?

Annotations cover safety (readOnly, idempotent, non-destructive), but the description adds substantial context: cached DefiLlama data refreshed every few hours and never live, `as_of` for cache age, 422 with suggestions on unknown names, 503 on missing/over-2-day-old cache with no charge, sub-second local reads, USD 0.004 price, and a 10-read/day free tier. This is unusually rich behavioral disclosure.

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

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

Front-loaded purpose and sibling routing are excellent, but the middle sentence ("Returns the TVL of a protocol or chain with 1d and 7d change, the protocol's chains or the chain's largest protocols...") restates the opening and is denser than needed. Overall efficient, with mild 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?

An output schema exists, so return values need no explanation. The description still covers freshness, error codes, latency, pricing, and rate limits — everything an agent needs to call it correctly given the tool's complexity.

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 per-parameter meaning is already documented. The description still adds cross-parameter semantics ("give one, both or neither") and the composed behavior of protocol+chain, which is value beyond the schema — though it stops short of detailing all combination outputs.

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?

Starts with a specific verb and resource ("Get protocol or chain TVL with 1d and 7d change") and immediately contrasts itself with two named siblings, get_protocol_fees and get_dex_volume. An agent can distinguish this from every other DeFi-data tool without opening a schema.

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

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

Explicitly routes the agent: "For fees and revenue use get_protocol_fees; for DEX volume use get_dex_volume." It also states the input combinations ("give one, both or neither") and what each produces, leaving nothing 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?

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them: 422 error semantics with no charge, sub-0.1s latency, USD 0.001 price, a 10-calls-per-IP-per-UTC-day free tier, and an important accuracy caveat that data comes from python-holidays rules rather than an official calendar.

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 purpose, then routing, error behavior, cost/latency, caveat and docs link in a logical order. Every sentence carries distinct information, though the pricing/latency/free-tier block makes it denser than strictly necessary.

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 no explanation. The description covers the remaining gaps an agent would care about: the alternative tool, error behavior, cost, rate limits, and the reliability caveat for legal/payroll use.

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 year, country, language and subdivision. The description only references these parameters collectively via the 422 message and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (public holidays of a country for a year), and the title reinforces it. It explicitly names the sibling it is not for ('To count working days use count_or_add_business_days'), so an agent can separate it from count_or_add_business_days 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 alternative and the condition that selects it: counting working days routes to count_or_add_business_days. It also tells the agent what happens on bad input (422 naming supported values), so edge-case routing is covered.

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

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

Goes well past the annotations (which only declare read-only/idempotent/open-world) by disclosing 15-second caching, pool-source coverage, error semantics (422 no_pool, 422 malformed before payment, 503 unreachable/stale/failing RPC, none charged), latency of 1-4 s, and payment/free-tier terms. This is exactly the kind of operational detail 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 purpose and efficient, but the error/payment information is stated twice in near-identical form: 'no pool is a 422 no_pool and an unreachable pool list or stale oracle a 503 (neither charged)' and 'A malformed input is a 422 before payment and a failing RPC read a 503 (neither charged).' That duplication costs it a point.

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

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

With an output schema already present, return values need no explanation, and the description still covers coverage scope, caching, latency, failure modes, and cost. Nothing an agent needs to invoke 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?

Schema description coverage is 100% and the single mint parameter is already fully documented in the schema (SPL Token or Token-2022, base58, length bounds). The description adds only 'by mint address', which restates the schema, 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?

States a specific verb and resource ('Get the USD price and liquidity of a Solana token by mint address') and immediately names the sibling it is not for ('For large recent trades use get_large_solana_token_trades'). An agent can distinguish it from get_solana_token_info, get_token_price, and get_dex_price_candles without opening any schema.

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

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

Explicitly routes one case to an alternative (large recent trades -> get_large_solana_token_trades) and constrains coverage to Raydium/Orca/Meteora pools against USDC/USDT/SOL on mainnet. It gives clear qualifying context but no explicit 'do not use for X' exclusions beyond the one sibling named.

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 read-only/idempotent/non-destructive, but the description adds far more: data is cached DefiLlama data refreshed every few hours and never live, `as_of` exposes staleness, 422 vs 503 error semantics, neither error is billed, typical latency under 1s, and pricing/free-tier limits. This is exactly the extra context the 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 purpose and the alternative tool, then behavior, then inputs, then operational constraints. It is dense and every sentence carries information, though the leading "chainpeek:" tag and the repeated mention of cached DefiLlama data are mildly redundant against the title.

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

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

An output schema exists, yet the description still sketches the return shape, and it covers staleness, error codes, billing, rate limits and a docs link. Nothing an agent needs to decide or call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents coin, chain and limit in detail. The description nevertheless adds genuine meaning beyond the schema by spelling out the combination semantics (one, both, or neither) that govern how those fields interact.

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 gives a specific verb+resource ("Get stablecoin supply by coin and chain") and immediately names the sibling it must not be confused with (check_stablecoin_peg for peg status). An agent can route correctly 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 states the alternative tool and the condition that selects it, and it explicitly resolves the parameter-combination question ("give one, both or neither") plus what each combination returns (a coin's chains, a chain's coins, or the largest coins and chains). No usage inference is required.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond that: 422 for an unsupported pair with the 'not charged' caveat, typical latency of 0.2-1s, $0.002 price, a 10-reads-per-IP-per-UTC-day free tier, and a prompt-injection warning about treating returned page text and on-chain strings as untrusted. This is unusually rich disclosure for a paid, open-world 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-loaded with the core verb+resource in the first clause, then alternatives, error/cost/latency facts, and a safety note. Dense but each sentence carries actionable information; the pricing/free-tier detail makes it slightly heavier than strictly necessary.

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 covers the remaining gaps an agent needs: alternatives, failure semantics, cost, latency, free tier, and untrusted-data handling. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and both params carry enum lists with descriptions already covering the pair allow-list and the Ethereum/Base-only constraint. The description adds only the pair×chain failure mode (422 on an unavailable pair), so the baseline 3 is appropriate.

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 ('read a token price from a Chainlink on-chain price feed') and immediately frames the scope qualitatively as a deterministic oracle answer rather than a DEX spot price. It names two sibling tools it is not, so an agent can distinguish it without opening a schema.

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

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

Explicitly routes alternatives: use get_swap_quote for a DEX quote of any token, and get_solana_token_price for Solana. Combined with the 'oracle not DEX spot' framing, the selection condition between oracle pricing and DEX pricing is clear.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, and the description adds meaningful traits beyond them: error outcomes (422 for bad input, 422/503 unquotable, not charged), latency (1-3 s), cost (USD 0.005) and a free tier (10 chain reads/IP/UTC day). It also clarifies the semantic subtlety that impact is measured against the smallest size, not the market, and that the result is not a firm price.

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 the sibling alternative are front-loaded, and most sentences carry distinct operational facts. It is dense and slightly cluttered by enumerating return fields the output schema already defines, plus pricing/docs appended in-line, but nothing is fatally wasteful.

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

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

For a read-only pricing tool with a full output schema, the description covers usage routing, error semantics, cost and timing, so an agent can call it correctly and interpret partial failures. Nothing needed for 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%, so the baseline is 3 and the schema carries most parameter meaning. The description still adds value by explaining ordering ('smallest first'), the impact reference point ('against the smallest size, not the market') and that unquotable sizes surface as error rows.

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 ('Check a Uniswap V3 swap at up to five sizes') with the scope of the check (price impact and candle gap) front-loaded. It explicitly names the sibling get_swap_quote and the condition that separates them, so an agent can disambiguate 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 gives an explicit routing rule: 'For one quote use get_swap_quote,' with the multi-size capability being this tool's differentiator. The error-handling conditions (422/503) and refund note further reduce misuse.

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 readOnly, idempotent, openWorld, and non-destructive, but the description adds substantial operational context beyond them: gross vs. net spread calculation, normalisation to hourly annualised rates, `venues_failed` and `symbols_not_found` behavior, 60-second caching, 422 on bad input (not charged), 1–5 s latency, USD 0.005 price, and a free-tier rate limit. That is a rich behavioral profile.

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

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

The description is front-loaded with the core purpose and alternatives, then layers on detailed behavior. It is dense but every sentence adds information; the pricing and free-tier lines are operationally useful though slightly tangential to selection, keeping it just short of 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?

Despite an output schema existing, the description still clarifies key return concepts (best long/short pair, gross vs. net spread, failed venues, missing symbols), and it covers error handling, latency, and caching. For a 6-parameter, read-only ranking tool, nothing an agent needs 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?

Schema description coverage is 100%, so the schema already documents all six parameters, including the taker-fee formula. The description repeats the taker-fee/net relationship rather than adding new parameter semantics beyond what the schema provides, so the baseline 3 is appropriate.

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 first sentence states a specific verb and resource: 'Rank cross-venue perpetual funding carry.' It also names the exact scope (five venues) and explicitly distinguishes itself from siblings compare_funding_rates and get_perp_markets, so an agent can select 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?

Explicitly routes the agent: 'For Hyperliquid against dYdX alone use compare_funding_rates; for market data use get_perp_markets.' This gives both a when-to-use and named alternatives, leaving no inference needed for tool selection.

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 readOnly/idempotent/openWorld/non-destructive, and the description layers on substantive behavior: caching up to 1 hour, error taxonomy (422 bad input, 404 company_not_found, 503 outage), the fact that error responses are not charged, latency of 1-3s (sub-0.1s cached), pricing, and a free-tier rate limit. It also flags the informational-only disclaimer and no-implied-endorsement constraint.

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 the sibling routing before descending into response fields, errors, latency, price and docs. Dense but well ordered; the pricing/free-tier/docs tail is long, though each element is actionable for an agent that must decide whether to spend a call.

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

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

For a read-only lookup with an output schema and full schema coverage, the description covers everything an agent needs: inputs, alternatives, response shape, error semantics, cost, rate limits and data provenance. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint not encoded in the schema: exactly one of ticker or cik must be sent. It also hints at accepted CIK formats (leading zeros/prefix), which the schema covers, and clarifies what include_facts adds to the response.

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 ('Look up a company in SEC EDGAR by ticker or CIK') and enumerates the returned fields (name, CIK, tickers, exchanges, SIC, state, FY end, latest 10 filings). It explicitly distinguishes itself from the sibling sec_financials, so an agent can route 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 and the condition selecting it: 'For financials per year or quarter use sec_financials.' It also spells out the input contract ('Send exactly one of ticker or cik') and how failures map to 422/404/503. There is no broader when-not-use guidance, but the main routing decision is covered.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses tie-breaking ('Latest comparable filed fact wins (/A, accession, tag ties)'), null handling for missing metrics, caching up to 6 hours, latency (1-4 s, under 0.1 s cached), price and free-tier limits, and the exact 422/404/503 error semantics including which are not charged.

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

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

Front-loaded with purpose and the sibling hand-off, and nearly every clause carries operational information (tie-breaking, errors, limits). Slightly overpacked with pricing/legal boilerplate ('Informational only, not investment advice... no SEC endorsement implied'), which dilutes but does not bury the useful content.

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

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

For a read-only lookup with an output schema, everything an agent needs to call it correctly is present: input exclusivity, period semantics, cost, rate limits, latency, and failure modes with charging implications. No call-blocking gaps remain.

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 genuinely new constraints: ticker and cik are mutually exclusive and exactly one must be sent (neither is marked required in the schema), and the 'up to 20' cap on periods. It does not add format detail beyond what the schema's ticker/CIK descriptions already give.

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 ('Get a US company's reported financials per fiscal year or quarter from SEC EDGAR') and enumerates the returned metrics (revenue, income, EPS, balance sheet, cash flow, capex, shares). It explicitly distinguishes itself from the sibling sec_company_lookup, which handles the registrant and filings.

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 tool and the condition that selects it ('For the registrant and filings use sec_company_lookup'), and specifies the input rule 'Send exactly one of ticker or cik'. The annual vs quarterly scope is restated so the agent knows which mode to pick.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds real operational context: nothing is signed or sent, unreadable parts become not_checked with verdict warn, a missing blacklist function is not_available rather than a fail, bad input returns 422 and is not charged, typical latency 1-4 s, price USD 0.01 and a free 10 reads/IP/day. These are exactly the caveats 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 purpose, then alternatives, then return shape, then caveats and pricing; every sentence carries information. It is dense for a single paragraph and the 'chainpeek:' prefix plus docs URL add some noise, but nothing is truly 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?

For a 5-param, no-nested-object tool with an output schema, the description still summarizes the return contract (verdict, checks rows, reasons) without over-explaining return values, and covers failure modes, cost, latency and free-tier limits. Nothing an agent needs 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?

Schema description coverage is 100% and the schema already explains each field (address format, chain enum, USDC/USDT-vs-contract token rule, decimal amount in token units not raw units). The description adds only marginal parameter-level meaning, chiefly that the lookalike check is chain-conditional. Baseline 3 is appropriate since 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?

Opens with a specific verb+resource+scope: 'Preflight a USDC or USDT transfer' and enumerates the exact checks (balance, gas, nonce, blacklist, recipient, simulation). It clearly distinguishes itself from sibling tools like check_sanctions, check_wallet_drain, check_token_honeypot and estimate_gas by naming them as alternatives.

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

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

States the trigger condition ('one planned ERC-20 transfer') and explicitly routes two adjacent needs elsewhere: OFAC screening to check_sanctions and historical wallet pulls to check_wallet_drain. It also scopes a sub-check geographically (lookalike on Ethereum and Base only), so the agent knows when a result will differ by chain.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description layers on real operational context: 6-hour refresh eligibility, possible stale copy with published date within 24 h, 422 for bad/pre-1990/future dates and 503 for upstream outage (neither charged), typical <0.1 s vs ~25 s cold path, price and free-tier quota. This is exactly the added value annotations cannot express.

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

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

Front-loaded with the core purpose and the sibling pointer, then progressively discloses return shape, fallback, errors, latency and cost. It is dense but nearly every clause carries actionable information; the legal disclaimers ('not investment advice', 'no Treasury endorsement') and docs link are the only soft 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?

For a single-optional-parameter read tool with an output schema, the description covers everything an agent needs to call it correctly: valid date range, default, fallback semantics, failure codes, cost, rate limit, and latency expectations. Return-value shape is left to the output schema, as intended.

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's own date description already covers the format, valid range, default, and the adjusted:true fallback. The description restates the nearest-earlier-curve behavior without adding syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get US Treasury yields: the daily par yield curve for a date') and scopes the output precisely (1 Mo to 30 Yr, percent, nulls where unpublished). It also names the sibling it does not replace (get_macro_snapshot for SOFR/FX/oil), so an agent can distinguish 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 explicit routing to get_macro_snapshot for related macro data and clarifies default-date behavior, so the agent knows the primary use case and one alternative. It stops short of full when-not guidance (e.g. no mention of whether to prefer this over check_solana_reward_token_yield or lending-yield siblings for yield comparisons).

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 past the annotations (readOnly/idempotent/non-destructive) with charging semantics (invalid identifier is a normal, charged answer; malformed request is a 422, not charged), offline python-stdnum execution with no registry/bank/VIES call, in-memory-only handling with no logging, latency (~0.1 s), price, and free-tier quota. These are exactly the operational facts an agent needs for cost and privacy decisions.

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

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

Dense but front-loaded: purpose, then sibling routing, then return shape, then operational behavior. Every clause carries non-redundant information, and no sentence merely restates the tool name or annotations.

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 enumerated, yet the description still names the key fields and error reasons. Combined with pricing, error-code semantics and the offline caveat, 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?

Schema coverage is 100%, so the baseline is 3, but the description still adds real meaning: it constrains the `luhn` kind (no payment card numbers) beyond the schema's 'generic mod-10' wording and illustrates what the kind-specific `detail` field carries. The `value` length/character constraints remain schema-only, which keeps this from a 5.

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

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

States a specific verb+resource ('check the format and check digits of an identifier') and immediately routes two adjacent cases to named siblings (decode_vin for VINs, parse_phone_number for phone numbers). An agent can distinguish this from lookup_lei/search_lei and validate_json without opening any schema.

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

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

Explicit alternatives and when-not conditions are given: VINs go to decode_vin, phones to parse_phone_number, and 'Payment card numbers are not accepted, not even under `luhn`' rules out a tempting misuse. It also states the scope boundary (format/checksum only, no registry or VIES lookup), which tells the agent when this tool is insufficient.

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