AgentPay — trust routing + spend caps for x402 agents

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the data source (reddit), the per-headline sentiment taxonomy (bullish/neutral/bearish), the score field, and a concrete example response. It omits pagination, result caps, and rate limits, which keeps 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?

Front-loaded with the core statement, then cleanly sectioned into Use when / Not for / Returns / Example. The example response is long but justified because no output schema exists. The 'Price' line is boilerplate rather than description content, the only real padding.

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

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

With no output schema, the description compensates by spelling out the return shape (headlines[] with title, url, sentiment, score, published_at) and giving a full sample payload, so an agent knows exactly what it will get. Nothing needed to call this two-parameter read 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?

Schema description coverage is 100% for both parameters (filter with its enum and default, currencies with its format example), so the schema already carries parameter semantics. The description's example only implicitly demonstrates the currencies argument and adds no detail on filter values; baseline 3 is appropriate.

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

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

States a specific verb+resource+source: 'Latest crypto news and community sentiment from r/CryptoCurrency for any token.' The scope (tokens) and provenance (r/CryptoCurrency subreddit) immediately differentiate it from generic news siblings like web_search.

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

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

Explicit 'Use when' clause gives the triggering condition (need recent headlines or community sentiment for one or more tokens), and 'Not for' names three alternatives by name — web_search, url_reader, fear_greed_index — with the condition that selects each. This is textbook 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful context beyond that: the data source (DeFiLlama), the exact return fields, and a concrete example response, which is valuable since there is no output schema. It omits any rate-limit or freshness caveats, so not a full 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?

Front-loaded purpose line followed by clearly labeled 'Use when', 'Not for', 'Returns', and an example — every section earns its place. The embedded example JSON and the '$0.000 USDC per call' line add mild bulk without much utility, keeping it short of a 5.

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

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

With no output schema, the description correctly carries the return contract by listing tvl/change_1h/change_1d/change_7d/chains[]/category and a sample payload. Combined with the usage routing, an agent has what it needs; minor gaps like pagination or data staleness keep it from 5.

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 'protocol' param already documents accepted names/slugs and the empty-string-equals-top-10 behavior. The description's example names and 'leave empty' semantics largely duplicate the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('DeFi protocol Total Value Locked from DeFiLlama') and clarifies the two retrieval modes (top 10 or a named protocol). It explicitly distinguishes itself from yield_scanner and dune_query, so an agent can separate it from siblings without reading another schema.

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

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

Provides explicit 'Use when' conditions and a 'Not for' block that routes the agent to named alternatives (yield_scanner for yields, dune_query for revenue/custom metrics). This is textbook when/when-not/alternative 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them, disclosing that fast_only returns cached data or raises immediately and never blocks, and that each call has a price. Those are latency and cost behaviors the 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?

Bulleted 'Use when / Not for / Returns / Example response' structure is front-loaded and skimmable. The embedded example JSON is somewhat verbose for a tool with no output schema, but it earns its place by showing the exact return shape.

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, exclusions, latency semantics, return fields, a concrete example response, and cost. With no output schema present, the description supplies the return contract itself, so nothing an agent needs to call and interpret this 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds selecting guidance for fast_only ('for live bots') that maps the parameter to a concrete use case rather than restating its type. query_parameters nesting is the only element left purely to the schema.

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

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

States a specific verb and resource ('Run any Dune Analytics query ... by query ID') and immediately distinguishes itself from siblings by noting that alternatives cover prices, derivatives, TVL and security without a query ID. An agent can tell it apart from token_price or defi_tvl without opening any schema.

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

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

Explicit 'Use when' and 'Not for' blocks name the selecting condition (no Dune query ID) and the latency fallback (fast_only=true or a cached tool). This is exactly the when/when-not/alternatives structure the rubric reserves for a 5.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety side rests on structured data. The description adds real behavioral value beyond that: the call is free, requires no payment or wallet, and returns per-step cost, a total, a fits-budget verdict, and a cheaper alternative per paid step. It does not discuss 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?

The leading imperative 'Price a multi-tool plan BEFORE spending anything' front-loads the core value, followed by mechanics and then a routing clause. Every sentence carries information, though the 'Use when' list is slightly verbose for the amount of content.

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

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

No output schema exists, and the description compensates by naming the exact return fields (per-step cost, total, fits-budget verdict, cheaper alternative per paid step). Combined with the no-payment prerequisite, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both `steps` (ordered tool names, with an example) and optional `budget` (USDC, with an example) are already documented in the schema. The description's mention of the budget verdict adds framing but 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+resource (price a multi-tool plan) and a clear temporal scope (BEFORE spending anything). It is readily distinguishable from siblings like session_create (which commits a cap) and pre_trade_check (single-trade validation).

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

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

Explicit 'Use when' clause enumerates the triggering scenarios: multi-step planning with paid tools, 'what would this cost', budget-fit questions, and pre-commitment before a Session cap. The alternative (session_create) is implicitly referenced via the Session-cap language.

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond them by disclosing the return shape (value, value_classification, optional history[]) and a concrete example response with source. It does not mention rate limits, but the per-call price line covers the cost dimension.

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 definition, then uses labeled blocks (Use when / Not for / Returns / Example) with zero filler. Every line — including the example response and price — earns its place for an agent deciding whether to call.

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

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

No output schema exists, but the Returns line and example response fully describe the payload, and the routing clauses handle the alternatives. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100% and the single 'limit' parameter is fully documented in the schema (default 1, max 30). The description only gestures at it via 'optional history' and adds no format or syntax 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 ('Crypto Fear & Greed Index') with its scale semantics (0=extreme fear, 100=extreme greed) and scope ('optional history'). It names the sibling tools it is not (crypto_news, funding_rates), so an agent can distinguish 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?

Explicit 'Use when' clause defines the triggering condition (gauge overall crypto market sentiment), and an explicit 'Not for' clause routes away to the correct alternatives for token-specific sentiment. Both the positive and negative selection criteria are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the multi-exchange source set, the returned fields (funding_rate_pct, annualized_rate_pct, sentiment), and how sentiment should be read. It still omits failure modes or rate-limit behavior, but with annotations present this is solid.

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

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

The Use when / Not for / Returns structure is front-loaded and scannable, with no redundant sentences. The full example JSON is somewhat long but provides concrete payload shape, and the price line is minor boilerplate.

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

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

There is no output schema, so the description carries the return-value burden and does so completely: named fields, per-exchange granularity, sentiment values, and a sample response. Combined with the explicit routing to siblings, an agent has everything needed 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 description coverage is 100% and the single optional 'asset' parameter is fully documented in the schema (symbol, empty for all majors). The description adds no syntax or defaulting detail beyond that, so the baseline of 3 applies.

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

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

The description names a specific verb+resource ('Get perpetual futures funding rates') and enumerates the exact sources (Binance, Bybit, OKX). An agent can distinguish this from siblings like open_interest or market_snapshot 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?

It explicitly states 'Use when' (gauge leveraged sentiment or cost of holding a perp) and 'Not for' (open interest / long-short ratio → open_interest; combined verdict → pre_trade_check). Alternatives and the conditions selecting them are named directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful context beyond that: the specific return fields, the data source (etherscan), and the constraint that only Ethereum mainnet gas is reported.

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 cleanly sectioned into Use when / Not for / Returns / Example. The example response is somewhat redundant with the Returns field list, and the price line is extraneous, 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 output schema and no annotations describing return values, the description compensates by listing the return fields and providing a concrete example response. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, which is the baseline 4 for this dimension. Nothing further is needed since there is no input to describe.

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

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

States a specific verb (Get) and resource (current Ethereum gas prices) with explicit scope (slow, standard, fast). It also distinguishes itself from siblings by noting only Ethereum mainnet gas is reported, so an agent can tell it apart from market_snapshot without opening any schema.

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

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

Explicit 'Use when' clause names the triggering scenario (before submitting a transaction or estimating costs), and a 'Not for' clause routes the agent to market_snapshot when gas is needed as part of a broader read. The when/when-not/alternative triad is fully covered.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: it aggregates three upstream sources into one normalized response, and it is free ($0.000 USDC per call). It stops short of noting rate limits, caching, or refresh cadence, so it is strong but not maximally rich.

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 scope in the first sentence, then structured as Use when / Not for / Returns / Example. The example response is verbose but it is the section that carries the most information in a zero-parameter tool, so every part earns its place.

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

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

With no output schema, the description compensates by enumerating all returned fields (sp500_price, treasury_yield_10y, btc_price_usd, gas_standard_gwei, timestamp) and providing a concrete example with source attribution. Nothing an agent needs to call or interpret this 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 takes zero parameters and the schema is an empty object, so there is nothing to disambiguate. This matches the baseline of 4 for a parameterless tool; the description correctly claims no input is needed.

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 scope: Fed rate, inflation proxy, S&P 500, BTC, ETH, and gas in a single normalized call. It explicitly distinguishes itself from siblings as 'the only tool that gives you macro + crypto in one shot,' so an agent can separate it from token_price or gas_tracker 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?

Provides explicit 'Use when' and 'Not for' blocks, and names the alternatives for the excluded cases (token_price, gas_tracker, funding_rates for single-asset depth; dune_query for history/time series). No inference is required to route correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description goes further by enumerating the exact returned fields, giving a full example response payload, and noting the interpretive rule (rising OI + high funding = overcrowded), which is context the annotations cannot convey. It stops short of stating data freshness/latency or failure modes.

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

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

Front-loads the purpose, then usage, then returns — good ordering. The embedded example response JSON is long, but it is justified because there is no output schema and it communicates the return shape more precisely than a field list alone. Slightly heavy overall but every section earns its place.

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

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

With no output schema, the description compensates by listing returned fields and showing a full example response, and it supplies routing guidance against 21 siblings. An agent has everything needed to select and call this tool correctly; only latency/caching behavior is unstated, which is minor.

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 optional 'asset' parameter with a default, so the schema carries the burden; the description only echoes 'for any asset'. Baseline 3 is appropriate since the description adds no format, valid-set, or defaulting semantics beyond the schema.

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

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

States a specific verb and resource (total open interest in perpetual futures) plus the key derived metrics (1h/24h change), and explicitly names the sibling tools it complements (funding_rates) and is not (pre_trade_check). An agent can distinguish it from market_snapshot, funding_rates, and pre_trade_check 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?

Provides an explicit 'Use when' with a concrete condition (need total OI and its direction) and an explicit 'Not for' routing two adjacent needs — funding cost — to funding_rates and trade verdicts to pre_trade_check. This is the full when/when-not/alternatives pattern.

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 declare readOnlyHint and openWorldHint, so safety is already covered; the description adds the source scope (Binance/Bybit CEX only, not DEX pools) and the exact payload shape. It does not discuss rate limits or latency, but the exchange-coverage constraint is meaningful 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?

Front-loaded with the core purpose, then clearly sectioned into use-when, not-for, returns, and an example. It is long but every block earns its place; the trailing price line is neutral noise rather than padding.

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

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

With no output schema, the description carries the return-format burden and does so fully via a labeled 'Returns' list plus a concrete JSON example. Every sibling-routing and scope detail an agent needs to call this correctly is present.

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

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

Schema coverage is 100% and the single asset parameter is documented with examples in the schema itself. The description adds no syntax or format detail beyond that, so the baseline 3 for a fully-covered schema 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: fetches real bid/ask depth and slippage at three notional tiers from Binance and Bybit. It explicitly distinguishes itself from siblings by name (token_market_data, pre_trade_check) and scopes to CEX books only, so an agent can tell what it is 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?

Provides explicit 'Use when' and 'Not for' clauses, naming the alternative tool (token_market_data for market cap/volume, pre_trade_check for a full pre-trade verdict) for each exclusion. The condition that selects this tool — estimating slippage before a large trade — 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?

Beyond the annotations, it discloses that the call settles $0.01 on-chain, that an unpaid call returns PaymentRequired, that major ERC-20s auto-resolve, that native assets report security n/a, and that an unrecognized token caps the verdict at caution. These are meaningful behavioral traits the annotations do not convey.

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

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

It is long but well front-loaded and segmented into Use when / Not for / Returns / Example. The example response and verdict logic justify their space, though a few clauses (e.g. listing individual token names) are slightly more than 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?

With no output schema, the description fully compensates by documenting the return shape (verdict, factors, components) and giving a concrete example response, plus the cost and payment model. An agent has everything needed to invoke and interpret the 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?

Schema coverage is 100%, so side/size_usd/token_address semantics are already documented in the schema. The description reinforces the token_address auto-resolution and verdict-capping behavior but adds little beyond what the schema fields already state, so baseline 3 applies.

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

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

The description states a specific function (a one-call pre-trade sanity check producing an ok/caution/avoid verdict) and names the four factor families it aggregates. It explicitly distinguishes itself from siblings by naming funding_rates, open_interest, orderbook_depth, and token_security as the raw alternatives.

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

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

It has explicit 'Use when' (about to enter a position, wants one verdict instead of four feeds) and 'Not for' (only need a single raw factor; not about to size a position) sections, and points to the free sibling tools that serve the excluded case. This is textbook 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?

With readOnlyHint=true and openWorldHint=true already covering the safety profile, the description still adds substantial behavior: it drops stubs, ranks by a stated formula (unique payers × 3 + calls + recency), enforces the budget as a hard filter, tiebreaks on price, and clarifies 'Advise-only — no payment happens here'. That is context well 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?

Front-loaded with the key fact (legacy alias, prefer verified_route), and the dense sentences each carry information. Slightly repetitive — verified_route is referenced twice — and 'price- tiebreaks' has a garbled spacing, but overall it is tight for the amount of behavior it conveys.

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, open-world routing tool with no output schema, the description covers what it returns (ranked candidates + recommendation + ready-to-pay details) and what it does not do (no payment). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing budget as an enforced exclusion ('Tools priced above this are excluded') and tying need to the vetting flow, which gives the agent operational context the schema does not.

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 (find and judge the best paid x402 tool for a need) and immediately distinguishes itself from its sibling by declaring it is the 'legacy alias of verified_route'. It also names the discovery sources and ranking basis, so the agent knows exactly what the tool does without opening anything else.

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

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

Explicitly says to prefer verified_route, explains the condition that selects it ('same vetting, matches the paid tool + Bazaar listing'), and gives concrete trigger phrases ('which x402 tool for X', 'find a paid API for X under $Y'). When-to-use and the alternative are both spelled out.

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

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

Annotations only mark readOnlyHint=false and openWorldHint=true; the description goes well beyond by disclosing the $0.01 USDC charge, the hard max_spend enforcement across all subsequent calls, the on-chain settlement, and the x402 PaymentRequired flow for unpaid calls. This is exactly the behavioral context (cost, auth/payment, error behavior) an agent needs before invoking.

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

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

Front-loaded with the core action and cost, then organized into Use when / Not for / Returns / Example sections. It is on the long side and the full example-response JSON is somewhat verbose, but with no output schema each block 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?

No output schema exists, so the description must carry the return contract, and it does: it enumerates returned fields and provides a full example response including the receipt and sdk_hint. Combined with the payment/error behavior, an agent has everything needed to call and use this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: max_spend is described as a 'hard max_spend cap across all subsequent tool calls' enforced by the SDK, which is more than the schema's 'Hard budget cap in USDC for this session.' It doesn't add much for label or agent_address 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 verb+resource ('Open a budget-capped agent session on AgentPay') with the concrete outputs (session_id, budget config, gateway URL) and positions itself as 'the entry point for agents discovering AgentPay on Base Bazaar.' This is clearly distinguishable from every sibling, none of which create sessions.

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

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

Provides explicit 'Use when' and 'Not for' clauses, including the alternative (SDK's quickstart() for cost-free sessions) and the reason to prefer this one (settles $0.01 on-chain). Nothing about tool selection is left to inference.

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

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

With readOnlyHint and openWorldHint already declared, the description adds genuine value by naming fields it does NOT return (pool depth, slippage) and disclosing the data source ('coingecko'). It goes beyond the annotations without contradicting them, though it doesn't discuss rate limits or freshiness/latency of the market 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?

Front-loads the purpose, then uses labeled sections ('Note', 'Use when', 'Not for', 'Returns', 'Example response') that are scannable and each earn their place. Slightly verbose for a 2-param read tool, but nothing is wasted or redundant.

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

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

No output schema exists, yet the description enumerates the return fields and provides a concrete example response including the source field, fully compensating for the missing output schema. An agent has everything needed to call and interpret results.

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 token_a and token_b are already documented in the schema; the description only implies the pair semantics. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb+resource ('Get market cap, 24h volume, ATH, and price change for any token') and explicitly distinguishes itself from siblings token_price and orderbook_depth. An agent can identify the tool's scope without consulting 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?

Uses explicit 'Use when' and 'Not for' sections that name the alternatives (token_price for spot price, orderbook_depth for pool depth/slippage) along with the conditions selecting each. Routing guidance is complete and actionable.

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 (readOnlyHint, openWorldHint), so the description focuses on added value: the exact return fields and a realistic example response. It also notes the per-call price. It doesn't discuss rate limits or caching, but for a simple read-only public price query the disclosure is solid.

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

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

Front-loaded purpose followed by tightly labeled sections (Use when, Not for, Returns, Example). Every sentence earns its place; no filler.

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

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

No output schema exists, and the description compensates by listing return fields and a concrete example. Usage routing, return shape, and pricing are all present, making it complete for this tool.

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

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

With 100% schema description coverage and a single documented parameter, the schema carries the semantics. The description adds no syntax or formatting guidance beyond the schema's example (BTC, ETH, SOL). Baseline 3 is 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 verb and resource ('Get the current USD price of any cryptocurrency token') and explicitly distinguishes itself from three named siblings via the 'Not for' section. An agent can select it unambiguously.

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

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

Provides explicit 'Use when' criteria (price, 24h change, market cap) and 'Not for' exclusions routing to token_market_data, market_snapshot, and orderbook_depth. No inference required.

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

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

Annotations already mark it readOnly and open-world, so safety is covered. The description still adds real value beyond them: chain support is limited to Ethereum and BSC, the data source is goplus, the returned risk fields are enumerated, and the per-call price is disclosed. It stops short of discussing rate limits or failure modes, but the mutation/safety burden is low for a read-only scan.

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 action, then cleanly separated Use when / Not for / Returns / Example blocks. Every line is scannable and none is redundant filler.

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

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

With no output schema, the description compensates by listing the exact return fields and providing a full example response object. Combined with the chain limitation and exclusions, an agent has everything needed to call and interpret 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?

Schema coverage is 100% and both parameters already carry descriptions including the enum values and default. The description's 'Ethereum and BSC contracts only' restates the enum rather than adding new syntax or format guidance, 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 ('Scan') and resource ('token contract') with an enumerated scope of risks (honeypot, rug pull, security). An agent can instantly distinguish this from token_price or orderbook_depth, which are named as the wrong tools for related questions.

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

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

Explicit 'Use when' and 'Not for' sections, including the concrete exclusion of native coins with no contract and the pointer to orderbook_depth / token_price for liquidity and price. This is textbook when/when-not/alternatives 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?

Beyond readOnlyHint/openWorldHint annotations, it discloses the transformation behavior (strips ads, nav, boilerplate), auth needs (no API key), truncation potential (truncated flag), pricing, and a sample response. Rich behavioral context.

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

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

Front-loaded purpose followed by clearly labeled sections; the return fields and example add value. The embedded example response is somewhat long, but overall it remains well-structured and readable.

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 no output schema, the description names the return fields, gives an example, and covers limitations (login pages, JS-only rendering). An agent has everything needed 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% with a single self-documented 'url' parameter, so the schema already carries the semantics. The description adds no syntax or format detail beyond what the schema provides, warranting 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+resource ('Convert any URL to clean, LLM-ready markdown') and clarifies the output transformation. It also differentiates from the sibling web_search, telling the agent exactly when each applies.

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

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

Explicit 'Use when' and 'Not for' sections with named alternatives (web_search) and exclusion conditions (login-required pages, browser-only rendering). Nothing is left to inference.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses a lot: the free preview withholds the provider URL and x402 challenge, paid mode requires funding the install wallet and setting AGENTPAY_ENABLE_PAID=1, the paid call costs $0.01, and no payment occurs while paid mode is off. This is exactly the kind of side-effect/auth disclosure the annotations can't 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?

Purpose is front-loaded and the paid/preview gating is well organized, but the text is long, uses all-caps emphasis ("PROVE", "WITHHOLDS") and double spaces that add noise. Information density is high, so most sentences earn their place.

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

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

With no output schema, the description fills the gap by stating exactly what is returned (vetted pick name, usage stats, rationale, survivor count) and what is withheld (provider URL, ready-to-pay challenge). An agent has everything needed to call it 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 coverage is 100%, so the schema already documents need, chain, and budget_usd. The description adds only the budget-gating concept ("budget-gate", "budget $Y") without new syntax or format detail beyond the schema.

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

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

The description states a specific verb+resource+scope: a buyer-side trust oracle that vets x402 providers (Coinbase Bazaar) and ranks by unique-payer usage. It clearly distinguishes itself from generic discovery by being a vetting/oracle layer, but never names the adjacent siblings it overlaps with (route, pre_trade_check, estimate_plan), leaving some differentiation to inference.

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

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

It gives explicit triggering phrases ("which x402 tool for X", "vet this provider before I pay") and explains the preview-vs-paid decision boundary. It does not say when to prefer a plain search/route sibling instead, so alternatives are 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes further by disclosing the supported chain set, address formats, the shape of the return payload, a concrete example response, and even per-call pricing — useful context beyond structured fields. Minor gaps remain (no pagination or rate-limit behavior), but disclosure is strong.

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?

Well front-loaded: purpose first, then usage routing, then return shape, then price. The example response and pricing line are somewhat bulky, but each block is scannable and earns its place for a tool with no output 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 no output schema, the description compensates by stating the return format (symbol, amount) and giving a full example response. Chain coverage, address formats, and exclusions are all present, so an agent has everything needed 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 description coverage is 100% and both parameters are documented there, including the 'Ethereum 0x... or Stellar G...' format hint that the description repeats verbatim. The only marginal addition is 'no other chains', which the enum already encodes, so the description adds little beyond the schema 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 (get) and resource (token balances) with explicit scope: Ethereum or Stellar wallet addresses only. It distinguishes itself from sibling tools by naming token_price, token_market_data, and whale_activity as the wrong fit for this use case.

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

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

Contains explicit 'Use when' and 'Not for' sections that name the alternative siblings (token_price / token_market_data for price data, whale_activity for cross-wallet transfers). The routing decision is fully specified with no inference required.

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

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

Annotations cover readOnlyHint and openWorldHint, but the description adds substantial context beyond them: a fixed result count (5), content delivered as clean markdown, that results include page content rather than just links, and even pricing ($0.000 USDC). No contradiction with annotations.

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

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

Front-loads the core purpose, then layers Use when / Not for / Returns / example / price in clean labeled sections. Every block earns its place — the example response substitutes for the absent output schema and the price line carries cost 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 no output schema, the description must describe return values, and it does: a 'Returns' field list plus a concrete example payload. Combined with routing guidance and pricing, an agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100% for the single 'query' parameter, so the schema already documents it. The description characterizes the query domain ('news, documentation, prices, events') 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+resource ('Search the web') and immediately specifies the output shape: 'top 5 results with their full content as clean markdown.' It explicitly differentiates from siblings by naming url_reader and crypto_news, so an agent can route without reading 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?

Provides explicit 'Use when' and 'Not for' sections. The alternatives are named with the exact condition that selects them ('you already have the URL — url_reader'; 'crypto headlines with sentiment — crypto_news'), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it scopes the data to 'Ethereum ERC-20 transfers only', names the data source (etherscan in the example), documents the return shape, and discloses a per-call price. Rate limits and refresh/latency semantics are not stated, but coverage is well above the annotation baseline.

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?

Well front-loaded and sectioned (purpose, Use when, Not for, Returns, Example). Every block earns its place, though the worked example response is somewhat long relative to a two-parameter tool. No filler 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?

There is no output schema, so the description correctly carries the return contract, listing large_transfers[] fields (from, to, amount, usd_value, minutes_ago) and total_volume_usd, plus a concrete example. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters (token, min_usd) are already fully documented in the schema. The description implies the threshold behaviour through 'large transfers' and usd_value, but adds no syntax, default value, or format detail beyond the schema. Baseline 3 is correct 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: 'Detect recent large wallet movements for a token (whale tracking)'. An agent can immediately tell this apart from wallet_balance and orderbook_depth, which the description names as non-overlapping alternatives.

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

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

Explicit 'Use when' and 'Not for' clauses with named sibling alternatives ('one address's holdings — wallet_balance; exchange order-book size rather than on-chain transfers — orderbook_depth'). The routing decision is fully specified with no inference required.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), but the description adds real context: risk_level is explicitly flagged as a heuristic and the agent is told to run token_security on the pool token before depositing. It also discloses result ordering (APY descending) and the upstream source (defillama).

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, then cleanly sectioned into Use when / Not for / Returns / Example. The inline example response partly duplicates the Returns line, making it slightly longer than strictly necessary, but every section is scannable and earns its place.

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

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

With no output schema, the description fully compensates by enumerating returned fields (protocol, apy, tvl_usd, chain, risk_level), ordering semantics, and a concrete example payload including the source. Nothing an agent needs to call or interpret the result 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 all three parameters (token, chain, min_tvl) are documented in the schema with defaults and formats. The description adds only 'for a given token', which does not extend parameter meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Find best DeFi yield opportunities across protocols for a given token') and explicitly distinguishes itself from the sibling defi_tvl, which covers protocol TVL rather than pool APYs. An agent can route between them without opening either schema.

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

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

Has explicit 'Use when' and 'Not for' clauses naming the alternative tool (defi_tvl) and the condition that selects it. It also proactively routes to token_security before depositing, which is genuine decision guidance rather than restated purpose.

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