MAD Synapse · Chain

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

Goes well beyond the readOnly/idempotent annotations: it discloses parallel per-venue querying, the OKX USDT-vs-USD substitution quirk, the $0.001/call cost with 10 free/day and x402 payment-required handling, and that errors return isError without being charged. 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 returned data, then venue behavior, then labeled 'When to use', 'Price', and 'Errors' sections. Dense but every sentence carries distinct operational information with no 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?

With an output schema present, return values need not be described, and the description still covers purpose, routing, cost, venue quirks, and error semantics. 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 the single 'pair' parameter already carries examples (BTC/USD, ETH-USDT, SOL), so the baseline is 3. The USDT-on-OKX note is about venue output rather than the parameter itself, adding little to 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?

The first sentence states the specific resource (live bid/ask/last, 24h change, volume, range for a pair) and the exact scope (Kraken, Coinbase, OKX side by side plus cross-venue spread). An agent can tell this apart from generic price tools and from orderbook_depth without opening the schema.

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

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

Explicit 'When to use' for top-of-book prices and a named alternative (orderbook_depth) with the condition that selects it. It does not distinguish from closer siblings like crypto_price, price, or price_history, so the routing guidance is clear but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavioral context: pricing ('free') and error semantics ('returns isError... not charged'), plus what the two modes return. It does not discuss pagination or rate limits, but the mode behavior and charge model are useful additions.

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

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

Front-loaded with the dual behavior before the DefiLlama attribution and usage routing. Dense and mostly waste-free, though the attribution line ('DefiLlama chain TVL') is mildly redundant with the opening sentence.

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 the two operating modes, the parameters that switch them, pricing, and error behavior, and an output schema exists so return values need no explanation. An agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond it by mapping the 'chain' parameter to an output mode, explaining that 'days' yields up to 365 days of history plus 7d/30d/90d change metrics, and clarifying the ranking scope. Only 'limit' semantics are left entirely 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 resource and scope: total value locked per chain, ranked, or a single chain's daily history. It explicitly distinguishes itself from defi_rankings (protocols) and from other TVL tools, so an agent can pick it without opening the schema.

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

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

Gives explicit mode-selection rules ('Without "chain": ranking... With "chain": daily TVL history') and names the alternative for a different use case ('for protocols use defi_rankings'). Nothing about when to use it versus alternatives 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?

Annotations already cover read-only/idempotent/open-world safety, and the description adds substantial behavior beyond them: resolution order against the top 1,000 coins by market cap, oracle provenance with a confidence score, the 30-asset cap, ambiguity handling, and error/charging semantics (isError, not charged).

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

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

Front-loaded with the core capability before the routing and resolution detail, and every sentence carries new information. It is dense — a URL, error semantics, and resolution rules in one paragraph — but not padded.

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

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

An output schema exists so return shape needn't be restated, and the description still covers the essentials an agent needs: accepted input forms, asset limit, pricing source and confidence, ambiguity behavior, cross-server alternatives, and error/charge behavior.

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 chain enum plus assets array are fully documented in the schema, so the baseline applies. The description does add resolution-format nuance the schema lacks — chain-qualified forms like 'base:0x…', 'coingecko:ethereum', bare 0x addresses, and Solana mints — which nudges it to a solid but not exceptional 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+scope: live USD price and 24h change for up to 30 assets across any chain, priced from DefiLlama's aggregated oracle. It explicitly distinguishes itself from siblings cex_ticker and price_history, so an agent can route without opening either schema.

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

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

Provides an explicit 'When to use' clause: current prices by symbol on any chain; routes Solana mint lookups to a named sibling tool on another server and history to price_history. When-not-use is also implicit in the ambiguity note (ambiguous symbols list 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?

With readOnlyHint/idempotentHint already declaring the safety profile, the description still adds substantial context the annotations cannot: the $0.002/call price, 10 free calls per day, the x402 payment-required result, fuzzy-match behavior that returns best match plus alternatives, and error semantics (isError message, not charged).

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

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

Front-loaded with the payload contents, then input format, then cost/error semantics — a sensible ordering with no filler sentences. It is dense and slightly packed (data-source sentence, pricing, errors, fuzzy matching all in one paragraph), but every sentence carries actionable information.

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

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

An output schema exists so return values need no explanation, and the description covers everything else an agent needs: what is returned, accepted input forms, fuzzy-match side effects, cost, and error/charging behavior. No material gap remains for a single-parameter lookup.

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 'protocol' parameter, so baseline is 3. The description adds value beyond the schema by giving example slugs with varied casing/naming ('aave', 'Uniswap', 'jupiter') and explaining fuzzy-match resolution behavior, which shapes how the agent should format input.

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

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

The description names a specific resource ('One DeFi protocol in depth') and enumerates exactly what the profile contains: TVL by chain, TVL trend, fees/revenue across three windows, market cap, audits, links. The 'one protocol' scoping implicitly distinguishes it from list-style siblings such as defi_rankings, chain_tvl, and fees_revenue.

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 clearly states the lookup key ('by name or DefiLlama slug') and gives concrete slug examples, so an agent knows the calling context. However, it never explicitly routes the agent away from siblings like defi_rankings (multi-protocol lists) or chain_tvl (chain-level TVL) — no when-not-to-use 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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: cost ('Price: free'), error semantics (isError for invalid input or upstream failure, not charged), and the exact row fields returned.

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 definition, then examples, then when-to-use, pricing, and errors. Information-dense with little waste, though the enumerated row fields and category list border on schema duplication.

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 an existing output schema and full annotations, the description still contributes data provenance, pricing, and error behavior, and covers filtering and ranking semantics. Nothing an agent needs to select and 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%, so all five parameters are already documented in the schema with defaults, ranges, and enum values. The description adds only category examples ('lending, DEX, liquid staking, bridges, perps') that largely overlap the schema's own examples, 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 (rank), resource (DeFi protocols), the ranking basis (TVL or 1d/7d change), and the data source (DefiLlama, ~6,000 protocols). It explicitly distinguishes itself from the closest sibling by noting 'for one protocol in depth use defi_protocol'.

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

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

Provides explicit when-to-use guidance with concrete example queries ('biggest lending protocols on Base', 'fastest growing DEXes this week') and names the alternative tool (defi_protocol) for the in-depth single-protocol 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 cover the safety profile (readOnly=true, idempotent=true, destructive=false, openWorld=true), so the description's added detail is what counts: 'Price: free' and the error contract ('returns isError with a message for invalid input or an upstream failure (not charged)') are genuinely useful operational facts not present in 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 output (volume + top venues) and packed into a few dense sentences with no filler. Slightly overloaded with parenthetical clauses, but nothing is truly wasted.

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

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

For a zero-required-param read tool with a full output schema, the description covers scope, modes, chain scoping, pricing, and failure behavior. An agent has enough to call it correctly; only explicit sibling routing 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 each parameter is already documented with defaults and ranges, so the baseline is 3. The description's mapping of perps/aggregators is helpful, but it says 'type=perps' while the schema enum only accepts 'derivatives', which could lead an agent to submit an invalid value — a small but real mismatch.

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 (DEX trading volume over 24h/7d/30d), the entity set (top DEXes with share and change), and the data source (DefiLlama DEX overview) plus chain scoping and perps/aggregator coverage. It is clearly a rankings tool, though it does not explicitly route against close siblings like cex_ticker, defi_rankings, or fees_revenue.

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: 'all chains or one', 'Optionally scoped to one chain', and the perps/aggregator variants hint at use cases but give no explicit when-to-use/when-not or alternative-selection guidance (e.g., DEX volume vs CEX volume vs protocol fees). Adequate but leaves 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, non-destructive and open-world, so the bar is lower; the description nonetheless adds real context beyond them: pricing (free), the 365-day history cap, and error semantics (isError message on invalid input or upstream failure, not charged). It does not describe caching or refresh behaviour, but for a read-only public index 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?

Front-loaded with the resource and scope, then cadence, source, limits, price, and error behaviour as compact clauses. Dense but every fragment carries information; the telegraphic style slightly hurts readability but wastes nothing.

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 covers source, cadence, history bound, cost, and failure behaviour. An agent has everything needed to call it correctly; only explicit alternative-routing guidance 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 'days' parameter is fully documented in the schema (range 1–365, default 30). The description's 'Up to 365 days of history' merely restates the schema bound rather than adding new meaning, 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?

Names a specific resource (Crypto Fear & Greed Index 0–100), states what is returned (current value plus history, 7d/30d average, extremity), and identifies the data source (alternative.me, daily). It is clearly distinguishable from market-price siblings like crypto_price or price_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?

The source and daily cadence imply when this tool applies (sentiment readings, not price data), but there is no explicit when-to-use or when-not guidance and no sibling is named as an alternative. Usage must be inferred.

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 goes further and adds context annotations cannot carry. It discloses pricing ($0.002/call, 10 free/day, x402 payment-required response) and error handling (isError with a message, not charged), plus the return shape (ranked, day-over-day change). This is exactly the value-add behavioral layer the dimension rewards.

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

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

The definition is front-loaded with the resource and metric framing, then layers semantics, ranking behavior, pricing and error handling in compact sentences. Slightly dense, and the tagline "the cash-flow view of crypto" is decorative, but every substantive sentence carries operational 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, and it does not try to. It instead covers what structured fields omit: metric definitions, pricing/payment flow, and error semantics, which is complete for a zero-required-parameter read-only ranking 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%, with limit, metric and chain all documented in the schema itself, so the baseline is 3. The description restates the fees-vs-revenue distinction and adds the 24h/7d/30d notion, but it does not document limit behavior or the default, so it adds only marginal meaning beyond the schema.

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

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

The description states a specific resource (protocols and chains) and a concrete framing: ranking fees or revenue over 24h/7d/30d windows, filterable by chain. It clearly defines the two metric modes ("fees" = what users paid; "revenue" = what the protocol kept), which helps separate it from look-alikes such as defi_rankings or chain_tvl. It stops short of explicitly naming a sibling to contrast against, so it lands at 4 rather than 5.

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

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

"The cash-flow view of crypto" and "filterable by chain" imply when the tool is relevant, but there is no explicit when-to-use / when-not-to-use statement and no routing to alternatives like chain_tvl or defi_rankings. The metric enum is explained, but that is parameter semantics, not tool-selection guidance. Usage is therefore implied rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description goes well beyond them: sign convention ('Positive = longs pay shorts'), venue settlement intervals driving normalization, per-call pricing with a free tier, x402 payment-required behavior, and error semantics (isError on invalid input/upstream failure, not charged). This is unusually rich disclosure for a read-only 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?

Purpose and sign convention are front-loaded, and each subsequent element (normalization, use case, alternative, price, errors) earns its place. It is dense and slightly packed into dash-separated clauses, but there is 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?

With an output schema present, return-value explanation is unnecessary, and the description still supplies the interpretive context an agent needs: the sign convention, cross-venue normalization, pricing/quota behavior, and error handling. Nothing material for correct invocation is missing.

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

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

There is a single parameter with 100% schema description coverage ('BTC, ETH, SOL…'), so the schema already carries the semantics. The description adds no additional constraint beyond the implied coin scope, 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 (perpetual funding) with explicit scope (one coin across Hyperliquid, OKX and Kraken Futures) and names what it returns (per-interval rate, annualized APR, open interest, mark price). It is clearly distinguishable from the sibling hyperliquid_markets, which it explicitly points to for market-wide scans.

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

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

Gives explicit use cases ('basis/carry trades or crowding signals') and an explicit when-to-use plus an exclusion: 'For one coin across venues; to scan every Hyperliquid market use hyperliquid_markets.' The alternative tool and the condition that selects it are both named.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, yet the description adds substantial context beyond them: data provenance (eth_feeHistory, mempool.space, prioritization-fee percentiles), the L2-before-L1-data-fee caveat, billing ('Price: free'), and error semantics (isError with a message, not charged). This is exactly the extra behavioral detail the annotations cannot carry.

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

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

Front-loaded with the core purpose, then structured per chain with sourced details and a short errors/price trailer. Every sentence contributes information, though the per-chain enumeration borders on detail that could be trimmed for an agent that already sees the 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 an output schema present, the description need not explain return values, and it still covers sources, per-chain semantics, L2 caveats, cost and error behavior. 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?

There is a single optional parameter and schema description coverage is 100%, so the baseline is 3. The description contextualizes the valid chain space by naming the networks, but adds no format or syntax detail (e.g. exact accepted identifiers, default behavior) beyond what the schema already says.

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 ('what a transaction costs right now') with exact scope (17 EVM chains, Solana, Bitcoin) and enumerates the returned metrics (gwei/priority fee, USD cost of transfer and swap). An agent can distinguish this from fees_revenue, solana_network and bitcoin_network 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 chain coverage and per-chain breakdowns imply when the tool is appropriate (needing current, cross-chain tx cost estimates), which is clearer than most. However, it never names an alternative or states when NOT to use it (e.g. vs bitcoin_network or solana_network for chain-specific data), 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?

Goes well beyond annotations (readOnly/idempotent/openWorld): discloses pricing and x402 payment flow, the free-tier quota, that errors return isError without charge, that funding is hourly with apr = hourly × 8,760, and that data is live from the public info API — all operationally important 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-loads the resource and its metrics, then layers ranking, filtering, pricing and error behavior — every element earns its place, though the density of pricing/error clauses makes it slightly heavy for one paragraph.

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 needn't be explained; the description still covers cost, errors, funding conventions and both usage modes, leaving no material gap for an agent 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 the schema already documents coin, sort enum and limit. The description adds only marginal interpretation (rank vs filter, movers), which is the baseline case 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+resource (every Hyperliquid perpetual with mark/oracle price, 24h change, volume, OI, funding APR, premium) and distinguishes itself from siblings like funding_rates, cex_ticker and crypto_price by anchoring to Hyperliquid's perp board.

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 — 'Filter to one coin or rank the whole board' — and explains the rank modes. It stops short of naming an alternative tool or a when-not-to-use condition, so it lacks the explicit routing a 5 requires.

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/openWorld annotations, it discloses cost ($0.003/call, 10 free/day, x402 payment-required result), error behavior (isError on invalid input or upstream failure, not charged), and result semantics (slippage vs mid in bps, null meaning the book was too thin). This is rich context the annotations do not carry.

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

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

Front-loaded with the core capability and outcome dimensions, and every clause carries information (coverage, venues, pricing, errors). It is dense and reads as a long run-on, so it falls just short of ideal structure but wastes nothing.

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

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

With an output schema present, return values need no explanation, and the description still covers semantics, pricing, error handling, and interpretation of null slippage. 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 description coverage is 100%, so both parameters are already documented — including the venue enum with its default. The description adds no format or constraint detail beyond what the schema provides (BASE/QUOTE format comes from 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?

The description states a concrete verb+resource (pull the public L2 book and walk it) and enumerates exactly what is returned: bid/ask depth at ±0.1/0.5/1/2/5%, spread, and slippage for $10k/$100k/$1M orders. It also names the sibling it is not (cex_ticker for prices only), so an agent can distinguish it without opening the schema.

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

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

It gives explicit when-to-use guidance ('Use before sizing an order or comparing venue liquidity') and routes the agent to the alternative for a different need ('for just prices use cex_ticker'). Both the positive case and the exclusion 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context on top: per-call pricing ($0.002, 10 free/day, x402 payment-required results), error behavior (isError with a message, not charged on failure), and the computed stats returned. This is well beyond what the annotations provide.

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 what the tool returns, then usage, then price, then errors — a sensible ordering with no filler sentences. The server URL and payment detail make it slightly dense, but every clause carries actionable information.

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

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

For a priced, analytics-returning read tool with four params, an existing output schema, and full annotation coverage, the description supplies everything an agent needs: scope, sibling routing, cost, failure semantics, and return-shape summary. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents days, asset, chain and interval. The description adds the 'same asset resolution as crypto_price' hint, but it also introduces a conflict: it claims hourly points up to 90 days while the schema states hourly is allowed only up to 30 days.

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 (historical USD prices for any crypto asset) with the returned analytics enumerated (return, high/low, max drawdown, annualized volatility), and explicitly separates itself from the sibling crypto_price. An agent can distinguish it from every other tool in the list without opening a schema.

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

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

Contains an explicit 'When to use' clause covering past prices/drawdowns, names the alternative tool (crypto_price) for current price, and even gives the alternative's server URL. Exclusions are stated, not inferred.

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 bar is covered; the description adds genuinely new context: pricing (free), error contract (isError with message for invalid input or upstream failure, not charged), and the measurement basis for peg_deviation_pct. It stops short of describing pagination or freshness/update cadence.

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 lead sentence front-loads the payload (supply, change, price, peg deviation), followed by source, filter axes, the peg_deviation definition, and cost/error notes. Dense but each clause carries information; only the 'Filter by symbol or peg type' line is redundant with 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, return values need not be enumerated, and the description still clarifies peg_deviation_pct's measurement basis. Cost and error behavior are covered, leaving only minor gaps such as data freshness and whether the 1d/7d/30d windows are fixed.

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 peg, limit, and symbol with defaults, ranges, and enum values. The description only repeats 'filter by symbol or peg type' and adds no format or edge-case detail 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 concrete deliverables — circulating supply, 1d/7d/30d supply change, price, peg deviation, depegs, mint/burn flows — plus the data source (DefiLlama) and chain scope. It is immediately separable from siblings like crypto_price or defi_protocol, which cover price quotes and protocol TVL rather than stablecoin supply/peg 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 hints at filtering by symbol or peg type, which tells the agent the two selection axes, but never states when to prefer this over crypto_price or defi_rankings, nor any prerequisites. Usage is implied rather than prescribed, so it sits at the minimum-viable level.

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 annotations already covering readOnly/openWorld/idempotent, the description goes well beyond them: refresh interval, the base-vs-reward APY split, 30-day mean, IL risk and prediction fields, the $0.003/call price with 10 free/day and x402 payment-required fallback, and error semantics (isError, errors not charged). This is unusually rich operational context.

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

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

Dense and front-loaded with scope, filters and sort first, then output semantics, then pricing/errors. It is long and the pricing/error tail is somewhat run-on, but nearly every clause carries information an agent needs.

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 need not be re-explained, and the description still covers data provenance, freshness, cost model, error behavior and all filtering/sorting dimensions. 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 conceptual meaning the schema lacks, e.g. that base APY is organic fees/interest while reward APY is token emissions, and what IL risk and single/multi exposure imply. That aids interpretation of the enum and filter values.

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 ('Search ~19,000 DeFi yield pools across all chains') plus the filtering and sorting axes, which cleanly separates it from siblings like chain_tvl, defi_rankings and defi_protocol. The data source (DefiLlama yields) and refresh cadence add further specificity.

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 filtering dimensions imply when the tool is useful, and it hints at a use case ('spot unsustainable spikes'), but it never states when to prefer this over sibling tools such as defi_protocol, chain_tvl or dex_volumes, nor any explicit exclusions. 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.