AgentFeed

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

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing that decimals()/symbol() are read live from the contract, that ENS is resolved via two independent resolvers with agreement required, that unsupported chains are rejected rather than mis-answered, and that each call costs 0.005 USDC. These are exactly the operational facts 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?

Purpose and scope are front-loaded in the first sentence, followed by the highest-value behavioral caveats. Some sentences carry defensive/marketing flavor (the 'trillion times too large' example, resolver trust prose) that is longer than strictly necessary, but none are wasted entirely.

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 values; the safety profile is covered by annotations and the pricing, chain-support, and ENS-resolution behaviors are all stated. 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% so the baseline is 3, but the description adds genuine meaning: it explains the address/ENS contract for the required param and why token metadata is resolved at request time rather than assumed, which contextualizes the token parameter's 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?

Opens with a specific verb+resource+scope: ERC20 and native ETH balance on Base or Ethereum mainnet for an address or ENS name. An agent can immediately tell this apart from pricing/gas/wallet-activity siblings 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 clear usage context: chain must be base or ethereum, unsupported chains are refused, and cost is 0.005 USDC via x402. It does not name a sibling alternative (e.g. get_wallet_holdings) or state when NOT to use this tool, so it stops 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?

Goes well beyond the annotations: it discloses a per-call cost of 0.005 USDC with the x402 payment rails and accepted chains, and states the data comes from keyless public RPC with three-node fallback so no API key must be managed. This is exactly the auth/payment/reliability context annotations cannot express. No contradiction with readOnlyHint/idempotentHint.

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 and the payment/source facts are compact and useful. The 'a caller asking in wei and a caller asking in gwei are asking the same question' sentence is mildly redundant justification that could be trimmed, but the whole is still 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?

An output schema exists, so return values needn't be described; the description still names the returned fields and notes they appear 'when the node supplies them.' Combined with annotations covering safety and the description covering cost and sourcing, nothing needed to call this correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter noise, and its unit discussion (gwei and wei both returned) usefully frames the no-argument call.

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

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

States a specific resource and scope: 'Base gas price (chain 8453)' plus the exact fields returned (base fee, priority fee, block number). An agent immediately knows what this retrieves. It stops short of 5 because it never distinguishes itself from overlapping siblings like get_priority_fees or get_base_balance, which an agent scanning a 90-tool list would need.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite get_priority_fees and get_eth_price sitting adjacent and partially overlapping. The sentence about wei vs gwei explains output units, not tool selection. The agent must infer usage purely from the name.

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: it discloses the polling cadence (Base logs every minute), the staleness failure mode (>5 min snapshot returns 503), the enrichment applied (honeypot simulation only for the busiest pools), and the per-call cost with payment method (0.02 USDC via x402 across listed chains). These are exactly the operational facts an agent needs before calling.

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 trigger phrase and then packs the return shape, freshness contract, and pricing into dense but non-redundant sentences; every clause conveys something new. It is a single long paragraph, though, and could be easier to scan if the cost/freshness caveats were separated from the payload description.

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 (so return fields need no explanation), the description still covers freshness guarantees, failure behavior, cost, and venue scope. For a read tool with full schema coverage, this is complete enough for an agent to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so both `limit` (1-100, default 20) and `min_liq_usd` (quote-side liquidity, default 1000, 0 = all) are already fully documented in the schema. The description adds only the "newest first" ordering, which the schema already states, 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 resource (newest token launches / pools created in the last 24 hours on Base) and enumerates the venues covered (Uniswap V4/V3/V2, Aerodrome), which cleanly separates it from siblings like get_honeypot_check or get_liq_feed. An agent can identify the tool's scope 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?

"Use when an agent needs the newest token launches on Base" gives a clear triggering context, and the 24-hour window tells the agent when the tool's data is applicable. It does not name alternatives or state when not to use it (e.g. vs. a generic top-movers or honeypot tool), so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds genuinely new behavioral context: a 0.01 USDC per-call cost and the x402 payment rails (Solana, Base, Polygon, Arbitrum, Arc). That payment/auth detail is valuable and not present in the schema or annotations.

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

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

It is a single dense sentence that front-loads the core definition before the cost/payment tail. It is slightly long but every clause (metric definition, oracle methodology, output forms, price) earns its place.

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

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

With an output schema present, return-value detail is not strictly required, yet the description helpfully summarizes what is returned and discloses the cost mechanism. Combined with annotations covering safety, the definition is essentially complete for a one-parameter read 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?

There is a single optional parameter with 100% schema description coverage (symbol with example values and a default), so the schema already carries the semantics. The description adds nothing beyond confirming the scope is 'any Hyperliquid perp', making the baseline 3 correct.

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 metric (perp basis = mark price vs Hyperliquid oracle price), and defines the computation and its output form (premium/discount %, contango/backwardation, funding context). An agent can distinguish this clearly from siblings like get_funding_rate, get_perp, or get_spot.

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 scopes the tool to 'any Hyperliquid perp' and discloses the per-call cost, which implies usage context, but gives no explicit when-to-use/when-not guidance versus adjacent siblings such as get_funding_rate or get_trade_context. Usage is only implied.

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), yet the description adds substantial context: the three-pool median methodology, the explicit explanation that confidence is null because no pool publishes it, the per-call cost of 0.001 USDC, and the accepted payment rails (x402 on Solana, Base, Polygon, Arbitrum, Arc). The pricing/auth disclosure is exactly the kind of behavior an agent needs and cannot get from structured fields.

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

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

Three dense sentences, purpose front-loaded before methodology, cost, and payment details. Parentheticals carry load-bearing specifics (pool pairs, payment chains) rather than filler, and nothing is redundant with the schema 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 format needn't be described, yet the description still proactively explains the null confidence field — a genuine output quirk. Methodology, cost, and data provenance are all covered, leaving no gap an agent must fill before calling.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are needed, and there is nothing further to clarify about parameter semantics.

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 with full scope: 'Live BTC/USD spot price read on-chain', including the exact data sources (Uniswap V3 on Base and Ethereum, cbBTC/USDC, WBTC via WETH/USDC). This clearly differentiates it from siblings like get_eth_price, get_sol_price, and the generic get_spot without opening any schema.

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

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

The description explains methodology and cost, which implies usage, but never states when to prefer this over get_spot or other price tools, nor any when-not conditions. Usage is inferable from the name and the 'live on-chain' framing, but no routing guidance is given.

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, so the safety profile is covered. The description adds genuine context beyond that: the empty-array-means-no-cascade convention and the 0.01 USDC per-call payment requirement (x402, listed chains), which is real auth/cost information an agent needs.

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 first, then return shape, then the alternative, then cost. Every sentence carries information. Slightly packed, but no filler.

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

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

With an output schema present, the description needn't detail return values, yet it helpfully summarizes fields and the empty-result case. It covers scope, the key alternative, and cost. Minor gap: no mention of the forecast/history siblings that share the 'cascade' namespace.

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 all three parameters (window, min_usd, min_events) are documented in the schema with ranges and defaults. The description adds no additional meaning about these parameters, 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+resource (liquidation cascade detector) scoped to the 5 majors, and names what it returns (active NOW, with symbol/side/USD/prints/duration/severity). It explicitly differentiates from the sibling get_cascade_scan by restricting itself to the majors.

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 every USDT perp we record across 3 exchanges, use get_cascade_scan.' It also implies real-time-only scope ('active NOW', empty array = none). It does not, however, distinguish itself from get_cascade_history or get_cascade_forecast, which are equally close siblings.

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

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

Annotations already declare the read-only/idempotent safety profile, and the description adds substantial context beyond them: per-call cost (0.02 USDC across five chains), the decline-rather-than-guess behavior, what every answer carries, and the calibration data provenance.

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 key distinction (forward-looking vs historical) before details. Dense but mostly earning its place; the multi-chain cost enumeration and record-provenance sentences are slightly heavy for a tool description.

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 explained. The description covers purpose, behavior, cost, and failure mode, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so symbol/symbols are fully documented in the schema itself. The description adds no syntax or format detail beyond what the schema already 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+resource (probability a symbol liquidates more in the next 15 minutes than its 90th-percentile window) and explicitly separates itself from historical siblings with 'FORWARD-LOOKING and not a description of what already happened'. An agent can distinguish it from get_cascade_history 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?

Gives clear context for when the tool applies (forward-looking probability, declines when a state has too little history) and discloses cost. However, it never routes the agent to the obvious alternative, the sibling get_cascade_forecast_free, nor explains when the free version suffices versus this paid one.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the free nature, the scope (SOL only), and the purpose of calibration checking, which goes beyond the structured metadata.

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

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

Two sentences, front-loaded with the key facts: 'FREE taster' and 'full-quality liquidation forecast for SOL.' No filler, every word contributes to understanding the tool's scope and purpose.

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

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

The description is complete for an agent to select and invoke correctly. It explains what, scope, and why to use it. The output schema exists, so return format details are not required. It fully covers the free vs. paid distinction and the use case.

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?

With zero parameters and 100% schema coverage (empty schema), the description has no need to explain parameters. The baseline for 0-param tools is 4, and the description appropriately omits any param details.

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 clearly states it is a free liquidation forecast for SOL, explicitly noting it is the 'full-quality' version with 'no delay and nothing withheld.' It distinguishes itself from the paid sibling get_cascade_forecast by being free and limited to SOL, making its purpose unambiguous.

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

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

It explicitly tells when to use: 'Use it to check the calibration before paying for coverage of the other ~345 symbols.' This implies the alternative (get_cascade_forecast) for broader coverage and provides clear context for 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 cover readOnly/idempotent/non-destructive/openWorld, but the description adds genuinely new behavioral facts: the 0.03 USDC per-call cost, x402 payment flow and accepted chains, the 72h retention window, and that events are reconstructed from the provider's own tape. These are material for deciding whether to call the tool and are not in any structured field.

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

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

Three tight sentences, front-loaded with what the tool returns before the disambiguation and cost note. Every sentence carries distinct information (data shape, sibling contrast, price), with no filler.

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

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

With an output schema present, return values need no prose, and annotations carry the safety profile. The description closes the remaining gaps an agent would care about: cost, payment mechanism, retention window, and how this differs from the live cascade endpoint.

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

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

Schema description coverage is 100%, so gap_s, hours, scope, symbol and min_usd are all documented in the schema. The description only reinforces the 72h retention bound, adding no syntax or default detail beyond what the schema already gives; 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 (liquidation cascade history) and defines exactly what is returned: clustered same-side flush events with start/end, prints, USD total and peak print. The explicit contrast with '/api/cascade' separates it from the live-scan siblings.

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?

Clearly routes the agent: '/api/cascade tells you what is happening NOW; this tells you what already happened', giving a concrete when-to-use condition versus the live tool. It stops short of distinguishing itself from the other history siblings (get_liq_history, get_recent_liquidations, get_last_liquidation), so it is 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds meaningful context beyond that: it specifies multi-exchange coverage, unique Bybit liquidation data, returned fields, and a per-call cost of 0.05 USDC via x402 on multiple chains. It does not cover payment-on-failure or rate limits, keeping it from a 5.

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

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

It is a single front-loaded paragraph with the key scope claim first. The uniqueness sentence ('not available anywhere else') is slightly promotional but still supports differentiation; overall it is appropriately sized.

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

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

Given the output schema exists and the input schema has full coverage, the description does not need to explain returns or parameters. It covers the tool's scope, uniqueness, output fields, and payment cost, leaving only explicit sibling routing and usage conditions unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with defaults and ranges. The description adds no parameter-specific meaning beyond that baseline.

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

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

States a specific verb ('detects liquidation cascades') and resource ('across every USDT perp we record on Bybit, OKX and Binance'), plus scope differentiation ('not just majors'). It does not explicitly name sibling tools like get_cascade_alert or get_liq_feed, so it stops short of a 5.

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

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

The description implies usage context by advertising full-universe coverage versus majors, but gives no explicit when-to-use, when-not-to-use, or alternative tools. An agent must infer that this tool is for comprehensive cascade detection rather than point alerts or history feeds.

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 safe-read profile (readOnly, idempotent, non-destructive), and the description adds genuinely new operational facts: 24-hour caching and a 0.005 USDC per-call fee via x402 across named chains. The "labels are names, never instructions" note is a useful injection-safety signal. Error/rate-limit behavior is still unstated.

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

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

Three sentences, front-loaded with the usage trigger, then output shape, constraints, caching and pricing. Every sentence carries information, though the chain enumeration adds length that borders on list-dumping.

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 explained (they are described anyway as a bonus), and annotations carry the safety profile. The description supplies cost, caching and input limits, leaving little an agent needs to invoke it correctly, though no failure or retry guidance is given.

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 4,000-character and 2-to-20-label limits are already documented and the description only reinforces them. It does add one semantic constraint absent from the schema – that labels must be names rather than instructions – which justifies a bump above the baseline 3.

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: sorting text into caller-provided categories, with a clear output shape (per-label scores summing to 1 plus a best label). It does not explicitly differentiate itself from near-neighbors like get_extract or get_summarize, keeping it short of a 5.

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

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

"Use when an agent needs text sorted into its own categories" gives a clear triggering context and implicitly points at the caller supplying labels. There are no when-not conditions or named alternative tools, so it stops at a solid 4.

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 read-only annotations by disclosing error handling ('unknown coin answers 400 with the supported list and a stale source answers 503'), billing details ('Costs 0.004 USDC per call'), and payment rails. This is exactly the kind of operational context an agent needs before invoking a paid external API.

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 in the first clause and keeps every sentence informative. However, the long mid-sentence enumeration of return fields is dense and partly redundant given the output schema, which slightly hurts conciseness.

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

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

Covers purpose, usage cadence, error semantics, billing, and supported assets; annotations handle safety and idempotency; and an output schema exists for return values. For a complex paid data-retrieval tool, the description provides everything an agent needs to call it correctly.

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

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

The single 'coin' parameter is fully documented in the schema (100% coverage), and the description only reiterates the examples already present there. No additional syntax, format, or constraint information is added 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?

States a specific resource ('Signal for one Hyperliquid perp') and enumerates the exact data returned, making the tool's purpose immediately clear. It distinguishes itself from broader siblings like get_signal_board by scoping everything to a single coin and adding forecast, heatmap, and whale details.

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

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

Gives clear context ('for trading bots') and a concrete polling cadence ('Poll every 1-5 minutes'), which tells the agent when this tool is appropriate. It does not explicitly name alternative tools or state when not to use it, but the per-coin aggregation scope implies the intended use case.

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

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

Annotations already declare it read-only, idempotent and non-destructive, and the description layers on genuinely useful context beyond them: precision (12 significant digits), failure behavior (cross-category mix returns 400 and is never billed), and the payment model (0.005 USDC via x402 on Solana/Base/Polygon/Arbitrum/Arc). Cost and error semantics are never derivable from annotations alone.

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

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

Three tight sentences with no filler; the usage trigger is front-loaded, then output precision, then error and cost semantics. Every clause carries information an agent can act on.

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 restate return shape, and it still summarizes the return (converted value to 12 significant digits). For a 3-parameter, read-only, paid tool, the description covers invocation, failure mode, and billing, leaving nothing material unstated.

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

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

Schema coverage is 100% and each of value/from/to is documented in the schema, so the baseline is 3. The description adds only indirect parameter context (the set of valid unit categories and the category-mixing constraint) and gives no syntax or format detail beyond what the schema states.

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 operation (convert a value between units) and enumerates the covered categories (length, mass, volume, time, data, speed, area, pressure, energy, temperature), which cleanly separates it from siblings like get_fx_rates (currency) or get_base_gas (chain metrics). An agent can identify this as the unit-conversion tool 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?

"Use when an agent needs an exact unit conversion" gives an explicit trigger condition, and "Mixing categories is a 400" communicates a clear exclusion/constraint. It stops short of naming an alternative tool for edge cases (e.g. FX/currency conversion), so it is clear context rather than full when/when-not 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond them: the exact record/certificate payload, the public-hosts-only scope limit, and the 0.005 USDC per-call cost with the accepted payment rails. It stops short of describing failure modes (NXDOMAIN, unreachable hosts, missing cert).

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

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

Three tight sentences, front-loaded with the use case, then the return payload, then scope and cost. Every sentence carries distinct information; no filler.

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

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

With an output schema present the description needn't detail return values, yet it does so helpfully; annotations cover safety; and cost, payment rails and scope exclusions are all disclosed. An agent has everything needed to decide and call.

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

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

Only one parameter and schema description coverage is 100% – the schema already specifies 'a hostname such as example.com (no URL, no IP address)'. The description adds only the constraint that hosts must be public, which is marginal over 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 resource (a domain's basic facts) and enumerates exactly what it returns: A/AAAA/MX/NS/TXT records plus the live TLS certificate with issuer, SANs, validity and days-to-expiry. No sibling tool performs domain lookups, so it is trivially distinguishable from the surrounding finance/crypto tools.

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

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

'Use when an agent needs the basic facts about a domain' gives a clear trigger, and 'Public hosts only; no registrar data' carves out an explicit exclusion. There are no competing siblings to route against, so the absence of a named alternative is acceptable, but no prerequisite or edge-case guidance is offered.

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). The description adds real value beyond them: it discloses the limitation 'No SMTP probe' and the per-call cost (0.005 USDC via x402 across named chains), which materially affects invocation 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?

Three sentences, tightly front-loaded: trigger first, then what it returns, then the SMTP limitation and cost. Every sentence earns its place with no 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 not be re-explained; the description still summarizes the verdict vocabulary. Combined with cost, limitation disclosure, and covered annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the single parameter is documented as 'the address to check, up to 254 characters'. The description adds no syntax or format detail 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 resource (email address deliverability) and enumerates the exact checks performed (syntax, MX, disposable-domain, role-account, free-provider) plus the verdict types. No sibling tool performs email verification, so the definition unambiguously owns this capability.

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?

Opens with an explicit trigger: 'Use when an agent needs to know whether an email address can plausibly receive mail.' Clear context for invocation, though it names no exclusions or alternative tools for adjacent tasks (e.g. generic domain or sanctions checks).

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond that: the actual data sources, the session taxonomy returned, explicit 'indicative, never an exchange quote' caveat, 503 error condition when no source has liquidity, and a pay-per-call cost of 0.01 USDC via x402 across named chains.

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

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

The purpose and asset class are front-loaded, and the trailing sentences carry distinct information (caveat, error behavior, cost). The first sentence is a dense run-on with many stacked clauses, which is slightly heavy, but nearly every element earns its place.

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

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

For a single-parameter pricing tool with an output schema already present, the description supplies everything an agent needs: scope, sources, session/return semantics, error behavior, and payment model. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single symbol parameter is already documented with examples, so the baseline is 3. The description adds example tickers (TSLA, NVDA, S&P 500, Nasdaq) but these largely restate the schema examples (which use SP500, XYZ100), adding little new meaning.

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

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

States a specific verb/resource and scope: an indicative 24/7 price for US stocks or indices sourced from Hyperliquid stock perps and a tokenized-stocks DEX. It clearly separates itself from crypto-price siblings like get_btc_price, get_eth_price, get_sol_price by naming the equity asset class explicitly.

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

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

Implied usage is clear from the framing ('Weekend price for US stocks', session labels including weekend), so an agent can infer it is for off-hours equity pricing. However, it never explicitly says when to use this versus alternatives such as get_tradfi_perps, get_spot, or get_tradfi_radar, leaving 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 cover readOnly, idempotent, openWorld, and non-destructive, so the safety profile is handled. The description adds genuine behavioral context beyond that: the exact on-chain data source, the median-plus-per-pool return shape and cross-chain spread, and a concrete cost of 0.001 USDC per call via x402 with accepted chains.

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

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

Four tight sentences, front-loaded with the purpose and source, then return shape, then sourcing caveat, then cost. Every sentence carries distinct, non-redundant 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 and annotations covering the safety profile, the description needs only to establish what is measured, from where, and at what cost – all of which it does. 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?

The tool takes zero parameters, so there is nothing to disambiguate; the schema is empty and 100% covered. The baseline of 4 applies since no parameter-level meaning is missing.

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 (ETH spot price in USD) with the data provenance spelled out: read on-chain from the two deepest WETH/USDC Uniswap V3 pools on Ethereum and Base. It is trivially distinguishable from siblings like get_btc_price and get_sol_price, and even from an exchange-feed price tool.

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

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

The description implies a use context ('Computed from chain state; no exchange feed') which differentiates it from feed-based pricing, and it discloses a per-call cost. However, it never explicitly names an alternative or states when-not to use it, so routing guidance is only implied rather than stated.

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

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

Annotations already state readOnly/openWorld/idempotent. The description goes well beyond them by disclosing that data is 'computed from the tape at request time, nothing hardcoded,' that it is free, and that the status vocabulary distinguishes events like 'a router refusal and an empty book' as different facts. These are behavioral specifics not derivable from 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?

The description is a dense single paragraph covering many distinct aspects (measurement methodology, corroboration rule, status vocabulary, control design, row counts, covered symbols, cadence) with no filler. It is front-loaded with 'FREE' and the core question about overhang, though a bulleted structure would slightly improve scannability.

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

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

For a zero-parameter read-only informational tool with an output schema, the description is complete: it explains what is returned, why the tool exists, how the data is computed, and when to use it relative to the paid sibling. Nothing an agent needs to correctly select and invoke the tool 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 has zero parameters and schema coverage is trivially 100%, so the baseline of 4 applies. The description correctly contains no parameter information because none is needed for invocation.

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

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

The description clearly defines the tool as returning the methodology and live-computed data behind exit liquidity measurements, with specific phrases like 'Returns what is measured' and 'the corroboration rule in plain terms.' It distinguishes itself from the paid sibling get_exit_quote by being explicitly 'FREE' and framed as the precursor, so an agent can tell it apart 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?

It explicitly tells the agent when to use it: 'Read this before paying for get_exit_quote, and to check the claim rather than trust it.' This both identifies the alternative tool and the condition that selects this one, 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 only declare safety (readOnly, idempotent), so the description adds real behavioral context: REFUSED-quote vs no-route status distinction, six consecutive agreeing observations required before a verdict, fallback to last corroborated measurement with its age rather than null, and the caveat that zero bad debt doesn't disprove findings. This is exactly the kind of non-obvious behavior an agent needs.

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, then lays out return fields and the corroboration/refusal nuances. The sentences are dense and mostly earn their place, but the parentheticals and the 'zero bad debt' caveat push toward long-windedness.

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 isn't required, yet the description still names key fields (max_exitable_usd, exitable fraction, conservative bound, nearest-probe realised USD/haircut/margin). With annotations covering safety and the schema covering both params, only minor gaps remain (e.g., exact cost flow timing for x402).

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 parameters already carry their meaning (symbol examples; size_usd maps to nearest MEASURED clip, never interpolated). The description reinforces the 'nearest clip actually probed' idea but adds no syntax or format detail beyond the schema. 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 (measure exit liquidity on seized collateral) against a specific resource (a Kamino reserve sold into live routing, versus oracle price), and enumerates its return fields. Distinguishable from siblings in a crowded liquidation family, and explicitly points to get_exit_method for the method.

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?

Sets clear context (measuring realisable exit value on seized collateral) and points to get_exit_method for method/corroboration details, plus discloses the 0.02 USDC x402 payment. It doesn't name a sibling that should be used instead when you don't need liquidity measurement, but the intended use case is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely new behavior: null for unstated fields rather than invented values, and a per-call cost of 0.025 USDC across five chains. This is exactly the extra context 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?

Three tight sentences: use condition, output contract, cost. Every sentence carries distinct information and the when-to-use clause is front-loaded ahead of the mechanics.

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?

Output schema exists so return shape needn't be repeated, yet the description still clarifies the null semantics that govern the schema's values. With only two fully documented params and a clear cost/authorization note, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both params are documented in-schema, including the 20-field/2 KB constraint. The description restates the field count and type palette rather than adding syntax or format meaning beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb+resource: extracting named fields from a page or PDF into JSON. Clear enough to distinguish from raw-text siblings like get_ocr/get_pdf_markdown, but it never names those alternatives, so the agent must infer the distinction.

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

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

"Use when an agent needs named fields from a page or PDF" gives a clear triggering condition. It stops short of stating when NOT to use it or pointing to the sibling extraction tools, so the routing guidance is contextual rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds minimal extra behavioral context: it is free and includes a classification. It does not contradict annotations, but it does not disclose rate limits, update frequency, or other operational nuances.

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 extremely concise and front-loaded: it states the data source, scale, output characteristic, and cost in two short sentences. Every word adds value with no 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?

For a zero-parameter, read-only tool with an output schema and comprehensive annotations, the description is sufficient for an agent to understand what the tool provides and to invoke it correctly. Missing usage guidance is captured under usage_guidelines, not completeness.

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 has zero parameters)Skip, and schema coverage is 100% with an empty properties object. There are no parameters requiring additional semantic explanation, so the baseline of 4 applies; the description need not add parameter detail.

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

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

The description identifies the specific resource (Crypto Fear & Greed index) and adds the scale (0-100) and classification aspect, making the purpose clear. It lacks an explicit verb like 'returns' or 'retrieves', and it does not explicitly differentiate itself from sibling tools, though the resource is unique.

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

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

The description provides no guidance on when to use this tool versus alternatives. The word 'Free' hints at a cost advantage but does not state a use case, prerequisites, or exclusions. An agent would not know when this is preferred over other data tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description only needs to add extra context. It adds useful behavioral detail: the data is free, machine-readable, from the public exchange feed, and includes self-settlement instructions and covered symbols.

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 compact: two sentences with the key 'FREE' fact and main content front-loaded. The repetition of 'Free' at the end is a minor redundancy, but overall it is efficient.

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

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

For a parameterless, read-only tool with an output schema, the description is sufficiently complete. It states what is returned, the data source, the free nature, and the correct usage order, with no important gap for an agent selecting and invoking the 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 has zero parameters and 100% schema description coverage, so the baseline of 4 applies. There are no parameters for the description to explain.

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 clearly identifies the tool as returning the exact question a forecast answers, including machine-readable settlement details and the list of covered symbols. It lacks an explicit verb like 'returns' and doesn't name a differentiating sibling, but the purpose is unambiguous enough.

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

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

The phrase 'Read this before building on the forecast' explicitly gives a precondition for using this tool, and the 'FREE' marker signals a no-cost entry point. It doesn't discuss when not to use the tool or point to alternative tools, but the context 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses valuable behavioral details: forecasts are written before the window opens, settled from the exchange public feed afterward, and raw rows are returned for independent recomputation. It also notes the output fields and that the tool is free, giving agents a strong safety and trust 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 key fact ('FREE: the live track record of this miner') and contains useful details, but it is slightly wordy with the repeated 'Free' at the end and a somewhat rhetorical backtest sentence. It earns a high score but loses a point for minor 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?

Given the read-only annotations, optional parameters, and existing output schema, the description covers what an agent needs: what the record is, how it was produced, what metrics are returned, and why it can be trusted. No critical call-invocation information 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 coverage is 100% and both parameters have clear descriptions. The tool description adds general context about raw rows being returned, but it does not contribute meaningfully beyond the schema's own parameter documentation, so the baseline score 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?

The description names a specific verb-resource pair ('get the live track record of this miner') and clearly states what is returned: settled count, Brier skill, coverage, calibration error, and reliability curve. It also distinguishes the tool from a backtest, so an agent can understand what this record is and is not 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?

The description gives clear context for when this tool is appropriate: when you need a verifiable live track record rather than an author-computed backtest. It explicitly contrasts it with backtests ('this is not that') but does not name specific sibling tools or provide a full when-to-use vs alternatives matrix.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the bar is lower, and the description still adds real value: a per-call price of 0.02 USDC and the x402 payment rails (USDC on Solana, Base, Polygon, Arbitrum, Arc) that an agent must know before invoking. It does not mention rate limits, tiering, or fallback behavior if payment fails, keeping it short of a 5.

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

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

Three sentences, properly front-loaded with what the tool returns, then the trading interpretation, then the cost. Every sentence is load-bearing; the only minor slack is that the parenthetical payment-rail list is longer than strictly needed.

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

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

An output schema exists, so the description needn't explain return values, and it correctly focuses on scope, use case, and the non-obvious x402 cost. The one gap is sibling disambiguation within a very crowded funding-tool family.

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

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

Schema description coverage is 100%, so both parameters (limit, min_turnover_usd) are already documented with ranges and defaults. The description restates the existence of a 'liquidity floor' and 'top N each side' but adds no format, unit, or interaction detail 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+resource+scope: the most positive and most negative funding across every Hyperliquid perp above a liquidity floor, with named output fields (annualized %, 24h move, open interest). It differentiates by scope (extremes across all perps) but never names the close siblings get_funding_radar, get_funding_pulse, get_funding_rate or get_funding_history, so an agent must infer which funding tool to pick.

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

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

The line 'The most crowded trades in the market — crowded shorts are squeeze candidates' implies the use case (squeeze/positioning hunting) and hints at a relationship with get_squeeze_score, but gives no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuinely non-structured behavioral context: the per-call cost of 0.005 USDC, the x402 payment requirement, and the accepted chains (Solana, Base, Polygon, Arbitrum, Arc). It does not, however, describe latency or failure modes beyond the 200-settlement cap.

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

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

Three sentences, front-loaded with the concrete capability before the interpretive line and the payment clause. Mostly earns its place, though 'What the carry has actually been.' is flavor rather than specification and could be trimmed.

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?

Output schema exists, so return values needn't be spelled out, yet the description still previews them usefully. The payment/auth detail is an important completeness addition for an x402-priced tool. Nothing essential for correct invocation is missing, though alternatives routing is absent.

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

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

Schema description coverage is 100%, so both params (limit, symbol) are already fully documented in the schema. The description only echoes 'up to 200 hourly settlements' and 'any Hyperliquid perp' without adding format or default guidance beyond the schema. Baseline 3 is correct 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 (funding rate history), scopes it (any Hyperliquid perp, up to 200 hourly settlements), and enumerates what it returns (average rate, annualized %, positive-interval share, raw series). The word 'history' plus the aggregate-stat framing cleanly separates it from the sibling funding tools (get_funding_rate, get_funding_pulse, get_funding_extremes), even without naming them.

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

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

Usage is only implied: 'What the carry has actually been' hints at assessing realized funding carry, but there is no explicit when-to-use, no when-not-to-use, and no named alternative among the many sibling funding tools. The agent must infer that this is the historical/aggregate counterpart to the live-rate tools.

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), so the bar is lower. The description adds genuinely useful non-annotation context: the exact cost (0.005 USDC per call) and the x402 payment rails (Solana, Base, Polygon, Arbitrum, Arc), plus the fixed liquidity-floor filter and the 5-item cap.

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

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

Four tight sentences, front-loaded with the when-to-use trigger and the returned payload; the cost and payment rails come last. Nothing is redundant and the size matches a zero-parameter, single-shot tool.

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

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

An output schema exists, so the description need not detail the return shape, yet it still summarizes the payload usefully. Payment requirements are disclosed, which is essential for a paid endpoint. The one real gap is routing guidance against the other funding tools, which the description leaves unresolved.

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 no parameters, so the baseline is 4. The description's mention of an internal liquidity floor is context rather than a parameter, and there is no parameter surface that needs explaining.

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

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

States a specific verb+resource and a precise scope: the 5 largest absolute annualised funding rates on Hyperliquid perps above a liquidity floor, with named fields (8h rate, open interest, 24h price move). However, it fails to differentiate itself from obvious siblings like get_funding_extremes, get_funding_radar and get_funding_rate, which sound like near-identical capabilities.

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

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

"Use when an agent needs the most extreme funding rates right now" plus "One call, not a full screen" gives implied usage context. But with get_funding_extremes and get_funding_radar in the sibling list, the description never says when to pick this over them — a significant omission for a crowded funding-rate family.

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 read-only/idempotent annotations: it discloses the 5-minute precompute cadence, the as_of field, the 503-on-stale-snapshot rule (and that stale calls are never billed), and the 0.02 USDC x402 cost with supported chains. These are operationally decisive facts an agent cannot get from 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?

Dense but front-loaded: scope first, then returned fields, then filtering, then operational caveats. Every clause carries a distinct fact, though the pricing and chain list at the tail is slightly tangential.

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 handling return shape, the description still covers the things only prose can: default filtering, cost, staleness failure mode, and freshness guarantee. Nothing needed to invoke or interpret 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 both params (top, min_oi_usd) are already documented with ranges and defaults. The description restates the default threshold and the 0-returns-all behavior but adds no syntax or format detail beyond 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 (funding radar over every Hyperliquid perp) and quantifies scope (337 perps, 178 main dex, 159 HIP-3). It enumerates the exact returned fields, so an agent knows what this produces 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?

Explains the default behavior ($10M+ OI) and how min_oi_usd=0 returns everything, which implicitly guides usage, but never names or contrasts with close siblings like get_funding_extremes, get_funding_pulse, get_funding_history, or get_funding_rate. The agent must infer when this radar beats those alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), so the bar is lower. The description adds non-annotated behavior that matters operationally: a metered cost of 0.005 USDC per call and the x402 payment rails/ledgers accepted, which an agent must know 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?

Two dense, front-loaded sentences: what you get first, then the default behavior and price. The long enumeration of returned fields is partially redundant given an output schema exists, but it aids selection and nothing reads as 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 format needn't be explained, and cost/auth are covered. What remains unstated is freshness/real-time vs delayed pricing and any rate limits on the paid calls, minor gaps for an otherwise complete single-parameter read 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?

With one parameter at 100% schema coverage, the baseline is 3. The description goes slightly beyond the schema by spelling out the no-symbol fallback behavior including that open interest is returned in that case, adding meaning the schema's terse 'omit for SOL and BTC' only implies.

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 ('Funding rate for any Hyperliquid perp') and enumerates the exact metrics returned, which makes it easy to distinguish from history/radar/extremes siblings by intent. It never explicitly names a sibling to contrast with, so it stops short of the top score.

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

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

The description gives one conditional (omitting symbol falls back to SOL and BTC with open interest) and discloses the per-call cost, which is genuine usage context. However, it never says when to choose this over get_funding_history, get_funding_pulse, or get_funding_extremes, leaving alternative selection 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 read-only, idempotent, open-world, non-destructive. The description adds substantial context beyond them: the exact cost (0.002 USDC per call via x402), supported payment chains, and the licensing/disclaimer that ECB rates are free-of-charge and informational only. This goes well past what the annotations declare.

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 usage trigger and content scope efficiently. Most sentences earn their place, though the ECB-website availability note is somewhat extraneous marketing/flavor that could be trimmed without losing agent-relevant information.

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

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

With an output schema present, the description need not explain return values. It covers the essential agent-facing facts: what data is returned, the base/cross behavior, cost, payment methods, and the informational-only limitation. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'base' parameter is fully documented in the schema. The description's mention of 'as published or as crosses for another base' largely restates the schema rather than adding new syntax or format detail, so the baseline of 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: returns ECB euro FX reference rates for ~30 currencies, in published form or as crosses, plus Hyperliquid HIP-3 FX/commodity marks. This clearly distinguishes it from the many crypto price siblings (get_btc_price, get_eth_price, get_sol_price) since it is fiat reference-rate focused.

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?

Opens with an explicit trigger: 'Use when an agent needs official daily exchange rates.' It also gives the important caveat that the rates are for information only, not for transactions, which guides appropriate use. It does not, however, name a sibling alternative (e.g. get_convert) or state when NOT to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial operational context beyond them: a 2 KB input cap, a 400 on overflow that is never billed, and per-call pricing with the payment protocol and supported chains. This is exactly the extra context 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?

Three tight sentences, front-loaded with purpose, then limits, then cost. Every clause carries an actionable fact with no padding or repetition.

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 pure-function tool with an output schema present, the description need not explain return values, and it covers input limits, error behavior, supported algorithms/encodings, and billing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuinely useful meaning: it maps keccak256 to 'the Ethereum hash', clarifies utf8 vs hex byte interpretation, and specifies the output is returned as both hex and 0x-hex. That goes beyond the schema enum labels.

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 (returns a hash) plus the exact algorithms and encodings it produces, and frames the scope as something the agent should not compute itself. An agent can immediately tell what this tool returns versus every sibling in the list.

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

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

The opening sentence gives a clear condition for use ('when an agent needs a hash it should not compute itself'). It does not name an alternative or state when-not to use, but no sibling overlaps this function, so the routing gap is minor.

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 annotations (which only cover the read-only/idempotent safety profile), the description discloses three operationally critical traits: refresh cadence (every 5 minutes), failure behavior (stale data answers 503), and cost (0.02 USDC per call via x402 on five named chains). These are exactly the details an agent needs to plan a paid, freshness-sensitive call.

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

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

It is front-loaded with the trigger condition, then the return payload, then the coin-specific behavior, then the refresh/cost logistics. Every sentence carries distinct information with no filler or repetition of the schema.

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

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

For a read-only, idempotent, paid data tool with an output schema already defining return shape, the description covers purpose, trigger, the coin-mode behavioral difference, freshness, error behavior, and cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters and the baseline is 3. The description adds real meaning beyond it by explaining the behavioral effect of coin (adding liquidation bands and the largest positions), which is not captured in the schema's terse field description.

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

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

The description gives a specific verb and resource: it 'returns the open perp positions of the largest Hyperliquid accounts aggregated per coin,' then enumerates the exact metrics (net long/short USD, account counts, size-weighted entries, distance to liquidation, uPnL). This is specific enough to distinguish it from the many generic positioning and liquidation siblings like get_positioning or get_liq_heatmap.

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 opens with an explicit trigger condition ('Use when an agent needs to know how the biggest Hyperliquid traders are positioned'), which clearly frames the use context. However, it names no alternatives or exclusions, so an agent choosing between this and other Hyperliquid/positioning tools gets no routing guidance.

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

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

Annotations already establish read-only/idempotent safety, yet the description adds substantial non-obvious behavior: the verdict comes from a buy-then-sell simulation on the deepest pool, buy/sell tax is measured, bytecode flags and simulation/bytecode disagreement are returned, 'no pool found is a finding' (not an error), and RPC failure surfaces as 503. It also discloses the payment model (0.01 USDC per call via x402 and accepted chains), which no structured field covers.

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 when-to-use condition, then the returned verdict, then caveats and pricing — a sensible priority order. It is dense with fragment-style listing ("Also: whether...") and slightly long, but each sentence carries load-bearing information rather than 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-shape detail isn't required, yet the description still characterizes the verdict, tax measurement, bytecode flags, and disagreement output. With annotations covering the safety profile and pricing/cost and error behavior disclosed, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents both `token` and `chain` including the per-chain DEX lists. The description's venue mentions (Uniswap, Aerodrome, PancakeSwap) restate what the schema's chain description already says, adding no syntax or format guidance. Baseline 3 applies when the schema does the 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+resource (honeypot check on a token) and its outcome (verdict from a buy-then-sell simulation). It clearly distinguishes itself from sibling risk tools like get_token_risk and get_sol_token_check by scoping to EVM chains and stating the sellability question. An agent can select it 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?

"Use when an agent needs to know whether a token ... can be sold before it buys" gives explicit, actionable timing and intent. It does not name the alternative for Solana tokens (get_sol_token_check) or contrast with get_token_risk, so routing among near-siblings still requires 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses the three return classifications, the 4,000-char input cap, the matched-rule categories, and — critically — the per-call cost and payment rails (x402, USDC on five chains). Cost and billing model are behavioral facts 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?

Three sentences, front-loaded with the usage trigger, then return semantics, then cost. Every clause adds decision-relevant information with no filler.

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

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

An output schema exists, yet the description still summarizes the verdict taxonomy, and it adds the cost dimension an agent must budget for. Nothing needed to call this single-parameter, read-only tool correctly is missing.

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

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

Schema coverage is 100% for the single 'text' parameter, and the description's only parameter detail (the 4,000-character limit) merely restates the schema. Baseline 3 applies since the schema already does the documentation work.

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 (screened) and resource (untrusted text for prompt-injection attempts) with clear scope. It is trivially distinguishable from siblings like get_sanctions_check or get_honeypot_check, which screen different artifacts.

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

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

The opening 'Use when an agent needs untrusted text screened for prompt-injection attempts' gives a concrete trigger condition. It does not name when-not-to-use or an alternative sibling, but no sibling overlaps enough to require 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 safety (readOnly, idempotent, non-destructive), but the description adds behavior they don't: a per-call cost of 0.01 USDC, the x402 payment mechanism, and accepted chains. It also discloses the row-level grain and the aggregate buy/sale totals, which is real behavioral context beyond 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?

Two sentences, front-loaded with the use case, then the return shape, then source and cost. Every clause is load-bearing; no filler.

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

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

With an output schema present, return values need not be explained, yet the description still sketches them; the cost/payment caveat and data source are surfaced. An agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 100%, so both ticker and days are already documented with ranges and defaults. The description only alludes to the window ('for the window') without adding format or boundary detail, 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 ('what a company's insiders bought and sold') and pins the exact data source (SEC Form 4 filings, one row per transaction). This cleanly separates it from siblings like get_sec_filings and get_sec_8k, which cover different filing types.

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?

Opens with an explicit trigger condition ('Use when an agent needs what a company's insiders bought and sold'), which is clear routing guidance. It does not name an alternative tool or state when-not-to-use, so it falls short of the top score.

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 this is a safe, idempotent read, so the bar is lower, yet the description still adds two behaviors annotations cannot express: a 5-minute refresh cadence (data staleness) and a 0.005 USDC per-call charge via x402 on five named chains (payment/auth requirement). Both are decision-relevant before an agent commits to calling.

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?

One sentence, front-loaded with the data content (percentile range, unit, source, cadence) and only then the cost clause. No filler and nothing redundant with the schema 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?

An output schema exists, so return values need no explanation, and the description supplies the non-obvious operational facts an agent needs: freshness window and payment requirement. Nothing material is missing for a zero-parameter read 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 is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly spends no words on inputs.

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 resource and scope: 'Jito tips sampled on-chain: p25 to p99 in SOL of the newest transfers into Jito's tip accounts.' It also distinguishes the data source from a generic fee feed by specifying 'what landed bundles actually paid' and a refresh cadence, which is enough to separate it from siblings like get_priority_fees.

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

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

Usage is implied rather than stated: the mention of 'a landing recommendation' signals the tool is for sizing tips to land bundles, but there is no explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The agent must infer the context from the resource itself.

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 behavior. The description adds meaningful context beyond annotations: the 15-minute delay, the limited asset universe, and the free/taster nature of the data.

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

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

The description is short and front-loaded with the key facts. The word 'Free' appears twice, which is slightly redundant, but the overall structure is efficient and 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?

With no parameters, a rich output schema, and strong annotations, the description covers the essential context: what data is returned, for which assets, with what delay, and when to use the real-time alternative. It is complete for a no-argument read-only 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?

There are zero parameters and schema description coverage is 100%, so the baseline is 4. The description appropriately focuses on scope and data freshness rather than parameter details, since none exist.

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 clearly states the resource ('last liquidation'), the specific assets covered (SOL, BTC, ETH, XRP, DOGE), and the data delay. It also distinguishes itself from get_recent_liquidations by explicitly pointing to that sibling for real-time data.

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 tool (get_recent_liquidations) and the condition for choosing it ('Real-time'). The 'FREE taster' phrasing implies this is for a free, delayed sample, though it does not explicitly state 'use this when you need delayed data'.

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 per-caller pacing (1 bucket per 5s for x402/prepaid pack, 1 per 10s for pass keys, except while has_more), the 429 + Retry-After behavior for early calls, the fact that rejected calls are never billed, the per-call price of 0.001 USDC, and the accepted payment chains. These are exactly the operational traits 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?

Purpose is front-loaded in the first sentence, followed by payload, then pacing/billing. The pacing sentence is a long run-on but every clause (intervals, exception, 429, no billing, price, chains) carries distinct information, so little is wasted.

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

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

For a paid, rate-limited streaming feed this covers the essentials an agent must know: what each bucket contains, cursor continuity, rate limits per key type, error handling, and cost. An output schema exists, yet the description still summarizes the shape usefully without being redundant.

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 next, since, and symbols with format and defaults. The description only alludes to the cursor ('from a gap-free cursor') and adds no syntax, ordering, or constraint detail beyond 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 ('liquidation pressure feed') and details the payload precisely: 5-second buckets per symbol of long/short USD liquidated across venues, dominant side, and pressure versus the symbol's baseline. However, it never distinguishes itself from closely-named siblings such as get_liq_pulse, get_recent_liquidations, or get_liq_history, so an agent cannot route between them from this text alone.

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

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

'Use when an agent needs liquidation pressure as it happens' gives a clear real-time trigger and implicitly separates it from the historical siblings by temporal framing. It stops short of naming alternatives or stating when NOT to use it (e.g. for historical backfill use get_liq_history), so the routing is implied rather than explicit.

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

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

Annotations already carry readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds beyond them: per-call cost (0.02 USDC via x402 on several chains) which is critical invocation context, and data provenance ('real liquidation prints, not entry-price estimates'). It also enumerates returned fields (USD, prints, long/short split, hottest zone flagged).

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 scope, then layered with data fields, provenance, symbols, and cost. Every sentence carries information, though promotional phrasing ('where leverage actually got flushed', 'not entry-price estimates') is slightly padded.

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

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

With an output schema present, return values need not be explained, and annotations cover safety; the description still supplies the payment model, provenance, and symbol universe. The only notable gap is explicit sibling routing in a crowded liquidation-tool family.

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 hours, symbol, and buckets with ranges and defaults. The description only echoes the symbol options and the N-hour lookback, adding no format or constraint detail 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?

The opening clause states a specific verb+resource and scope: 'Liquidation heatmap by PRICE LEVEL'. The emphasis on price-zone bucketing implicitly differentiates it from the many sibling feed/history/stats liquidation tools, though it never names a specific alternative sibling like get_liq_feed or get_liq_history.

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

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

Usage is implied rather than stated: the agent can infer this is for viewing flushed leverage by price over an N-hour window, but there is no explicit 'use this instead of X when...' routing despite a large cluster of competing liquidation tools. The 'last N hours' framing hints at a time-scoped context but no exclusions are given.

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, openWorld, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: a paid x402 call costing 0.05 USDC per call across specific chains, the underlying data source (Bybit), and a hard 7-day retention limit. It does not mention rate limits or failure modes, keeping it short of a 5.

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

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

Purpose, granularity, and scope are front-loaded in the first sentence, with cost and payment details last. The middle sentence ('Bybit is the only complete liq tape in crypto and no exchange publishes history of it') is promotional and contributes little to tool selection, a minor deduction from an otherwise tight three-sentence entry.

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 explained, and annotations carry the safety profile; both are handled by structured fields. The description covers the remaining gaps an agent needs: data source, lookback ceiling, scope options, and the payment requirement. Nothing essential 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 coverage is 100%: hours, scope, symbol, and bucket_min all carry ranges, defaults, and examples. The description only restates scope semantics ('any USDT perp or the whole recorded universe') and the 7-day cap, which duplicate the schema rather than extend it. Baseline 3 is appropriate 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 and resource plus granularity and output contents: 'Liquidation history, time-bucketed: total, long and short USD, prints and biggest print per bucket.' The scope ('any USDT perp or the whole recorded universe') and depth ('up to 7 days back') are explicit. It never names or contrasts a sibling (e.g., get_liq_feed, get_liq_pulse, get_liquidation_stats), so the differentiation is implicit at best.

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

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

The 'up to 7 days back' horizon and the 'history, time-bucketed' framing imply this is the retrospective tool rather than a live feed, which is weak implied guidance. No when-to-use, when-not, prerequisites, or named alternatives are given, so an agent must infer its place among the many liq siblings.

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 goes well beyond them: it discloses the stale-data failure mode (503, never billed), the exact per-call cost (0.005 USDC), and the x402 payment rails (USDC on Solana, Base, Polygon, Arbitrum, Arc). Billing and failure semantics are exactly the behavioral context an agent needs before calling a paid endpoint.

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

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

Three sentences, front-loaded with the use case, then what is returned, then failure/billing terms. Every clause carries distinct information and nothing is repeated from the schema 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?

An output schema exists, so return shape needs no elaboration, yet the description still summarizes the payload (total USD, long/short split, prints, top 5 symbols). Combined with cost, payment options, and stale handling, an agent has everything needed to decide and invoke correctly.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and it correctly does not invent any input surface. The stated scope (60-minute window, all USDT perps) effectively documents the implicit query dimensions.

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

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

The description names a specific verb and resource ('what is being liquidated right now') and pins the scope tightly: last 60 minutes, every USDT perp, with total USD, long/short split, prints and top 5 symbols. That is enough to distinguish it from broader history tools, though it never names a sibling explicitly despite the crowded liq_* family (get_liq_feed, get_last_liquidation, get_recent_liquidations).

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

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

'Use when an agent needs to know what is being liquidated right now' gives a clear trigger, but there is no when-not and no comparison against the many near-identical siblings (get_liq_feed, get_recent_liquidations, get_last_liquidation, get_liq_history). The 'right now' framing implies recency-scoped usage but leaves the agent to infer which liquidation tool 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 declare read-only, idempotent and open-world, so the safety profile is covered. The description adds genuinely useful context beyond them: a per-call cost of 0.02 USDC settled via x402 across five named chains, plus which venues are aggregated and what each row contains. It does not mention rate limits or data freshness/lag, which would have pushed it to 5.

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

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

Three sentences, front-loaded with the core capability and the scope constraint before the payoff line and the payment detail. The rhetorical opener 'What is blowing up RIGHT NOW' costs a few words but is short enough not to bury the substance.

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 explained, and the description still usefully enumerates the per-symbol fields. Combined with full parameter documentation, annotation coverage and explicit payment/coverage details, an agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100% – both limit (1-50, default 10) and window_min (5-1440, default 60) are fully documented with ranges and defaults. The description adds no additional semantics for either parameter, so the baseline 3 applies.

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

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

States a specific verb+resource (top symbols ranked by liquidation USD) and constrains scope precisely: 'every USDT perp we record on Bybit, OKX and Binance'. The ranking framing clearly separates it from siblings like get_liq_feed, get_recent_liquidations and get_liq_heatmap, which are feeds/views rather than leaderboards.

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

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

The line 'The fastest read on where leverage is being flushed' implies a use case, but there is no explicit when-to-use vs when-not guidance and no sibling alternative is named (e.g. get_liq_pulse or get_cascade_alert for other angles). Usage is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds substantive context annotations cannot: this is a x402-metered call costing 0.01 USDC, settled on five named chains. That payment/authorization requirement is exactly the kind of operational fact an agent must know before invoking. It omits data freshness/caching and any rate limit, hence not a 5.

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

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

A single dense sentence that front-loads what is returned and closes with the cost, which is the one fact an agent might otherwise discover only after failing. No filler, no restatement of 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, so return-shape explanation is not required; the description nonetheless summarises the metrics, which helps selection. Cost and chain coverage are disclosed. What is missing is sibling disambiguation in a namespace crowded with liquidation tools and any note on update cadence for the 1h/24h windows.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly does not invent parameters, and instead spends its words on the fixed dimensions of the response (windows, split, exchange breakout) — the right allocation for a no-arg call.

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

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

States a specific verb+resource and enumerates the exact payload: 1h/24h totals, longs vs shorts USD split, biggest print, per-exchange breakout for the five named majors. That scoping ('the 5 majors') is genuinely differentiating. It stops short of naming which sibling it displaces, so an agent still has to guess between this and get_liq_pulse / get_liquidation_leaders / get_liq_feed.

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

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

Usage is only implied: the coverage/resolution described (aggregate 1h/24h windows on majors) hints at a summary use case, but there is no explicit 'use this instead of X when Y' and no exclusions against the eight other liquidation siblings. The cost disclosure ('0.01 USDC per call') does usefully signal a paid-vs-free routing decision, which is closer to guidance than most tools get.

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

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

Adds rich context far beyond the read-only/idempotent annotations: data is pulled daily from Fed/BLS/BEA pages and never hand-entered, records verified more than 35 days ago return 503 and are never charged, and DST-aware conversion is documented. Freshness and billing failure behavior are exactly the non-obvious traits an agent needs.

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 resource and its contents, then behavior and cost. Efficient overall, though the first sentence is dense and the pricing/solana-chain detail could be trimmed without losing call-relevant meaning.

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

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

An output schema exists, so return shape needn't be described; the description instead covers the things schema cannot: data provenance, freshness cutoff, failure semantics, and payment cost. Complete for a monetized external-data 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 coverage is 100%, so the schema already documents 'days' (range/default) and 'type'. The description names the event categories (FOMC, CPI, NFP, PCE) matching the type parameter but adds no syntax, format, or interaction detail beyond the schema. 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 resource (FOMC, CPI, NFP, PCE calendar) with the exact contents: next Fed rate decisions, release dates, UTC times converted from NY time, source URLs, and verification timestamps. No sibling tool competes with a macro-event calendar, so no differentiation is needed. An agent immediately knows what it returns.

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?

'For traders' gives an implicit audience but there is no explicit when-to-use, when-not-to-use, or named alternative. With no competing sibling, the gap is smaller, but the description still leaves usage conditions 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, openWorld, and non-destructive, so safety is covered. The description adds a genuinely useful behavioral fact beyond the structured fields: this is a paid call costing 0.005 USDC via x402 and the accepted payment chains, which an agent must know 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?

Two short sentences, front-loaded with what the tool returns and reserving the second for cost. No filler, no 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 not be explained, and the description covers both content and payment cost. Complete for a zero-parameter, paid read tool, with only the deliberate sibling-routing guidance left implicit.

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 is nothing for the description to clarify; the baseline for a no-param tool applies. The description correctly avoids inventing parameter guidance.

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

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

The description names a specific verb-implied resource (a market snapshot) and enumerates its exact contents: SOL+BTC prices, funding rates, and Fear & Greed. The phrase 'in one call' distinguishes it from the single-purpose siblings (get_btc_price, get_sol_price, get_fear_greed, get_funding_rate), though it never explicitly names them.

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?

'In one call' implies this is a bundle useful when several of these datapoints are needed at once, which is reasonable implied guidance. However there is no explicit statement of when to prefer this aggregate over the individual sibling tools, nor any when-not-to-use condition.

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: it discloses per-part source and as-of timestamps, that missing parts are null with a reason, that a total build failure returns 503 and is never billed, and the exact price and payment rails (0.02 USDC via x402 on Solana/Base/Polygon/Arbitrum/Arc). These are exactly the cost, failure, and data-provenance facts 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?

The opening content inventory is long but earns its length by letting an agent judge coverage at a glance, and the operational facts (nulls, 503, billing) are packed into short trailing sentences. Slight density cost, but front-loaded and waste-free.

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 need not be explained; the description still covers the non-schema essentials — data provenance, null/missing semantics, failure mode, and cost. Nothing an agent needs to decide and pay for the call 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 symbol parameter's allowed values are already documented in the schema; the description repeats 'BTC, ETH, SOL or HYPE' without adding format, casing, or default-resolution detail beyond what the schema states. Baseline 3 applies when the schema carries the parameter semantics.

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

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

States a specific resource (composite market state) and enumerates exactly which series it bundles: spot, perp basis vs Hyperliquid oracle, realized vol, funding z-score, OI, whale net-long share, liquidations, Fear and Greed, macro calendar, flags. An agent can distinguish it from narrower siblings like get_basis, get_fear_greed, get_open_interest, or get_market_snapshot 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?

The phrase 'in one call' implies this is the aggregation shortcut versus calling the many single-metric siblings, and the symbol list constrains the universe. However, no sibling is named explicitly and there is no when-not guidance (e.g. when a single cheap metric is preferable to the 0.02 USDC bundle).

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

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

Adds far more than the readOnly/idempotent/openWorld annotations: output shape (text in reading order, blocks with line breaks, detected language), a prompt-injection guarantee ('it never follows text in the image'), and cost/auth details (0.04 USDC per call via x402 across five chains). The annotation-contradiction risk is nil and the pricing disclosure is genuinely load-bearing.

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?

One dense paragraph, front-loaded with the trigger and return shape before the cost details. Every clause carries information the agent needs; nothing is redundant with the schema 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?

For a single-parameter tool with an output schema and full annotations, the description covers trigger, output semantics, input limits, safety behavior and pricing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is a single url parameter, so the baseline is 3. The description compensates by adding input constraints the schema omits: accepted formats (PNG, JPEG, WebP, GIF) and limits (5 MB, 4096 px per side), which materially affect whether a call succeeds.

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 text inside an image') with the exact acceptance condition, and the OCR framing implicitly separates it from audio transcription (get_transcribe), document extraction (get_extract, get_pdf_markdown) and URL conversion (get_web_markdown). An agent can route to 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?

'Use when an agent needs the text inside an image' gives a clear triggering condition. It stops short of naming a sibling alternative or stating when not to use it (e.g. for PDFs use get_pdf_markdown), so it is context without exclusions.

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/openWorld/non-destructive): it discloses the data source (own 5-minute sampler), an availability constraint (returns 503 until the record is 24 hours deep), and a per-call cost (0.02 USDC via x402 across five chains). That is exactly the operational context an agent needs before calling.

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

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

Purpose is front-loaded in the lead clause and no sentence is wasted; every clause adds a distinct fact (scope, units, fields, source, cost). The first sentence is dense with embedded detail but remains readable and information-efficient.

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

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

With an output schema present and annotations covering the safety profile, the description fills the remaining gaps an agent needs: what makes a spike, units that isolate OI from price, the sampler's freshness caveat, and the billing model. Complete for a single-parameter, read-only 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?

Only one parameter (limit), fully documented in the schema at 100% coverage, so the schema carries the burden. The description adds nothing about the limit parameter's meaning or defaults, making the baseline 3 correct.

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

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

States a specific resource (open interest spikes across every Hyperliquid perp) and precisely scopes it: coins whose open interest moved abnormally in the last hour relative to their own previous day. It then lists the returned fields (1h/4h/24h change in coin units, z-score, price move, funding), which clearly differentiates it from siblings like get_open_interest that return raw levels.

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

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

The description makes the use case inferable (surfacing abnormal OI moves), but never explicitly says when to pick this over get_open_interest, get_funding_extremes, or get_squeeze_score. No exclusions or alternative routing are given, so the agent must infer the appropriate context.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema behavior: null semantics for 1h/24h change until the sampler has enough history, the data's provenance (own 5-minute sampler), and the per-call cost of 0.01 USDC via x402 with the accepted chains.

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

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

Three tight sentences, front-loaded with the core capability before the provenance detail and pricing. No filler, though the payment-chain enumeration is dense enough to slightly dilute the main 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?

An output schema exists so return fields need not be explained, and the description still covers data source, null behavior, and cost. What is missing is rate-limit or caching behavior for a paid endpoint, but the core is complete for a single-optional-param read 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 coverage is 100% and the single symbol parameter is already documented with format examples and a default in the schema. The description adds only the scoping phrase 'ANY Hyperliquid perp', 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 description names the specific resource (open interest for ANY Hyperliquid perp) and enumerates the exact outputs: OI in base units and USD with mark price, plus 1h and 24h change from a documented 5-minute sampler. This distinguishes it from siblings like get_oi_spike_scan and get_positioning without the agent needing to open 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?

Usage is implied (query perp OI) and the description usefully notes that /api/positioning adds whale net-long share for SOL and BTC, which hints at an alternative. However, it never explicitly states when to prefer this tool over get_oi_spike_scan or the get_positioning tool, nor any exclusions.

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, open-world access, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot express: a paid endpoint at 0.01 USDC per call via x402, with the accepted settlement chains enumerated. It does not mention rate limits or failure behavior, but the payment requirement is the key operational fact.

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 measurement, then a compact second sentence for the cost and payment rails. Information-dense with no filler; the first sentence is long but each clause contributes a distinct output field.

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-field documentation is not required, and the description covers what is measured, the venue scope, the default symbol, and the cost model. The notable remaining gap is routing relative to the many overlapping market-data siblings.

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

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

Schema description coverage is 100% with only two params, both already documented with ranges and defaults, so the schema does the heavy lifting. The description's '±N bps of mid' framing reinforces the bps semantics but adds no syntax, units, or edge-case detail beyond what the schema states.

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 metric (orderbook imbalance), the underlying computation (resting bid/ask liquidity in USD within ±N bps of mid), and the derived outputs (ratio and skew read) for a named venue universe (Hyperliquid perps). An agent can distinguish this from sibling get_orderbook_walls 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?

No when-to-use or when-not-to-use guidance, and no alternatives named despite many closely related siblings (get_orderbook_walls, get_perp, get_market_snapshot). The only decision-relevant fact offered is the per-call cost, which is pricing rather than routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the burden is lower. The description adds genuinely useful non-schema context: a pay-per-call cost of 0.01 USDC via x402 and the accepted settlement chains, which is essential for an agent to invoke it successfully.

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

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

Two tight sentences with zero filler: the capability and its output shape come first, the payment terms second. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the schema covers inputs. The pricing/payment requirement is surfaced, which is the main non-obvious prerequisite. The only gap is routing guidance relative to the orderbook/imbalance siblings.

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

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

Schema description coverage is 100%, so both parameters (top, symbol) are already fully documented with ranges and defaults. The description adds no parameter-level syntax or constraints beyond the schema; the 'distance from mid' detail describes output rather than inputs. 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 resource (orderbook walls), scopes it (Hyperliquid perps), and defines what a wall is ('largest resting orders on each side of the book, with USD size and distance from mid'). This clearly separates it from sibling get_orderbook_imbalance, which measures aggregate imbalance rather than discrete large orders.

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

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

The description implies the use case (finding large resting liquidity on Hyperliquid perps) but never states when to choose this over get_orderbook_imbalance or other book-derived siblings, nor any prerequisites beyond the pricing note.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, and the description goes well beyond them: it discloses the 0.005 USDC per-call x402 cost with the accepted chains, the CC0 data source, and the caveat that the abstract is only present where OpenAlex holds it. This is exactly the payment/coverage context an agent needs before invoking a paid 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?

Three front-loaded sentences that move from trigger to payload to invocation format to cost. Slightly redundant on the DOI path detail, which the schema already covers, but nothing is wasted.

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

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

An output schema exists, so return values need no elaboration, and the description still flags the abstract-coverage caveat. Combined with the explicit pricing model and path formatting, an agent has everything needed to call this correctly on the first attempt.

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?

With a single parameter at 100% schema coverage, the schema already documents the DOI format including the %2F alternative. The description's path example ('/api/paper/10.1038/nature14539') restates that without adding new semantics, 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 ('the paper behind a DOI') and the exact return payload. However, it never distinguishes itself from the sibling get_papers, so an agent choosing between the singular and plural tools gets no help from the description.

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

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

'Use when an agent needs the paper behind a DOI' gives a clear trigger condition. It lacks any when-not guidance or explicit routing to get_papers, but the usage context itself is unambiguous.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description usefully adds caching ('Cached 24 hours'), a per-call price and payment rails (x402, USDC on five chains), and the CC0 licensing of the data. That is real operational context beyond the annotations, though it says nothing about failure modes, rate limits, or payment failure handling.

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

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

Three tight sentences with the usage trigger front-loaded, followed by return shape, then cost/caching. The field enumeration and payment-rail list make it dense but nothing is filler.

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

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

With an output schema present, the description need not explain return values, yet it still does so succinctly; cost, cache lifetime and data source are all covered. The one gap is sibling disambiguation from get_paper, which is material for an agent choosing among 80+ tools.

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 q, limit and year_from are already documented with ranges and defaults. The description only restates 'up to 25' and 'optionally from a given year' without adding syntax or format detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('scholarly papers on a topic' returning 'OpenAlex works') and enumerates the returned fields, so the purpose is unambiguous. However, it never distinguishes itself from the sibling 'get_paper' (singular), leaving the agent to infer which of the two to pick.

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

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

'Use when an agent needs scholarly papers on a topic' gives clear triggering context, and the description hints at scoping via 'optionally from a given year'. There are no exclusions or named alternatives, notably the singular get_paper sibling, so the routing guidance stops 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?

Goes well beyond the annotations by stating hard operational limits (http/https, 10 MB, 10 s), the robots.txt and private-address policy, the failure modes that are not charged, and the exact cost and payment rails. For an openWorld, paid network call this is exactly the context an agent needs.

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, then constraints, then pricing, so the most decision-relevant content comes first. It is dense but every clause carries distinct information (limits, policy, cost), with only minor overlap between 'http or https' and the schema.

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

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

With an output schema present the return shape needn't be spelled out, yet the description still summarizes it (title, page count, word count). Combined with annotations covering safety and the description covering limits, policy, failure handling and payment, nothing required 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 there is a single parameter whose format is already documented as an absolute http/https URL. The description's 'the one PDF URL you pass' essentially restates the schema, adding no syntax beyond it, 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 action and resource ('the text of a PDF as markdown') so the agent immediately knows the input type and output format. It implicitly distinguishes itself from web-markdown siblings by being PDF-specific, but never names an alternative tool for contrast.

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?

Opens with an explicit when-to-use trigger ('Use when an agent needs the text of a PDF as markdown') and identifies the failure case of a scanned PDF with no text layer. It does not, however, route that case explicitly to a sibling such as get_ocr.

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