Aave

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

Discloses that the gasless route is state-changing, the on-chain route returns a transaction for the user to sign, and 'the server never signs.' This meaningfully supplements the annotations, which only indicate readOnly=false and idempotentHint=true.

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 dense and slightly long but every sentence carries meaning. It front-loads the core purpose and then efficiently explains the two routes and the server's non-signing behavior.

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

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

Given the tool's moderate complexity, the description fully covers how to choose between the two invocation routes, what the signature parameter is for, and what the server will or will not do. The absence of an output schema is offset by this clear behavioral explanation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics by explaining that the signature must be over prepare_cancel_order's typed data and that omitting the argument entirely triggers the on-chain route, going beyond the schema's brief description.

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

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

Clearly states the tool cancels an open order and distinguishes two distinct routes: gasless cancellation via signature and on-chain transaction generation by omitting signature. This differentiates it from siblings like prepare_cancel_order and submit_signed_order.

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 when to pass 'signature' (intent orders, gasless route) versus when to omit it (orders that went on-chain, native-token sells). It also references prepare_cancel_order as the prerequisite for obtaining the signature, giving clear route-selection 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?

The readOnlyHint annotation is consistent with the described read-only purpose. The description adds substantial behavioral context beyond annotations: it applies to both protocol versions, explains that 'lookingFor' returns the full capability list, and notes that gaps are recorded when a capability does not exist.

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 slightly long but every sentence contributes value: scope, purpose, usage timing, topic list, fallback behavior, and external docs. Information is front-loaded with the core purpose before the topic enumeration.

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

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

Given the simple two-parameter schema, the strong readOnlyHint annotation, and the absence of an output schema, the description is complete enough for an agent to use the tool correctly. It explains the fallback 'lookingFor' behavior, the topic list, and external documentation routing without leaving critical 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 100%, so the baseline is 3. The description adds some usage context for both parameters, especially the 'lookingFor' fallback behavior, but it largely reinforces what the schema already documents rather than adding meaningfully new 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?

The description clearly states a specific purpose: providing protocol and usage guidance for building Aave flows correctly. It distinguishes itself from data-fetching sibling tools by explicitly positioning itself as the place to go when no tool seems to fit the request.

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 explicit usage direction: read the relevant topic before constructing an action, use the 'lookingFor' argument when no other tool fits, and redirect users to external docs for deep protocol documentation. This clearly tells the agent when and how to select this tool versus alternatives.

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

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

Beyond the readOnlyHint annotation, the description discloses return shape, units ('apyPct is a percent'), averaging behavior, sampling-interval widening, and the caveat that the series is not comparable to instantaneous rates. This gives the agent a clear mental model of what the data means and how it behaves.

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 dense but every sentence earns its place: purpose, return format, sampling semantics, prerequisite, and a practical comparison use case. It is front-loaded with the core definition and avoids filler 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 no output schema, the description covers the return format and units. It explains version-specific parameter sourcing, the sampling behavior, and the relationship to get_reserve_details. Combined with the 100%-covered input schema, an agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to obtain parameter values ('Use get_markets first for the reserveId (v4) or market+token (v3)') and by tying the window parameter to sampling intervals. It doesn't describe every parameter, but the schema already covers those details.

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

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

The description opens with a specific verb and resource: 'Historical supply or borrow APY for a reserve over time, on v3 or v4.' It clearly identifies what data is returned, distinguishes itself from get_reserve_details by contrasting historical averages with instantaneous rates, and is unambiguous about scope (supply/borrow, reserve, v3/v4).

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 explicitly tells the agent when to use this tool vs alternatives: 'so a series is not directly comparable to the instantaneous rate from get_reserve_details' names the alternative and the exclusion. It also gives prerequisite usage ('Use get_markets first') and a concrete decision scenario ('When comparing v3 against v4 for the same asset... read the history on both sides').

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 exposes a subtle and important behavior: chains with 'notServed': true will return empty data and zero addresses, and the agent is explicitly warned not to send transactions to those gateway addresses. This prevents misinterpretation of empty results and provides actionable safety guidance.

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 yet information-dense. The purpose is front-loaded in the first sentence, and each subsequent sentence explains the crucial 'notServed' behavior and its transaction-safety implication. No sentence 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 simple tool with one optional parameter and no output schema, the description fully covers what the tool returns, how to interpret the notServed flag, and what action to avoid. There are no major gaps that would prevent an agent from calling this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'v3, v4, or both,' which aligns with the version enum, but it does not add meaning beyond what the schema already provides. No extra parameter guidance is necessary because the single optional parameter is fully self-documenting.

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 chains Aave supports' and immediately scopes it by version ('v3, v4, or both'). This clearly distinguishes it from sibling tools like get_markets or get_hubs, which concern different resources.

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 first sentence tells the agent exactly when to use the tool: when the supported chains for Aave are needed. It does not explicitly name alternative tools or exclusions, but the resource scope is clear enough that an agent is unlikely to confuse it with the related get_hubs or get_markets tools.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: v3-only availability, omission of markets with no matching category, the categoryId/LTV/liquidation threshold return contents, and the broad unfiltered response across every chain. This gives the agent a realistic expectation of scope and output without relying solely on 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?

The description is slightly longer than average, but the front-loaded 'v3 only' scoping and the eMode explanation earn their place. The sentences flow from definition to output to filtering behavior, with no redundant restatement 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?

There is no output schema, so the description compensates by listing the key returned fields (categoryId, LTV, liquidation thresholds, symbols) and explaining what happens when no category matches. It is sufficient for an agent to call the tool correctly, though a precise response shape or chain-grouping structure would make it fully 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?

The schema already documents both parameters fully, so the baseline is satisfied. The description adds extra meaning by explaining filtering behavior, such as how omitting chainId covers all chains, how symbols narrow the result, and that markets without a matching category are excluded.

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 action and resource: it returns each market's eMode categories, including the categoryId consumed by prepare_set_emode, LTV and liquidation thresholds, and member symbols. It clearly scopes the tool to v3 only and explains the relationship to eMode, making it easy to distinguish from the large sibling 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?

It gives clear usage context: v3 only, v4 has no eMode, and filtering by symbols is recommended when the asset is known. It does not name an alternative tool to use instead, but the v4 exclusion and filtering guidance are enough for an agent to decide when this tool is appropriate.

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, and the description adds useful context beyond it: 'quorumMet' and 'differentialMet' as the two pass conditions, vote tallies and quorum both being in AAVE so they compare directly, and the IPFS write-up being omitted unless includeDescription is true. It does not disclose failure behavior for nonexistent proposal IDs or live IPFS fetch characteristics, but for a read-only getter these are minor.

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 most likely error source (the version confusion) before the purpose statement. Nearly every sentence earns its place, but the final IPFS sentence substantially repeats what the includeDescription schema description already states, so it is not perfectly lean.

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

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

With no output schema, the description carries the return-value burden and meets it: content fields, the two pass conditions, unit consistency, and the optional-description default are all stated. For a low-complexity read-only fetch with two fully documented parameters, nothing an agent needs to call it correctly or interpret the results is missing.

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

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

Schema coverage is 100% and both parameters are already well documented (decimal-string format with an example and provenance for proposalId; default and size caveat for includeDescription), so the baseline is 3. The description adds genuine value by warning there is no version parameter, preventing an agent from expecting market-scoped parameters, though it adds no new syntax or format details.

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

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

States a specific verb and resource — 'Full detail for one Aave DAO governance proposal' — and enumerates returned fields (state, author, vote tallies, quorum, timings, lifecycle tx hashes). The 'Takes no version argument' note distinguishes it from per-market siblings, and the single-item scope distinguishes it from search_governance_proposals, so an agent can identify it without opening the schema.

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

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

Provides clear context: the version-argument warning prevents a realistic misuse (treating DAO governance as per-market), and the schema ties proposalId provenance to search_governance_proposals, implying the search-then-detail workflow. However, it never names alternatives like get_proposal_votes or get_proposal_payloads, so routing among the governance family is largely left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description adds useful behavioral context: the tool is v4-scoped, returns hub-level accounting rather than user positions, and exposes specific aggregate fields. It does not contradict the annotation and provides meaningful operational semantics beyond the structured hint.

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 deliver the core scope, parameter provenance, and the key alternative tool without repetition or filler. The most important constraint ('v4 only') is front-loaded, and every sentence earns its place.

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

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

With only one required parameter, a fully covered schema, and no output schema, the description still explains what the tool returns at a high level and how to get the required identifier. The read-only safety profile is covered by annotations, and the description clarifies the hub-vs-market distinction, making it complete enough to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value by telling the agent where to obtain hubId (from get_hubs or the hubAddress on get_reserve_details), which is not in the schema. The version parameter is already fully explained by the schema enum and description.

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

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

The description names a specific verb ('Get') and resource ('assets held by one Aave v4 hub'), and further specifies the output includes supplied/borrowed totals, rates, and utilisation. It clearly distinguishes this from user-level get_markets, so an agent can tell them apart.

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

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

It explicitly states the tool is 'v4 only', gives the exact source for the required hubId ('get_hubs' or 'hubAddress on get_reserve_details'), and says to use get_markets instead when the concern is what a user can supply or borrow. This is explicit when-to-use and when-not-to-use guidance.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful context beyond the annotation by explaining the hub/spoke model, the returned fields, and the v4-only restriction. It does not introduce contradictions or hidden side effects.

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

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

Three tight sentences with no filler. The v4-only scope is front-loaded, the return contents are stated, and the sibling tool pointer is given in one clause. Every sentence 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 read-only list tool with zero required parameters, this description is complete. It tells the agent what the tool returns, how to scope by chain, that it is v4-only, and where to go for per-hub assets. The absence of an output schema is compensated by the explicit field list.

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

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

Schema description coverage is 100%, so the schema already documents both chainId and version. The description reinforces 'v4 only' and the 'omit chainId' behavior, but it mostly repeats the schema's own guidance rather than adding substantial new meaning.

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

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

States a specific verb and resource: 'Returns each hub's hubId, address, chain and totals.' It goes beyond a restatement of the tool name and explains what an Aave v4 hub is. It also distinguishes itself from the sibling get_hub_assets by pointing the agent to that tool for assets.

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

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

Explicitly routes to an alternative: 'Pass a hubId to get_hub_assets for the assets it carries.' Also gives clear call guidance with 'Omit chainId to cover every supported v4 chain,' and scopes the tool with 'v4 only.' The description tells the agent when to use this tool versus the closest sibling.

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 already set, the description goes well beyond annotations: it explains chainsCovered, chainsNotCovered, chainsNotServed, why an empty result on an unsupported chain is not an answer, that cap/frozen/paused flags appear only when set, and that repeated identical v4 APYs across spokes are expected. This is substantial behavioral disclosure.

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

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

The description is long but every sentence earns its place by covering a distinct behavioral nuance. It is front-loaded with a clear purpose and then systematically explains chain coverage, flags, version differences, and response shape without redundancy.

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

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

Given the complexity of version differences, chain coverage, per-spoke rows, and conditional flags, this description is remarkably complete. With no output schema, it still tells the agent that both versions return one row per reserve with supplyApyPct and borrowApyPct together plus canSupply/canBorrow, closing the most important understanding 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?

Input schema coverage is 100%, but the description adds meaning the schema cannot convey: 'v3 covers every chain when you pass symbols and Ethereum alone when you do not', 'pass symbols and no chainId' to compare one asset across chains, and the relationship between canSwapFrom and get_swappable_tokens. This is far beyond the baseline schema repetition.

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 'List Aave markets/reserves (symbol, APY, caps, liquidity) on v3, v4, or both', giving a specific verb, resource, and scope. It also differentiates itself from get_swappable_tokens by explaining that canSwapFrom is the per-reserve form of that tool's per-chain answer.

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 explicit guidance on when to pass symbols and no chainId, explains the trade-offs of unfiltered queries, and warns against ranking on APY alone. It also names a sibling tool as the alternative for per-chain swappable-token answers, providing clear routing 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?

The description goes well beyond the readOnlyHint annotation by explaining the ambiguous null behavior: both an invalid id and a just-submitted order produce null, and the agent should poll briefly before concluding. It also discloses the output contents (status, operation, explorer link), making the tool's behavior highly transparent.

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 carry a dense but well-organized amount of information: status enum, return contents, null semantics, and polling advice. There is no filler, no repetition of the schema, and the most important scoping note ('No version argument') is front-loaded.

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 read-only tool with no output schema, the description is complete. It covers what the tool returns, the possible status values, and the meaningful edge case around null results. An agent has enough context to call the tool correctly.

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

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

The input schema already fully documents orderId as 'The order id' with 100% coverage, so the description does not need to add much. It reinforces that the lookup is by id and clarifies what a null order value means, but this is supplemental rather than essential. 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: retrieving the status of an order by id. It enumerates the exact possible statuses (open, pending signature, fulfilled, cancelled, expired) and notes that it returns the operation and an explorer link, which clearly distinguishes it from list-style or mutation siblings.

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

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

The description makes the usage context clear: call this tool when you need the status of a specific order by id. It also gives polling guidance for null results. It does not explicitly contrast itself with get_pending_orders or other siblings, but the purpose is specific enough that an agent can infer the right choice.

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 signal read-only; the description adds substantial behavior beyond that: v4 backend chain coverage, chainsCovered/chainsNotCovered fields, newest-first ordering, status filtering semantics, 50-order per-chain cap, and more:true pagination signal. This is exactly the contextual detail an agent needs without an 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?

Four sentences with no filler; every sentence covers a distinct useful point (backend coverage, ordering, status semantics, pagination, use case). The main caveat is front-loaded before the details, and the recovery use case closes it cleanly.

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

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

With no output schema, the description explains the key response concepts (chainsCovered, chainsNotCovered, more) and scoping behavior, leaving only parameter mechanics already documented in the schema. The tool is complete enough for an agent to call it and interpret the result.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds value by prescribing the statuses array ['open','pending_signature'] for actionable orders and explaining that omitting chainIds sweeps the served chains through back-end coverage language. This supplements the schema descriptions rather than repeating them.

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

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

States a specific action on a clear resource: lists a wallet's orders, newest first, and explicitly corrects the name by saying it returns every status unless filtered. This differentiates it from single-order siblings like get_order_status and from prepare/submit order 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?

Gives concrete usage: pass ['open','pending_signature'] for actionable orders and use the tool to recover a lost orderId. It does not explicitly name alternatives or when not to use it, though the recovery use case implies when this list is preferred.

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 already establishes this as a safe read operation. The description adds meaningful behavioral context: it reveals what data is returned per item and notes the v4-only constraint, which is not fully captured by the annotation 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?

The description is tight and front-loaded: it opens with the v4-only constraint, then states the exact scope and output fields, and ends with a practical prerequisite. Every sentence contributes value and there is no redundancy.

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

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

For a read-only lookup with fully documented parameters, the description provides enough context to select and invoke the tool correctly. It explains the item-level return content and where to obtain the required spokeId. It does not describe pagination or empty-result behavior, but no output schema exists and the information provided is sufficient for typical use.

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

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

Schema description coverage is 100%, so the schema already fully documents each parameter. The description does add the practical hint that spokeId comes from get_user_positions, but that same instruction is already present in the parameter schema. No significant additional parameter meaning is provided beyond the structured definitions.

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

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

The description clearly states the tool returns individual supply/borrow items inside a v4 spoke, with specific attributes: principal, accrued interest, and withdrawable amount. It explicitly distinguishes itself from the per-spoke aggregate provided by get_user_positions, making its purpose unambiguous.

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

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

The description identifies get_user_positions as the source for the required spokeId and implies this tool is for item-level detail that the aggregate cannot show. It also clearly scopes usage to v4 only. There is no explicit 'when not to use' list, but the contrast with the sibling tool gives strong contextual 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 readOnlyHint annotation, the description richly explains behavior: no version argument exists because DAO governance is not per-market, Governance V3 is unrelated to Aave v3/v4 markets, and the result is a per-chain breakdown of payload execution state. The nuance that 'executed' on one chain does not mean all chains are executed is valuable behavioral context.

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

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

The description is compact but information-dense. Each sentence earns its place: the first warns about an irrelevant argument, the second defines what payloads are, and the third gives a practical use case. It is front-loaded with the most important caveat.

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 read-only tool with no output schema, the description sufficiently explains what the response contains, the per-chain nature of payloads, and how to interpret execution readiness. Nothing essential is missing for correct invocation and interpretation.

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 only parameter, proposalId, is fully documented in the schema with an example and source instruction. The description adds no further parameter-level detail, but because schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states what the tool returns: the payloads a DAO proposal executes per target chain, including execution state, timelock delay, grace period, and contract calls. It also distinguishes this from a general governance proposal endpoint by focusing on cross-chain payload execution rather than proposal metadata.

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 concrete use case: telling whether a passed proposal has landed on every chain, with the example that a proposal can be executed on mainnet while still queued elsewhere. It also warns against passing a version argument. It does not explicitly name alternative tools like get_governance_proposal, but the usage context is clear enough.

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 indicate readOnlyHint=true, and the description adds useful behavioral details: results are ordered largest voter first, voting power is denominated in AAVE, and the 'totals' field reflects all votes on the proposal rather than only the paginated page. This goes beyond the annotation without contradicting it.

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 concise and every sentence carries useful information. However, it opens with a caveat about the version argument rather than the core purpose, so it is not perfectly front-loaded, though this is a minor structural issue.

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 simple list-style tool with no output schema, the description covers the essential context: what is returned, ordering, pagination caveat, and units. It does not spell out the exact response field names, but the combination of schema and description is adequate for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the support parameter's filtering behavior, clarifying that proposalId comes from search_governance_proposals, and explicitly warning that no version argument is expected or needed.

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

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

The description clearly identifies the verb/resource: get who voted on an Aave DAO proposal and with how much voting power. It distinguishes this tool from governance-structure tools by clarifying that DAO governance is not per-market and Governance V3 is unrelated to Aave v3/v4 markets.

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

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

Provides clear usage context: no version argument is needed, and support=true/false can be passed to filter one side. It explains why the version parameter is absent, but it does not explicitly name alternative tools or state when to prefer this over get_governance_proposal or get_user_vote.

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 already conveys that this is a safe read operation. The description adds useful behavioral context beyond annotations: the tool is v4-only, operates protocol-wide across chains, and returns samples over a time window. It does not fully describe output shape or sampling semantics, but with annotations covering the safety profile this is a minor 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?

Three sentences with no redundancy: the first establishes scope, the second gives a key operational detail, and the third provides usage guidance with sibling references. Everything present 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 read-only historical data tool with optional parameters and no output schema, the description is complete enough. It covers what data is returned, how to scope it across chains, what the data is useful for, and what it should not be used for. No critical context is missing.

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

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

Schema description coverage is 100%, so the schema already documents window, chainId, and version. The description adds context about chainId omission and v4-only behavior, but most parameter meaning is already present in the schema. This is the baseline 3 case where the schema carries the parameter documentation load.

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

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

The description uses specific language: 'Aave v4 protocol-wide history' with concrete metrics (market size, total borrows, available liquidity). It explicitly distinguishes itself from get_user_summary_history and get_apy_history, making its scope clear relative to siblings.

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

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

The description states exactly when to use the tool ('is the protocol growing') and provides explicit exclusions with named alternative tools: not for a single wallet (get_user_summary_history) or a single reserve (get_apy_history). It also gives operational guidance on omitting chainId for all-chain 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?

Despite readOnlyHint=true already covering the safety profile, the description adds substantial behavioral detail: all percentages are literal percents with Pct suffix, v4 utilisation and rate curve are hub-wide, collateralFactorPct is the liquidation boundary with no separate threshold, and liquidityFeePct is already netted out of supplyApyPct. This materially prevents misinterpretation of returned data.

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

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

The description is long but densely informative, and every sentence earns its place. The main purpose is front-loaded, followed by unit semantics, v4-specific interpretation pitfalls, and a sourcing prerequisite. Nothing is padded or redundant given the complexity of the tool and the absence of an output schema.

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

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

With no output schema, the description must carry the burden of explaining what the tool returns, and it does: field categories, unit conventions, v4 hub-wide behavior, and the two non-obvious v4 field meanings. It also covers the required input acquisition path via get_markets, making it complete for correct invocation and interpretation.

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 each parameter, including v3-only vs v4-only. The description adds some value by telling the agent to source reserveId or market+token from get_markets, and by explaining output unit conventions, but most parameter-level meaning already lives 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 opens with 'Deep detail for a single reserve' and names the specific resource and the exact categories it returns (rates, caps, risk parameters, utilisation, interest-rate curve, token addresses). It also disambiguates v3 vs v4, making it clearly distinct from list-oriented siblings like get_markets.

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 explicit context about when to use the tool and how to prepare inputs: 'Use get_markets first to get the reserveId (v4) or market+token (v3).' It does not explicitly state when not to use it or name alternative tools for related data, but the prerequisite and version-specific param sourcing provide clear operational 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 provide readOnlyHint=true, and the description adds valuable behavioral context: which unit 'amount' is in depends on the action, deposit returns minted shares, withdraw returns GHO, and the index moves. It does not contradict the annotations and meaningfully expands on the read-only nature.

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 dense but every sentence carries essential information: platform/version constraints, core conversion behavior, per-action unit semantics, workflow ordering with prepare_sgho_action, and the dynamic-index rationale. It is front-loaded and concise without wordiness.

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

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

Given the moderate complexity, no output schema, and readOnlyHint annotation, the description is complete. It covers the action/amount relationship, the need to call it before prepare_sgho_action, and why previewing is preferable to manual rate multiplication, which is sufficient for safe and correct invocation.

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

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

Schema description coverage is 100%, but the description goes beyond it by explaining the key cross-parameter dependency: how to interpret 'amount' depends on 'action' (GHO for deposit, sGHO shares for withdraw). It also reinforces that 'version' is v3-only, which is useful despite the schema already covering 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 description states a precise verb and resource: it converts between GHO and sGHO shares at the vault's current index, without building anything. It also distinguishes itself from prepare_sgho_action, so an agent can tell this is a read-only quote/preview 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 explicitly tells the agent to call this with action 'withdraw' before prepare_sgho_action because that withdrawal is denominated in shares, and warns against passing a GHO figure there. It also directs the agent to use this preview instead of multiplying by the rate because the index moves, giving clear when-to-use vs. alternative guidance.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only nature by listing returned fields. It adds useful behavioral context beyond annotations: the rate is governance-set rather than utilisation-based, sGHO is not a lending position/collateral, and deposits/withdrawals are instant with no cooldown. There is no contradiction with annotations.

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

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

The description is front-loaded with scope ('v3 only, Ethereum only') and core return values. The longer explanatory section about what the rate is not is dense but earns its place by preventing conceptual misuse of the data. It is not overly verbose for the amount of semantic context it provides.

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

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

With no output schema, the description carries the burden of explaining return values and does so substantially: it enumerates the vault fields and the user-specific fields. It also provides product context (governance-set rate, non-collateral nature, instant liquidity) that helps an agent interpret results. Minor gaps like unit details or error behavior are acceptable given the read-only nature.

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 applies. The description adds some extra meaning for the 'user' parameter—clarifying it returns shares, GHO value, wallet balance, and maxDeposit/maxWithdraw—but the schema already conveys the core semantics ('to include its position'). The version parameter is fully documented in the schema, so no further compensation is needed.

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

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

The description names a specific resource (sGHO savings vault), states the verb ('Returns'), and enumerates the exact returned fields (targetRatePct, totalAssets, supplyCap, paused flag). It also scopes the tool to 'v3 only, Ethereum only', which makes its purpose unambiguous and distinguishes it from unrelated vault-like 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 description clearly implies when to use the tool (when vault state or a user's sGHO position is needed) and gives parameter-level guidance ('pass user to add...'). However, it never names an alternative tool or states when NOT to use this one, despite siblings like get_sgho_preview and prepare_sgho_action existing. Usage context is present but exclusions are absent.

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 already signals this is a safe read operation. The description adds useful behavioral context: it applies to both versions and contains guidance content, not just a tool list. This goes beyond the annotation without contradicting it.

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

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

The description is short and front-loads the key information: applicability, content, and when to call it. 'What this Aave server can do' slightly echoes the title, but the usage directive earns its place. Overall, it is economical and scannable.

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

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

For a zero-parameter, read-only orientation tool, the description is complete. It explains the tool's content, when to use it, and how to use it, leaving no ambiguity about invocation or expected role.

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

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

With zero parameters and 100% schema coverage, the schema fully describes the input surface. The description correctly implies no parameters are needed by presenting this as a callable overview, earning the baseline 4 for a no-parameter tool.

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

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

The description clearly states the tool's purpose: it provides an overview of what the Aave connector can do, including tool families, ready-made prompts, and guide topics. It positions itself as a starting point distinct from all sibling tools, explicitly telling the agent to 'answer from it, rather than guessing from tool names.'

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 explicit usage context: 'Call this when an Aave conversation opens with no specific request.' It also tells the agent what not to do ('rather than guessing from tool names'), making the selection criteria actionable.

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

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

Beyond the readOnlyHint annotation, the description discloses backend behavior (protocol-agnostic, v4 backend, coverage limited to chains that backend serves), response semantics (counts vs token lists, chainsNotCovered meaning, 0-token meaning), and how to interpret edge cases. This is rich, non-obvious behavioral context.

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

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

Every sentence in the description earns its place: backend scope, invocation guidance, response interpretation, and sibling pointer. The most important usage detail is front-loaded, and there is no fluff or repetition.

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

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

With one optional parameter and no output schema, the description fully covers invocation modes, response interpretation, edge cases, and related tools. An agent has everything it needs to decide when and how to call this tool and to make sense of the result.

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

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

The schema already covers chainIds at 100%, including the omit-argument behavior, so the baseline is 3. The description adds value by explaining why you'd pass chainIds (to reach chains the sweep doesn't cover), the 'cheap answer' performance trade-off, and the resulting output difference. This meaningfully exceeds 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?

The description states a specific verb ('get') and resource ('swappable chains and tokens') and clearly distinguishes itself from siblings: it is the cheap sweep for chains, while get_swap_quote is for actual quotes and get_markets returns per-reserve canSwapFrom. The behavior is unambiguous.

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

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

It explicitly says to call this before get_swap_quote, explains when to call with no arguments (cheap sweep) versus with chainIds (get token lists, ask about unreached chains), and points to get_markets as an alternative for per-reserve data. This is direct, actionable usage 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 marks it safe, and the description adds substantial context beyond that: swaps run on the v4 backend, coverage is not the same as Aave's market chains, unsupported chains are rejected rather than misquoted, and the result is a quote carrying a quoteId. This is far more than the annotations alone provide.

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

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

Every sentence carries real information, but the definition opens with a version/backend caveat instead of the action verb, and the actual purpose only appears near the end. It is not poorly sized, but it is not the ideal front-loaded structure.

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 no output schema, the description compensates by naming the quoteId and the prepare_order flow, and it preempts the main failure mode (unsupported chain). Minor additional return/error details could be added, but an agent has enough to invoke and integrate the tool correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds meaning on top by explaining the absence of a version argument, clarifying that the backend determines chain/token coverage, and tying the result to prepare_order via quoteId. This exceeds the baseline expected for full 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 action: 'Quote a token swap: returns the quote with a quoteId to prepare and sign through prepare_order.' It is unambiguously distinct from siblings like get_swappable_tokens, which is described as a prerequisite, and prepare_order, which consumes the quoteId.

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 to do prerequisite work: 'Call get_swappable_tokens first if you do not already know the chain is covered, or read canSwapFrom...' It also explains that unsupported chains are rejected outright rather than badly quoted, so the tool should not be tried blindly. The prepare_order follow-up is named as well.

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 discloses a non-obvious behavioral trait: the Aave API lags the chain, so dependent actions will not proceed until processing catches up. This adds context beyond the readOnlyHint annotation and helps the agent understand why polling this endpoint matters. It does not cover edge cases like error handling or timeouts, but the core behavior is well explained.

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 deliver the purpose, usage context, required inputs, and termination condition with no filler. The most important guidance is front-loaded, and every sentence contributes to correct invocation.

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 simple read-only polling tool, the description is complete: it explains when to call it, what to pass, what to expect (processed becomes true), and why it is necessary. The absence of an output schema is compensated by the explicit mention of the 'processed' flag. No critical calling information appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by clarifying that txHash is the hash you broadcast and that operations must come from the server-built transaction. This provenance detail helps the agent pass the correct values, going slightly beyond the schema's field-level descriptions.

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: 'ask whether the Aave API has processed it' after sending a transaction. It clearly distinguishes this tool from polling an RPC or sleeping, and from prepare_action's dependent-follow-up behavior. The title reinforces the purpose as a question about transaction visibility.

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 explicitly says when to use the tool ('after sending a transaction'), what to pass (txHash and operations), and what to do ('Poll until processed is true, then continue'). It also names the alternative it replaces—sleeping or polling an RPC—and explains why prepare_action is not sufficient on its own.

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 substantial behavioral traits: results are ordered 'most recent first'; v3 reads one market on one chain at a time due to upstream pagination; the response states its scope as 'chainsCovered' and 'market'. This explains why the tool behaves differently across versions and how the agent should adapt, which is genuinely useful context the annotation alone does not provide. No contradiction with the readOnlyHint: true 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?

Three sentences with zero filler, front-loaded with the core purpose. The second sentence is dense and slightly run-on, but every clause carries information (why v3 is scoped, what the output states, how to broaden coverage), and the routing guidance closes efficiently.

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 tool with 5 parameters, two protocol versions, multi-chain semantics, and no output schema, the description covers the essential ground: what transactions are returned, ordering, version-specific scope behavior, and the key sibling alternative. The main gap is that, with no output schema present, the full record shape of the returned history is left partly to inference, though the listed transaction types and scope fields mitigate this.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter meaning: it explains the v3/v4 model that determines how market, chainId, and version interact, and why a cursor belongs to a specific version's feed ('upstream paginates per market'). This connects the parameters into a coherent mental model that the individual schema descriptions do not provide.

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: it retrieves a wallet's Aave transaction history, enumerating the transaction types (supply, borrow, repay, withdraw, collateral changes) and the version scope (v3, v4, or both). It also differentiates itself from the closest sibling by explicitly saying use get_user_positions, not this, for holdings, so an agent can tell them apart 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?

The description gives explicit routing guidance: 'Use get_user_positions, not this, to find out where a wallet holds anything.' It also explains the invocation strategy for v3 (pass chainId to read another market/chain) versus v4 (covers every chain), which tells the agent when and how to use the version and chainId parameters.

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 provide readOnlyHint=true, so the description carries the load and does an exceptional job: it explains cross-version behavior, response naming differences, chainsNotServed semantics, empty-result meaning, and the wallet-balance exclusion. This far exceeds what annotations already 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?

Four sentences, every one earns its place: scope, chain coverage semantics, version response differences, and empty-result interpretation with an alternative tool pointer. Despite density, it is well-organized and front-loads the core purpose before caveats.

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

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

Complete for a read-only query tool with no output schema. It covers all salient behaviors: which chains, which versions, response shape differences, empty-result meaning, and the boundary with wallet balances. An agent can likely call and interpret results correctly based entirely on this description.

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 all three parameters. The description still adds behavior-level meaning: 'Omit chainId ... cover every chain' and 'v4 returns positions, v3 returns supplies and borrows' go beyond the schema field descriptions. One small gap: it doesn't restate the exact enum default 'all', though the schema covers that.

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 clear verb+resource: reading a wallet's Aave positions (supplies/borrows) on v3/v4/both. It distinguishes from most siblings by scoping to Aave positions and explicitly says wallet token balances are not included. It also contrasts with get_markets, demonstrating differentiation rather than overlap.

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?

Extremely direct usage guidance: omit chainId and both versions cover every chain, no need to loop; lists chainsNotServed meaning; distinguishes v3 vs v4 response shapes; warns that empty results mean no Aave positions, not an empty wallet, and directs users to get_markets for wallet balances. This includes both when-to-use and when-not-to-use.

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?

Read-only intent matches the readOnlyHint annotation. The description adds important behavior beyond the annotation: chainsCovered vs chainsNotServed semantics, that empty results for unserved chains are not answers about those chains and stay empty on retry, and that the v3 response also carries the claiming transaction.

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 a clear one-sentence purpose. Subsequent sentences earn their place by explaining edge cases, but the chainsNotServed explanation is slightly verbose and 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?

For a read-only rewards lookup with no output schema, the description covers the main input behaviors, output fields (chainsCovered, chainsNotServed, row chainId), and a version-specific return detail. It does not enumerate the exact reward amount/asset fields, so agents still have some ambiguity about the response shape.

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 already documents all three parameters at 100% coverage, so baseline is 3. The description adds meaning by explaining that omitting chainId covers all served chains, that version can be v3/v4/all, and that output rows are tagged with their own chainId.

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 clear verb and resource: a wallet's claimable Aave rewards, scoped to v3, v4, or both. It also positions itself as the endpoint where GHO/sGHO incentives appear, though it does not name specific sibling tools for contrast.

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

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

Gives clear context on when to call it: for claimable Aave rewards across Merit and protocol incentive programmes, saying such rewards show up here rather than elsewhere. It does not explicitly enumerate when not to use it or name alternate tools like prepare_claim_rewards.

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 the safety bar is low, and the description goes far beyond it: it discloses edge-case semantics (chainsNotServed yields an empty result that "is not an answer about that chain"), warns that a sole unsupported chain returns "no totals" so "a zero would read as a real balance", and explains the v3/v4 behavioral difference plus the meaning of "marketsWithPosition": 0. No contradiction with the readOnly 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?

Front-loaded with the core purpose; every sentence carries a distinct behavioral or routing fact with no filler. It is long (~200 words), but the length is proportionate to the v3/v4 and multi-chain complexity, and the prose is dense rather than padded.

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

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

For a tool with no output schema, the description covers the critical return semantics (v4 fields, v3 per-market entries, scope-only replies) and the main misinterpretation traps. It doesn't specify the exact response JSON shape or invalid-address behavior, which is the only notable gap given the complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the consequence of omitting chainId (both versions cover every chain, no looping) and what choosing v3 vs v4 changes in the output. It stops short of defining response syntax or parameter format details beyond the schema, so 4 rather than 5.

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

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

Opens with a precise statement of the resource — "A wallet's aggregate position and health factor" — which is specific and immediately separates it from siblings like get_user_positions (detailed positions) and get_user_summary_history (history). The title reinforces the same resource, and the body pins down exactly what is returned for v3 and v4.

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

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

Explicitly routes to an alternative: "For what it holds, pass 'user' to get_markets, which returns walletBalance per reserve" — a clear when-not/alternative rule telling the agent where to get token balances instead. It also gives direct usage instruction not to loop over chains: "there is no need to loop over chains yourself."

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 the description complements this by adding the v4-only constraint and the important behavior that omitting chainId covers every supported v4 chain. It does not contradict the annotations and adds useful operational context without repeating the 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 with the key v4-only scoping, then the functional purpose, example user questions, and a chainId behavior note. Every sentence contributes useful information with no filler.

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

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

For a read-only history query with all parameters fully documented in the schema, the description provides enough context for an agent to select and invoke it correctly. It does not describe the exact return shape, but the 'movement over a window' phrasing makes the expected time-series nature reasonably clear.

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 fully documents user, window, chainId, and version. The description adds some interpretive value by framing the window as movement over time and noting the all-chains behavior for chainId, but this is already present in the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific resource (a wallet's net worth, supplied, debt, health factor) and a clear action (how they moved over a window), which distinguishes it from sibling get_user_summary by the 'over time' framing. It also scopes the tool to Aave v4, making its purpose unambiguous.

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

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

It gives explicit use cases: answering 'how has my position changed' and checking proximity to liquidation. It also explains the cross-chain behavior when chainId is omitted. It does not name alternative tools or state when not to use it beyond the 'v4 only' restriction, so it falls just short of full exclusion 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?

Although readOnlyHint=true is present, the description adds meaningful behavioral detail: 'Returns voted:false when that wallet did not vote, which is an answer rather than an error' clarifies the non-vote case, and 'Voting power is in AAVE' discloses units. This goes beyond the annotation without contradicting it.

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, each with a distinct purpose: the version caveat, the core function, the non-vote behavior, and the unit. The opening caveat is slightly atypical but valuable. No redundant filler; it is appropriately compact for the information conveyed.

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

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

Given the simple two-parameter read-only tool with no output schema, the description is nearly complete. It explains the non-vote response, the voting power unit, and where proposalId comes from (schema). It could explicitly mention that the response includes the vote choice, but 'How one wallet voted' sufficiently implies this.

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 clear descriptions for both 'user' and 'proposalId'. The description adds the caveat about no 'version' argument, which is useful, but it does not elaborate further on the parameters themselves. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description states exactly what the tool does: retrieves how one wallet voted on one Aave DAO proposal and with how much voting power. It distinguishes this from per-market governance by explicitly noting it takes no 'version' argument, avoiding confusion with market-related tools. The verb 'get' is implied by the title but the behavior is clearly and specifically described.

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

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

The description provides clear context: it warns not to pass a 'version' argument because DAO governance is not per-market, which prevents a common misuse. It also indirectly distinguishes from broader tools like get_proposal_votes by stating it covers one wallet's vote. However, it does not explicitly name sibling alternatives or state when-not-to-use conditions, leaving a small gap.

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 the description aligns by explaining building is non-custodial, sends nothing, is free, and commits the user to nothing. It goes further by disclosing behavioral consequences: supply without enableCollateral gives zero borrowing power, collateral pinned by a borrow cannot be withdrawn, and permit fields only replay a prior approval step. This is exactly the kind of context beyond annotations that prevents misuse.

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?

Although long, the description is dense with high-value guidance and every sentence earns its place. Core purpose is front-loaded, followed by return semantics, non-custodial behavior, user-interaction instruction, parameter compatibility rules, and the two most common failure modes. The length is justified by the complexity of a 13-parameter tool with two protocol versions.

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 complex tool with no output schema, the description covers the essential call-decoding information: required fields, version-specific fields, action-specific booleans, permit replay flow, where to source opaque IDs, unit conversion, and post-call polling. It even warns about the two most common caller mistakes. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant cross-parameter meaning: v4 takes 'reserve' while v3 takes 'market'+'token'+'chainId', 'max' applies only to withdraw/repay, 'enableCollateral' applies only to supply, and permit fields must never be sent on the first call. It also explains the behavioral consequences of omitting enableCollateral and how to obtain reserve/market values from prior calls.

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 an unsigned transaction to supply, borrow, withdraw, or repay on Aave (v3 or v4).' It clearly states what the tool returns ('an execution plan') and is easily distinguished from sibling prepare_* tools like prepare_cancel_order or prepare_claim_rewards.

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 strong operational guidance: send only applicable args, never include permit fields on a first call, poll get_transaction_processed after sending, and don't stop to ask the user because they see the transaction before signing. It does not explicitly name alternatives such as preview_action or submit_signed_order, but the intended usage 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?

Annotations already mark readOnlyHint=true, and the description reinforces this with 'commits nothing' and 'non-custodial'. It adds useful behavioral context about returning a signature payload rather than executing anything, and clarifies the gasless nature of the operation. Minor gaps remain around output format and any prerequisites beyond having an orderId, but the core behavior is well 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?

The description is compact and front-loaded: it immediately states the input scope and core output, then clarifies the relationship to cancel_order and when the alternative route applies. Every sentence carries useful decision-or-behavioral information, with no filler or repetition of schema details.

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

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

For a single-parameter tool with no output schema, the description gives an agent everything needed to call it correctly: what it returns, that it requires no version argument, that it commits nothing, and how it differs from cancel_order's transaction route. The ordering and signing workflow is implied clearly enough.

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 schema already fully documents orderId, including its source from submit_signed_order, get_order_status, or get_pending_orders. The description adds little beyond restating that the tool takes an orderId, so it does not meaningfully elevate parameter understanding beyond the required baseline.

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

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

The description clearly states a specific action—returning the EIP-712 cancellation for a given orderId—and distinguishes this tool from cancel_order by explaining that cancel_order relays the result. It also identifies the gasless/intent-order context, so an agent knows exactly what this tool produces.

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 explicitly says when to use this tool: for gasless cancellation of an intent order. It also names the alternative route—cancel_order's transaction route for on-chain native-token sells—and notes that route needs no signature and no prepare. This gives clear selection criteria versus a sibling 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?

The description adds meaningful behavioral context beyond the readOnlyHint annotation by stating that the tool builds an unsigned, non-custodial transaction rather than submitting one. It also discloses the default 'claims everything currently claimable' behavior when ids is omitted. This is useful context that the annotations alone do not convey.

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

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

The description is concise and well-structured: it front-loads the v4 constraint, then states the output, the default behavior, the non-custodial nature, and the v3 alternative in just a few short sentences. Every sentence 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 the complexity of this tool, the description is complete: it covers scope, output type, custody model, default behavior when ids is omitted, and the relationship to get_user_rewards. The schema handles the parameter details, and the annotations cover safety, so no critical information 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 input schema already provides 100% description coverage for all parameters, including the conditional chainId behavior and the ids opt-out. The description mostly restates the ids behavior without adding substantial new parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with 'v4 only' and states a specific action: 'Build an unsigned transaction to claim a wallet's V4 rewards.' It clearly identifies the resource and output type, and it distinguishes itself from a v3 claim by explicitly saying there is no v3 equivalent and naming get_user_rewards as the tool that returns the v3 transaction.

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 explicit routing guidance: use this for v4 reward claims, while v3 claims require no second call because get_user_rewards already returns the transaction. It also clarifies the ids omission behavior, helping an agent decide between claiming everything vs. specific reward ids.

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 flag readOnlyHint=true, and the description adds important behavioral nuance: the tool builds an unsigned transaction rather than executing it, and the liquidator signs and submits. It also discloses the liquidation mechanics (repay part of debt, receive collateral and bonus) and the health-factor dependency. This goes beyond the annotation without contradicting it.

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

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

Three dense sentences deliver the core purpose, the precondition, the version-specific parameter conventions, and the custody model without repetition or filler. Key facts are front-loaded, and 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?

Given 11 parameters, 2 required, and no output schema, the description covers the critical preconditions, version distinctions, and non-custodial behavior. It could also spell out the expected return format in slightly more detail, but the schema already documents parameter meanings thoroughly, so nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful cross-version semantics by explicitly mapping collateral/debt to v4 reserveIds and collateralToken/debtToken/chainId to v3, which helps an agent disambiguate parameters that would otherwise look similar from schemas alone.

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 action—'Build an unsigned transaction to liquidate an unhealthy position'—and clearly defines what the tool accomplishes: repaying debt and receiving collateral plus bonus. It also distinguishes the two protocol versions by their parameter conventions, making it easy to tell this apart from generic prepare_* siblings.

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

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

It gives an explicit viability condition ('Only viable while that position's health factor is below 1') and tells the agent to check get_user_summary for the target, which is actionable routing guidance. It also clarifies version-specific inputs and the non-custodial signing flow, so the agent knows both when and how to use 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?

readOnlyHint already signals a read-only operation, and the description goes well beyond it by stating 'this returns what the user signs, and commits nothing', explaining that signature parameters exist only to carry back what a quote explicitly requested, and pinning the v4 backend behavior. There is no contradiction with 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?

Four sentences with no filler; the conditional argument rules are packed into one structured sentence, and every sentence adds distinct information. The version note is appropriately front-loaded and the non-custodial behavior lands last as a clarifying capstone.

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 tool with no output schema, the description makes the operation understandable: it prepares a signable payload, commits nothing, and explains the input selection rules. It could be more explicit about what to do with the returned payload, but the sibling list and title cover most of that 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 coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter constraints: permit arguments apply only for bySignature quotes, the transaction route takes no signatures at all, and optionality is dictated by the quoteId's originating quote. These additions exceed what the schema alone says.

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

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

The title and description together pin down a specific action: prepare an order as typed data or a transaction to sign. The description adds non-custodial semantics ('returns what the user signs, commits nothing') and route-specific behavior, which separates it from sibling prepare_* tools without needing their schemas.

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

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

The description gives explicit conditional guidance: optional arguments are decided by the quote, route:'transaction' applies only to a SwapByTransaction quote, and a signature must never be sent unsolicited. It does not explicitly name alternative tools, so it stops short of a 5.

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

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

The description discloses several important behaviors beyond the readOnlyHint: v4 'enable' sets state while v3 toggles, a toggle inverting the stated state is refused, disabling triggers simulation with different outcomes, and simulation failure is surfaced under 'warnings.' It also states 'nothing moves' and 'Non-custodial,' making the read-only nature concrete. No contradiction with annotations.

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

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

Every sentence in the description carries a distinct fact: primary action, v3/v4 behavior, precondition, simulation logic, warning outcomes, and custody. It is dense but not bloated, and the most important framing ('Build an unsigned transaction') is front-loaded. A reader gets a full mental model without skimming irrelevant detail.

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

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

With no output schema, the description carries the burden of explaining what the tool returns. It references a 'warnings' field and implies an unsigned transaction payload, covering the most important output details. It could be more explicit about the overall response shape and the fact that the returned transaction must be submitted elsewhere, but the given context is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds high-level context about the flow, but each parameter's semantics is already thoroughly documented in the input schema (e.g., enable_version behavior, reserveId caveats). The description doesn't add parameter-level meaning that the schema lacks.

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 action and resource: 'Build an unsigned transaction to change whether a supplied asset is used as collateral (v3 or v4).' It further clarifies scope by distinguishing v3 toggle semantics from v4 set semantics and by noting 'nothing moves,' which separates it from executing or liquidation tools. This is far more specific than the title alone.

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

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

The description gives clear situational guidance: a wallet must already hold supply in the reserve, v3 and v4 behave differently, and disabling is simulated with health-factor thresholds. It does not explicitly name alternative tools or state when not to use it, so it lands just below the 'explicit exclusions' bar.

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 the description adds useful behavioral context: it builds an unsigned transaction rather than submitting it, and explains the LTV/borrowing-power consequences of eMode. It does not explicitly state that the produced transaction should later be submitted, but 'unsigned' conveys the key limitation.

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-loaded with the critical 'v3 only' constraint. It earns its length by explaining eMode's purpose and consequences. Minor redundancy: 'v3 only' appears at both the start and the end.

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

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

The description covers the essential context needed to call the tool: v3 scope, prerequisite data sources, categoryId semantics, and the transaction-building behavior. It does not describe the exact return shape, but since there is no output schema and the purpose is clear, this is a minor 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 coverage is 100%, so the schema already documents all parameters. The description adds some contextual value by linking categoryId to the specific market and reiterating that 0 disables eMode, but most parameter-level detail is 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 resource: 'Build an unsigned transaction to switch a wallet's Aave v3 eMode category.' It also scopes the tool to v3 and explains what eMode means, making its purpose unambiguous and distinct from other 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?

The description explicitly says 'v3 only,' explains that v4 replaces eMode with risk premium and dynamic config, and tells the agent where to get categoryId (get_emode_categories) and how to disable eMode (pass 0). This gives clear when-to-use and when-not-to-use guidance.

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

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

The description goes well beyond the readOnlyHint annotation by explaining that the tool is non-custodial, builds an unsigned transaction, and commits the user to nothing. It also discloses the ApprovalRequired result shape and the need to submit approval before the original transaction. This adds meaningful behavioral context not present in the structured annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose and network/version constraint, then methodically covers mode-specific behavior, edge cases, and the allowance prerequisite without repetition or 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?

For a transaction-building tool with six parameters, two required, no output schema, and a potential approval flow, the description is remarkably complete. It covers unit semantics, defaults, exclusions, network/version constraints, and sequential transaction handling, leaving an agent with enough information to invoke it correctly.

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

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

Even though the schema covers all parameters, the description adds crucial semantic distinctions: amount means GHO on deposit but sGHO SHARES on withdraw, max:true means redeem the whole position and omit amount, recipient is optional and defaults to sender, and version is effectively constrained to v3. This is exactly the kind of operational meaning the schema alone does not provide.

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 specifies a clear verb and resource: 'Build an unsigned transaction to deposit GHO into the sGHO vault or withdraw from it.' It also scopes the tool to v3 and Ethereum only, which distinguishes it from the broader prepare_action and other prepare_* siblings.

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

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

The description gives explicit when-to-use guidance for each mode: deposit versus withdraw, when to pass max:true, when to omit amount, when to use recipient, and the required order for approval and originalTransaction when ApprovalRequired. It also tells the agent to proceed with sensible values instead of stopping to ask, which is clear operational 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?

Beyond the readOnlyHint annotation, the description reveals that the tool builds an unsigned, non-custodial transaction, migrates the entire stkGHO position, and cannot read balance or cooldown state. These are critical behavioral traits that the annotation alone does not convey.

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

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

Every sentence earns its place: scope constraints first, then the core action, then the all-or-nothing rule, then the server limitation and how to phrase it to the user, then the non-custodial behavior. It is front-loaded and avoids redundancy.

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

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

Given the tool has only two simple parameters, no output schema, and readOnlyHint annotation, the description provides all necessary context: what it does, its constraints, its limitations, and how to interact with the user before signing. Nothing important is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining why there is no amount parameter (all-or-nothing) and by linking the 'user' parameter to the wallet's entire stkGHO position, which clarifies the intent beyond the schema's concise address description.

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

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

States a specific verb ('Build'), resource (stkGHO), target (sGHO vault), and distinct scope (v3/Ethereum, all-or-nothing). This clearly differentiates it from sibling prepare_* tools, which cover actions, orders, collateral, and other operations.

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

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

Provides explicit conditions: v3 only, Ethereum only, and all-or-nothing with no amount parameter. It also instructs the agent to tell the user to verify balance/cooldown because the server cannot read it, and to build the transaction rather than ask permission. It does not name an alternative tool for partial migrations, so it stops short of a 5.

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

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

Annotations only say readOnlyHint=true, so the description adds substantial behavioral context: the operation commits nothing, return shapes differ by version, warnings signal non-succeeding actions, and the simulation reports position limits rather than token allowances. This goes well beyond the annotations and is operationally important.

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 long but every sentence carries operational value: version routing, argument selection, return differences, warning semantics, and simulation scope. It is front-loaded with the core directive and uses the remaining sentences for high-signal caveats rather than filler.

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

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

Given 11 parameters, version-dependent behavior, and no output schema, the description is remarkably complete. It explains what each version returns, how to handle failure warnings, and the relationship to the prepare step, leaving no major gap an agent would need to infer.

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

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

The schema already documents each parameter, so the baseline is 3, but the description adds critical cross-parameter guidance: v4 uses 'reserve' while v3 uses 'market'+'token'+'chainId', 'max' only applies to withdraw/repay, 'enableCollateral' is v4-only, and it warns about non-constructible IDs and the 'spokeId' confusion. This materially improves correct invocation.

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

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

The description opens with a specific verb and resource: it simulates supply/borrow/withdraw/repay actions against a wallet's position on v3 or v4 without executing. It clearly differentiates this from a real execution or prepare step by stating it commits nothing, making the tool's purpose unmistakable alongside siblings like prepare_action.

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 explicit guidance: 'Always do this before a borrow or a withdraw' and 'Simulate first even when you intend to build immediately.' It also explains why simulation is the cheapest way to detect failure and notes what a clean simulation does and does not mean, giving the agent clear conditions for use.

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 already signals safety, and the description adds useful behavioral context beyond that: DAO governance is not market-specific, Governance V3 is unrelated to Aave markets, full-text search covers title/author/description and is relevance-ranked, and vote tallies are denominated in AAVE. This goes well beyond the structured annotation without overclaiming. It does not describe return shape or error behavior, but that is not essential for selection here.

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, information-dense, and front-loaded with the most important disambiguation about the 'version' argument. Each sentence earns its place: scope, state-filter guidance, search behavior, and vote-tally currency. No filler or repetition of schema details.

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 list/search tool with optional parameters, a readOnly annotation, and no output schema, this description is complete enough for an agent to select and invoke the tool correctly. It explains the core purpose, the state lifecycle meanings, search behavior, and the fact that vote tallies are in AAVE. Remaining parameter details (limit, offset, includeSummaries) are already well-documented in the input 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the practical semantics of 'state': 'active' means open for voting and 'queued' means passed and waiting timelock. It also clarifies that 'search' combines with 'state' and that no 'version' argument should be passed, which is valuable contextual parameter guidance.

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

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

The description states a specific verb and resource: 'List or search Aave DAO governance proposals.' It explicitly distinguishes this from market-scoped tools by clarifying that DAO governance is not per-market and that Governance V3 is unrelated to Aave v3/v4 markets. This makes the tool's purpose instantly identifiable among the large sibling set.

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 concrete guidance for when to use specific parameters: use state 'active' for what is live now, state 'queued' for what is waiting to execute, and 'search' for full-text relevance queries. It clearly explains that the tool takes no 'version' argument, preventing a likely misuse. It stops short of explicitly naming alternative tools like get_governance_proposal for single-proposal lookups, so it does not fully meet the 'explicit alternatives' bar.

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 provide readOnly=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it is state-changing, posts the order, runs on v4, and the server never signs. No contradiction exists.

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, each carrying distinct information: the backend constraint, the required inputs and source, and the state-changing nature. No filler 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?

For a simple two-parameter tool, the description plus schema gives enough to call it correctly: where inputs come from, that it is a write operation, and that the server does not sign. There is no output schema, but that is not a blocker for calling the tool correctly.

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

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

Schema description coverage is 100%, with both parameters fully documented in the schema. The description reinforces that quoteId and signature come from prepare_order's PreparedOrder but does not add new semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('relay'/'submit') and resource ('an order the user already signed') and clearly distinguishes itself from prepare_order by stating it operates on a signed order with quoteId + signature from prepare_order's PreparedOrder. It also clarifies the backend version, making its scope unmistakable.

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 clearly indicates when to use this tool: after prepare_order, with an already-signed user order, and states that the server never signs. It does not explicitly name alternative tools to avoid, but the contrast with prepare_order and the emphasis on user-signed orders provides sufficient context.

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