Aave

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

The description discloses meaningful behavioral details beyond the annotations: the gasless route is state-changing, the on-chain route returns a transaction for the user to sign and send, and the server never signs. This significantly clarifies the division of responsibility between the server and user. It does not contradict the provided 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 efficient: the no-version note, core action, route logic, and server-signing boundary are each given in a few concise sentences. Every statement earns its place, and the most important routing 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 state-changing tool with no output schema and two distinct routes, the description covers prerequisites, route selection, and the on-chain route's return behavior. It does not describe the gasless route's success/error output in detail, but annotations cover idempotency and destructive behavior. Overall, an agent has enough context 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic difference between providing 'signature' versus omitting it, tying each route to order types (intent vs native-token sell). This enriches the schema's parameter descriptions rather than merely repeating them.

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

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

The description clearly states the tool cancels an open order, naming the resource and action precisely. It further distinguishes the two execution routes and references prepare_cancel_order, which differentiates this execution step from the preparation step. The title reinforces the purpose as well.

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 route-selection rule: pass 'signature' for the gasless route used by intent orders, or omit it for the on-chain route used by native-token sells. It also implicitly establishes prepare_cancel_order as a prerequisite. However, it does not explicitly name exclusions or alternatives beyond prepare_cancel_order, such as when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds that the tool returns a full capability list and 'records the gap' when a capability is missing, which is useful non-obvious behavior. The 'records the gap' phrasing hints at a side effect not reflected in the annotations, but it reads as telemetry rather than data mutation, so no contradiction is flagged.

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

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

Front-loaded with the core instruction and the fallback behavior before the topic enumeration. The 19-topic list duplicates the schema enum verbatim and is the one wasteful element in an otherwise tight definition.

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

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

Both parameters are optional and fully described in the schema, and the description explains what the tool returns (guidance content or a capability list) despite there being no output schema. Only minor ambiguity remains about the shape and length of the returned guide text.

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

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

Schema description coverage is 100% and the lookingFor parameter is already richly documented in the schema, including when to omit it. The description reinforces topic selection ('Read the relevant topic') and lists topic names, but the list merely duplicates the enum, so it adds little beyond structured fields.

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

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

States a specific verb+resource: protocol and usage guidance for building Aave flows, with an enumerated topic set. It is clearly differentiated from every sibling, all of which are data-fetch or action-preparation tools, and it additionally declares itself the fallback when no sibling fits.

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

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

Gives explicit timing: 'Read the relevant topic before constructing an action,' plus an explicit alternative path ('send lookingFor' when no tool seems to fit) with the condition that selects it. It also routes deep protocol questions out to docs.aave.com, so the agent knows when not to use this 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 mark it read-only and non-destructive. The description adds meaningful behavioral detail beyond that: the return format (time-series of {date, apyPct}), the meaning of apyPct as a percent, the averaging semantics per sampling interval, and the warning that series are not directly comparable to instantaneous rates. 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 appropriately sized—every sentence carries information: purpose, return format, sampling semantics, usage prerequisite, and migration caveat. It is front-loaded with the core purpose and structured logically, with no redundant or filler content.

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

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

For a tool with 7 parameters and a v3/v4 split, the description covers everything an agent needs: how to obtain the required identifiers, which parameters apply to which version, the return format (no output schema, so this is essential), and the comparison caveat. 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%, so the baseline is 3. The description adds value by explaining the v3/v4 selector relationship (reserveId vs market+token+chainId) and advising to use get_markets first, which helps agents assemble the correct parameter set. It doesn't detail every parameter, but the schema already does, so this exceeds the 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 action (get historical APY) on a specific resource (a reserve's supply or borrow rate), scoped to v3 or v4, and explicitly distinguishes itself from the instantaneous rate tool get_reserve_details. The verb-resource combination is clear and unambiguous.

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

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

It gives concrete prerequisites ('Use get_markets first for the reserveId (v4) or market+token (v3)') and explains when to use this tool versus the alternative (spot-rate comparison with get_reserve_details, and migration comparison guidance). The when-to-use is explicit and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the asset spans multiple reserves, supply/borrow include an APY spread, and a wide gap between highestApyPct and lowestApyPct is meaningful rather than noise. 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 longer than average, but every sentence carries substantive information: scope, metric semantics, differentiation from get_apy_history, and token-address lookup guidance. It is front-loaded with 'v4 only' and the core definition, so an agent gets the essential meaning early.

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, a complete schema, and read-only annotations, the description covers what an agent needs: cross-reserve behavior, metric meanings, the v4-only restriction, token address sourcing, and how it differs from the nearest sibling. No critical gap remains 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?

The input schema fully documents all parameters, so the baseline is 3. The description adds semantic depth to the 'metric' parameter by explaining exactly what each value means (oracle price per sample vs. amounts plus APY spread), which exceeds the schema's short enum labels.

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

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

The description states a specific verb and resource: retrieving one asset's price, supply, or borrows over time on v4. It further clarifies that the asset is tracked across every v4 reserve that holds it, and explicitly distinguishes this from get_apy_history, making the purpose precise and non-confusable with siblings.

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

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

The description gives explicit when-to-use guidance: it directly contrasts with get_apy_history and explains why the two questions differ. It also gives actionable routing advice for obtaining a token address, warning that get_markets does NOT return one and pointing to get_multichain_asset and get_hub_assets instead.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses important runtime behavior: notServed chains return empty market, position, and rewards reads, gateway addresses read 0x0, and transactions to such gateways should not be sent. This materially changes how an agent should interpret and act on results. 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 front-loaded with the core purpose in the first sentence, and each subsequent sentence adds a distinct, safety-relevant behavior. There is no filler or redundant restatement of the tool name.

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

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

For a read-only list tool with one optional parameter and no output schema, the description explains both the returned flag semantics and the practical consequences for downstream reads/transactions. This is enough for an agent to call the tool correctly and interpret its results without additional documentation.

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

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

Schema coverage is 100%, with the version parameter already documented as an enum of v3/v4/all and default all. The description only restates this as 'on v3, v4, or both,' adding no new parameter-level semantics. Baseline 3 is appropriate because the schema carries the full parameter burden.

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

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

The description opens with a specific verb and resource: 'List chains Aave supports, on v3, v4, or both.' This clearly distinguishes the tool from sibling get_* tools by its unique chain-list resource and version scope. The title reinforces the intent without ambiguity.

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

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

The description implies when to use it—when an agent needs the list of chains and their served/not-served status—but it does not explicitly name alternatives or state when not to use it. The rich flag explanation gives clear context for interpreting results, but no exclusionary guidance relative to sibling tools is provided.

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 annotations, it discloses that markets with no matching category are omitted, that unfiltered queries return every category on every chain, and that responses can be large enough to make 'symbols' strongly preferred. There is no contradiction with the read-only annotation.

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

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

The description is focused and every sentence earns its place: version gating, eMode behavior, return fields, filtering advice, and the v4 exclusion. There is no repetition of schema content and 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?

With no output schema, the description compensates by itemizing the returned fields (categoryId, LTV, liquidation thresholds, symbols) and explaining the omission behavior. It also covers parameter behavior and version constraint, leaving an agent with enough to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics: symbols is case-insensitive and strongly preferred for large chains, chainId omission covers all chains, and the return value includes the categoryId that feeds prepare_set_eMode plus LTV and thresholds.

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

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

The description names a specific resource ('eMode categories'), a specific verb ('Returns'), and the exact scope ('v3 only'). It distinguishes itself from siblings by explicitly calling out prepare_set_emode as the consumer of its categoryId and by noting v4 has no 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?

It gives clear when-and-how guidance: use it to discover eMode categories, LTV, and thresholds for v3, narrow the response with 'symbols', and omit chainId for all chains. It also says v4 should not use this tool, but it does not explicitly name other tools as alternatives for non-eMode reserve data.

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

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

Beyond the readOnlyHint annotation, the description discloses substantive behavioral details: the returned condition fields 'quorumMet' and 'differentialMet', the fact that vote tallies and quorum are denominated in AAVE and directly comparable, and the IPFS omission behavior controlled by includeDescription. This prepares the agent to interpret the result and understand returned data semantics.

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 earns its place: the first preempts a common misuse, the second states the tool's purpose and return content, the third explains pass conditions, and the fourth clarifies IPFS handling. The description is compact, front-loaded, and free of 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?

Even without an output schema, the description compensates by listing the key response elements, explaining units and pass conditions, and flagging the optional heavy payload. Combined with the well-described parameters and read-only annotations, an agent has enough to invoke the tool correctly and interpret the result.

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

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

Schema coverage is 100% and the parameter descriptions are already rich, so the baseline is 3. The description adds value by warning not to pass a 'version' argument at all, which prevents a plausible parameter hallucination, and by explaining the includeDescription behavior in context. It mostly complements rather than expands the schema, hence a 4 rather than 5.

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

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

The description clearly identifies the resource and verb: 'Full detail for one Aave DAO governance proposal' and enumerates what is included (state, author, vote tallies, quorum, timings, transaction hashes). It also disambiguates from market-specific governance by explicitly stating 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 useful exclusion guidance: it takes no 'version' argument because DAO governance is not per-market, which prevents a common misuse. It implies this tool is for retrieving one proposal's full detail, but it does not explicitly name alternative sibling tools such as search_governance_proposals or get_proposal_votes, so it stops short of the strongest routing guidance.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral context by clarifying this is v4-only, hub-level accounting, and that it returns aggregate supplied/borrowed totals, rates, and utilisation. 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?

Three compact, front-loaded sentences. The v4-only constraint is placed first, followed by what the tool returns, how to obtain the required parameter, and when to choose an alternative. 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?

Given the simple parameter set, read-only annotations, and the absence of an output schema, the description fully covers what the tool returns, how to get the required input, and when to avoid it in favor of get_markets. Nothing essential 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 already documents both parameters fully, so baseline is 3. The description adds value by clarifying where to get hubId (from get_hubs or hubAddress on get_reserve_details) and reinforcing that the version parameter is optional because the tool only exists on v4.

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

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

States a clear verb and resource: get the assets held by one Aave v4 hub, including supplied and borrowed totals, rates, and utilisation. It also distinguishes itself from get_markets by explicitly marking this as hub-level accounting.

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 guidance: use get_hubs (or get_reserve_details) to obtain the hubId, and use get_markets instead when the agent needs per-spoke user-level supply/borrow data. This makes the appropriate context and alternative crystal 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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the conceptual role of a hub, the return fields, the chain-scoping behavior, and the sibling routing. This goes meaningfully beyond what annotations alone provide.

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

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

Three focused sentences with no filler. The v4-only constraint is front-loaded, followed by the core definition, return contents, sibling guidance, and optional parameter behavior. 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 simple read-only tool with two optional parameters, the description is complete: it explains what a hub is, what the tool returns, how to restrict by chain, and where to go for hub assets. No output schema exists, but the description states the return fields sufficiently. The annotations and schema cover the remaining context.

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

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

Schema description coverage is 100%, so both parameters are already well documented. The description reinforces chainId behavior and the v4-only constraint, but does not add substantial new parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Returns') with a clear resource ('Aave v4 hubs') and the exact fields returned (hubId, address, chain, totals). It also differentiates itself from the sibling get_hub_assets by explicitly routing hubId lookups there, making the tool's 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?

Provides explicit usage guidance: 'v4 only', 'Omit chainId to cover every supported v4 chain', and points to get_hub_assets as the alternative when a specific hub's assets are needed. This clearly tells the agent when to use this tool versus a closely related sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context: it provides actual curve points used by the protocol, and explains how to interpret the curve (kink location, steepness, hypothetical rates). 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 front-loaded with the core purpose and structured logically: what it returns, why it's useful, when to use it, and how to get the parameter. Every sentence earns its place without redundancy, balancing clarity with brevity.

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 one required parameter and no output schema, the description fully covers what, why, when, and how. It explains the output nature (points on the curve), the practical use case, and the parameter source. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters (version enum and hubAssetId source). The description repeats that hubAssetId comes from get_hub_assets but adds no new information beyond the schema. Baseline 3 is appropriate since the schema already carries the semantic load.

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

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

The description clearly states the tool returns the rate curve for a hub asset, explaining borrow and supply APY across utilisation levels. It distinguishes itself from get_reserve_details by emphasizing it explains the curve rather than reporting a single point, making its purpose unambiguous and differentiated from 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?

Explicitly instructs when to use: before a large supply or borrow that would shift utilisation. Names the alternative get_reserve_details and explains why it's insufficient for large positions. Also directs the user to get_hub_assets for the correct parameter source, leaving no ambiguity about 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 declare readOnlyHint=true, and the description is consistent while adding substance the annotations can't: it explains the flash-loan/swap/supply/draw mechanics, that nothing is committed until the user signs, and what comes back (quoteId, approvals, maxSafeMultiplier). The maxSafeMultiplier constraint on a requested multiplier is exactly the kind of behavioral limit an agent needs before calling.

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

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

Four dense sentences, front-loaded with the version constraint and the core action, each carrying operational information (reserve selection rule, return contents, signing semantics). Slightly heavy as a single block, but nothing is padding.

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

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

For an 8-parameter tool with no output schema, the description covers the missing piece — the shape of the response (quoteId, approvals to sign, maxSafeMultiplier) — plus prerequisites and the follow-on tools that consume the quoteId. An agent has everything needed to call this correctly and use 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 earns above that by adding cross-parameter meaning the schema cannot express — the two reserves must be on the same spoke and satisfy the 'quotableAs' pair constraint, and the requested multiplier must stay under maxSafeMultiplier. It doesn't restate the optional params (slippagePct, enableCollateral, additionalCollateral), but the schema covers those fully.

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

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

States a specific verb and resource ('Quote opening or increasing a leveraged position in one atomic order') and immediately distinguishes itself from the swap/repay quote siblings by naming the leverage loop. The 'v4 only' scope is front-loaded, so an agent knows both what it does and where it lives.

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

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

Gives real selection guidance: both reserves must come from get_markets in this session, on the same spoke, with debtReserve listing leverageDebt in 'quotableAs' and collateralReserve listing leverageCollateral. It also routes downstream ('feeds preview_action and prepare_order') and clarifies the quoting-vs-committing boundary. It does not explicitly name the sibling quote tools it replaces (get_swap_quote, get_position_swap_quote), so no exclusion 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, so safety is covered. The description adds useful behavioral context: it is v4-only, rejects mismatched scope/id combinations ('wrong one is rejected'), and clarifies that IDs are not addresses. This goes beyond what annotations provide, though it does not discuss output shape or pagination.

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: version, output metrics, hub/spoke distinction, ID provenance, rejection warning, and explicit alternatives are all packed in without redundancy. It is front-loaded with the essential purpose and scales up with useful guidance.

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

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

For a read-only history tool with no output schema, the description covers the critical selection pitfalls (scope, id source, version) and routes to related tools. It does not describe the return value format, which is a minor gap given the name implies a time series, but the core decision factors are fully addressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the conceptual difference between hub and spoke ('hub is the liquidity itself... spoke is one venue onto that liquidity') and where to source each ID. This helps agents select and populate parameters correctly beyond the schema's enum 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 immediately states the exact resource and metrics ('Deposits, borrows, available liquidity and utilisation over a window, for one hub or one spoke') and distinguishes it from sibling tools by naming get_protocol_history, get_apy_history, and get_asset_history as alternatives. This removes any ambiguity about the tool's 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?

Provides explicit when-to-use guidance: hub vs spoke semantics ('hub is the liquidity itself... spoke is one venue onto that liquidity'), where to get IDs (get_reserve_details, get_hubs, get_user_positions), and when to prefer alternatives. Also cautions against using a non-existent position ID when evaluating a new venue, which 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?

Annotations only establish that this is a safe read operation; the description adds substantial behavioral context beyond them, including chain coverage semantics, the v3/v4 coverage asymmetry, empty-result interpretation for 'chainsNotServed', rate units, conditional flags, and v4 spoke/hub row 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 dense and long, but it is front-loaded with the core purpose and every block conveys non-obvious behavior needed to interpret this complex tool without an output schema. It could be easier to scan with bullets, but there is little empty 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 four optional parameters, no output schema, and fairly complex v3/v4 chain and reserve semantics, the description covers the return shape, field meanings, edge cases, and cross-tool field mappings thoroughly. An agent has enough context to call it correctly and interpret the result.

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

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

Although schema coverage is already 100%, the description adds non-obvious parameter interactions: 'symbols' expands v3 coverage beyond Ethereum, omitting 'chainId' produces 'chainsCovered'/'chainsNotCovered', and 'user' changes every row with wallet-specific fields. These are meaningful semantics beyond what the schema states.

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

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

The description opens with a specific verb and resource ('List Aave markets/reserves') and names the returned fields, versions, and scope. An agent can tell immediately that this is the market/reserve listing tool rather than a details, history, or quote tool.

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

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

It gives explicit parameter-driven usage conditions: pass 'symbols' and omit 'chainId' to compare one asset across chains, and pass 'user' when the question is about wallet capabilities. It also warns against ranking on APY alone, but does not explicitly name an alternative tool to use for deeper reserve-level questions.

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 useful behavioral context beyond them by restricting to v4, explaining that omitting chainId covers every v4 chain, and telling the agent the response includes 'chainsCovered.' 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?

Four sentences with no filler. Scope, output content, use cases, alternative routing, boundary, and optional-parameter behavior are all front-loaded, and every sentence adds distinct value.

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?

Even without an output schema, the description names the substantive response components: supplied/borrowed amounts, per-chain rates, best-rate summary, and chainsCovered. It also explains exactly how to invoke the tool, covering selection and behavior well enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by explaining the practical behavior of omitting chainId ('cover every chain v4 serves') and reinforcing that version only accepts v4. This complements rather than merely repeats 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 and resource: 'One asset across every v4 chain at once, by symbol,' and enumerates the outputs (supplied, borrowed, rates, best supply/borrow summary). This clearly distinguishes it from asset-level versus wallet-level tools like get_wallet_balances and per-chain tools like get_markets.

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

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

It explicitly names the use cases ('where should I supply USDC' and 'is this cheaper to borrow somewhere else'), calls out get_markets as the alternative requiring per-chain calls, and states the boundary: 'It answers about the asset, not about a wallet.' This gives an agent clear selection criteria.

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

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

Beyond the readOnlyHint annotation, the description discloses the null behavior, the ambiguity between a wrong id and a just-submitted order, and the advice to poll again briefly. It also mentions what the response contains: status, operation, and explorer link.

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 information-dense, covering status values, response contents, and null semantics in two sentences. The opening 'No version argument' is slightly cryptic but does not waste much space.

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 one-parameter read-only tool with no output schema, the description covers the return elements and the key edge case. It could be more complete by describing the exact response shape, but the essential information an agent needs to call and interpret the tool is present.

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

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

The input schema already fully describes the single orderId parameter, and the description adds little beyond restating that the lookup is by id. Schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

States clearly that it retrieves the status of a single order by id, enumerating the possible status values. It is unambiguous against sibling list tools like get_pending_orders, though it does not explicitly name any alternative.

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

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

Provides concrete usage guidance about null results: a null order can mean either a bad id or a recently submitted order, so the agent should poll again before treating it as nonexistent. It gives clear context for the read operation, but does not discuss when to prefer a sibling tool.

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

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

Even with readOnlyHint=true and destructiveHint=false present, the description adds substantial behavioral detail: v4 backend coverage, chainsCovered/chainsNotCovered semantics, default status behavior, the 50-order per-chain cap, and the 'more' pagination flag. This is far beyond annotation-only transparency.

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 distinct information: backend scope, order ordering, status behavior, per-chain limits, and intended use. There is no filler or unnecessary repetition of schema fields.

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 adequately explains the response contract: chain coverage fields, per-chain newest-50 limit, the 'more' flag, and status filtering. This is sufficient for an agent to understand what results to expect and how to detect incomplete chains.

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 all three parameters at 100% coverage, so the baseline is 3. The description adds extra value by recommending a specific statuses value for actionable orders and by clarifying the default behavior ('returns every status'), which helps an agent choose the right argument combination.

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

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

The description states a specific action and resource: listing a wallet's orders, newest first. It immediately disambiguates the misleading name by noting all statuses are returned by default, and it specifies the exact use case of recovering a lost orderId, which distinguishes it from singular tools like get_order_status.

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

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

It gives a concrete when-to-use instruction ('Use this to recover an orderId you no longer have') and tells the agent to pass ['open','pending_signature'] for actionable orders. It does not explicitly name alternatives or state when not to use the tool, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavioral facts: v4-only availability, per-item granularity the aggregate cannot provide, and the conditional presence of 'quotableAs' (absent when the item can enter neither route). Return shape and pagination are not covered, keeping it short of a 5.

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

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

Front-loaded with the v4 constraint and the core differentiator, then the identifier-to-downstream-tool mapping. Dense but every clause carries routing or interpretation value; the single long sentence is slightly harder to scan than a split structure would 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?

With no output schema, the description carries the return-value burden and does: principal, accrued interest, withdrawable amount per item, plus the meaning of positionItemId and quotableAs. It also explains where the required spokeId comes from. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema description coverage is 100%, so 'side', 'user', 'spokeId' and 'version' are already documented, including the enum values. The description reinforces the spokeId provenance but largely restates what the schema says, so the baseline 3 applies.

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

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

States a specific verb/resource tuple — the individual supply or borrow items inside one v4 spoke — and explicitly contrasts it with the per-spoke aggregate returned by get_user_positions. An agent can distinguish it from the sibling without opening any schema.

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

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

Names the prerequisite call ('Get spokeId from get_user_positions'), the hard scope constraint (v4 only), and the downstream consumers (get_position_swap_quote's sellPosition, get_repay_with_supply_quote's debtPosition) selected via 'quotableAs'. It also states when an item cannot be used for either route.

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 reinforces this with 'Nothing is committed until the user signs' and adds a workflow norm ('state the plan rather than asking permission to quote it'). It does not cover quote expiry/lifetime or rate-limit characteristics, so it stops just short of full behavioral disclosure.

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

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

Front-loaded with the v4-only constraint and the two-kind distinction, then dependencies, then downstream use, then the behavioral note. Every sentence carries actionable information and nothing is redundant.

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

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

Covers scope, prerequisites, downstream wiring, and safety posture for an 8-parameter quote tool. With no output schema, it only lightly implies the return shape (quoteId) and says nothing about the quote's other fields such as the suggested slippage or expected rates, which is a minor remaining gap.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds real value by tying sellPosition and buyReserve to their source tools and by stating the same-spoke constraint and the quoteId-to-prepare_order linkage. It restates kind semantics already in the schema, so the gain is incremental rather than substantial.

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

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

States a specific verb and resource ('Quote swapping one Aave v4 position for another, atomically and without leaving the protocol') and immediately disambiguates the two modes: kind=supply swaps collateral, kind=borrow swaps debt. It is clearly distinguishable from token-swap siblings like get_swap_quote.

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 names the upstream dependencies (get_position_items for sellPosition, get_markets for buyReserve) and the gating fields (quotableAs: supplySwapFrom/borrowSwapFrom, supplySwapTo/borrowSwapTo), plus the downstream consumer (prepare_order via quoteId). It does not explicitly contrast with get_swap_quote or get_repay_with_supply_quote, which would have completed the routing guidance.

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

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

Annotations already mark the tool readOnly and non-destructive, and the description adds meaningful behavioral context beyond them: the output includes each payload's execution state, timelock delay, grace period, and contract calls, and cross-chain execution can be inconsistent (e.g., executed on mainnet but queued elsewhere). This 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 composed of three sentences, each earning its place: one dispels a common parameter misconception, one defines the tool's core resource, and one gives the primary use case. It is front-loaded with the most decision-relevant information 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?

With only one parameter and no output schema, the description carries full responsibility for explaining what the tool returns. It adequately covers the return contents (execution state, timelock, grace period, contract calls) and the cross-chain interpretation. The information given is sufficient for an agent to select and call this tool appropriately.

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 proposalId parameter is already well documented. The description adds extra semantic value by explicitly stating the tool takes no 'version' argument, preventing an agent from mistakenly supplying one. It also reinforces that the proposal ID comes from search_governance_proposals, though that is 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 the tool retrieves an Aave DAO proposal's payloads, explaining what payloads are (per-chain execution packages with state, timelock, grace period, contract calls). It distinguishes itself from sibling tools by explicitly noting it takes no 'version' argument and that DAO governance 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 provides an explicit use case: 'Use this to tell whether a passed proposal has landed on every chain yet.' It also clarifies a common source of confusion (the version argument). However, it does not explicitly name alternative sibling tools such as get_governance_proposal or get_proposal_votes, so the guidance is clear but lacks explicit exclusions.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral detail: vote ordering (largest voter first), the effect of the support filter, that 'totals' reflects all votes across pages rather than just the returned page, and that voting power is expressed in AAVE. This gives the agent expectations that are not derivable 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?

Every sentence in the description earns its place: it clarifies version absence, defines the core output, explains the support filter, clarifies pagination semantics of 'totals', and states the unit of voting power. The most important disambiguation 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 list tool with no output schema, the description provides enough to call it correctly: input requirements, filtering, ordering, pagination-aware totals, and units. OpenWorldHint is false, and the described behavior fully covers the agent's likely decision needs.

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 describes all parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying that no version argument should be passed, that support=true/false lists one side, and that voting power is denominated in AAVE. These are useful semantic details beyond the field names and schema 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 the exact resource ('votes on an Aave DAO proposal') and the specific data returned (who voted, with how much power, largest voter first). It also proactively distinguishes itself from governance versioning confusion by stating it takes no 'version' argument and that DAO governance 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 for when to use the tool: to discover who voted on a proposal and with what voting power, and how to narrow to one side with support. It also excludes a common misuse by noting DAO governance is not per-market, but it does not explicitly name sibling alternatives like get_governance_proposal or get_user_vote for other use cases.

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 that: it is v4-only, returns per-sample data over a time window, and is protocol-wide rather than wallet- or reserve-scoped. It does not describe output shape or pagination, but this is minor for a read-only query 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 tightly packed sentences with no filler. The most important scoping fact ('v4 only') is front-loaded, followed by the key metrics, then clear routing guidance. Every sentence earns its place.

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

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

For a read-only, zero-required-parameter history tool, the description provides everything needed to select and invoke it correctly: scope, metrics, time-window concept, cross-chain behavior, and sibling differentiation. The annotations cover safety and the schema covers parameter details, 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 coverage is 100%, so the schema already documents all three parameters in detail. The description reinforces key semantics like omitting chainId for all chains and the per-sample window concept, but it does not add substantial meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('get'), resource ('protocol-history'), and scope ('Aave v4 protocol-wide history') with concrete metrics: market size, total borrows, available liquidity. It explicitly distinguishes itself from sibling tools get_user_summary_history and get_apy_history, making it immediately clear what this tool is and is not.

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

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

The description gives explicit usage direction: 'Use this for "is the protocol growing"' and names the exact alternatives to use instead for wallet-level or reserve-level history. It also clarifies how to cover all chains by omitting chainId, leaving no ambiguity about invocation 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 is consistent while adding real context: the operation is atomic, the health factor never dips in between, and nothing is committed until the user signs. It even sets the expected agent behavior ('state the plan rather than asking permission to quote it'), which 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 version constraint is correctly front-loaded and every sentence carries information, but the middle sentences are dense with chained prerequisites and would benefit from clearer separation between id-discovery and invocation guidance. No filler, though.

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 quote tool with no output schema, it covers the workflow handoff (quoteId -> prepare_order) and the non-commitment guarantee, which is what an agent needs to act. It does not describe what the returned quote contains (prices, slippage application, resulting health factor), a minor gap given there is no output schema to fall back on.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description goes further by identifying the source tool and filter for each id (positionItemId from get_position_items with side=borrow and quotableAs repayDebt; reserveId from get_markets with quotableAs repayWith) and the 'same spoke' constraint. That is meaning the schema does not carry.

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 and resource ('Quote paying down a borrow using supplied collateral') plus scope and a distinguishing mechanism ('atomically and without the funds leaving Aave'). An agent can separate it from get_swap_quote, get_position_swap_quote and preview_action without opening any schema.

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

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

Explicitly names the alternative it replaces ('Use this instead of withdraw-swap-repay by hand') and the reason (single atomic step, health factor never dips). It also documents prerequisites for each id (get_position_items side=borrow whose quotableAs lists repayDebt; get_markets quotableAs listing repayWith, same spoke) and the downstream step ('quoteId feeds prepare_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 declare readOnly/non-destructive, yet the description goes far beyond them: unit conventions ('3.32' means 3.32%, Pct suffix), v4 hub-wide vs per-spoke utilisation semantics, and explicit warnings about two misleading fields. The note that collateralFactorPct is the liquidation boundary itself ('do not look for one') and that liquidityFeePct is already netted out of supplyApyPct is exactly the interpretive context an agent cannot get from structured fields.

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

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

The purpose and field inventory are front-loaded, and most sentences carry non-obvious payload (hub-wide semantics, fee netting, price location). It is dense and runs long, with the price/'quotableAs' material reading as a slight digression from the core field semantics, but nothing is purely 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 carries the full burden and does so: it enumerates the returned field groups, fixes the unit convention, flags the two counterintuitive fields with formulas, and tells the agent where the price lives. An agent can interpret the response without further tooling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that the version is inferred from the selector (reserveId vs market+token+chainId), that reserveId must be copied verbatim from get_markets, and that v3-only params are mutually exclusive with v4 usage. It does not elaborate on chainId or market formatting beyond the schema, keeping it at 4 rather than 5.

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

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

Opens with a specific verb+resource plus an enumerated field list ('rates, caps, risk parameters, utilisation, the interest-rate curve, token addresses') scoped to 'a single reserve... on v3 or v4'. Directly distinguishes itself from get_markets by stating that tool carries no price at all. An agent can tell what it returns without opening the schema.

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

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

Gives an explicit prerequisite/ordering rule ('Use get_markets first to get the reserveId (v4) or market+token (v3)') and routes price lookups here while denying it to get_markets. It stops short of stating when NOT to reach for near-neighbours like get_interest_rate_model or get_aave_guide, so it is clear context rather than full when/when-not coverage.

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

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

The description adds meaningful behavioral details beyond the readOnlyHint/destructiveHint annotations: results are ordered largest first, the token is named once for the whole list, and an empty list means no indexed holders on that side rather than an error. These details help the agent interpret responses correctly without an output schema.

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

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

The description is front-loaded with the most important scope and version constraint, and each sentence carries useful information. The reserveId sentence is slightly redundant with the schema, and the token-naming detail could arguably live in an output schema, but the overall length is reasonable and organized.

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

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

Given no output schema, the description does well to explain ordering, the single-token naming behavior, and the empty-list error semantics. It does not spell out the exact fields returned per wallet, but this is a relatively simple list tool and the schema plus description cover the essential calling context adequately.

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 five parameters. The description's only param-related contribution, pointing to get_markets or get_position_items for reserveId, is also already present in the schema description. Thus the description adds little semantic value beyond the input schema.

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

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

The description states a specific verb and resource: listing the biggest wallets supplying or borrowing a v4 reserve, sorted largest first. It clearly centers on concentration questions, which distinguishes it from the many other get_* siblings. The title and first sentence together make the tool's purpose immediately recognizable.

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 use this tool for concentration questions, such as whether one address holds most of a reserve's liquidity or debt. It also notes the v4-only constraint and tells the agent where to obtain reserveId. It does not name specific alternative tools or exclusion cases, but the usage context is clear.

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

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

Annotations already mark this as read-only and non-destructive. The description adds significant context: it explains the meaning of the two weight fields (current vs latest) and that their difference indicates a repriced position that hasn't caught up, affecting the borrow rate. This goes beyond the annotations by revealing the interpretive insight. However, it does not mention potential edge cases (e.g., missing collateral) or the exact output structure beyond these fields.

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

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

The description is dense yet efficient. It leads with 'v4 only' to set scope, then states the purpose, explains the two key fields, gives a use case, and ends with a parameter dependency. Each sentence serves a distinct purpose with no filler. The structure is logical and front-loaded with the most critical constraint.

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 compensates by explaining the two key output fields (currentRiskPremiumWeightPct and latestRiskPremiumWeightPct) and their behavioral meaning. It also covers the use case and parameter provenance. It does not describe the full output shape (e.g., whether it returns a list or single object), but for a read-only tool with clear annotations, the provided context is largely sufficient.

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

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

Schema coverage is 100% for required parameters (user and spokeId have descriptions, version has an enum). The description adds a crucial hint: spokeId comes from get_user_positions, which is not in the schema. This dependency clarification goes beyond the schema and helps the agent source the correct value. No additional syntax or format is needed beyond what the schema provides.

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

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

The description clearly states the tool's function: it provides a per-collateral breakdown of a position's risk premium, including token composition and protocol weight. It also specifies the version (v4 only) and differentiates from reserve headline rates by explaining the use case for why a borrow rate might deviate. This distinguishes it from related tools like get_reserve_details or get_interest_rate_model.

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 states when to use this tool: 'Use it to answer why a v4 borrow costs what it does when the reserve's headline rate says otherwise.' It also notes that spokeId comes from get_user_positions, indicating a prerequisite and source. It does not name alternatives but provides a clear trigger scenario, which is sufficient for a niche tool.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing the data source, the read:false error state and its proper interpretation, the dynamic reward APY behavior, the USD oracle-price basis, and the staking-versus-supplying distinction. This is rich behavioral context that an agent needs to avoid misreporting results.

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

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

The description is long but every sentence carries a distinct, decision-relevant fact. It front-loads the product, scope, and return structure, then layers caveats about pricing, APY, and error interpretation in a logical order.

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

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

With no output schema, the description fully carries the burden of explaining return values and error behavior. It covers umbrella and legacy contents, user-scoped additions, the read:false failure mode, reward APY semantics, and USD pricing, leaving nothing essential for correct invocation or interpretation missing.

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

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

The single 'user' parameter is already fully documented in the schema with 100% coverage, so the schema does the heavy lifting. The description adds only a slight nuance about the parameter affecting both umbrella and legacy generations, which is useful but not a substantial semantic addition.

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 product and scope ('Aave's Safety Module, Ethereum only') and states it is read from contracts rather than the Aave API. It then enumerates the two returned generations, making the tool's operation and output unmistakable.

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

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

The description gives clear context on when to use the tool: it is Ethereum-only, contract-sourced, and should be included in portfolio answers because staking is part of a wallet's Aave position. It also explains exactly when to pass 'user'. It does not explicitly name an alternative sibling tool, but the guidance is strong enough for an agent to route correctly.

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

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

Annotations already establish read-only, non-destructive behavior, and the description reinforces this with 'without building anything.' It adds meaningful behavioral context beyond annotations by disclosing that the vault index is live and moves, explaining the unit-of-amount asymmetry, and warning that a GHO figure in a withdraw would withdraw the wrong amount. This is exactly the kind of context 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?

Four dense sentences, each serving a purpose: constraints, core behavior, unit semantics, and call-order/rate warnings. Front-loaded with 'v3 only, Ethereum only,' and no filler. The one mild redundancy with the version schema is negligible.

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 two required parameters and no output schema, the description fully specifies both action directions, the correct amount denomination, the prerequisite ordering for withdrawals, and why not to use a static rate. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%: the action and amount properties already state which unit applies to each action. The description restates this relationship but does not add new parameter-level meaning beyond the schema; it merely reinforces what is already documented.

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

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

The description states a precise verb ('Convert') and resource (GHO/sGHO shares at the vault's current index), and explicitly disclaims building actions: 'without building anything.' It also distinguishes itself from sibling prepare_sgho_action by instructing when to call it for withdrawals, making the tool's unique role unmistakable.

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

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

Provides explicit when-to-use guidance: 'Call this with action withdraw before prepare_sgho_action' and 'When quoting what a user-named amount converts to, use this preview rather than multiplying by the rate.' It names the incorrect alternative (multiplying by the rate) and explains why it fails: 'the index moves.'

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 readOnly/destructive, but the description adds substantial behavioral nuance: governance-set rate vs utilisation, campaign incentive APR semantics, no Aave collateral or borrowing, and instant no-cooldown deposits/withdrawals. This goes well beyond the structured hints and gives agents a reliable model of the vault.

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 first sentence front-loads scope, and subsequent sentences add value rather than padding. It is longer than necessary for a simple read, but the extra context about APRs and collateral status is relevant and earned.

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 lacking an output schema, the description enumerates the important returned fields and explains the present/absent campaign APR fields, user-specific values, and non-obvious semantics. An agent has enough information to call the tool and interpret the response.

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 both parameters, but the description enriches 'user' by specifying what it adds (shares, GHO value, wallet balance, maxDeposit/maxWithdraw) and reinforces 'version' as v3-only. This exceeds the baseline for high 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?

Opens with 'v3 only, Ethereum only' and identifies the tool as the sGHO ERC-4626 vault reader, then lists exactly what it returns (targetRatePct, totalAssets, supplyCap, paused flag). This is a specific verb+resource definition that distinguishes it from generic vault tools like get_vaults.

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

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

Clear context on when to pass 'user' vs omit it and that it is v3-only, with an explicit scope constraint. It stops short of naming sibling alternatives or stating when to choose another tool, so not a full 5.

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

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

Annotations already carry the read-only, non-destructive safety profile, so the bar is lower. The description adds real interpretive value: the distinction between 'halted' (stops supply, borrow, withdraw, and repay alike) and 'not active' (never configured on that spoke), which prevents an agent from conflating two very different states in 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?

Four sentences, each carrying distinct information: version scope and purpose, usage trigger, flag semantics, and parameter provenance. The core purpose is front-loaded in the first sentence. It is on the longer side, 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?

There is no output schema, so the description compensates by listing the returned data fields. It covers version scope, when to use it, where parameters come from, and how to interpret the halted/inactive flags. Minor gaps such as the exact format of the cap values keep it from a 5.

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

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

Schema description coverage is 100%, so hubId, spokeId, and version are already documented in the input schema. The description adds the timing nuance that get_reserve_details is the ID route that works before a wallet holds anything, but this largely restates the schema's parameter source notes. The baseline 3 for high schema coverage applies.

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

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

The description states a precise scope — per-asset limits for exactly one (hub, spoke) pair — and enumerates the returned fields (supply/borrow caps, active state, halted state, risk premium threshold). It distinguishes itself from the many sibling get_* tools through the single-pair granularity and v4-only constraint, so an agent can pick it without opening the schema.

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

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

Gives an explicit trigger condition: 'Read it before sizing a large position, because a cap is what turns a valid-looking supply into a reverting one.' It also explains the preferred ID route (get_reserve_details) that works before a wallet holds anything on the spoke, implicitly contrasting with get_user_positions. It stops short of explicitly naming a sibling alternative for when a different granularity is needed, but the 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 cover read-only and non-destructive behavior, so the description's burden is lower. It adds useful context: it applies to both versions, returns an overview of tool families/prompts/guides, and tells the agent to answer from the result. It does not detail return format, but for a zero-parameter read-only orientation tool this is not a significant gap.

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

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

Two concise sentences with no filler. The when-to-use and how-to-use guidance are both explicit, and the description is appropriately front-loaded for an agent scanning tool definitions.

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 no-parameter, read-only overview tool, the description covers scope of content, trigger condition, and how to use the returned information. The only minor ambiguity is 'both versions,' but this does not prevent an agent from invoking 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 tool has zero parameters and the schema is fully documented/covered, so there are no parameter semantics for the description to add. The description appropriately focuses on usage context instead, and the baseline 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 states a specific verb ('Call this') and a clear resource: the Aave server/connector's capabilities, including tool families, ready-made prompts, and guide topics. It clearly distinguishes itself from the many data-retrieval sibling tools by positioning this as the orientation/overview tool.

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

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

It gives an explicit trigger condition: call when an Aave conversation opens with no specific request. It also provides a direct behavioral instruction to answer from this tool's content rather than guessing from tool names, which is especially valuable given the large sibling list.

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

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

The description goes well beyond the readOnlyHint/destructiveHint annotations by explaining the v4 backend behavior, the meaning of 'chainsNotCovered', and the semantic difference between a chain not being reachable versus a chain with zero swappable tokens. This gives the agent crucial interpretation guidance that annotations alone cannot provide.

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

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

The description is dense and informative but not bloated; every sentence adds meaningful context. The opening sentence is slightly indirect because it starts with version/backend context rather than a direct statement of the tool's purpose, but the overall structure is efficient and front-loaded with important behavioral 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?

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: counts vs token lists, chainsNotCovered, zero-token chains, and the get_markets alternative. For a single-optional-parameter read-only tool, nothing essential is missing.

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

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

The schema already fully describes the single optional chainIds parameter with 100% coverage. The description adds extra value by noting that chainIds can also be used to ask about chains not reached by the initial sweep, and clarifies that omission returns counts rather than token lists.

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 gets swappable chains and tokens, and explains it returns either a chain sweep with token counts or an actual token list for given chain ids. It differentiates itself from get_swap_quote and get_markets by explicitly positioning this as the pre-quote discovery tool.

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

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

The description explicitly says to call this before get_swap_quote, and specifies when to omit chainIds versus when to pass them. It also tells the agent that get_markets returns 'canSwapFrom' per reserve as an alternative source of the same information.

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 quote is explicitly non-mutating ('returns the quote with a quoteId'), aligning with readOnlyHint: true and destructiveHint: false. It also discloses a meaningful behavioral edge case—unsupported chains are rejected outright rather than quoted with poor data—which is not captured in annotations or 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?

The description is information-dense and organized around behavioral caveats, preconditions, and output usage, but opens with a caveat ('No version argument...') before stating the core purpose. The quote purpose is clear and all sentences earn their place, though the main verb-object statement could be 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?

The description covers what the tool does, when to verify chain/token coverage first, what it returns (quote with quoteId), and how the result feeds into prepare_order. Combined with the rich schema, this gives an agent everything needed to invoke it safely and in the correct sequence.

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 description does not add parameter-level detail, but the schema already provides thorough descriptions for sell/buy tokens, amount in main units, kind semantics, user validation, and optional slippage. Because schema coverage is near 100%, the lack of additional parameter explanation is acceptable and sits at the baseline for this dimension.

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

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

The description clearly states the tool's purpose: 'Quote a token swap: returns the quote with a quoteId to prepare and sign through prepare_order.' It also scopes the tool precisely to the v4 backend's supports chains and explicitly notes unsupported chains are rejected rather than mishandled.

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 actionable guidance: call get_swappable_tokens first if chain coverage is unknown, or check 'canSwapFrom' on get_markets. It also explains how to use the returned quoteId downstream with prepare_order, removing ambiguity about the next step.

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

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

Beyond the readOnly and destructive annotations, the description explains important behavior: the API lags the chain, dependent actions are gated on this tool, and the correct pattern is to poll until processed is true. It does not state the exact return shape, but the behavioral contract is clear.

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

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

Three dense sentences front-load the version constraint, state the purpose, justify the tool over RPC polling, and give the polling protocol. Every sentence earns its place with no wasted words.

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 check with full schema coverage, the description covers when, why, and how to poll, and names the critical prepare_action dependency. A slight gap is that the return value is only implied ('processed is true') rather than explicitly specified, which matters because there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that txHash is the hash you broadcast and that operations must be the array that came back from the server on that transaction, tightening the relationship between the two required 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 uses a specific verb and resource: it asks whether the Aave API has processed a sent transaction. It also distinguishes itself from the sibling family by explicitly contrasting with sleeping or polling an RPC and by naming prepare_action's dependency behavior.

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

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

It explicitly states when to use the tool ('After sending a transaction'), which alternative to avoid ('instead of sleeping or polling an RPC'), and the underlying reason: prepare_action will not issue a dependent follow-up until the API has caught up. This gives an agent 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?

Annotations already establish read-only, non-destructive behavior. The description adds useful behavioral context: results are ordered most recent first, v4 covers all chains while v3 is per market/chain due to upstream pagination, and the output includes scope fields. It doesn't cover every operational detail, but it complements the annotations well.

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: definition/order, version-specific behavior, and alternative routing. Every sentence earns its place and the most important scoping 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?

With no output schema, the description still gives enough to invoke the tool correctly: it covers versions, chains, markets, ordering, and the alternative tool. Combined with the fully described input schema and read-only annotations, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how version, chainId, and market relate (v3 reads one market/chain at a time; pass chainId to read another), which helps an agent choose parameter combinations correctly.

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: a wallet's Aave transaction history, enumerating operation types (supply, borrow, repay, withdraw, collateral changes) and versions. It also names the sibling to avoid, get_user_positions, so the tool's identity is unambiguous.

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

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

It gives explicit routing guidance: use get_user_positions to find holdings, not this tool. It also explains when v3 versus v4 is involved and how chainId is used to read another market, making the selection criteria 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?

With annotations already marking readOnly/openWorld/destructive hints, the description adds meaningful edge-case behavior: empty result semantics, chainsNotServed caveats, v3 vs v4 response shapes, and the 'asking again returns the same nothing' idempotency note. 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 dense but every sentence carries distinct information, front-loading the core purpose before edge cases. No redundant restatement of the title or schema.

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

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

For a read-only tool with no output schema, the description covers return shapes, empty-result semantics, chain coverage behavior, and the relevant sibling alternative. Nothing an agent needs to call it correctly and interpret results is missing.

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

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

Schema coverage is 100%, but the description goes beyond the schema: omitting chainId covers every served chain, version changes the return shape (positions with health factor vs supplies/borrows), and user is scoped to Aave-side positions only. This materially improves an agent's ability to pass correct 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 first sentence identifies a specific verb (get), resource (wallet Aave positions), and scope (supplies and borrows on v3, v4, or both). It also differentiates from the sibling get_markets by explicitly stating what belongs elsewhere.

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 tells the agent to omit chainId to cover every chain without looping, explains the meaning of chainsNotServed, and directs the caller to get_markets when wallet-owned balances are needed. This is explicit when-to-use and when-not-to-use guidance with a named 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 it read-only and non-destructive, and the description adds meaningful behavior beyond that: it covers both Merit-distributed and protocol-native incentives, explains chainsNotServed semantics, notes that repeated queries on unsupported chains return the same empty result, and calls out the extra claim transaction on v3 responses. This is substantial non-obvious context.

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

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

The description is dense but front-loaded with the core purpose, followed by high-value edge-case guidance. Each sentence adds distinct information, and no filler or restatement of the name appears.

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 nevertheless conveys the key return semantics: chain coverage fields, per-row chain IDs, unsupported-chain behavior, and the v3 transaction addition. It gives an agent enough context to call the tool correctly and interpret ambiguous empty results.

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

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

Input schema coverage is 100%, so all three parameters are already documented. The description restates the omit-chainId behavior and default all version already present in the schema, and the main added value is response-shape context (chainsCovered, per-row chainId, v3 transaction) rather than new parameter 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 opening sentence identifies the tool as returning a wallet's claimable Aave rewards on v3, v4, or both, with a specific noun-verb-resource structure. It also states which incentive programmes are included, distinguishing this read tool from reward-related actions like prepare_claim_rewards.

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

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

The description gives concrete invocation guidance: omit chainId to cover all chains, interpret chainsNotServed as unsupported chains, and treat empty results there as non-answers. It does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context: chain-coverage behavior, v4 vs v3 response shapes, the meaning of marketsWithPosition: 0, and the fact that token balances, Safety Module stake, and Savings GHO are excluded. 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 long, but the density is justified: it covers chain semantics, version differences, edge-case interpretation, and exclusions with almost no filler. The most important purpose statement comes first, and every sentence contributes operational guidance.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it succeeds: it names response fields like 'chainsCovered', 'chainsNotServed', and 'marketsWithPosition', describes v4's cross-chain summary versus v3's per-market entries, and clarifies how zeros and empty results should be interpreted. This is complete enough for an agent to invoke and interpret the 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 documents all three parameters with 100% coverage. The description adds meaning beyond the schema by explaining the effect of omitting chainId, that both versions cover all served chains, and how version changes the response structure. This is above the baseline for fully-schema-documented 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 opens with 'A wallet's aggregate position and health factor,' giving a specific verb, resource, and scope. It then explicitly distinguishes the tool from get_markets, get_safety_module, and get_sgho_vault, so an agent can tell exactly which concept this covers.

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

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

The description gives explicit usage guidance: omit chainId to cover all chains, do not loop over chains, treat chainsNotServed as genuinely absent markets, and use get_markets for token balances. It also names excluded alternatives (Safety Module and Savings GHO), making when-not-to-use crystal 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 establish read-only safety (readOnlyHint=true), and the description adds non-obvious call-time behavior: the tool is v4-exclusive and omitting chainId makes it span every supported v4 chain. Listing the tracked metrics also sets expectations for response content, and nothing in the description contradicts 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 sentences, each earning its place: version constraint front-loaded, purpose stated next, usage examples and chain behavior at the end. No filler; the only nit is 'v4' appearing in both the first sentence and 'Aave v4' in the second.

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 conveying what the call returns, and naming the four tracked metrics largely covers it. It doesn't describe the exact response shape or window granularity, but the schema already enumerates all window values and parameters, so nothing needed for a correct call is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies and the description need not restate parameter docs. The chainId-omission guidance mirrors what the schema already says ('Omit the argument entirely to cover every chain'), adding no net-new parameter meaning beyond schema.

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

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

States a specific operation — retrieving a single wallet's historical progression of net worth, supplied, debt, and health factor over a configurable window on Aave v4. The temporal framing ('over time', 'over a window') cleanly separates it from snapshot-oriented siblings like get_user_summary and get_user_positions in the sibling list.

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

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

Gives concrete question types the tool answers ('how has my position changed', 'how close to liquidation a wallet has been'), which tells an agent when to invoke it. It does not name the alternative (e.g., get_user_summary for a current snapshot) or state exclusions, so it stops short of explicit when/when-not guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, it discloses that a wallet that did not vote returns voted:false as an answer rather than an error, and that voting power is denominated in AAVE. This directly prevents the agent from misinterpreting a non-vote as a failure.

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 adds value, though the core purpose appears after the version caveat rather than front-loaded. It remains efficient and free of redundancy.

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

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

With no output schema, the description covers the important return behavior: the voted:false case, the power unit, and the single-wallet/proposal scope. It does not specify exact positive-vote response fields, but the essentials for correct invocation and interpretation 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?

The input schema already documents both parameters with 100% coverage. The description adds no new semantic detail about user or proposalId beyond what the schema provides, so the schema-driven baseline of 3 is appropriate.

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

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

The description states 'How one wallet voted on one Aave DAO proposal, and with how much power,' which is a specific verb-resource pair. It clearly distinguishes this from siblings like get_proposal_votes or get_governance_proposal by the single-wallet/single-proposal scope.

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 version caveat ('Takes no version argument') gives a clear exclusion and prevents misuse. However, it never explicitly names alternatives or states when to choose this tool over get_proposal_votes or search_governance_proposals, leaving some 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 declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds value beyond that: it specifies 'v3 only', describes the output structure (total yield plus per-sample breakdown), and explains the window buckets (no day or six months). It does not contradict annotations and provides useful behavioral context.

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

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

The description is three sentences, front-loaded with the key constraint ('v3 only') and purpose. Every sentence earns its place: purpose, differentiation from APR, and prerequisite guidance. No 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?

For a 5-parameter tool with no output schema, the description is remarkably complete. It explains what is returned (total yield and per-sample breakdown), the window buckets, the version restriction, and where to get required inputs. The complexity is low but the description covers all essential aspects an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema. The description adds nuance beyond the schema: it clarifies the window enum has only specific buckets and warns against expecting others, and it reiterates the v3-only constraint. This goes beyond a baseline of 3 by enriching parameter understanding.

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: 'How one wallet's position in one vault moved over a window', with specific outputs (total yield, per-sample breakdown of balance, deposits, withdrawals). It explicitly distinguishes from the APR concept, which is a different metric, and mentions get_vaults as the source for required inputs, differentiating it from other history tools.

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

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

The description explicitly says when to use it: to answer 'what has this vault actually paid me', contrasting with the current APR which is not the same. It also notes that the vault address and chain come from get_vaults. However, it does not explicitly name alternative tools like get_apy_history or get_user_activity, though the context implies them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: the conversion happens at the current index, the index moves over time, and nothing is built on-chain. This goes beyond the annotations, though it does not detail output format or error 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 dense and front-loaded: it opens with 'v3 only', gives the core conversion concept, then the unit mapping, and then call-time guidance. It is somewhat long, but each sentence earns its place by covering required semantics rather than repeating 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?

For a read-only preview tool with no output schema, the description tells the agent what each action returns, what unit the amount must be in, when to call it relative to prepare_vault_action, and that it is v3-only. Combined with full schema coverage of all parameters, this 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 coverage is 100%, so the baseline is 3. The description adds important semantics by explaining that 'amount' is interpreted as assets for deposit/withdraw and as shares for mint/redeem, and by advising the agent to use the assets pair or shares pair to fix the exact amount or count. This materially clarifies the interplay between 'action' and 'amount'.

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 operation: converting a vault's assets to/from shares at the current index, and explicitly says 'without building anything', which distinguishes it from prepare_vault_action. It also names all four action modes, making its 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 explicitly instructs the agent to call this before prepare_vault_action rather than multiplying by a rate because 'the index moves'. It also warns that the unit of 'amount' depends on the action and gives the exact unit mapping for deposit/mint/withdraw/redeem, which is clear invocation 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 readOnly and non-destructive, and the description adds valuable behavioral context beyond that: v3-only restriction, exclusive selectors, chainId requirement for vault, vault domain semantics (ERC-4626, fee on yield, APR net of fee), and the absence of a browse-all endpoint. No contradictions with annotations.

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

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

Every sentence adds crucial information: the opening line gives the critical exclusivity rule, followed by mode definitions, domain context, and negative scope. It is dense but tightly structured with no filler or redundancy.

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

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

For a 6-parameter tool with no required parameters and no output schema, the description fully covers the calling pattern (selectors, chainId condition), the domain meaning, and a key output semantic (aprPct net of fee). It also anticipates a likely misuse (finding best vault) and preempts it. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds extra meaning by enforcing exactly-one-of user/owner/vault, stating that only vault requires chainId, and clarifying aprPct/feePct relationship. However, it leaves some parameter details like cursor pagination to the schema, which is acceptable given full schema coverage.

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

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

The description clearly states the tool gets Aave vaults or a wallet's shares, and enumerates three distinct selector modes ('user', 'owner', 'vault') with explicit scope for each. This distinguishes it from sibling tools like get_markets or get_reserve_details, and explicitly states what it cannot do (no list-every-vault catalogue).

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 to name exactly one of the three selectors and when to use each mode ('portfolio question', 'what one curator runs', 'single vault'). It also gives a negative usage rule: because there is no catalogue, it cannot answer 'best vault' requests and requires known addresses, which tells the agent when not to use it.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description clarifies that the rates are potential (what Aave would pay/charge), not actual earnings, and that zero balances are omitted. It also reveals the 'chainsCovered' output field. This adds meaningful behavioral context that an agent needs to 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 information-dense but every sentence serves a purpose: scope, output composition, semantic distinction, usage guidance, chainId default, and zero-balance omission. It is well-structured with the core definition first and no redundancy.

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

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

Given three parameters, no output schema, and the complexity of distinguishing wallet balances from positions, the description covers all essential aspects: what data is returned, what it means, how to filter by chain, and when to use an alternative. An agent can call this tool correctly and interpret the response 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 schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by reinforcing the chainId omission behavior and pointing to the 'chainsCovered' field, and clarifies that 'version' is only v4. This is a modest but useful addition 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 exactly what the tool returns: wallet holdings of Aave-accepted tokens, per token and summed across chains, with per-chain breakdown, plus best supply and borrow APYs. It explicitly distinguishes itself from position-based queries ('This is the wallet, not a position') and names the sibling tool for the other use case (get_user_summary). The purpose is unambiguous and well-differentiated.

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

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

It provides explicit guidance on when to use this tool: start 'what should I do with what I have' here, and 'how is my position doing' at get_user_summary. It also specifies the v4-only scope and the optionality of chainId ('Omit chainId to cover every chain'). This leaves no ambiguity about when to call it versus alternatives.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false. The description reinforces this by explaining that building is non-custodial, free, commits the user to nothing, and sends nothing. It also discloses the approval-step and permit-replay behavior, which adds meaningful context beyond the annotations.

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

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

The description is long, but justified for a 13-parameter tool. It front-loads the core behavior, then flows through simulation guidance, build instructions, parameter rules, and finally the two most common gotchas. Every sentence carries operational value.

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

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

For a complex prepare tool with no output schema, the description covers the execution plan return, approval-step possibility, session-context dependencies, cross-version differences, and post-transaction polling. An agent has enough to call it correctly on the first attempt.

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 substantial meaning: amount must be in MAIN units with a concrete conversion example, market/reserveId must come verbatim from session data and cannot be recalled or constructed, sender cannot be a placeholder, and enableCollateral has behavioral consequences for later borrows. This is far 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 opens with a specific verb and resource: "Build an unsigned transaction to supply, borrow, withdraw, or repay on Aave (v3 or v4)." This clearly separates it from sibling prepare_* tools and from preview_action, which is explicitly positioned as the simulation counterpart.

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

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

The description gives explicit when-to-use guidance: call preview_action first for borrow/withdraw, read its warnings, build without asking the user, and poll get_transaction_processed before dependent calls. It also tells the agent what not to send on first calls and when permit parameters are appropriate.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds context by stating it is non-custodial, commits nothing, and only returns what the user signs, which clarifies the side-effect profile beyond the raw annotation booleans.

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. It front-loads the purpose and version caveat, then adds routing and safety context, every clause contributing useful 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 single-parameter tool with read-only annotations, the description covers the routing decision, signature requirement, version behavior, and side-effect profile. There is no output schema, so the description adequately conveys the return value as an EIP-712 cancellation to sign, though it does not detail its structure.

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 only parameter, orderId, already has a description with source hints. The tool description mentions 'from an orderId' but adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: from an orderId, it returns the EIP-712 cancellation payload for the user to sign. It clearly differentiates itself from cancel_order, which relays the result, and from the transaction route.

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 names cancel_order as the alternative and explains the split: intent orders use this gasless prepare-then-sign route, while native-token sell orders on chain use cancel_order's transaction route without prepare or signature. This is strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: the tool is 'non-custodial' and builds an 'unsigned transaction,' so the agent knows nothing is broadcast or mutated. It also discloses default behavior when ids is omitted.

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

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

Four short, information-dense sentences with no filler. The most important qualifier ('v4 only') and the core purpose are front-loaded, and the v3 clarification is placed at the end where it serves as useful extra context.

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

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

The description covers purpose, version scoping, non-custodial behavior, default claim-all behavior, and the v3 alternative, which is sufficient for invoking the tool correctly. It does not describe the exact output structure, but the phrase 'build an unsigned transaction' conveys the key return concept and there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents ids, user, chainId, and version. The description adds a useful conditional relationship—that chainId can be omitted when ids is omitted because the chain is discovered—but most parameter meaning is already present in the schema.

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

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

The description begins with 'v4 only' and states a specific action: 'Build an unsigned transaction to claim a wallet's V4 rewards.' This clearly identifies the verb, resource, and scope, and the wording distinguishes it from get_user_rewards and other prepare_* siblings.

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

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

The description explicitly scopes usage to v4 and explains the v3 alternative: 'There is no v3 equivalent because a v3 claim needs no second call: get_user_rewards already returns the transaction.' It also clarifies when to omit ids, telling the agent to claim everything when no ids are supplied.

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 that this is non-custodial and that the liquidator signs and submits the transaction. It also discloses the version-specific input model, which goes beyond what the annotations provide.

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

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

The description is compact and front-loaded: purpose, viability condition, version differences, and custody model are each covered in a few efficient sentences. No filler or redundant restatement of 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?

Given the tool's 11 parameters, two protocol versions, and no output schema, the description covers the essential decision points well. It does not describe the exact shape of the returned unsigned transaction, but for a transaction builder the purpose and version-specific inputs are the critical context, so this is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning by mapping v4 to reserveIds and v3 to token addresses plus chainId, and clarifying that the liquidator is implicit in v3 but explicit in v4. This adds value beyond individual schema 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 and resource: 'Build an unsigned transaction to liquidate an unhealthy position.' It explains the economic flow (repay debt, receive collateral plus bonus) and clearly distinguishes this from sibling prepare_* tools like prepare_order or prepare_claim_rewards.

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

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

It gives an explicit viability condition ('health factor is below 1') and points the agent to get_user_summary to verify it. It also provides version-specific routing guidance, though it does not name a when-not-to-use 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 declare readOnlyHint=true and destructiveHint=false, and the description is consistent with them ('Non-custodial: this returns what the user signs, and commits nothing'), reinforcing the non-mutating nature. It adds genuinely useful behavior beyond the annotations — no version argument, per-quote signature requirements, and that no signature should ever be sent unsolicited.

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

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

It is a single dense paragraph front-loaded with a negative edge case ('No version argument') rather than the core purpose, and the conditional signature rules would be far clearer as a list. Content is mostly substantive, but the structure makes it hard 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 7-parameter tool with no output schema, it covers routing, signature preconditions, and the fact that the return value is unsigned user-facing data. It omits what to do with the result (submitting via submit_signed_order) and the distinction between the intent route's return shape and the transaction route's orderReceipt, so a small gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining which quote type maps to each signature parameter (permitSignature under 'bySignature' vs a leverage 'byPermit', adapterContractSignature/positionManagerSignature/setCollateralSignature per listed approval) and when route applies.

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

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

States a specific verb+resource whose scope is defined by a quoteId ('One prepare for every product - a token swap, position swap, repay-with-supply or leverage quoteId all come here'), which cleanly separates it from prepare_action, prepare_set_collateral and the other prepare_* siblings that handle non-quote flows.

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

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

Gives explicit conditional rules: signatures only when the originating quote asked for them, route:'transaction' only for SwapByTransaction quotes from a native-token sell. It does not state the surrounding workflow (get quote first, submit_signed_order after), so it falls short of full when/when-not coverage, but the per-quote routing guidance is unusually 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?

Goes far beyond the readOnlyHint annotation by explaining the v3/v4 difference, toggle-refusal behavior, health-factor simulation with refusal/warning thresholds, and the fact that nothing moves. The description makes side effects and failure modes explicit.

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

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

Front-loaded with the core purpose, then the v3/v4 divergence, then constraints and simulation behavior. Dense but each sentence adds necessary information; 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?

Comprehensive for a complex tool: covers version behavior, preconditions, health-factor effects, refusal and warning semantics, and sender requirements. It doesn't enumerate the return shape beyond warnings, but that gap is acceptable without an output schema.

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

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

Adds meaning beyond the schema: explains 'enable' means set-state on v4 but toggle on v3, that sender must be a named wallet, and how version and reserve selector are inferred. This compensates for ambiguous parameter names like 'enable'.

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 operation (build an unsigned transaction to change collateral status) and immediately distinguishes v3 from v4 semanticsatio. It clearly tells an agent what the tool does and how it differs from 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?

Provides strong context: requires an existing supply in the reserve, explains that disabling is simulated firstholved, and notes non-custodial execution. It does not name a sibling tool as an explicit alternative, so it misses full exclusion guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds context beyond annotations: it builds an unsigned transaction (not submitting), it explains the eMode concept and its tradeoff, and it notes that v4 replaces eMode. It doesn't explicitly say 'this does not submit a transaction', but 'Build an unsigned transaction' implies that. The description is consistent with annotations and adds meaningful behavioral context.

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

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

The description is compact and front-loaded: it opens with 'v3 only' and the core action, then explains the eMode concept in one sentence, then gives the two key usage instructions (take categoryId from get_emode_categories, pass 0 to disable), and closes with the v4 exclusion. Every sentence earns its place; no filler.

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

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

For a transaction-building tool with no output schema, the description covers the essential context: what the tool does, how to get the required categoryId, how to disable eMode, the version constraint, and the v4 alternative. The schema covers parameter details, and annotations cover safety. An agent has enough to select and invoke 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%, so the schema already documents all parameters. The description adds value by explaining the semantic meaning of categoryId (from get_emode_categories, 0 to disable) and the market constraint (v3 only, from a get_markets row, cannot be recalled). It also clarifies the version parameter is optional and only 'v3'. This goes beyond the schema's field-level descriptions.

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

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

The description states a specific verb ('Build an unsigned transaction'), a specific resource ('Aave v3 eMode category'), and the exact scope ('v3 only'). It also explains what eMode does (groups correlated assets, higher LTV, borrowing power vs. asset restrictions), which distinguishes it from generic prepare_* siblings. The phrase 'v3 only' is repeated, reinforcing the version constraint.

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

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

The description explicitly says when to use this tool: to switch a wallet's Aave v3 eMode category. It tells the agent to take categoryId from get_emode_categories, and to pass 0 to turn eMode off. It also explicitly excludes v4 ('v4 replaces eMode with risk premium and dynamic config'), which is a clear when-not-to-use signal. This is strong 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 the tool as read-only and non-destructive; the description reinforces and expands this by explaining the non-custodial unsigned-transaction behavior and that building commits the user to nothing. It also discloses the allowance/ApprovalRequired flow. 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 dense but every sentence carries operational value. It front-loads scope and the core action, then flows into parameter rules and the approval edge case without 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?

Even without an output schema, the description covers chain and version constraints, both actions, parameter semantics, the max flag, recipient behavior, and the ApprovalRequired result path. This is sufficient for correct selection and invocation.

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

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

Schema coverage is 100%, but the description adds crucial semantics beyond the schema: amount means GHO on deposit but sGHO shares on withdraw, max:true omits amount, recipient defaults to sender, and only applicable arguments should be sent. This significantly reduces ambiguity for an agent.

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 deposit GHO into the sGHO vault or withdraw from it.' It also narrows scope with 'v3 only, Ethereum only' and clearly separates the two actions. This distinguishes it from sibling data/read tools like get_sgho_vault and 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?

The description gives clear eligibility conditions (v3, Ethereum) and decision rules: amount is GHO for deposit but sGHO shares for withdraw, max:true omits amount, recipient is optional, and approval transactions must be submitted in order. It references get_sgho_preview for conversions, but does not explicitly name alternative prepare_* tools or state when not to use this tool.

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

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

The description adds meaningful behavioral context beyond annotations: the transaction is unsigned/non-custodial, it is all-or-nothing, it takes no amount, and it should be built rather than permission-asked. These details complement the readOnlyHint=true annotation without contradicting it.

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

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

Four sentences with no fluff: scope constraints come first, then the action, then the critical all-or-nothing and prerequisite behavior. 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 tool with one required parameter and no output schema, the description is complete: it explains what is built, the full-position behavior, the prerequisite get_safety_module call, and the non-custodial flow. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description clarifies that 'user' is the stkGHO holder and explains why no amount parameter exists, but it does not add significant format-level meaning beyond the schema.

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

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

The description states a specific 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 adds scope constraints ('v3 only, Ethereum only') and the all-or-nothing behavior, clearly distinguishing it from 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?

It gives an explicit precondition: call get_safety_module first and quote the legacy stkGHO balance before signing. It also states v3/Ethereum-only applicability and that the transaction covers the entire position, but it does not explicitly name alternatives or spell out when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be non-mutating. The description goes well beyond this: it reveals that the unsigned transaction commits the user to nothing, explains the approval requirement and the exact sequence (submit approval, wait, then submit originalTransaction), and clarifies that 'recipient' is only for relaying. It also exposes the dependency of unit on action. This is rich behavioral disclosure with no contradictions.

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

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

The description is compact yet dense, with every sentence adding distinct value. It leads with the key constraint ('v3 only') and the core operation, then methodically covers the crucial edge cases (units, asAToken, recipient, approval flow). No fluff or repetition of schema fields; it's an ideal length for an agent to parse quickly.

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 (8 params, 5 required, no output schema), the description covers all critical aspects an agent needs to call it correctly: version restriction, non-custodial nature, unit semantics, approval handling, and even hints at the response shape (ApprovalRequired, approval, originalTransaction). There's no missing information that would cause an agent to mis-invoke the tool.

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

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

Although schema coverage is 100% (all parameters have descriptions), the tool description adds substantial semantic meaning: it clarifies the ambiguous 'amount' by tying it to action type (assets vs shares), explains the effect of asAToken (skips supplying when wallet holds aToken), and states that omitting recipient defaults to sender. This elevates the parameter understanding beyond 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 tool's purpose: 'v3 only. Build an unsigned transaction to move value in or out of an Aave Vault.' It identifies the specific resource (Aave Vault), the verb (build), and the exact set of actions (deposit, mint, withdraw, redeem). This distinguishes it from sibling prepare_* tools like prepare_order or prepare_liquidation, which operate on different instruments.

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 usage context: it's v3 only, non-custodial (so the agent should proceed without asking), and explains the unit handling (assets vs shares) and asAToken behavior. It also describes the approval flow when needed. However, it does not explicitly name alternative tools or state when to use this instead of them, though the abundance of other prepare_* siblings makes that somewhat 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?

Beyond the readOnly/non-destructive annotations, it discloses that the call commits nothing, that 'warnings' with error level predicts a prepare-step refusal, and — a genuinely valuable caveat — that it checks position limits rather than token allowances, so a clean simulation does not mean no approval is needed. It also spells out version-specific return payloads (health factors only on v3; APY, risk premium, net collateral/balance, borrowing power, rewards on v4).

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

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

Purpose and the imperative to simulate first are front-loaded, and almost every clause carries information an agent needs for a 12-parameter conditional tool. It is, however, a dense run-on chain, and the 'cheapest way to find out... commits nothing' sentence partially restates the earlier 'WITHOUT executing'/'Always do this' framing.

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 no-output-schema tool with 12 parameters and two protocol versions, the description covers the return shape of both versions, warning semantics, selector sourcing, and the allowance blind spot. Nothing an agent needs in order to call it correctly or interpret the result appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by adding cross-field routing the schema does not state as such — which argument set each version and each action type takes, and which quote tool each quoted-order action name corresponds to. Most individual parameter meaning (reserveId opacity, max, native, sender) is duplicated from the schema rather than extended.

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

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

States a specific verb and resource — simulate a supply/borrow/withdraw/repay or quoted order against a wallet position WITHOUT executing — and enumerates the exact action set. It also separates itself from the build path by naming 'the prepare step' that will refuse a failed simulation, so an agent can tell it apart from prepare_action and the quote tools without opening a schema.

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

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

Gives an explicit directive: 'Always do this before a borrow, a withdraw or any of those orders,' reinforced by 'Simulate first even when you intend to build immediately.' It also routes each quoted-order action to the sibling that minted its quote (get_leverage_quote, get_position_swap_quote, get_repay_with_supply_quote), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: vote tallies are in AAVE, search ranks by relevance over title/author/description, state values map to lifecycle phases, and includeSummaries has a size/bandwidth tradeoff. It does not disclose pagination edge cases or default ordering, but provides solid additional transparency beyond 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 information-dense. Every sentence earns its place: it clarifies the version misconception, explains core filtering use cases, describes search behavior, and notes the AAVE tally unit. The most important scoping fact 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 list/search tool with no output schema and 100% schema coverage, the description is nearly complete. It explains state semantics, search scope, result ranking, tally unit, and the includeSummaries tradeoff. It does not mention default sort order or how limit/offset pagination behaves, but those are less critical for a simple query tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds value by explaining the meaning of active/queued states and the tradeoff of includeSummaries, but it does not add significant syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List or search') and resource ('Aave DAO governance proposals'), and clarifies scope by noting it is not per-market and unrelated to Aave v3/v4 markets. It also distinguishes from the sibling get_governance_proposal by implying list/search vs single-item retrieval, making it easy for an agent to select correctly.

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

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

The description gives concrete when-to-use guidance: use state 'active' for 'what is live right now' and state 'queued' for 'what is waiting to execute'. It also notes that the tool takes no 'version' argument and explains why, preventing a common misuse. It does not explicitly name sibling alternatives, but the search/filter behavior is clearly scoped.

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