Aave

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

Annotations already indicate destructive and non-readOnly behavior, but the description adds significant context: it is state-changing, the on-chain route returns a transaction for the user to sign, gasless cancellation is relayed, and 'the server never signs.' This clarifies exactly what side effects and signing responsibilities 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 efficient and front-loaded with the core action. It packs the two-route decision, signing behavior, and server constraint into three sentences. The wording is slightly dense with repeated route clauses, but 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 destructive, state-changing tool with no output schema, the description covers route selection, prerequisites, and signing behavior well. The only notable gap is that the return value for the gasless route is not described; only the on-chain route's return transaction is explicit.

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 beyond the schema by clarifying that 'signature' must be signed over prepare_cancel_order's typed data and that omitting it entirely switches to the on-chain route. This connects the parameter semantics to concrete tool flow.

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 'Cancel an open order' — a specific verb and resource — and then distinguishes two execution routes. It also references prepare_cancel_order, making clear this tool is the cancellation action and not the preparation step.

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 explains when to pass 'signature' versus omit it: the gasless route for intent orders and the on-chain route for native-token sells. It clearly maps parameters to routes, though it does not mention alternative cancellation-related tools beyond the prerequisite prepare_cancel_order.

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 the tool as read-only and non-destructive; the description adds meaningful behavior beyond that: it applies to both v3 and v4, returns the full capability list for lookingFor, records gaps when a capability is missing, and points users to external docs for deep protocol details. This is useful context for an agent deciding how to use the result.

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 four sentences in a logical order: scope, guidance, topics, fallback, and external docs. It could be tighter because the topic list duplicates the schema enum, but every sentence serves a functional purpose and the most important guidance 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 read-only guide with two optional parameters and no output schema, the description gives enough to select and invoke it: when to read, what topics exist, how lookingFor behaves, and where to send users for deeper docs. A minor gap is not explicitly stating the return format, but 'answers' and 'returns the full capability list' imply textual guidance.

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 does not need to carry parameter documentation. It reinforces topic usage and adds a small behavioral detail for lookingFor ('records the gap'), but it largely repeats the schema's enum and descriptions. Value added is modest but real.

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 a specific role: a protocol and usage guide for building Aave flows correctly, with a fallback for capability discovery when no tool fits. The verbs 'read' and 'guide' plus the resource 'Aave protocol' are explicit, and the 'no tool seems to fit' behavior distinguishes it from the many data/action 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 concrete when-to-use triggers: read a topic before constructing an action, and send 'lookingFor' when no tool seems to fit or a flow dead-ends. It also directs deep-documentation cases to docs.aave.com. It does not explicitly contrast with get_started or state when not to use this tool, but the guidance is 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 and destructiveHint annotations, the description discloses return shape ({date, apyPct}), value semantics (percent, e.g. '3.32'), averaging behavior, window-dependent sampling intervals, and the comparability caveat with get_reserve_details. This significantly enriches what the agent knows before calling.

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

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

The description is dense but efficient, front-loading the core purpose and progressively adding return format, averaging semantics, and usage caveats. Each sentence adds distinct value 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?

Given there is no output schema, the description fulfills the burden by explaining the return time-series and percent format. It also covers prerequisites, version-specific parameter requirements, and a nuanced migration comparison scenario, making it highly complete for this tool's 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 parameter basics are already documented. The description adds valuable semantic context by explaining that market/token/chainId belong to v3, reserve belongs to v4, identifiers come from get_markets, and window affects aggregation granularity.

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

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

The description names the specific operation: retrieving historical supply or borrow APY for a reserve over time, and explicitly scopes it to v3 or v4. It also distinguishes itself from get_reserve_details by noting the historical series is not comparable to an instantaneous rate.

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

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

It clearly states to call get_markets first for the required identifiers and gives a concrete migration scenario where both v3 and v4 histories should be read. It does not enumerate all alternatives, but the key routing guidance is present and actionable.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals important behavior: notServed chains produce empty market/position/rewards reads, gateway addresses read 0x0, and sending transactions to such chains is unsafe. This is exactly the kind of context annotations cannot express.

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

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

The description is three sentences with the core purpose front-loaded and the notServed caveat following in a logical order. Every sentence adds value, and there is no redundant wording.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the key decisions: which version to query, what notServed means, and why gateway transactions should be avoided. It does not spell out the full response shape beyond the notServed and gateway fields, but the low complexity keeps this gap small.

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 the only parameter fully with an enum and a default value. The description's 'on v3, v4, or both' mirrors the schema rather than adding new semantic detail, so it stays at the baseline for 100% 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 opens with a clear verb and resource: 'List chains Aave supports', then scopes it by protocol version (v3, v4, or both). This gives the agent an unambiguous purpose and naturally separates it from sibling tools like get_markets or get_hubs.

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 practical guidance: chains with 'notServed': true return empty data and have 0x0 gateway addresses, so transactions should not be sent to them. It does not explicitly compare with alternatives, but the tool's narrow read-only scope makes this omission minor.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavioral details beyond that: markets without matching categories are omitted from results, unfiltered calls return every category on every chain, and the returned categoryId is specifically what prepare_set_emode consumes. This gives the agent accurate expectations about response scope and edge cases.

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: version restriction, conceptual context, return contents, filtering guidance, omission behavior, and v4 contrast. The description is dense but well organized, front-loading the critical v3-only constraint before operational 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?

Despite having no output schema, the description explains the key return fields (categoryId, LTV, liquidation thresholds, symbols), scoping behavior, and filtering semantics. For a read-only lookup tool with optional parameters, this is sufficient for an agent to select and 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?

Schema coverage is 100%, so the baseline is 3, but the description enriches both parameters: it explains that omitting chainId covers all chains and that filtering by symbols returns only the categories containing that asset, with a strong preference hint due to response size. This goes beyond the schema's basic descriptions without being redundant.

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 ('Returns') and clearly identifies the resource: eMode categories per market, including categoryId, LTV, liquidation thresholds, and symbols. It also distinguishes itself by noting v3-only applicability and contrasting with v4's replacement of eMode, making it unambiguous versus sibling tools like prepare_set_emode.

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

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

The description gives clear context for when to use the tool: only for v3 chains, with v4 explicitly called out as not having eMode. It also provides practical guidance on using the 'symbols' filter and notes the large unfiltered response, though it does not explicitly name alternative tools or say when not to use this one beyond the v4 exclusion.

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

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

Beyond the read-only annotations, the description adds substantial behavioral detail: the relationship of quorumMet/differentialMet to passing, the directly comparable AAVE units, and the fact that the long IPFS description is omitted unless includeDescription is true. It does not contradict the annotations.

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

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

The description is dense but free of fluff. Every sentence earns its place: scope clarification, field listing, pass-condition semantics, and parameter behavior are all functional rather than redundant.

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

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

With no output schema, the description carries the burden of explaining return content and does so thoroughly: state, author, tallies, quorum, timings, lifecycle hashes, pass conditions, and optional IPFS content. The input schema and annotations cover the rest.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by clarifying the source of proposalId ('from search_governance_proposals') and the behavior of includeDescription, including that the short description is always returned.

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: 'Full detail for one Aave DAO governance proposal' with a concrete list of included fields. It distinguishes itself from market-scoped tools by explicitly saying 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?

The description gives clear context and an exclusion: it takes no 'version' argument and is not per-market, so agents won't misuse it for market-specific queries. It does not explicitly name sibling alternatives like get_proposal_votes or get_proposal_payloads for narrower lookups, but the core 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 declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: this is hub-level accounting, v4-only, and returns aggregate totals, rates, and utilisation. It does not contradict annotations and adds useful scope clarification.

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, front-loaded with the critical 'v4 only' constraint, and every sentence earns its place: purpose, contained metrics, parameter sourcing, and routing to the alternative tool.

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

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

For a read-only, two-parameter tool, the description fully covers what an agent needs: version, input sourcing, output contents, and when to choose a different tool. No output schema exists, but the description provides sufficient return-value orientation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds extra value by telling the agent where hubId comes from and reiterating the version constraint, which helps ensure 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 states a specific verb ('get') and resource ('assets held by one Aave v4 hub'), and further specifies the contents: supplied and borrowed totals, rates, and utilisation. It explicitly distinguishes itself from get_markets, so an agent can tell them apart without inspecting 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 clear when-to-use guidance: 'v4 only', explains how to obtain hubId from get_hubs or get_reserve_details, and explicitly directs to get_markets for per-spoke user supply/borrow data. This is a model example of routing.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavior beyond the annotations: the v4-only constraint, the hub/spoke relationship, and the explicit output fields. It does not discuss pagination or error behavior, but for a simple read-only list tool with safe annotations, this is adequate.

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 four short sentences with every sentence contributing: scope, concept, return fields, sibling routing, and chainId behavior. It is front-loaded with 'v4 only' and contains no filler or redundant restatement.

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 hub-listing tool with no required parameters and no output schema, the description is complete: it identifies what a hub is, what fields are returned, which chains are covered, and where to go for asset details. The annotations cover the safety profile, so nothing critical is missing.

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

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

Schema description coverage is 100%, with chainId and version already well documented. The description restates the 'omit chainId' behavior but adds no new parameter semantics beyond what the schema provides. The baseline of 3 applies because 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 uses a specific verb ('Returns') and a concrete resource ('Aave v4 hubs'), and states exactly what is returned: hubId, address, chain, and totals. It also clarifies the hub concept and explicitly distinguishes this tool from get_hub_assets by pointing to that sibling for asset-level data.

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

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

The description gives clear usage context: it is v4-only, it lists hubs, and omitting chainId covers all supported v4 chains. It also routes the agent to get_hub_assets when assets are needed. It does not enumerate exclusions against the many other sibling list tools, but the guidance covers the main alternative.

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 far beyond the readOnly/destructive annotations: 'chainsCovered' vs 'chainsNotCovered', v3 reading only Ethereum without symbols, 'an empty result for one of them is not an answer about that chain', and 'asking again returns the same nothing'. It also explains that isFrozen/isPaused/cap flags appear only when set and that v4 spokes sharing a hub share rates. These are exactly the behavioral traits an agent needs.

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

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

Though long, every sentence carries non-obvious operational knowledge: chain coverage, version differences, rate units, flag semantics, row labeling, and swap direction. It is front-loaded with the core list purpose and then layers essential caveats without fluff 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?

Given no output schema and four parameters, the description fully compensates by explaining response shape ('one row per reserve under reserves', 'supplyApyPct and borrowApyPct together'), edge cases, repeated-query behavior, and version-specific behavior. An agent can correctly invoke the tool and interpret results without guessing.

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 already covers all four parameters at 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to combine parameters ('pass symbols and no chainId', omit chainId for full coverage) and by connecting symbols to response size. This goes beyond repetition of schema text, warranting a 4.

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 Aave markets/reserves (symbol, APY, caps, liquidity) on v3, v4, or both.' It names the exact output scope and distinguishes itself from sibling tools by noting that get_swappable_tokens answers the per-chain form of canSwapFrom. This is unambiguous and differentiating.

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

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

Explicit guidance is pervasive: 'to compare one asset across chains, pass symbols and no chainId', 'omit chainId and every response states the chains it read', and 'Strongly preferred when you know the asset'. It names get_swappable_tokens as an alternative and explains the v3-only behavior when symbols is omitted. No important usage context is left to inference.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals what the response contains (status, operation, explorer link) and the ambiguous null behavior for unknown or just-submitted orders, including the advice to poll again briefly. This materially helps an agent interpret results correctly.

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, leading with the core purpose and status list, then covering the important null edge case in the final sentence. 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 single-parameter read-only lookup with no output schema, the description covers the returned statuses, included information, and the key failure/races condition. This is sufficient for an agent to invoke the tool and interpret its result without further clarification.

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 only says orderId is 'The order id.' The description adds that the lookup is by id, notes there is no version argument, and explains how a valid but not-yet-visible id behaves. This adds meaningful semantics beyond the schema, though the schema coverage is already complete.

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

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

The description uses a specific verb and resource: 'Status of an order by id', and enumerates the exact statuses returned. It clearly distinguishes this single-order lookup from sibling tools like get_pending_orders or cancel_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?

The description makes clear this is for checking the status of a specific order by its id and even explains the null result is expected for recently submitted orders. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it appropriately.

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 beyond the readOnlyHint annotation by disclosing that the v4 backend determines chain coverage, that a chain in 'chainsNotCovered' could not be read, that each chain returns only its newest 50 orders, and that 'more: true' signals older history exists. These are critical behavioral details not captured in the schema or annotations. The description does not contradict the readOnlyHint.

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

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

The description packs substantial detail into four sentences, with the most decision-relevant facts front-loaded: backend version, chain coverage, and ordering. It is dense but every sentence carries useful behavioral or usage information. The only minor issue is that 'more: true' is somewhat jargon-heavy, but it is explained immediately after.

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 no output schema, the description covers input semantics, chain coverage, status filtering, result limits, pagination signals, and a concrete use case (recovering an orderId). It even addresses a likely failure mode (chainsNotCovered). There is no meaningful gap for an agent to call 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 description coverage is 100% for the three parameters, so the baseline is 3. The description adds semantic value by explaining the consequence of omitting chainIds ('sweep every chain') and the recommended statuses value for actionable orders, which goes beyond the raw schema descriptions. It doesn't restate the enum values, which is appropriate since they are already 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 clearly states it lists a wallet's orders, sorted newest first, across chains served by the v4 backend. It distinguishes itself from get_order_status by explaining it can recover an orderId. However, the name already implies 'pending orders' while the description clarifies it returns every status unless narrowed, which adds clarity.

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 explicit when-to-use guidance: use it to recover an orderId you no longer have, pass ['open','pending_signature'] for actionable orders, and omit chainIds to sweep every chain. It also tells the agent that chains under 'chainsNotCovered' should be asked about again, which is practical routing advice beyond what the schema provides.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it is restricted to v4 and exposes per-item breakdowns rather than aggregates. 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 compact and front-loaded: it begins with the critical 'v4 only' constraint, states the output content, and names the alternative it complements. Every sentence adds distinct value with no repetition.

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

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

For a read-only, low-complexity tool with fully documented parameters, the description is complete. Even without an output schema, it tells the agent what data to expect (principal, accrued interest, withdrawable amount) and how to obtain the required spokeId.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, defaults, and constraints. The description's only parameter-related addition is the pointer that spokeId comes from get_user_positions, which the schema already states. It does not meaningfully compensate beyond the schema.

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

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

The description names a specific verb ('get') and a specific resource ('individual position items'), and clearly defines the content: principal, accrued interest, and withdrawable amount per item. It also explicitly contrasts itself with the per-spoke aggregate from get_user_positions, making the tool's scope 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 states that the tool is v4 only, explains that it fills a gap left by get_user_positions ('which the per-spoke aggregate ... cannot show'), and instructs the agent to obtain 'spokeId' from get_user_positions. This gives clear when-to-use and how-to-prepare guidance with reference to the relevant 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?

Annotations already indicate read-only and non-destructive behavior. The description adds meaningful context beyond that: the tool takes no 'version' argument and why, the per-chain structure of payloads, and the meaning of execution state across chains. This provides useful behavioral detail without contradicting the annotations.

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

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

The description is three sentences with no filler. Each sentence earns its place: the first corrects a likely misuse, the second explains what the tool returns, and the third gives a concrete decision-oriented use case.

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, read-only tool with no output schema, the description is nearly complete: it explains the payload concept, its components, and how to use the results to assess cross-chain execution. It could be more explicit about the output format, but the provided context is sufficient for an agent 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?

The input schema already documents the only parameter, proposalId, with an example ('508') and its source (search_governance_proposals), so schema coverage is 100%. The description does not add new parameter-level detail beyond what the schema provides, so a 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 states a specific verb and resource: retrieve the payloads of an Aave DAO proposal. It goes beyond the title by detailing what a payload is (per-chain execution state, timelock delay, grace period, contract calls), making it clearly distinct from governance proposal or vote 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 gives an explicit use case: 'Use this to tell whether a passed proposal has landed on every chain yet', with a concrete example of mainnet executed while another chain is still queued. It does not name alternatives directly, but the context makes the tool's role clear relative to sibling governance 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 and destructiveHint annotations, the description discloses important non-obvious behaviors: results are sorted largest voter first, 'totals' covers every vote including those beyond the returned page, support filters by voting side, and voting power is expressed in AAVE. These are exactly the behavioral details an agent needs.

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

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

Each sentence carries useful information and there is no filler. However, the description opens with a caveat about the nonexistent 'version' argument rather than the main purpose, which slightly hurts front-loading. It is compact and well structured overall.

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

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

For a read-only tool with four parameters and no output schema, the description is sufficient: it explains result content, ordering, units, totals behavior, and filtering. Required parameters and pagination semantics are covered by the schema. No critical calling behavior is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description restates support filtering and pagination-related behavior in prose, but it does not add parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate here.

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 action: listing who voted on an Aave DAO proposal and with how much power, ordered largest voter first. It clearly distinguishes this from governance proposal metadata tools by focusing on vote-level detail, and the 'no version argument' note disambiguates it from market-related governance confusion.

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

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

The description gives clear context: this is DAO governance, not market-specific, and warns against passing a 'version' argument. It also explains when to pass support=true or false. However, it does not explicitly name sibling alternatives like get_governance_proposal or get_user_vote, so routing is mostly inferred rather than fully spelled out.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable non-obvious behavior: the tool is v4-only, can aggregate across all chains when chainId is omitted, and returns sampled data per window. This goes beyond the structured annotations without contradicting them.

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 filler. It front-loads the version constraint and core purpose, then provides routing guidance. Every sentence carries necessary information.

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

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

For a read-only tool with zero required parameters and a well-covered schema, the description supplies the essential decision context: use case, exclusion criteria, and chain scope behavior. It even summarizes the return data (market size, borrows, liquidity per sample), which compensates for the absent output schema.

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

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

Input schema covers 100% of parameter descriptions, so the baseline is 3. The description adds a useful clarification about omitting chainId for multi-chain coverage, but most parameter meaning (window options, chainId semantics, version restriction) is already in the schema. No significant added value beyond 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 specific verb and resource: get protocol-wide Aave v4 history, with concrete metrics (market size, total borrows, available liquidity) and sampling over a window. It explicitly distinguishes itself from wallet-level and reserve-level history tools, so an agent can identify it among many 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?

Provides explicit usage context: 'Use this for is the protocol growing' and names the alternatives it is not (get_user_summary_history, get_apy_history). It also gives a concrete call-time guideline: omit chainId to cover all supported v4 chains.

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 the tool read-only and non-destructive, and the description adds substantial semantic context: percentages are percent values with Pct suffix, v4 utilisation is hub-wide, collateralFactorPct is the liquidation boundary (health factor 1.0), and liquidityFeePct is already netted out of supplyApyPct with a formula. 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?

Although long, every portion earns its place: scope sentence, unit caveat, v4 field semantics, price ownership, and call sequencing. It is front-loaded with the core purpose before diving into edge-case explanations.

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 must carry the burden of describing what the agent will receive; it names the important fields (priceUsd, priceSource, collateralFactorPct, liquidityFeePct) and explains their interpretation. The supplyApy formula closes a significant double-counting trap, and the get_markets-first guidance fills the parameter prerequisite gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value by explaining how to populate the v3 vs v4 identifiers (reserveId from get_markets, market+token for v3) and by clarifying unit conventions for output values. It doesn't need to re-explain chainId because the schema already covers 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 opens with 'Deep detail for a single reserve' - a specific verb and resource - and lists concrete content areas (rates, caps, risk parameters, utilisation, curve, token addresses). It also distinguishes the tool from get_markets by pointing out that get_markets quotes no price and that the reserve IDs come from there.

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 sequences the workflow: 'Use get_markets first to get the reserveId (v4) or market+token (v3).' It also tells the agent that price data lives here and not in get_markets ('what an asset is worth on Aave is answered here'), creating a clear selection rule.

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 destructiveHint=false, and the description adds meaningful behavioral context: the conversion uses the vault's live index, the tool does not build or submit anything, and the result is a quote rather than a transaction. It also explains the reason the index matters for correctness. No contradiction with annotations 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?

The description is dense but efficient, with every sentence contributing a necessary constraint or behavioral fact: version and chain scope, conversion semantics, unit asymmetry, usage ordering, and the reason to avoid manual rate multiplication. The critical caveats are front-loaded and clearly worded.

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 preview tool with no output schema, the description provides enough context for correct invocation: what inputs mean, what each action returns, which version is supported, and how this tool relates to prepare_sgho_action. An agent has all the information needed to select and call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value by tying the amount's unit to the action: 'deposit' takes GHO and returns shares, while 'withdraw' takes sGHO shares and returns GHO. It further reinforces the critical distinction that passing a GHO figure to the withdrawal path would be wrong. This goes beyond the schema's per-parameter 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 names a specific verb and resource: previewing an sGHO deposit or withdrawal. It clearly states it converts between GHO and sGHO shares at the vault's current index and says it does so 'without building anything,' which distinguishes it from prepare_sgho_action. The unit asymmetry between deposit and withdraw is explicitly explained, leaving no ambiguity about what the tool does.

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 call this tool before prepare_sgho_action, warns that withdraw is denominated in shares rather than GHO, and cautions against using simple rate multiplication because 'the index moves.' It also scopes the tool to v3 and Ethereum only. This gives clear when-to-use guidance and names the relevant alternative.

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 destructiveHint=false, and the description goes well beyond them: it spells out scope (v3/Ethereum), the specific returned values, optional per-wallet enrichment, and the rate's governance-set nature. It also states deposits/withdrawals are instant with no cooldown, adding behavioral nuance an agent could not infer from annotations alone.

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

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

The description is front-loaded with chain/version scope, and each sentence earns its place: return fields, optional user behavior, and rate caveats. It is longer than average but packed with decision-relevant detail 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?

For a read-only getter with no output schema, this description covers the essential invocation context and return semantics. It names all return fields, handles the optional parameter, and adds limitations/caveats an agent would need to interpret the data correctly. Very little is left for the agent to guess.

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 description does not need to re-document parameters, but it adds real value by explaining the effect of passing 'user' and the alternative of omitting it. The version parameter is correctly constrained to v3 in both schema and prose.

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 concrete resource ('sGHO savings vault'), a specific verb ('Returns'), and enumerates the exact data fields returned. It also clarifies what sGHO is not (a lending position/collateral), which prevents confusion with Aave lending tools. This is enough to distinguish it from siblings such as get_sgho_preview.

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

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

It opens with scoping constraints ('v3 only, Ethereum only') and explains the optional user parameter flow ('pass user to add... omit... for vault state only'). It gives clear context for invocation, though it does not explicitly name alternative sibling tools or state when to prefer this over get_sgho_preview.

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 the tool is read-only and non-destructive. The description adds useful behavioral context: it applies to both versions, it returns an overview of tool families, prompts, and guide topics, and it is meant to be the source for an initial response. No contradiction exists between the description and 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 compact and front-loaded, with the key orientation purpose stated in the first sentence. Every sentence adds value: scope, content, and the exact trigger condition for use.

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 informational tool, the description is complete: it names the content covered, the versions it applies to, when to call it, and how to use the returned information. The absence of an output schema is acceptable because the tool's output is described at a high level as an answer source.

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 has zero parameters and 100% schema description coverage, so there is no parameter ambiguity. With no parameters, the description does not need to explain parameter meaning; the baseline score of 4 applies.

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

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

The description clearly states that this tool is an orientation resource for the Aave connector, covering tool families, ready-made prompts, and guide topics. It distinguishes itself from the many specific get_/prepare_/preview_ siblings by positioning itself as the entry point when no specific request exists.

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 instructs the agent to call this tool when an Aave conversation opens with no specific request and to answer from its content. It also warns against guessing from tool names, which is a clear routing rule against using the alternative specific tools prematurely.

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 the tool as read-only and non-destructive, but the description adds meaningful behavioral detail: the v4 backend scope, the distinction between a chain not covered and a chain with zero swappable tokens, and the cheap count-sweep behavior. These edge cases are not visible in the input schema and materially affect how results should be interpreted.

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 packed with useful operational distinctions; no sentence is wasted. Some phrasing is slightly awkward, such as the opening 'No version argument' clause and the semicolon-heavy 'chainsNotCovered' explanation, but the overall structure front-loads the most important usage context.

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

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

Given a single optional parameter, no output schema, and safety-related annotations, the description is remarkably complete. It covers invocation modes, result interpretation, failure semantics, and relevant sibling tools, so an agent has enough information to call and interpret 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?

The schema documents chainIds as an optional array, but the description enriches this by explaining that omitting the argument produces a chain-count sweep while providing chainIds yields token lists. It also clarifies that passing chainIds can query chains outside the default sweep, adding meaning well beyond the schema 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 clearly states that the tool returns swappable chains and tokens, either as a count sweep when called with no arguments or as an actual token list when chainIds is passed. It also differentiates the tool from related siblings like get_swap_quote and get_markets, so an agent can understand its unique role.

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 to call this before get_swap_quote, explains when to omit chainIds versus passing them, and describes how to handle chains that appear under 'chainsNotCovered'. It also points to get_markets as an alternative source of per-reserve 'canSwapFrom' data, giving clear routing guidance.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses non-obvious behavior: the v4 backend scoping means coverage is not every Aave market, unsupported chains are hard-rejected instead of mis-quoted, there is no version argument, and the returned quoteId is the handoff to prepare_order. This is exactly the behavioral context an agent needs and could not infer from 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?

Every sentence carries substance and there is little waste, but the structure is poorly ordered: it opens with the confusing 'No version argument:' reference, then backend scoping, then prerequisite routing, and only finally states what the tool does. The core purpose should be front-loaded; as written, an agent must parse a dense caveat-heavy paragraph before learning the tool's function.

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 7 parameters, prerequisites, and no output schema, the description covers the essential ground: backend scope, rejection behavior, prerequisite alternatives, the quoteId return value, and the next step in the flow (prepare_order). Minor gaps remain, such as quote validity/expiry and what other fields the quote contains, but nothing that would prevent a 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 per the rubric. The description does not add parameter-level detail; the schema already thoroughly documents user (e.g., never substitute a placeholder), amount, kind, and slippagePct. The chain-coverage caveat tangentially informs chainId but does not add meaning 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 ends with 'Quote a token swap: returns the quote with a quoteId to prepare and sign through prepare_order,' which states a specific verb, resource, and the key output, and implicitly distinguishes the tool from the downstream prepare_order flow. However, the purpose statement is placed last, after the backend-scoping caveat, so the core function is not immediately legible on first read.

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 routes the agent: 'Call get_swappable_tokens first if you do not already know the chain is covered, or read canSwapFrom on the reserve from get_markets.' It also sets expectations for the unsupported-chain case ('rejected outright rather than quoted badly'), so an agent knows both when to use this tool directly and when to consult an alternative first.

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 this as read-only, and the description adds useful behavioral context: the API lags the chain, prepare_action will block follow-ups until processing catches up, and the tool should be polled until processed becomes true. This effectively communicates the return semantics without an output schema. It stops short of describing error or timeout behavior, but that is not a major gap for this polling tool.

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

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

Three sentences with no filler. The v4-only constraint is front-loaded, followed by the purpose, usage rationale, and concrete invocation guidance. Every sentence earns its place and the description is easy to scan.

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

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

For a simple read-only polling tool with full schema coverage and no output schema, this description is complete. It explains when to use it, why it is needed, what inputs to pass, and how to interpret the result ('poll until processed is true'). The annotations cover the safety profile, so no critical operational detail 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 parameters are already documented. The description adds meaningful operational context beyond the schema by specifying that txHash should be the hash you sent and operations should be the array that came back on that transaction. It also clarifies that the expected usage is polling, which gives the parameters a clear role in the workflow.

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 a transaction. It clearly differentiates this from generic RPC polling and related tools by naming prepare_action's dependency on this check. The title reinforces the purpose as a clarifying question.

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

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

Explicitly says when to use it: after sending a transaction, before issuing a dependent follow-up. It also names the alternatives it replaces (sleeping or polling an RPC) and explains why, giving the agent a clear decision rule. The instruction to pass the txHash and operations array and poll until processed is true is concrete.

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 the tool as read-only, and the description adds useful behavioral context: results are newest-first, v4 covers all chains, v3 is market-scoped due to upstream pagination, and cursors are tied to a version. It could go further by describing the return item shape, but it goes well beyond the annotation baseline.

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

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

Three dense sentences with no filler: purpose and ordering are front-loaded, v3/v4 scope is explained efficiently, and the alternative tool is pointed to last. The complexity justifies the length.

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 complexity and lack of an output schema, the description covers event types, ordering, chain/version scope, pagination behavior, and when to use a sibling tool. The main omission is an explicit statement of the return structure, but an agent has enough to select and 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?

Schema coverage is 100% and each parameter already has a meaningful description, so the baseline is 3. The description adds extra semantic value by explaining the v3/v4 scope model and why chainId/market/version interact, which helps an agent choose the right combination of parameters.

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 a wallet's Aave transaction history, enumerates the event types, and names the supported protocol versions. It also distinguishes itself from get_user_positions, so an agent can tell which tool answers which question.

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 when not to use this tool ('Use get_user_positions, not this') and gives detailed scope behavior for v3 vs v4, including how chainId and market interact. This is actionable routing guidance, not just a restatement of purpose.

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 annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: chainsCovered/chainsNotServed semantics, v3 vs v4 response shape differences, the meaning of an empty result, and the fact that asking again for a non-served chain returns the same nothing. This meaningfully helps an agent interpret results correctly.

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: the core purpose is front-loaded, and the rest addresses common misunderstandings about chain coverage, empty results, and version-specific outputs. Despite being dense, it contains no filler and reads as a compact set of essential behavioral rules.

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 thoroughly: v4 returns positions with health factors, v3 returns supplies and borrows, and chainsCovered/chainsNotServed are described. It also resolves ambiguity about empty results and directs users to get_markets for token balances, making it complete for an agent to call and interpret the tool correctly.

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

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

Although the schema already covers 100% of parameters, the description goes further by explaining the practical behavior of omitting chainId, the default version behavior, and how version affects the returned structure. It also clarifies the meaning of chainsNotServed in relation to the chainId parameter, which is valuable beyond the schema.

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

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

The description states a specific verb-resource relationship: it returns a wallet's Aave positions (supplies and borrows) on v3, v4, or both. It also clearly differentiates the scope from related tools by noting these are Aave-side positions only and explicitly points to get_markets for wallet token balances.

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 direct usage guidance: omit chainId to cover all served chains, don't loop over chains yourself, and interpret chainsNotServed as 'no market to read' rather than an empty-result answer. It also specifies the alternative tool for wallet holdings, saying 'pass user to get_markets'.

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 substantial behavioral detail beyond the readOnlyHint annotation: it explains the chainsCovered and chainsNotServed fields, how per-row chainId tagging works, the meaning of an empty result on an unsupported chain, the idempotent 'asking again returns the same nothing' behavior, and the v3-specific claim transaction. This is far beyond what annotations alone convey.

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

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

The description is dense but every sentence earns its place, starting with the core purpose and then unpacking edge-case behavior that an agent needs to interpret results correctly. The chainsNotServed explanation is long but necessary because the tool has no output schema to carry this information.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: version coverage, chain coverage fields, per-row chainId, unsupported-chain semantics, and the v3 claim transaction. Combined with the schema's parameter documentation, an agent has what it needs to invoke the tool and interpret an empty or partial result 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 covers all three parameters with descriptions, including the effect of omitting chainId and the default version. The description reinforces these semantics and adds meaningful output-oriented meaning to chainId and version choices, such as covering both versions and tagging each row with its 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?

The description immediately identifies the resource as a wallet's claimable Aave rewards on v3, v4, or both, and clarifies the exact scope including Merit and protocol-native incentives. It explicitly distinguishes this tool from anywhere else a GHO/sGHO incentive might appear, making its purpose unambiguous 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 gives clear context for when to use this tool: for claimable rewards, including Merit-distributed incentives, across selected or all chains. It does not explicitly name sibling tools or state when not to use it, so the exclusion guidance is only implied rather than fully explicit.

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

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

The annotations already mark this read-only, but the description goes beyond them by disclosing subtle behavioral traits: empty results for unsupported chains are not answers, a zero would be misinterpreted as a real balance, and 'marketsWithPosition': 0 means no v3 position anywhere rather than a narrow read. This prevents serious misreadings of the response.

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 longer than average, but every sentence carries distinct, non-redundant guidance. It is front-loaded with the core purpose, then expands into necessary caveats about version differences, chain coverage, and empty-result interpretation. No sentence is filler.

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

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

With no output schema, the description compensates by describing return shapes for both v4 and v3, including key fields like 'chainsCovered', 'chainsNotServed', and 'marketsWithPosition'. It also tells the agent where to go for token balances. This is sufficient 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 baseline is 3, but the description adds meaningful semantics for chainId and version: omitting chainId covers all served chains, unsupported chains yield scope-only replies, v4 returns a cross-chain summary, and v3 returns per-market entries. User is not further enriched, but schema already covers it well.

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

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

Opens with a specific verb-resource pair: 'A wallet's aggregate position and health factor.' It clearly distinguishes itself from related siblings like get_user_positions and get_markets by staking out its exact scope, and it explicitly describes the different v3/v4 output behaviors. An agent can immediately know what this tool does and what it does not do.

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?

States an explicit alternative: 'For what it holds, pass user to get_markets, which returns walletBalance per reserve.' It also gives operational guidance such as not looping over chains, and explains how chainId omission changes coverage. This makes the when-to-use decision 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 this read-only and non-destructive. The description adds useful behavioral context: it is v4-only, covers historical movement over a window, and omitting chainId spans every supported v4 chain. It does not specify return shape or pagination, but for a read-only history tool the added context is meaningful.

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

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

Three short sentences front-load the version constraint and core purpose, then give practical usage guidance and a key chain-scoping tip. Every sentence earns its place 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 four-parameter read-only history tool with no output schema, the description covers purpose, version, scope, and usage context well. It could be more explicit about the return format, but the described metrics and time-window behavior give an agent enough to select and 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?

Schema description coverage is 100%, so the baseline applies. The description mostly reinforces what the schema already says, such as omitting chainId to cover all chains. It adds little semantic value beyond the structured parameter 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: it reports how a single wallet's net worth, supplied, debt, and health factor moved over a time window on Aave v4. The 'over time' framing clearly distinguishes it from snapshot-style siblings like get_user_summary, even though no sibling is named.

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 use cases: 'how has my position changed' and 'how close to liquidation a wallet has been'. It also clarifies chain coverage behavior. It does not explicitly say when not to use it or name a preferred alternative, so it stops short of full exclusions.

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

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

Annotations already mark the tool read-only and non-destructive, and the description adds meaningful behavioral details: it explicitly states no version argument is accepted and why, explains that voted:false is a valid answer rather than an error, and clarifies voting power is denominated in AAVE. These details go beyond annotation structure and set accurate expectations.

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 short sentences, all informative with no filler. The first sentence front-loads a version clarification before the core purpose, slightly delaying the main statement, but overall the structure is efficient and each 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 no output schema, the description covers the essential behavior: result for non-voters, voting power unit, and scope. It does not detail the full response shape for a vote, but that is a minor gap given the tool's simplicity and the annotation coverage.

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 fully documents both parameters (100% coverage), so the baseline is 3. The description adds little parameter-specific meaning beyond restating the wallet/proposal focus; the version note addresses a non-existent parameter, and the AAVE mention pertains to output rather than inputs.

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

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

The description clearly states the tool retrieves how one wallet voted on one Aave DAO proposal and with how much power, using a specific verb-resource relationship. The title reinforces this, and the scope distinguishes it from siblings like get_proposal_votes (all votes) and get_governance_proposal (proposal details).

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

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

The description implies usage by defining the exact scope—one wallet on one proposal—but never explicitly says when to choose this over alternatives such as get_proposal_votes. The version-argument clarification is a parameter note, not a use-case guide, so selection guidance is left to inference.

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

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

Even with readOnlyHint=true, the description adds significant behavioral context: it is non-custodial, commits nothing, free to build, and describes consequences (supply not collateral unless enableCollateral, withdraw of pinned collateral requires repay first). It also discloses that permit fields are only for replaying after approval.

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 dense, front-loading the main purpose and then covering operational pitfalls. Every sentence carries actionable guidance; minor redundancy around collateral and borrowing power appears twice, but it is a deliberate emphasis.

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 13 parameters, no output schema, and a complex multi-version protocol, the description covers version-specific parameter rules, required pre-steps (preview_action, get_markets), post-steps (get_transaction_processed), and common failure modes. Nothing an agent needs to safely call it 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%, but the description adds crucial meaning beyond it: main units vs base units with an example, v4's opaque reserveId cannot be constructed/recalled and what it is not (spokeId), market cannot be recalled, and the logic around when to omit 'amount' (max=true). This strongly compensates and exceeds 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 states a specific verb ('build') and resource ('an unsigned transaction to supply, borrow, withdraw, or repay on Aave (v3 or v4)'). It also differentiates from siblings like preview_action and submit_signed_order, clarifying it returns an execution plan rather than executing anything.

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

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

Explicitly says when to call preview_action first for borrow/withdraw, when to use v3 vs v4 parameters, when to use 'max', 'enableCollateral', and permit fields. It also gives clear exclusions ('Never send permitSignature... on a first call') and mentions polling get_transaction_processed after sending.

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 destructiveHint false, and the description meaningfully adds that this is non-custodial, commits nothing, and returns the exact payload the user signs. It also clarifies the resulting signature must be relayed via cancel_order, which is behavior above what annotations 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, each with a distinct job: version caveat, core function, route selection, and safety commitment. The most decision-relevant information 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 preparation tool, the description fully covers what the tool returns, how it should be used, when not to use it, and what it does not commit. No output schema exists, but the description sufficiently characterizes the return value.

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

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

Schema coverage is 100% and the schema already documents orderId and where it comes from. The description adds no extra parameter semantics beyond saying 'from an orderId'; the baseline of 3 is appropriate because the schema carries the param 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?

The description names a specific verb ('return') and resource (EIP-712 cancellation for an orderId), and clearly differentiates this prepare step from the cancel_order tool that relays it. The 'No version argument' note and the distinction from the transaction route remove ambiguity among sibling 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?

It states exactly when to use this tool: the gasless route for an intent order. It also gives an explicit exclusion: an order that went on chain (native-token sell) should use cancel_order's transaction route instead, which needs no signature and no prepare. This leaves no inference to the agent.

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 the tool read-only and non-destructive. The description adds meaningful behavior: it builds but does not submit an unsigned transaction, is non-custodial, and defaults to claiming all currently claimable rewards when 'ids' is omitted. 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 the key constraints and purpose, and every sentence carries useful information. The 'v4 only' opening and 'V4 rewards' in the next sentence are slightly redundant, but overall it is efficient.

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

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

Given the annotations, full schema coverage, and no output schema, the description covers the important operational context: unsigned/non-custodial nature, default behavior, and v3 alternative. It could mention return-value shape, but no output schema exists and the schema already explains chainId/ids behavior.

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

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

The schema already documents all four parameters (100% coverage), so the baseline applies. The description reinforces the 'omit ids to claim all' behavior and 'v4 only' constraint, but adds little beyond the schema's parameter 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 uses a specific verb ('Build'), resource ('unsigned transaction to claim V4 rewards'), and scope ('v4 only'). It distinguishes itself from get_user_rewards and explicitly states there is no v3 equivalent, so an agent can tell this apart from related 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?

It clearly states this is for v4 reward claims and explains why v3 users should not call it (get_user_rewards already returns the transaction). It does not enumerate all alternative prepare_* tools, but the v3 exclusion and the 'v4 only' qualifier give enough context.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context beyond them: the tool builds an unsigned transaction, is non-custodial, and requires the liquidator to sign and submit. It also discloses the division between v3 and v4 parameter formats, which is valuable behavioral information not present in the annotations.

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

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

Three dense sentences carry the core message without waste: what the tool does, when it is viable, how to check viability, version differences, and custody behavior. The most important information is front-loaded, and there is 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?

Given the tool's complexity (11 parameters, two protocol versions, no output schema), the description covers the essential operational context: the liquidation condition, prerequisite check, version-specific field mapping, and non-custodial execution. It could go slightly further by hinting at the shape of the returned unsigned transaction, but the current level 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, but the description adds useful semantic grouping: v4 uses reserveIds for collateral and debt while v3 uses addresses plus chainId, and it clarifies that the liquidator defaults to the signer on v3. This helps the agent correctly select the version-specific parameter set.

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 ('Build an unsigned transaction') and resource ('liquidate an unhealthy position'), then explains exactly what the operation does: repay debt, receive collateral, and earn the liquidation bonus. It clearly differentiates this from generic prepare_* siblings by naming the liquidation flow and the v3/v4 parameter distinction.

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

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

The description provides an explicit viability condition: only use when the target position's health factor is below 1, and tells the agent to check get_user_summary. It also clarifies version-specific inputs, but does not explicitly mention when to prefer this over other prepare_* tools or what to do if the health factor is above 1.

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 behavior beyond the annotations: it is non-custodial, returns signable material, commits nothing, always uses the v4 backend, and warns against sending signature arguments unless the quote explicitly requested one. This strongly complements the readOnlyHint and destructiveHint annotations without contradicting them.

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: backend version, quote-driven optionality, route-specific behavior, signature discipline, and non-custodial side-effect-free behavior. It is appropriately sized for a tool with complex conditional parameters and contains 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?

Given the complex conditional rules and no output schema, the description covers the key decision logic and side-effect profile well. It could be more complete by explicitly naming submit_signed_order as the follow-up step and describing the exact return shape for the default 'intent' route, but the essentials are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important parameter relationships: permitSignature and permitDeadline only apply once a bySignature permit is signed, route:'transaction' takes no signatures, and signatures must never be sent on a first call. This goes beyond the schema by explaining the orchestration and sequencing of parameters.

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 make clear this prepares an order as typed data or a transaction to sign, with the description emphasizing it 'returns what the user signs' and 'commits nothing.' It is distinct enough from submission tools like submit_signed_order, though it does not explicitly name or contrast sibling 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 gives strong conditional guidance: optional arguments are decided by the originating quote, route:'transaction' applies only to SwapByTransaction quotes, and signatures should never be sent unsolicited. However, it does not explicitly state when to prefer this tool over alternatives such as submit_signed_order or prepare_cancel_order, so that routing is left mostly implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is fully consistent with them. It goes well beyond annotations by disclosing important behavioral nuances: v4 sets state while v3 toggles, disabling is simulated with health-factor-based refusals and warnings, simulation failures are surfaced under 'warnings', and nothing actually moves. This gives the agent a reliable mental model of side effects and failure modes.

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

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

The description is dense but well-organized, leading with the core purpose then layering version nuances, prerequisites, simulation behavior, and warnings. It is longer than average, but nearly every sentence carries needed semantic weight. A small amount of restructuring could improve scannability, but the content 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 tool with no output schema, the description still covers the essential behavioral contract: what the transaction does, what must be true before calling, how different versions behave, how failures are signaled, and that this is non-custodial. Together with the fully described parameters, an agent has enough context to invoke the tool correctly and interpret likely outcomes.

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, but the description adds substantial meaning beyond it. For example, the 'reserve' parameter is explained as opaque, non-constructible, fetchable only from get_markets or get_position_items, with explicit warnings about 'spokeId' and token symbols being rejected. The 'enable' and 'version' parameters also get version-specific behavioral clarification that the schema alone does not fully convey.

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 change whether a supplied asset is used as collateral (v3 or v4).' It clearly distinguishes the tool from generic siblings like prepare_action by naming the exact action, the version-specific semantics, and the requirement that the wallet holds a supply. An agent can tell what this tool does without inspecting the schema.

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

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

The description provides strong context for when to use the tool: it explains the v3 vs v4 differences, the prerequisite that the wallet must already hold supply, and that disabling is simulated first. It does not explicitly name alternative tools or say 'use this instead of X,' but the version-specific guidance and the wallet-holding precondition make the intended usage 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 declare readOnlyHint=true and destructiveHint=false, and the description is consistent: building an unsigned transaction implies no state change. The description adds useful behavioral context beyond annotations, including the eMode LTV/restriction tradeoff, the v3-only constraint, and the categoryId=0 disable behavior.

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

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

The description is front-loaded with the version and core action, and the eMode explanation is valuable. It loses a point for repeating 'v3 only' twice and for slightly over-explaining, but it remains compact and purposeful.

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 and no output schema, the description provides enough context to select and invoke it appropriately: purpose, version constraints, category source, and zero-to-disable behavior. It does not describe the output shape, but 'unsigned transaction' gives a reasonable expectation.

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 mostly restates what the schema already says for categoryId ('from get_emode_categories, or 0 to disable') and does not add substantial new parameter-specific meaning beyond the explanatory eMode context.

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: 'Build an unsigned transaction to switch a wallet's Aave v3 eMode category.' It also clearly scopes the tool to v3 and distinguishes eMode from other Aave actions, so an agent can tell this apart from prepare_set_collateral or 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 when-to-use and when-not-to-use guidance: 'v3 only', 'v4 replaces eMode', and 'Take categoryId from get_emode_categories for that market; pass 0 to turn eMode off.' This tells the agent the prerequisite data source and the disabling behavior clearly.

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 the tool read-only and non-destructive. The description adds valuable behavioral context: the transaction is unsigned and commits the user to nothing, and it explains the ApprovalRequired flow where the approval transaction must be submitted before the original transaction. This goes beyond the annotations without contradicting them.

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 necessary information. It front-loads the constraints, then explains the core action, argument selection rules, and the approval sequence. No filler or repetition.

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

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

For a tool with no output schema, the description is thorough: it covers chain/version constraints, deposit vs withdraw behavior, amount units, max semantics, recipient default, and approval handling. It gives an agent enough context to call the tool correctly and interpret the likely 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?

Even though schema coverage is 100%, the description significantly enriches the parameter meanings. It clarifies that amount is GHO on deposit but sGHO shares on withdraw, that max:true redeems the whole position and requires omitting amount, that recipient is only for a different address, and that deposit requires a GHO allowance. These are essential semantics not fully captured by the schema 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 clearly states the verb and resource: 'Build an unsigned transaction to deposit GHO into the sGHO vault or withdraw from it.' It also scopes to v3 and Ethereum. It does not explicitly distinguish itself from sibling tools like prepare_action, but the specific resource and action make the 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 gives detailed context: v3-only, Ethereum-only, non-custodial, and when to use deposit vs withdraw. It explains conditional argument handling and the approval flow. It does not explicitly name alternative tools or say when not to use this tool, but the guidance is strong and actionable.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses key behavioral traits: it builds an unsigned transaction, is non-custodial, cannot read stkGHO balances or cooldown state, and requires the whole position with no amount input. This materially changes how the agent should interact with the user and what it can promise.

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: constraints first ('v3 only, Ethereum only'), then the action, then the critical caveats. Every sentence contributes essential information, and there is no redundancy with the schema.

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

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

Despite having no output schema, the description gives enough context for an agent to invoke the tool correctly: chain and version restrictions, what the transaction does, what the server can and cannot determine, and how to frame the request to the user. It is complete for a low-complexity tool with one meaningful parameter.

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 parameters themselves are already documented. The description adds useful semantic context by explaining that the tool takes no amount and always acts on the entire stkGHO position, which clarifies the absence of an amount parameter and reinforces the meaning of 'user' as the wallet owner.

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

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

The description uses a specific verb and resource: 'Build an unsigned transaction that moves a wallet's stkGHO out of the Safety Module and into the sGHO vault.' It also states the exact scope ('v3 only, Ethereum only') and the all-or-nothing behavior, which clearly distinguishes this migration tool 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?

The description gives explicit when/when-not guidance: use only on v3 and Ethereum, do not take partial amounts, and build the transaction rather than asking permission first. It also tells the agent to inform the user that the migration covers the whole position and to have the user verify the balance before signing, which is strong 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 mark readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: it commits nothing, returns warnings when an action would not succeed, and reports position limits but not token allowances. It also explains version-specific return fields and the operational meaning of warnings, giving the agent an accurate mental model of the simulation's semantics beyond the annotation flags.

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 decision-relevant information: version-specific arguments, return fields, warnings semantics, and strategic advice to simulate before building. There is no filler or redundant restatement of the schema; the length is justified by v3/v4 complexity.

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

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

With no output schema and 11 parameters, the description carries the full burden: it defines returned health factors for both versions, enumerates v4-only fields, explains the warnings array's operational meaning, and cautions about allowance misinterpretation. This gives an agent everything needed to invoke, interpret, and react to the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable cross-parameter/version grouping ('v4 takes reserve; v3 takes market+token+chainId; max is for withdraw and repay; native works on both; enableCollateral is v4 only'), which goes beyond the individual schema entries and helps the agent select the correct parameter set for the intended version.

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 ('Simulate') and a precise resource ('a supply/borrow/withdraw/repay against a wallet's position', on v3 or v4). The explicit 'WITHOUT executing' contrast makes its role unambiguous and clearly differentiates it from execution-oriented 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?

Provides explicit when-to-use guidance: 'Always do this before a borrow or a withdraw' and 'Simulate first even when you intend to build immediately.' It also tells the agent to fix inputs rather than build when the simulation fails. It does not name an alternative tool explicitly, but the referenced 'prepare step' and execution flow give clear usage context.

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

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

Annotations already establish readOnlyHint=true, and the description adds useful behavioral context beyond that: search results are 'ranked by relevance,' vote tallies are denominated in AAVE, and the tool rejects a 'version' argument due to the DAO governance model. These details help set expectations for the response without contradicting the annotations.

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

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

The description is compact and every sentence earns its place: it clears up a common confusion (no version argument), gives search and filter guidance, explains relevance ranking, and notes vote tally units. It is front-loaded with the most important disambiguation and avoids repetition.

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

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

For a read-only list/search tool with comprehensive schema descriptions and no output schema, the description covers all necessary aspects: what it returns, how to filter, how to search, and when to include summaries. An agent has enough context to invoke it correctly without needing additional details.

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 enriches several parameters: 'state' values are mapped to real-world meanings ('active' is open for voting, 'queued' passed and waiting out the timelock), and 'includeSummaries' includes a practical size tradeoff. This adds value beyond the schema's raw parameter 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 opens with a clear verb and resource: 'List or search Aave DAO governance proposals.' It also distinguishes itself from per-market tools by explicitly stating it takes no 'version' argument and that Governance V3 is unrelated to Aave v3/v4 markets, making it easy to differentiate from siblings like get_governance_proposal.

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 on when to use this tool, such as filtering by 'state' to answer 'what is live right now' or 'what is waiting to execute,' and using 'search' for full-text relevance queries. It does not explicitly mention alternatives like get_governance_proposal for single-proposal lookups, but the 'List or search' framing and the surrounding sibling context make the use case 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 this as non-read-only, idempotent, and destructive/state-changing, so the description adds useful specifics: it posts the order, never signs server-side, and always targets the v4 backend. This clarifies side-effect and security behavior beyond the structured hints.

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 useful information: version behavior, prerequisite input, and state-changing side effect. It is appropriately sized and front-loads an important constraint, though the 'No version argument' phrasing is slightly less direct than it could be.

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

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

For a two-parameter submit tool with no output schema, the description plus annotations cover the core behavior, inputs, and state-changing nature. It does not describe the return shape or post-submission status, but complexity is low and sibling get_order_status provides a follow-up path.

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

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

Schema coverage is 100% and both params already have meaningful descriptions (newQuoteId, EIP-712 signature). The description reinforces that these come from prepare_order's PreparedOrder, but adds no syntax or format details beyond the schema, so a 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?

Description states a specific verb and resource: it relays/posts an already user-signed order. It clearly differentiates from prepare_order by requiring the quoteId+signature from prepare_order's PreparedOrder and by being the state-changing submission step. The sibling context includes many prepare_* tools, making this distinction essential and explicit.

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

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

The description gives clear context: use this after prepare_order once the user has signed, because it relays the signature. It does not explicitly name alternatives or state when not to use it, but the reference to prepare_order's output makes the intended workflow evident.

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