Ekubo Protocol

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

Annotations already establish readOnlyHint=true and openWorldHint=false. The description adds useful output-behavior context beyond the annotations, notably that the fee is never returned as a JSON number, which prevents an agent from expecting numeric JSON for that field. It still does not describe invalid-config handling or chain-specific behavior, but the added transparency is meaningful.

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

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

Two tightly written sentences with no filler. The decoded fields are front-loaded, and the output caveat about the fee follows immediately as relevant supporting context.

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

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

The tool takes one required input param, has an output schema, and carries read-only annotations, so the description does not need to explain return shape in full. It is complete enough for an agent to call it correctly, with the fee caveat adding important completeness; only edge-case error behavior is left unmentioned.

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 parameter is documented as 'bytes32 hex'. The description adds context about what the packed bytes32 represents internally, but does not add syntax, validation, or formatting details beyond the schema's own description, 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 uses a specific verb and resource: decode a pool config, and enumerates the exact packed fields returned (bytes32 extension, Q64 fee, discriminator, tick spacing/stableswap parameters). That is clearly distinct from sibling tools like get_pool or decode_uniswap_v4_position_info, though it does not explicitly name or contrast an alternative.

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

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

The description says what the tool decodes but gives no explicit when-to-use context, prerequisites, or alternatives such as get_pool or derive_pool_id. The agent must infer that this is for raw bytes32 configs rather than general pool lookups.

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

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

readOnlyHint=true and openWorldHint=false already signal a safe, non-networked operation; the description reinforces this by characterizing the work as local integer decoding rather than a state query. Beyond that reinforcement it adds little about failure modes, e.g. what happens with a malformed or out-of-range integer, and the returned fields are already carried by the output schema.

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

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

Two tight sentences with zero filler; the decoded outputs come first and the disambiguating 'not a state query' note closes. Every clause earns its place.

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

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

For a one-parameter pure decode function with an output schema and clear read-only annotations, the description is essentially sufficient. A minor gap remains around input expectations (e.g. accepted magnitude, whether the value must come from a specific wallet-read surface), but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% with a single required param ('info', decimal integer), so the baseline is 3. The description does add the provenance of that value — it is the packed PositionInfo returned by wallet reads — which helps an agent source it correctly, but adds no formatting or range guidance 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 ('Decode the packed PositionInfo') and immediately enumerates the decoded outputs (signed tick bounds, subscriber flag, truncated pool-ID prefix), so an agent knows exactly what it gets back. The closing clause distinguishes it from the many state-query siblings like get_position and get_positions_by_owner.

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

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

The line 'This is local integer decoding, not a state query' implicitly tells the agent to reach for this after a wallet read rather than instead of one, and rules out on-chain lookup. However, it never names the adjacent decoding sibling (decode_pool_config) or states explicitly 'use this when you already have the raw positionInfo value'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is largely covered; the description adds that the result is a deterministic keccak256 hash of the encoded key. It does not say what happens with malformed hex, mismatched token ordering, or whether the output is checksummed, so it goes only modestly beyond the structured fields.

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

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

Two dense sentences with the derivation formula front-loaded and no filler. The second sentence on fee string encoding is useful but reads as a schema note rather than tool-level guidance.

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 one required nested parameter and an output schema that covers the return value, the description supplies the essential computation and the encoding constraint. It could still note the ordering requirement for token0/token1 or the relationship to decode_pool_config, but nothing critical 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 nested schema already documents token0, token1, fee, config, extension, tick_spacing, and stableswap_params individually, so the schema does most of the work. The description only reinforces that pool_key must be an exact, complete configuration and repeats the fee-as-string rationale already present in 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 names a specific verb and result: derive pool_id = keccak256(abi.encode(PoolKey)) from an exact PoolKey config. That clearly distinguishes it from decode_pool_config and list_pool_keys, though the opening phrase 'Pack or accept' is slightly ambiguous about whether it encodes a supplied key or accepts a pre-packed one.

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

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

Usage is only implied: you need a pool_id and have the PoolKey fields. There is no explicit statement of when to prefer this over decode_pool_config (the inverse) or list_pool_keys, and no prerequisites or failure conditions are mentioned.

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=true, so the description carries most of the burden. It adds the data source (Uniswap interface API), the ordering (ranked by TVL), and the pagination model, which are real behavioral facts an agent needs. It omits caveats such as index freshness or rate limits, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with the core action, then filtering/pagination, then return shape. No filler or redundant restatement of the tool name.

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 little explanation, though it still summarizes them. For a filtered, paginated list tool this covers what an agent needs to call it correctly; the main gap is that it does not state whether pool addresses/IDs are returned, which matters for chaining into get_uniswap_pool.

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 only 20% (token_address has a bare 'address' label), so the description must compensate. It does explain the non-obvious tvl_cursor semantics and mentions chain/token filtering, but says nothing about 'first' page-size behavior beyond the schema or the meaning of the chain_id/version enums, leaving half the parameters undocumented in either place.

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

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

The description states a specific verb and resource: fetch indexed V2/V3/V4 pools ranked by TVL from Uniswap's interface API. This is clearly a discovery/list operation, implicitly distinct from single-pool siblings like get_uniswap_pool. However, it never names a sibling tool or explicit boundary, so differentiation is inferred rather than stated.

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 concrete mechanics: filter by chain and token, paginate using the last pool's TVL as tvl_cursor. That is useful operational guidance but there is no when-to-use/when-not guidance, no mention of when to prefer get_uniswap_pool or get_liquidity_opportunities, and no prerequisites 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?

readOnlyHint=true already covers the safety profile, so the description's added value is real: it discloses that the envelope carries 'no entries' (a non-obvious trait) and explains that 'complete=false means the export is a prefix of the chain's list,' which no annotation conveys. It stops short of noting anything about ordering or how the wallet tool consumes the reference beyond 'unchanged,' which keeps it from a 5.

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

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

Two tightly packed sentences, front-loaded with the return artifact and then the wallet handoff. The phrase 'and its count, with no entries' is momentarily confusing on first read — the count-with-no-entries juxtaposition could be stated more cleanly — but there is no fillers or redundancy.

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

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

With an output schema present and readOnlyHint supplied, the description only needs to cover the handoff and the completeness flag, both of which it does. The reference to 'the wallet tool's reference argument' points at a tool not among the listed siblings, a minor dangling reference the agent must resolve elsewhere.

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 chain_id and max_tokens already carry their own guidance (including the ~5,600 Ethereum token note and the whole-refusal behavior). The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 holds.

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

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

The description names the exact artifact produced — a 'token_list_reference envelope (chain ID, address, symbol, name, decimals) and its count, with no entries' — rather than a generic 'export'. It also draws a sharp line against the nearest sibling with 'Use list_tokens to read entries yourself,' so an agent can pick 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?

It states the intended consumer and handoff explicitly: return the envelope 'so a wallet can import token names' and 'pass it unchanged as the wallet tool's reference argument.' It names the alternative (list_tokens) and the condition that selects it, 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 declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with an explicit 'no RPC, indexer, API, or other network request' guarantee, plus a pinned-snapshot disclosure that signals possible staleness. That is real added context beyond the annotations. The only shortfall is that it never says how current the snapshot is or how an agent should detect an out-of-date list.

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

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

Three sentences, front-loaded with the core behavior, then the negative guarantee, then the alternative data source and sequencing advice. No filler; every sentence carries decision-relevant information.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the remaining ambiguity for a zero-required-parameter read tool — is it live data, is it network-bound, what do I do with the result — is fully resolved in the text.

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 chain_id parameter is fully documented in the schema, so the schema already carries the semantics. The description adds only the framing that the listed markets are 'supported by the preparation tools', which is a marginal addition over the parameter's own text. 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 concrete verb and resource — locally returns six major Aave V3 core deployments plus a bounded set of reserve/aToken/variable-debt-token addresses from a pinned address-book snapshot. It immediately distinguishes itself from discovery siblings (get_aerodrome_deployment, get_lido_deployment) by framing what is and is not covered, so an agent knows exactly what it gets without opening the schema.

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

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

Explicitly tells the agent when NOT to use this tool: live rates, caps, pause state, liquidity, collateral settings, eMode and account data must come from Aave's public GraphQL endpoint, which is named with a URL. It also gives a concrete sequencing instruction — intersect the API result with this fixed list before calling a preparation tool — routing the agent to the prepare_aave_v3_* siblings.

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

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

Annotations only declare readOnlyHint=true; the description adds genuinely new behavior: the data is resolved locally with no API or RPC round-trip, and it carries protocol behavior rules the agent must respect. It does not say what happens when chain_id points at a non-Base chain, but that is a minor gap against an otherwise informative disclosure.

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

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

Front-loaded with the verb and the returned contract list, then the two caveats in short sentences. The phrase 'plus the protocol behaviour an agent must respect' is slightly vague and could be sharper, but there is no filler overall.

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

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

For a single-optional-param read tool with an output schema, the definition covers contents, locality, and scope limits. The only unaddressed case is the outcome of a mismatched chain_id, which the agent would have to discover at call time.

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

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

Schema description coverage is 100% for the single optional chain_id, so the baseline is 3. The description reinforces the Base-only constraint ('Aerodrome is Base-only'), which hints at why chain_id exists, but adds no format or validation detail beyond the schema text.

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 ('Locally return Aerodrome's Base contracts') and then enumerates the exact contents (AERO, veAERO, Voter, Router, v2 factory, RewardsDistributor, Slipstream, Sugar lenses). The explicit 'Aerodrome is Base-only; Velodrome is not prepared here' line separates it from deployment lookups for other protocols.

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 operating context ('No API or RPC request', data derived on chain from the Voter) and an explicit exclusion (Velodrome is not covered), which tells an agent when this tool does not apply. It stops short of naming the sibling it complements — e.g., that it should precede prepare_aerodrome_* calls — so the routing to alternatives is left implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds genuinely new behavioral context: the data is served locally and no Lido API, RPC, or indexer request is made, which tells the agent the addresses are static/fixed rather than live-queried. It could go one step further by saying the values are mainnet-only and immutable, but the key behavioral trait is disclosed.

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

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

Two short sentences with zero filler: the first front-loads what is returned, the second immediately qualifies the network behavior. Nothing is repeated from the title or 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 enumerate return values, and with zero parameters there is no input surface to explain. The remaining gap is minor: it never states the deployment is fixed to Ethereum mainnet (only the title does) or that the addresses are stable over time.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter hints are present.

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 ("Locally return") and an exact resource set (canonical Ethereum stETH, wstETH, and WithdrawalQueueERC721 addresses), which separates it from the prepare_lido_* siblings that build transactions. It stops short of explicitly contrasting itself with the other deployment tools (get_aerodrome_deployment, get_sky_savings_deployment, get_uniswap_deployments), relying on the token names to do that work.

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

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

Usage is only implied: "plus direct wallet-read guidance" hints the tool is for resolving addresses before a manual wallet interaction, but there is no explicit statement of when to call this instead of prepare_lido_stake/wrap/withdrawal_request. No exclusions or prerequisites are given, so the agent must infer the call context.

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

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

Annotations only supply readOnlyHint=true; the description adds substantial context beyond that: APR is an annualized snapshot rather than guaranteed yield, its components/denominator/freshness/range must be surfaced, impermanent-loss risk matters, and a partial ranking is signalled by ranking_complete=false requiring a follow-up call. The two-pass protocol with local decoding is behavior an agent could not infer from the schema or annotations.

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

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

Three sentences, front-loaded with the return contract before the cautionary yield guidance and the retry protocol. Dense jargon ('boosted-fee', 've(3,3)') is unavoidable domain vocabulary, and every sentence carries a distinct instruction; slight compression could still improve it.

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

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

With an output schema present, annotations covering safety, and 83% schema coverage, the description fills the remaining gaps: precedence in the conversation flow, yield-caveat handling, and the partially-ranked retry path. What it leaves implicit is how chain/token/type filters interact with ranking or what a 'pool-discovery handoff' looks like, but that is modest given an output schema.

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 83% and the ve33_emission_state parameter is already fully documented in the schema, so the description adds little parameter-level meaning. It never explains how token, chain_id, types, min_apr or limit shape the ranking beyond the obvious. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a concrete verb and resource ('Return ... boosted-fee, incentive and projected ve(3,3)-emission opportunities ranked by APR') and enumerates the payload (actionable pools or pool-discovery handoffs, freshness, risk context). That is specific enough to separate it from lookup siblings like get_pool_liquidity or get_ve33_allocations, which return single-pool or allocation data rather than a ranked opportunity list.

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

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

Gives an explicit sequencing rule ('Call this before asking the user to choose a pair') and a concrete conditional loop: if ranking_complete=false, run local_read_requirement through the wallet, decode locally, and re-call with ve33_emission_state. It does not name competing siblings it should be preferred over, so it stops short of full when/when-not coverage.

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=true, so the description adds real value by specifying that everything is resolved locally and that 'No Merkl API, RPC, or indexer request' is made, plus that preparation scope is bounded by the verified chains. It does not discuss caching, staleness of the local catalog, or what happens for an unverified chain_id, 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?

One front-loaded sentence returns the resource first and the constraints afterward, with no filler. The phrase 'how Merkl's reward fields behave' is slightly abstract but is the only soft spot in an otherwise tight definition.

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?

Return values need no explanation since an output schema exists, and the readOnly annotation covers safety, so the description's remaining burden is scope and locality, both of which it addresses. Only the missing pointer to the reward-preparation tools it feeds leaves a small gap.

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

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

There is a single optional parameter and the schema already documents it at 100% coverage ('Optional chain to check against the verified Merkl Distributor catalog'). The description's mention of verified chains echoes rather than extends that, so no meaning is added 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 uses a specific verb ('Locally return') and names exactly what comes back: the Merkl Distributor address, the chains it is verified on, and how Merkl's reward fields behave. That is enough to tell it apart from sibling deployment tools such as get_aerodrome_deployment and get_lido_deployment, though it never explicitly contrasts itself with them.

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

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

'preparation is limited to those chains' implies this is a setup/verification step preceding Merkl reward preparation, but the description never names prepare_merkl_claim or any alternative, and never states when not to call it. The usage context is inferable rather than stated.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with an unambiguous statement that no API, RPC, indexer, or network request occurs. It goes further by telling the agent it must supply its own discovery from external sources, which is exactly the behavioral surprise an agent needs flagged.

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

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

Three sentences, front-loaded with the core fact (local, bounded, pinned catalog) followed by the no-network constraint and the agent's required follow-up work. Nothing is redundant, though 'official direct-discovery guidance' is somewhat vague phrasing that could be tightened.

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 a single optional filter and an output schema that already describes return values, the description covers the essential behavior: locality, no network access, and the required intersection step. It could say more about how extensive the fixed catalog is or what happens when a requested chain is absent, but the gaps are 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 coverage is 100% and the single chain_id parameter is fully documented there as an exact filter on the fixed catalog. The description mentions intersecting with 'fixed chain, vault, and asset addresses' but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a concrete verb-plus-resource: it returns a local, bounded, pinned catalog of listed Morpho Vault V2 deployments. The scope qualifiers ('bounded', 'pinned', 'listed', 'V2') separate it cleanly from sibling tools like prepare_morpho_vault_deposit and from a live-chain query tool.

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

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

The description gives a clear usage context: use this for the static catalog, then query Morpho's GraphQL API and onchain state yourself and intersect against the fixed addresses before preparation. It implies the pre-step role before the prepare_morpho_vault_* siblings without naming them explicitly, so the routing signal is strong but not fully explicit.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the important behavioral caveat that returned state is indexed (i.e., potentially stale) and prescribes a concrete follow-up path for fresh values. No auth, rate-limit, or failure-mode context is given, keeping it below 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?

Two sentences, both earning their place: the first states inputs and outputs, the second delivers the actionable caveat. The follow-up call guidance is front-loaded enough to be read before invoking.

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

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

An output schema exists, so return values need not be described, and the description covers the one thing the schema cannot: that the state is indexed and how to refresh it. What remains missing is how this differs from adjacent pool tools (list_pool_keys, get_pool_liquidity).

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 pool_id, chain_id and core_address all documented in the schema itself. The description only echoes the field names in prose and adds no format or constraint detail, 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?

Uses a specific verb ("Resolve") on a specific resource (chain/core/pool ID) and names the concrete outputs: verified PoolKey, decoded config, indexed pool state. This implicitly separates it from list_pool_keys and derive_pool_id, but no sibling is named explicitly, so an agent must infer the boundary.

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

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

Gives a clear conditional: use this for indexed state, and route to wallet_batch_eth_call with current_state_query.read_calls_reference when fresh sqrtRatio/tick/liquidity are required. It does not address alternatives like get_pool_liquidity or list_pool_keys, so the when-not guidance is partial rather than 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?

readOnlyHint already covers the safety profile, and the description adds genuinely non-obvious behavior: the response is per-tick net deltas, not cumulative liquidity, and must be accumulated in ascending tick order to reconstruct depth. That prevents a serious misinterpretation. It omits response size/pagination concerns, which matter for tick-level data on a large pool.

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

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

Two sentences, no filler, with the resource and scope front-loaded and the interpretation rule immediately after. Nothing is redundant with the structured fields in a wasteful way.

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

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

An output schema exists, so return-value documentation is not required, and the description still supplies the one interpretive fact an agent needs (deltas must be accumulated). Only response-volume/pagination guidance is missing, which is minor for a read-only tool whose schema is fully documented.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the three identifiers must designate exactly one pool and must be mutually consistent (chain/core/pool), which is a small addition over the per-field schema text, but it adds no format or validation 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?

Specific verb and resource: 'Return tick-level net liquidity deltas' scoped to 'one exact chain/core/pool ID.' It is clear this returns raw deltas rather than a computed depth figure. It does not name a sibling (e.g., get_uniswap_pool_ticks or get_pool) to disambiguate, so it falls short of a 5.

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

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

The description implies usage via the exact-match scoping ('one exact chain/core/pool ID') and via the instruction to accumulate deltas, which tells the agent what the output is good for. However, it never states when to prefer this over sibling readers like get_pool or get_uniswap_pool_ticks, and no exclusions or prerequisites are given.

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

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

Beyond the readOnlyHint annotation, the description discloses that the tool includes a pending current-state read and explains how to resolve it with wallet_batch_eth_call and state_call_id joining. It does not cover error behavior, prerequisites, or limits, but the operational follow-up detail is substantial.

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

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

The description is compact and front-loads the core action, with a necessary second sentence explaining the current_state_query handoff. The first sentence is dense with returned fields, which slightly reduces readability, but there is little unnecessary wording.

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 position-detail tool with an output schema and 100% input schema coverage, the description covers the key behavior and the non-obvious wallet_batch_eth_call follow-up. It is nearly complete, though it lacks explicit sibling routing and does not clarify whether current_state_query is always 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 description coverage is 100%, so all four required inputs are already documented in the schema. The description does not add syntax, constraints, or selection meaning for owner, chain_id, positions_address, or token_id beyond what the schema provides, 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?

The description states a specific verb and resource: hydrate one owner position, and enumerates the included data such as pool key, bounds, liquidity, metadata, history, rewards, and prices. It implicitly distinguishes single-position hydration from bulk lookup via 'one owner position', but it does not explicitly name distinguishing siblings like get_positions_by_owner.

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

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

The description gives procedural guidance for resolving current_state_query via wallet_batch_eth_call in the same code block, which is useful. However, it does not state when to choose this tool over get_positions_by_owner or get_position_pool_candidates, so alternatives remain implied rather than explicit.

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

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

readOnlyHint=true already covers the safety profile, so the description only needs to add context beyond that. It implies a filtering behavior by emphasizing 'verified PoolKeys' and 'indexed' pools, which usefully suggests unverified pools are excluded, but it says nothing about result ordering, limits, empty-result behavior, or whether the token order actually matters.

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

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

It is a single front-loaded sentence with no filler, but the long comma chain of return fields reads as a run-on inventory and could be tightened. The most decision-relevant information (token pair + indexed pools) does come first.

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 7-parameter discovery tool with an output schema, the definition is serviceable but spends most of its words describing return contents that the output schema already defines, while omitting the usage guidance and filter behavior an agent actually needs. It is adequate, not complete.

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 86% schema description coverage, the schema already explains most parameters, and min_tvl_usd even documents its default. The description's mentions of 'pool type', 'extension', and 'Core generation' loosely map to pool_type, extension, and core_address but add no semantics, and it never addresses the token_a/token_b order tolerance.

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 opens with a specific verb and resource ('List indexed pools for a token pair') and enumerates distinguishing content such as verified PoolKeys, Core generation, and the Positions/Ve33Positions manager. That is enough for an agent to tell it apart from a plain pool lookup, though it never names the siblings it replaces or complements (e.g., get_pool, list_pool_keys, discover_uniswap_pools).

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The only routing signal is the title's 'for an LP position', which implies this is a discovery step before prepare_lp_position_deposit, but the description itself never says so or states prerequisites such as whether a position must already exist.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the lower bar applies. The description adds genuinely useful behavior beyond that: results are indexed (potentially stale) and a companion fresh-read path exists via state_call_id / results[].id joining. It stops short of saying how fresh the index is or what an empty result means, so it lands at a 3 rather than higher.

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

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

Two tight sentences: the what-and-what-returns comes first, the fresh-state escape hatch second. Dense identifier notation but nothing is filler; the only cost is that the second sentence requires decoding for an agent unfamiliar with the join keys.

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

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

An output schema exists, so return values need not be spelled out, and safety is covered by annotations. However, for a tool with five parameters including state and chain filters, the description omits any guidance on filtering, pagination, or cross-chain behavior, which leaves a meaningful gap for correct invocation.

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

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

Schema description coverage is only 40% (owner is just "address", page/page_size/state/chain_id carry no descriptions), so the description needed to compensate and does not — no parameter is explained. The only identifiers discussed (read_calls_reference, state_call_id) belong to the response shape, not the input 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 ("Enumerate") and resource ("an owner's indexed Ekubo position NFTs") plus the payload contents (pool keys, bounds, liquidity, pool state, rewards), which clearly separates this list-by-owner tool from the single-position sibling get_position. It does not explicitly name a sibling to contrast against, keeping it just below a 5.

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

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

Gives an explicit conditional workflow: when fresh onchain state is needed, pass each current_state_reads[].read_calls_reference into wallet_batch_eth_call. That is real when-to-use guidance with a named alternative. It does not cover the state (opened/closed) filter or pagination choices, so exclusions are incomplete.

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=true, and the description adds substantial behavior beyond that: the safe workflow (quote → unchanged execution_plan_reference → wallet simulation → owner authorization), the retry prohibition ('never retry reverted bytes or widen protection'), and the distinction between unavailable_sources (provider failures) and execution_unavailable (plan failures). The attestation must stay client-side and not be sent to the API, which is a valuable non-obvious constraint. The remainder is policy prose rather than tool behavior, which keeps it from a 5.

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

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

A dense single block of roughly 250 words that front-loads legal disclaimers ('A quote, execution plan, simulation or wallet approval is not permission to trade') ahead of any operational content. The middle section on jurisdiction, Regulation S and attestation is long and could be compressed, and the actually usable quoting instructions are stranded near the end with no structure or separation.

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 12-parameter tool with an output schema, the definition covers the essential workflow, retry discipline, failure-field meanings, and cross-parameter constraints, so an agent can invoke it correctly. Gaps remain: it never defines the exact_input vs exact_output enum choice, and recipient/destination_chain_id behavior is left entirely to the schema.

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 92% schema coverage the baseline is 3, but the description genuinely adds cross-parameter semantics the schema cannot express: that slippage_bps and max_output_loss are mutually exclusive and both require sender, that they must all be omitted for indicative quotes, that max_output_loss is denominated in output-token base units, and that all/max swaps must use the wallet's exact balance. It also explains that execution.execution_plan_reference must be passed unchanged downstream.

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 tool's function is inferable from buried fragments ('Quote EVM swaps: Ekubo/0x same-chain; Across/LayerZero/LI.FI cross-chain', 'Omit all three for indicative quotes'), but the description opens with a compliance disclaimer rather than a statement of what the tool returns. It never says plainly 'returns a quote plus an optional execution plan,' and it does not distinguish itself from siblings such as quote_uniswap_liquidity or the prepare_* tools.

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

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

Explicit decision rules are supplied: omit sender/slippage_bps/max_output_loss for indicative quotes, supply sender plus exactly one protection for plans, and re-quote only after revert, expiry or a changed request. It also names the follow-on sibling ('Track LayerZero/LI.FI delivery with get_value_transfer_status') and states a hard when-not: 'If required facts or asset-policy coverage are unknown, do not proceed.'

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description is consistent with that ('Fetch'). It adds that the result includes per-chain isClaimed/isAvailable call data, but gives no detail on chain coverage, freshness/caching, or whether missing chains are omitted — modest value beyond the annotation.

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

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

One front-loaded sentence with the verb first and no filler or repetition. It loses a point only because the trailing 'eth_call list used by the interface' clause is more cryptic than the rest and could be expressed more plainly.

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

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

An output schema exists, so return values needn't be explained, and readOnlyHint covers the safety profile; for a one-parameter read this is close to sufficient. The remaining gap is that 'used by the interface' leaves mild ambiguity about whether the tool returns booleans or call payloads, though the output schema resolves it.

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

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

Schema coverage is 100% but the schema description for 'owner' is only the bare word 'address', so the description could have clarified whether this is the wallet whose claims are queried versus a contract owner. With a single fully-covered parameter the baseline of 3 applies, and the description neither harms nor meaningfully enriches it.

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 verb 'Fetch' and resource 'canonical reward-claim records' identify the operation, and the closing clause 'before preparing claim transactions' implies the boundary against the sibling prepare_rewards_claim. The second half ('supply the exact per-chain isClaimed/isAvailable eth_call list used by the interface') is jargon-dense and makes the precise output nature harder to grasp, so it stops short of a clean 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 phrase 'before preparing claim transactions' hints at sequencing and identifies the downstream step, which is useful implied guidance. However, it never explicitly names prepare_rewards_claim or prepare_merkl_claim as the alternative, nor states when this read should be skipped, leaving the agent to infer the 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 the read-only and closed-world annotations, it explains that the result is produced locally from fixed canonical deployment information. The explicit statement that no Sky service, RPC, indexer, or third-party API is proxied makes the lack of live retrieval or external dependency unusually clear.

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

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

Two compact sentences front-load the returned resource and then disclose the local, non-proxy behavior. Every phrase contributes scope or operational context, with no filler or repetition of the title.

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

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

For a zero-argument local read with an output schema, the description supplies the essential chain, assets, result type, and fixed-data behavior. Although explicit sibling alternatives could improve discovery, nothing important is missing for selecting and invoking this simple 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?

There are no parameters, so the empty schema already makes invocation straightforward and establishes the baseline score. The description usefully clarifies that callers cannot select another chain or asset set through this tool: its scope is fixed to Ethereum USDS and sUSDS.

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 uses a specific verb and scope: locally returning canonical Ethereum USDS and sUSDS addresses plus wallet-read guidance. The fixed, local deployment-metadata focus distinguishes it from the sibling Sky deposit, redeem, and withdraw preparation tools and from live data lookups.

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 clear context for choosing the tool when fixed deployment addresses or direct wallet-read guidance are needed, and explicitly rules out using the server as a Sky, RPC, indexer, or third-party API proxy. It does not name an alternative for live protocol state or transaction preparation, so the routing guidance is not fully explicit.

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

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

Annotations already declare readOnlyHint=true, but the description goes substantially beyond that: it discloses that no transaction is constructed, that the snapshot refreshes daily and snapshot_age_seconds should be read, that voter input changes target optimality, and that missing emission state flips execution_ready to false.

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 text is dense but front-loaded: recommendation shape and constraints come first, then the invocation workflow and next step. Every sentence carries operational information, though the jargon-heavy phrasing (provider-neutral, bps, Ve33) makes it slightly harder to scan than ideal.

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 that an output schema exists, the description needn't explain return fields, yet it still covers the key decision points an agent needs: snapshot freshness, execution_ready gating, what to read when emission state is missing, and the exact follow-up invocation. Nothing material for correct invocation is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: combining voter with ve33_emission_state produces voter-optimal targets while preserving a neutral plan in provider_targets, and omitting the emission state changes execution readiness and local read requirements.

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

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

States a specific verb and resource: returns a provider-neutral STONX allocation recommendation with an emissions_efficiency KPI per pool and an executable target list constrained to 10,000 bps and at most 25 Ve33 pools. That level of specificity clearly separates it from siblings like get_ve33_allocations and prepare_ve33_reallocation.

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 explains the two calling modes (with or without voter/ve33_emission_state) and the resulting output differences, including that execution_ready is false without the emission state. It also names the exact follow-up path: require execution_ready=true, then pass targets plus state_id from get_ve33_allocations and strategy=compact_max_lock to prepare_ve33_reallocation.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context beyond that. 'Canonical' is a genuinely useful disclosure that results are normalized/authoritative rather than raw, but nothing is said about behavior for unknown addresses or non-canonical tokens. An output schema exists, so return-shape detail is rightly omitted.

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

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

A single front-loaded sentence with zero filler, and the scope qualifier arrives before any implied detail. It is arguably too terse to route the agent against the many token-related siblings, but nothing in it is wasteful.

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

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

For a two-required-parameter read tool with full schema coverage, annotations, and an output schema, the definition covers what is needed to call it correctly. The only shortfall is the missing disambiguation from get_tokens and list_tokens in a crowded sibling set.

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 both chain_id and address are already documented, making 3 the baseline. The word 'exact' hints that matching is strict with no fuzzy/symbol resolution, but the description adds no format or type guidance 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 ('Fetch') and resource ('canonical token metadata') scoped to an exact chain and address, which implicitly separates it from the plural siblings get_tokens/list_tokens/export_tokens. It stops short of naming an alternative, so an agent must infer the singular-vs-list split.

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

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

The phrase 'for an exact chain and address' implies this is the single-token lookup path, giving implied usage context. There is no explicit when-to-use/when-not or named alternative such as get_tokens for batch or list_tokens for discovery.

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

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

readOnlyHint already declares this a safe read, so the description's job is to add context — and it does: it discloses the 1,000-identifier ceiling, guarantees output order matches input order, and states that unknown identifiers are silently omitted rather than causing an error. That omission behavior is exactly the kind of surprise an agent needs warned about; it only stops short of describing failure modes for malformed or cross-chain input.

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

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

A single front-loaded sentence with the batch cap and ordering guarantee stated before the edge-case omission rule. No preamble, no restatement of the tool name, nothing that could be cut without losing 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 needn't document return values, and annotations cover the safety profile; the remaining essentials — batch cap, ordering, omission semantics — are all covered. The one gap is sibling disambiguation against get_token and list_tokens, which an agent must resolve from tool names alone.

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 'tokens' parameter, so the baseline is 3, but the description earns extra credit by supplying a constraint absent from the schema — the 1,000-entry maximum (the schema sets only minItems: 1, no maxItems). It also reinforces cross-chain acceptance, consistent with the array-of-{chain_id, address} shape.

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

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

The description names a specific verb and resource ('Fetch canonical metadata for ... token identifiers') and qualifies it as a batch operation with a hard cap of 1,000. The word 'batch' implicitly separates it from the single-token sibling get_token, but no sibling is named explicitly, so differentiation requires 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?

Usage is implied rather than stated: the 1,000-item batch framing suggests this is for resolving many tokens at once, while get_token and list_tokens would be alternatives. There is no explicit 'use this instead of X when Y' routing, and no note on what to do when some identifiers resolve and others do not.

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

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

readOnlyHint already establishes that this is a safe read, but the description adds two pieces of genuinely behavioral context: the data mirrors the open source Uniswap interface's GraphQL fields, and an empty series signals missing indexed data rather than zero volume. It does not disclose timestamp bucketing granularity or rate limits, but it exceeds what the annotations alone 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?

Two sentences with no filler: the first front-loads what is returned and over what window, the second delivers the one caveat an agent needs. Nothing is repeated from the title or 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?

An output schema exists, so return-value shape need not be explained, and the empty-series caveat covers the main interpretation pitfall. However, for a tool with three required identifier parameters at 0% schema description coverage, omitting any explanation of chain/version/pool or of the duration enum's meaning leaves meaningful gaps.

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 0%, so the description needs to carry parameter meaning and it does not. Only 'duration' is referenced, and even there it does not clarify whether the enum selects a lookback window or a bucket size; chain_id, version, and pool semantics (especially the 40- vs 64-hex pattern) 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?

The description uses a specific verb and resource: 'Fetch timestamped token0/token1 prices and USD volume history over the requested duration.' This is clearly distinct from sibling pool-metadata reads such as get_uniswap_pool or get_uniswap_pool_ticks, although no sibling is named explicitly.

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

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

There is no statement of when an agent should choose this tool over alternatives (e.g., get_pool vs get_uniswap_pool_ticks vs quote_uniswap_liquidity), and no prerequisites or exclusions. The only guidance present concerns interpreting an empty result, not selecting the tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that these are 'canonical' addresses with named chain coverage, which is genuinely useful behavioral context, but it says nothing about whether results are static/cached or how missing chains are represented.

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

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

A single compact sentence-fragment that front-loads the resource and then enumerates chains, with no filler. It could be tightened into a full clause stating it returns addresses, but nothing is wasted.

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

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

For a zero-parameter, read-only lookup with an output schema already describing the return shape, the description covers what an agent needs: what contracts, which chains, which extras. A brief note on how to use the returned addresses (e.g. as the target for prepare_uniswap_* calls) is the only real gap.

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

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

The tool takes zero parameters, so per the baseline there is no parameter semantics for the description to carry and the schema has nothing to document. Nothing in the description misleads about inputs.

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

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

The description names the exact resource: canonical V2/V3/V4 contract addresses, plus Permit2 and wrapped native tokens, and enumerates the supported chains. It is a noun phrase with no verb, so the retrieval action comes from the tool name rather than the description, but the scope is specific enough to distinguish it from address-returning siblings like get_aerodrome_deployment.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites, and no routing hint toward the sibling deployment tools (get_aerodrome_deployment, get_lido_deployment, get_morpho_vaults) for other protocols. The agent must infer that this is the address-book lookup to consult before preparing Uniswap transactions.

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 only readOnlyHint=true supplied, the description still contributes the important behavioral fact that the data is indexed rather than live, which determines staleness and trust expectations. It also disambiguates the pool identifier format by version. It does not cover what happens when a pool is unknown or absent from the index, so it is not exhaustive.

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

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

Two sentences, the payload description first and the identifier rule and alternative second, with no filler. Every clause carries information an agent needs before calling.

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

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

An output schema exists, so return values need not be spelled out, and readOnlyHint covers the safety profile; the description fills the remaining gap on identifier format and data source. Only chain_id semantics and unknown-pool behavior are left unaddressed, which are minor for a three-required-parameter read tool.

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

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

Schema coverage is 0%, so the description has to carry the parameter semantics. It does the most valuable part by explaining that V4 requires a bytes32 pool ID while V2/V3 take an address, which disambiguates the regex. chain_id and version are only enum-constrained with no explanation of chain selection or what a version mismatch would mean.

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

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

The description gives a specific verb and resource ('Fetch indexed pool details') plus the concrete payload fields (currencies, fee, TVL, volume, supplies). It implicitly separates itself from live-state siblings via the word 'indexed', though it never names get_pool or get_uniswap_pool_ticks, which occupy adjacent territory.

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 a clear when-to-use/alternative split: use this for indexed pool details, and use prepare_uniswap_reads when current chain state is required. That is a real routing rule, not just implied context. It stops short of stating exclusions such as discovery or tick-level data, which the sibling list shows exist.

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, but the description adds real behavior: results are paginated via first/skip, values are returned as exact strings (relevant for precision-sensitive math), and 'Indexer data can lag' warns that results may be stale relative to on-chain state. No auth or rate-limit details, so not a 5.

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

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

Three short sentences with the core capability first, then pagination mechanics, then the staleness caveat. Every clause carries information an agent needs; nothing is padded.

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

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

An output schema exists, so return-shape explanation is correctly omitted, and the read-only safety profile is covered by annotations. For a paginated 5-parameter indexer read the description is nearly sufficient, missing only guidance on which pool identifier form applies to V4 and how pagination termination is detected.

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 0%, so the description must carry parameter meaning; it explains only that first/skip bound each request (pagination) and that version selects V3 vs V4. The three required parameters — pool, chain_id, version — get no semantic detail (e.g., that a V4 pool is a 32-byte pool id while V3 is a 20-byte address, or what the six chain_id values mean), leaving a real gap against 0% schema coverage.

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

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

States a specific verb and resource: 'Fetch paginated initialized ticks and exact liquidityNet/liquidityGross strings for V3/V4'. Naming the per-tick liquidity fields distinguishes it from indexer-level siblings such as get_pool_liquidity and get_uniswap_charts without the agent needing to open a schema.

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

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

Gives a concrete composition rule — 'combine with current pool liquidity and tick from prepare_uniswap_reads' — which tells the agent this tool is a building block for a depth chart rather than a standalone read. It stops short of naming alternatives (e.g., get_pool_liquidity) or saying when this tool is unnecessary, so no explicit exclusions.

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

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

Annotations supply only readOnlyHint=true, and the description is consistent with a read. Beyond that it discloses real behavioral traits: polling cadence, that each poll draws on the quote budget, that early UNKNOWN/NOT_FOUND is expected latency, and that LI.FI REFUNDED/PARTIAL surface as status DONE.

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 question ('has it been delivered'), then the polling protocol, then the edge-case interpretation, then scope exclusion. Every sentence carries operational information; nothing restates the name or title.

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

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

With an output schema present, return-value documentation is not required, so the description's job is timing and interpretation, which it covers well for both protocols. A minor gap is that 'settled' is referenced without explaining how to obtain it, though the output schema presumably carries that.

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 per-parameter meaning is already documented (quote_id required for layerzero, transaction_hash required for lifi, origin/destination chain for lifi only). The description mentions protocol-specific interpretation but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Report whether an executed LayerZero or LI.FI transfer has been delivered.' It distinguishes the tool from execution/quote siblings by noting the origin receipt is not proof of delivery, and explicitly excludes out-of-scope work with 'Across transfers are not tracked here.'

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

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

Clear context: call it after a transfer is executed, poll every 15-30 seconds while 'settled' is false, and interpret UNKNOWN/NOT_FOUND as not-yet-indexed rather than failure. It does not explicitly name the sibling tool that prepares or executes transfers, so the routing signal is contextual rather than nominal.

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=true, it discloses the non-obvious behavior that the returned onchain_validation is marked not_executed until the client performs its eth_call, and that deployment resolution is automatic from owner. That is genuinely useful context an agent could not infer from the annotation. It does not discuss pagination or size limits for large allocation sets.

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

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

Four sentences, front-loaded with the trigger phrase, then defaults, then return shape, then the alternate-deployment caveat. Nothing is redundant, though the long middle enumeration of return fields is denser than needed given an output schema exists.

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 correctly avoids over-explaining return structure while still flagging the not_executed validation caveat. Annotations cover safety and the schema covers params, so the remaining gaps (pagination, behavior for empty allocations) are minor for a read-only lookup 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 3 is the baseline, but the description adds deployment-resolution meaning: omitting chain_id/ve_token selects the production STONX chain and canonical VeToken, and the two must be supplied as a pair for other deployments. The canonical token identity is also spelled out. The addition is largely reinforcement of the schema text rather than new syntax detail.

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

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

The description gives a concrete verb and resource ('show all my Ekubo STONX allocations') and enumerates what comes back (pools, swap fee, NFT, vote weight, totals, state_id). It also pins the deployment identity (production Ekubo ve(3,3) = STONX voting system). It does not explicitly contrast with the closest siblings such as get_stonx_allocation_recommendation or get_positions_by_owner, so it stops short of full differentiation.

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 front-loads a usage pattern ('Use for requests such as ...') and gives a clear conditional rule: pass only owner for production, pass chain_id and ve_token together only for another deployment. The schema adds the 'ask the user when no wallet address is available' fallback. Missing is any explicit statement of when to prefer a sibling read tool instead.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: results are ordered by pool_id, pagination is keyset-based, and each row's indexed state is null until indexed. It does not discuss rate limits or error behavior, but for a read-only list tool this is solid added value.

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

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

Two dense sentences with the resource and scope front-loaded, then pagination and row semantics. Nothing is wasted, though 're-derived from its PoolKey' is jargon that adds length without much clarity for an unfamiliar agent.

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

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

An output schema exists, so return-value detail is unnecessary, and the description covers the two things the schema cannot: ordering/pagination strategy and the null-until-indexed state. For a 7-parameter read-only listing tool, this is close to complete, with only sibling routing left unaddressed.

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

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

Schema coverage is 100%, so all seven parameters are already documented, setting the baseline at 3. The description reinforces the filter modes (token, pair, extension) and the keyset cursor concept but adds little syntax or constraint 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?

States a specific verb+resource ('Discover initialized pools') scoped to one chain and Core deployment, which separates it from the single-pool sibling get_pool. It does not explicitly name any sibling (e.g. discover_uniswap_pools) as an alternative, so it falls short of a 5.

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

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

The description implies the use case is enumeration with optional narrowing by token, pair or extension, and explains keyset pagination via the previous page's cursor. It gives no explicit when-to-use/when-not guidance or routing against siblings such as get_pool or discover_uniswap_pools.

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=true, the description discloses the result ordering (visibility_priority), the default interface threshold of 0, and that negative min_visibility_priority reaches tokens the UI hides. That is meaningful behavioral context an agent cannot get from the annotations or schema alone.

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

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

Two sentences, front-loaded with the primary use case and followed by the refinement path. It is dense but every clause carries information; no filler or restatement of the title.

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

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

With an output schema present and 100% parameter coverage, the description only needs to supply purpose, ordering semantics, and hidden-token access, all of which it does. Only the absence of explicit sibling routing (get_token vs list_tokens) keeps it from a 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 coverage is 100%, so every parameter is already documented, including the subtle after_token caveat. The description adds rationale (ambiguity resolution driving ordering) but no syntax or format detail beyond the schema, which is the baseline-3 situation.

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 ('list canonical Ekubo tokens'), the ordering ('descending visibility_priority'), and the reason for that ordering ('so the preferred token wins an ambiguous symbol'). An agent can distinguish this from generic siblings like get_tokens or get_token purely from the text.

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 frames the tool as the 'first step for symbol-based swaps' and tells the agent how to widen the search (symbol prefix/suffix via search, hidden tokens via min_visibility_priority). It does not state when to prefer a sibling such as get_token for an exact known address, so it stops short of full when/when-not guidance.

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

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

readOnlyHint=true already declares the safety profile, and the description is consistent with it by framing the tool as preparation rather than execution. It adds genuinely useful context beyond the annotations: that no preflight validation of collateral, delegation, health factor, caps, or liquidity occurs, putting that burden on the caller. It does not say what the prepared output looks like or whether approvals must exist first.

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

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

Two sentences, zero filler, with the capability stated first and the limitation second. Every clause carries information an agent would otherwise have to guess.

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 all five parameters are documented. The remaining gap is that the description does not state prerequisites such as token approval or where the market/asset list comes from, but the core call semantics are complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'supported fixed reserve' constraint on asset and mentions on-behalf-of credit delegation, but adds no syntax or format detail beyond what each parameter's schema description already provides.

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

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

States a specific verb (prepare), a specific protocol action (Aave V3 variable-rate borrow), and the reserve constraint (supported fixed reserve). The optional on-behalf-of credit delegation is called out, which distinguishes it from the sibling prepare_aave_v3_supply/repay/withdraw tools.

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

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

The second sentence gives a clear negative scope: the tool does not check collateral, delegation, health factor, caps, or liquidity, which tells the agent this is a blind transaction builder rather than a validated one. It does not name a sibling or prerequisite tool (e.g. get_aave_v3_markets) to satisfy those checks, so it stops short of full 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, so the description's job is to add risk context, and it does: disabling collateral can lower health factor or revert when open debt depends on it, and simulation is required. It doesn't say what the preparation produces (a plan/simulation result versus signable calldata), though an output schema exists to cover that.

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

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

Two sentences, no filler, and the action is front-loaded ahead of the risk caveat. Every clause carries information an agent needs before calling.

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 four-parameter, fully documented tool with an output schema, the description covers purpose, risk, and a hard simulation prerequisite. Remaining gaps are minor: no explicit sibling routing and no mention of what the prepared artifact is used for next.

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 four parameters are already documented, including the 'fixed major-reserve list' constraint on asset and the boolean semantics of use_as_collateral. The description adds no format, default, or edge-case meaning beyond the schema, so baseline 3 applies.

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

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

The description names the exact contract method (setUserUseReserveAsCollateral) and the resource (a supported fixed reserve), which distinguishes it from sibling Aave prepare tools like prepare_aave_v3_supply or prepare_aave_v3_borrow. It stops short of explicitly contrasting those siblings, but the verb+resource pair is specific enough to route correctly.

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

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

Use is implied: toggle collateral on a reserve from the fixed major-reserve list. The description adds a real precondition ('exact wallet simulation is mandatory') but never states when to choose this over the other prepare_aave_v3_* tools or when not to attempt it (e.g., reserve unsupported, no position).

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=true; the description adds the crucial operational fact that the server performs no data or RPC request, so category IDs are caller-supplied and unverified against live chain state. That explains why the tool is read-only despite preparing a state-changing user action. It does not describe what the prepared payload looks like, though an output schema exists to cover that.

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

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

Two tight clauses with no filler, and the operative fact (caller supplies the category, server does no lookups) is front-loaded. The density makes it slightly hard to parse, but every phrase carries 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?

Annotations and a full-coverage schema plus an output schema cover most needs, and the description supplies the non-obvious constraint that live eMode configuration must be fetched elsewhere. What is missing is the downstream step: that the returned object is an unsigned transaction/calldata the caller must submit.

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 all three parameters are already documented in the schema, including the uint8 range, the zero-disables semantics, and the GraphQL sourcing of category IDs. The description restates the category_id constraints rather than adding meaning beyond them, 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 the exact contract method (setUserEMode) and the resource it acts on, which unambiguously separates it from the many sibling prepare_aave_v3_* tools (supply, borrow, repay, collateral, withdraw). An agent can identify the operation 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 the key semantic rule (zero disables eMode) and tells the caller how to obtain nonzero category IDs, namely from Aave's public GraphQL API. It stops short of naming sibling alternatives (e.g. get_aave_v3_markets for chain selection) or stating that the result must be signed and broadcast by the caller.

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 supply only readOnlyHint=true, so the description has to carry most of the behavioral burden, and it does add real context: underlying repayment bundles an exact ERC-20 approval plus cleanup into one atomic plan, which tells the agent about approval lifecycle side effects. It stops short of saying explicitly that the output is an unsigned plan rather than an executed transaction, or whether on_behalf_of requires authorization.

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

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

Two tight sentences with the resource and funding modes front-loaded, followed by the atomic-approval consequence and the max-amount convention. Nothing is wasted and there is no repetition of the title.

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

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

An output schema exists, so return values need not be described, and the six-parameter surface is fully documented in the schema. What is missing is small but real: the plan-vs-execution nature of a 'prepare' tool and the authorization expectations for on_behalf_of are left implicit.

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

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

Schema description coverage is 100%, so the schema already documents asset, amount, sender, chain_id, on_behalf_of, and funding_source, which sets the baseline at 3. The description reinforces the max-uint256 convention and the underlying/aToken distinction but adds no syntax, constraints, or format detail beyond what the schema fields already say.

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 (prepare) plus the exact resource (Aave V3 variable-debt repayment) and the two funding modes (underlying ERC-20 or sender-owned aTokens). This clearly separates it from siblings such as prepare_aave_v3_borrow, prepare_aave_v3_supply, and prepare_aave_v3_withdraw without opening any schema.

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

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

The description implies when each funding path applies (underlying vs aToken) and notes that uint256 maximum requests all available debt, which is genuine usage guidance. It never states prerequisites or exclusions relative to other prepare_* tools, so an agent must infer that a market must first come from get_aave_v3_markets and that this tool only builds a plan rather than executing it.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden and does add real value: it discloses the atomic multi-step composition (approve → supply → allowance cleanup) and, importantly, that no live on-chain state is read, warning the agent that validation is absent. It does not explicitly state that nothing is broadcast or how the returned plan is executed, leaving a small gap.

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

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

Two sentences, no filler: the first front-loads what the tool produces, the second front-loads the key limitation. The negation list of unqueried data sources is dense but each item is meaningful for the agent's expectations.

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, 100% parameter coverage, and a readOnly annotation, the description supplies enough for correct invocation. Minor residual gaps are what happens if the asset is outside the fixed reserve list and how the resulting plan is submitted, though these may be covered by the output schema or sibling tools.

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

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

Schema description coverage is 100%, so every parameter (asset, amount, sender, chain_id, on_behalf_of) is already documented in the schema, including the base-units constraint and the aToken recipient default. The description adds only the market-scoping notion of a 'fixed major-reserve list' and does not elaborate per-parameter semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Prepare a fixed-market Aave V3 Pool supply') and enumerates the three artifacts produced: an exact ERC-20 approval, supply calldata, and allowance cleanup bundled as one atomic wallet plan. This clearly distinguishes it from siblings such as prepare_aave_v3_borrow, prepare_aave_v3_repay, and prepare_aave_v3_withdraw.

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 'fixed-market' qualifier plus 'No live balance, allowance, reserve, cap, pause, or rate data is queried' gives the agent clear context that this is a purely constructive call for a market previously obtained from get_aave_v3_markets, and that no pre-flight validation happens here. It stops short of naming an explicit alternative or stating a when-not condition, so it lands at 4 rather than 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 only supply readOnlyHint=true, and the description adds genuine behavioral context beyond that: the action is validated by 'exact simulation' against balance, health-factor, collateral, and liquidity, so the agent knows the transaction can be rejected pre-flight. The 'direct Pool' framing also hints at the execution path. Remaining gaps (e.g., whether a failed simulation returns an error or a plan) are modest given the output schema.

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

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

Three short sentences, front-loaded on what the tool does, then the sentinel value, then the validation model. No filler; the only near-redundancy is the max-amount sentence, which repeats the schema but earns its place as a call-time reminder.

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 prepare-style tool with a true readOnlyHint and a full output schema, the description covers the essentials: reserve restriction, the max-balance sentinel, and the simulation-based validity checks. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents asset, amount, sender, chain_id, and recipient. The description's uint256-maximum sentinel meaningfully restates the 'amount' semantics but adds nothing the schema does not already say, 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 ('Prepare a direct Aave V3 Pool withdrawal') plus scope ('for a supported fixed reserve'), which separates it from prepare_aave_v3_supply/borrow/repay by resource alone. It stops short of naming any sibling or contrasting 'direct Pool' with alternative withdrawal routes, so it is clear but not fully differentiated.

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: you call it when you want to exit an Aave V3 position on a fixed reserve, and the 'supported fixed reserve' phrase flags a prerequisite. There is no explicit when-not guidance, no pointer to get_aave_v3_markets or the market-selection flow, and no mention of how this relates to other prepare_* exit paths.

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=true; the description adds substantive behavior beyond that – the payout address comes from the account argument rather than the sender, and the plan states which, plus the notable edge case that a zero-earned claim succeeds and transfers nothing. It omits gas/approval or execution-flow context, which is reasonable given the plan-producing nature of the tool.

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

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

Three short sentences, front-loaded with the action, then the sharpest gotcha (account vs sender), then the empty-claim edge case. 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?

Output schema exists, so the plan contents need not be described. The description covers the two non-obvious behaviors an agent could get wrong (payout address and the no-op-with-success case), which is sufficient for a four-parameter prepare tool restricted to a single chain.

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 account parameter already documents the getReward crediting behavior, so the description mostly restates the schema. Its only additional contribution is that 'the plan states which' address is paid, which reframes rather than expands parameter meaning; 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: 'Claim accrued AERO from a gauge,' which is concrete enough for an agent to act on. It does not explicitly distinguish itself from the several claim-shaped siblings (prepare_aerodrome_incentive_claim, prepare_rewards_claim, prepare_merkl_claim), leaving the AERO-from-gauge scope as the only differentiator.

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 by 'claim accrued AERO from a gauge' – you use it when emissions have accrued to a gauge position. There is no explicit when-to-use, no prerequisites (e.g. approvals, veAERO requirements), and no routing to alternative claim tools, so the agent must infer selection.

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

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

Annotations only supply readOnlyHint=true, so the description should carry the behavioral burden, and it does: it discloses the approval and allowance-cleanup steps, the two-phase call requirement, the fee-redirect economic tradeoff (trading fee income for emissions), and the dead-gauge failure mode that silently pays nothing. It also consistently frames output as a 'plan' rather than an on-chain execution, which aligns with the read-only annotation.

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

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

Purpose and the phased-call mechanic are front-loaded, and every sentence (phasing, fee redirect, dead gauge, amount sizing) carries actionable information. It is dense and clause-heavy, but no sentence is filler.

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

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

With an output schema and full parameter documentation already present, the description covers the remaining gaps an agent needs: the two-phase invocation, pre-flight gauge liveness check, input sizing source, and the economic consequence of staking. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains why lp_token exists as an optional phase selector and warns that amount must be sized from the live LP balance rather than a stale simulation. It does not add anything for gauge, sender, or chain_id beyond what the schema already 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 and resource (stake v2 LP tokens into a pool's gauge) plus the yield intent (AERO emissions) and the two side effects bundled in (LP-token approval, allowance cleanup). This clearly separates it from siblings such as prepare_aerodrome_gauge_withdraw, prepare_aerodrome_gauge_claim, and prepare_aerodrome_liquidity_deposit.

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 procedural guidance: call once without lp_token to read the gauge's stakingToken, then call again with the resolved address for the full plan. It also gives a negative rule for sizing (use live LP balance, not a prior deposit simulation two-phase. It never names a sibling alternative for when not to use this tool (e.g. deposit into the pool rather than stake), so it stops short of full when/when-not coverage.

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?

The readOnlyHint annotation is present, so the bar is lower, and the description still adds substantive context beyond it: what the caller receives (LP token, not the underlying pair), what is deliberately not performed (AERO claiming), and that remaining earnings are surfaced by a read bundle so they are not abandoned. The one thing left unsaid is that this only prepares a transaction rather than broadcasting it, which is the fact that would fully reconcile the mutation-sounding verb with readOnlyHint.

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

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

Two sentences, front-loaded with the action and immediately followed by the two most consequential caveats (LP token not pair, no AERO claim). The final clause is dense with internal jargon ("read bundle") but still earns its place by explaining why rewards are not silently lost.

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

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

With an output schema present and full schema coverage, the description only needs to cover action semantics and gotchas, and it does: token type returned, reward non-claiming, and residual earnings visibility. What is missing is the prepare-versus-execute distinction and any approval prerequisite, both relevant given the readOnlyHint annotation.

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 four parameters are documented in the schema, so the baseline is 3; the description's mention of unstaking LP tokens from a gauge reinforces the semantics of the gauge and amount fields rather than duplicating them. It adds no new syntax or constraints, so it sits at the schema-driven baseline rather than above it.

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 ("Unstake v2 LP tokens from a gauge") and immediately scopes the result ("returns the LP token, not the underlying pair"), which separates it from the liquidity-withdraw sibling. It also carves out the reward side by noting it "does not claim AERO", implicitly distinguishing it from prepare_aerodrome_gauge_claim, though no sibling is named directly.

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

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

Usage is implied rather than stated: the note that it does not claim AERO hints that a separate claim step exists, and the note that rewards are still reported hints at a follow-up action. There is no explicit when-to-use versus prepare_aerodrome_liquidity_withdraw or prepare_aerodrome_gauge_claim, and no stated prerequisites such as approvals or existing deposits.

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 only readOnlyHint=true supplied, the description adds real behavioral context: the output is a single combined plan, addresses are non-derivable external inputs, and a wrong address fails silently ('claims nothing rather than failing loudly') — a meaningful hazard worth surfacing. It does not discuss how the plan is returned or sequenced, but the output schema can carry that.

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

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

Three sentences, front-loaded with what the tool does before the input rationale and the sibling contrast. The middle sentence is dense and slightly run-on, but no sentence is filler and nothing is repeated from 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?

Covers the parts an agent could plausibly get wrong — sourcing the contract addresses and choosing between voter-reward and gauge-emission claims — while the output schema and field descriptions handle chain restriction, token lists, and return shape. Complete for a plan-preparation tool of this size.

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 goes beyond it by explaining why `fees`/`bribes` are mandatory (per-pool contracts obtainable only from a Sugar rewards read) and by framing `claim_rebase` as an optional compounding add-on. That rationale is not present in the schema text.

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 — claiming a veNFT's voting rewards (fees, bribes, or both, plus optional rebase) as a single plan — and explicitly separates itself from prepare_aerodrome_gauge_claim by contrasting voter rewards with LP emissions. An agent can place this tool without opening a schema.

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

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

Gives an explicit alternative (prepare_aerodrome_gauge_claim) and the condition that selects it, plus the prerequisite that fee/bribe contract addresses must come from a Sugar rewards read. It stops short of routing the agent to the specific Sugar read tool (prepare_aerodrome_sugar_reads) or addressing other claim-style siblings such as prepare_ve33_claim_fees.

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 supply readOnlyHint=true, so the description carries the rest: it discloses that the emitted plan bundles approvals and allowance cleanup, that a quote bundle resolves the pool and computes the actual split, and that a missing pool is caught before pricing. That is meaningful behavior beyond the annotation and is consistent with a read-only planner that returns unsigned transactions, though the description never says explicitly that nothing is broadcast.

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

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

Two front-loaded sentences with no filler; the primary action comes first and the caveats follow. The second sentence is slightly compressed ('catches a pair with no pool before a deposit sets its price'), which costs a little readability but not correctness.

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 an 11-parameter preparation tool with an output schema and full parameter documentation, the description covers the important non-schema facts: approval handling, pre-flight pool validation, and the downstream staking requirement. Only the absence of an explicit 'returns a plan, does not execute' statement leaves a small gap.

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

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

Schema description coverage is 100% and every parameter including deadline, min/max amounts and stable-vs-volatile is documented there, so the baseline is 3. The description's mention of the split quote and pool resolution echoes rather than extends the schema's 'with the pair it identifies the pool' note.

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

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

The description gives a specific verb-plus-resource: it prepares a v2 addLiquidity call routed through Aerodrome's Router, and it states the scope of the artifact (exact approvals plus allowance cleanup). Against siblings such as prepare_aerodrome_liquidity_withdraw or prepare_uniswap_v2_add_liquidity, the chain/protocol is unambiguous 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 routes the agent to a named follow-up (stake LP with prepare_aerodrome_gauge_deposit to earn AERO) and explains when the tool is safe to call (the read bundle resolves the pool first). It does not explicitly exclude or compare against adjacent tools like prepare_lp_position_deposit, but the operational context is clear.

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

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

Beyond the readOnlyHint annotation (consistent, since the tool only builds a plan and never broadcasts), the description discloses the approval step, the post-approval allowance cleanup, and the two-phase address resolution. It also explains how to interpret a liquidity shortfall as gauge-staked tokens.

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

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

It is front-loaded with the action and follows with phasing rationale and the shortfall tip, so every sentence earns its place. The sentences are dense and slightly run-on, but nothing is redundant.

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

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

With an output schema, full schema coverage, and a readOnly annotation, the description fills the remaining gaps: coordinate phasing, approval/cleanup behavior, and the common staked-liquidity failure mode. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented; the description nonetheless adds meaning about the lp_token two-phase flow and frames liquidity against the actual LP balance, helping the agent reason about the value rather than just the format.

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 and resource: 'Prepare a v2 removeLiquidity that burns LP tokens back into the underlying pair,' and it adds the LP-token approval and allowance cleanup the plan includes. This distinguishes it from the deposit and gauge siblings, which do not burn LP tokens into the pair.

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 phasing: call without lp_token to get the pool read, then again with the resolved address for the full plan. It also provides a diagnostic that a short LP balance usually means the rest is staked in the gauge and needs unstaking first, pointing the agent to the gauge-unstake path.

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=true, the description discloses non-obvious behavior: durations are measured from now and floored to a week boundary, sub-week requests are refused rather than signed, and a read bundle is fetched to reject impossible actions before signing. That 'builds but never signs or submits' framing is exactly the context an agent needs, though it says nothing about what the returned action contains or whether it must be re-validated.

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

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

Two sentences, both front-loaded with the most important information (what it builds, then the duration and validation rules). Dense but no filler; the middle clause listing action types is slightly redundant with the enum but earns its place as a quick scan.

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

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

An output schema exists so return values needn't be explained. Given six parameters with an enum and only a readOnlyHint annotation, the description supplies the missing behavioral layer — duration rounding, refusal instead of signing, and pre-signing state checks — leaving nothing important unsaid 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 every parameter already carries its own description including the week-floor and four-year cap. The description restates those rules and clarifies which actions are relevant per field only implicitly; it adds little machine-relevant meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Build one veAERO escrow action') and then enumerates every operation the tool covers: create, increase, extend, toggle permanent, withdraw. That enumeration matches the action enum and lets an agent distinguish this from the many sibling prepare_* tools without opening the schema.

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

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

Usage is implied through the action list and the statement that impossible actions are caught before signing, which tells the agent this is a build-and-validate step. However, it never names alternatives — notably prepare_ve33_extend, prepare_ve33_withdraw, prepare_ve33_stake and prepare_aerodrome_sugar_reads sit adjacent and an agent gets no explicit rule for choosing between them.

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=true, and the description adds real context beyond that: it produces a bundle plus decode plan rather than results, execution happens on the user's RPC, and Sugar has no API. It does not discuss failure modes (unsupported chain, missing conditional params) or how large bundles behave, so it is informative but not exhaustive.

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

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

Two dense sentences with zero filler; the core action is front-loaded and the second sentence carries the downstream chaining fact that an agent most needs. Nothing is repeated from the schema or annotations.

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

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

With an output schema present and readOnlyHint covering safety, the description supplies what structured fields cannot: the two-step flow (build here, execute on the user's RPC) and how outputs feed sibling prepare tools. Minor gap: it does not mention chain support limits beyond what the chain_id schema note says, nor what an agent should do if a required conditional parameter is absent.

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

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

Schema description coverage is 86%, and the schema already states the conditional requirements (pool for pool_epochs/venft_pool_rewards, account for positions/venfts_by_account, venft_id for the three venft datasets) and the 500/200 limits. The description adds only the framing that the dataset choice selects which call bundle is built, and that returned addresses and veNFT ids become inputs elsewhere — useful but not per-parameter 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 uses a specific verb ('Build the eth_call bundle and decode plan') on a specific resource (one Sugar dataset) and enumerates the datasets supported. It also distinguishes itself from the other prepare_aerodrome_* tools by explaining that its outputs are their inputs, so an agent can place 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?

It makes clear the tool does not fetch data itself: the bundle is 'for the wallet to run against the user's RPC' and 'Sugar has no API', which tells an agent this is the read path for Aerodrome Sugar data. It stops short of naming explicit exclusions or contrasting with near neighbors such as decode_pool_config or get_ve33_allocations.

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?

The description carries real behavioral payload beyond readOnlyHint: weights are ratio-based, the allocation fully replaces the prior vote, a second vote in the same epoch reverts, and voting locks the NFT against withdrawal until reset. However, readOnlyHint=true is never reconciled with the imperative 'Cast one veNFT's gauge vote', which reads as a state-changing broadcast; it never says the tool only builds an unsigned transaction for later submission. This is a notable ambiguity for a tool with a single, minimal annotation.

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

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

Four tight sentences, front-loaded with the action and mode, then the weight semantics, then the epoch revert, then the lock side effect. No filler and no repetition of the tool name or title.

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

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

With an output schema present and full schema coverage, the description need not explain return values, and it supplies the epoch and lock constraints that no structured field carries. The one remaining hole is the prepare-vs-execute distinction, which matters for an agent chaining this into a signing flow.

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 every semantic point in the description — relative weights, full replacement, omitted pools voting zero, reset required before withdrawal — is already written into the corresponding schema property descriptions. The prose adds emphasis but no new parameter meaning, so it sits below the baseline rather than at it.

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 names the exact resource and scope: one veNFT's gauge vote, with the reset variant called out. The reader immediately knows the unit of operation (a single veNFT) and the two modes, so it is distinguishable from neighboring prepare_* tools even without opening the schema.

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

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

It states the operative constraints that drive usage: one vote per weekly epoch, a revert on a second attempt, and that the read bundle surfaces lastVoted plus gauge liveness so the caller can check preconditions first. What it lacks is an explicit pointer to the sibling to call for those reads or to prepare_ve33_vote for the Velodrome equivalent, so alternatives are only implied.

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

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

With readOnlyHint=true already supplied, the description still adds real behavioural content: the plan is ordered and exact, and the caller must not discover or re-derive the transaction list. Those are genuine planning contracts beyond the annotations. It stops short of stating that no signing or broadcasting occurs, or how gas/nonce are handled, which would have made it 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?

Two short sentences, both front-loaded with the essential facts: what is produced and how the caller must treat it. There is no filler or restatement of the title.

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

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

An output schema exists, so return-value detail is not required, and the description covers the plan-building contract and ordering constraint adequately for a three-parameter tool. The remaining gap is edge-case behaviour (mixing multiple chains or tokens, or what happens when a revocation is already in place), which is minor but not covered anywhere else.

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