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 establish readOnlyHint=true and destructiveHint=false, so no contradiction exists. The description adds useful behavioral context beyond annotations: it applies to both protocol versions, it returns a full capability list when 'lookingFor' is used, and it records gaps when a capability does not exist.

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

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

The description is moderately sized and front-loaded with the core purpose before enumerating topics. The topic list is somewhat redundant with the schema enum, but it serves as a quick reference for the agent and the edge-case guidance about 'lookingFor' 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, but the description explains what the tool returns for the 'lookingFor' path and implies guidance content for the topic path. Given the tool's role as a meta-guide among many specialized siblings, the description covers the selection and invocation needs well, though it could state the return format for normal topic queries more explicitly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful usage context for both parameters: it explains when to send 'lookingFor' versus when to omit it, and stresses that topic should be read before building an action. The topic list duplicates the enum but reinforces the intended workflow.

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

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

The description clearly states this is the protocol and usage guidance tool for building Aave flows, covering both v3 and v4. It differentiates itself from the many get_/prepare_ siblings by explicitly positioning itself as the fallback when no tool seems to fit and offering the 'lookingFor' capability to discover tools by intent.

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

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

It gives explicit when-to-use guidance: read the relevant topic before constructing an action, and come here when no other tool seems to fit. It also gives a clear boundary by directing users to external docs for deep protocol documentation, which functions as a when-not-to-use signal.

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 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 already declare readOnlyHint=true and destructiveHint=false, so the bar is for added context, and this description goes far beyond: it discloses response metadata fields (chainsCovered, chainsNotCovered, chainsNotServed), conditional flags that 'appear only when set, so a reserve with none of them is not flagged', the v3/v4 coverage asymmetry, the percent-unit convention, and that identical APYs across spoke rows 'are expected rather than duplicates'. Nothing 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?

Long but with zero filler: every sentence addresses a distinct misinterpretation risk (coverage semantics, empty-result trap, APY ranking, conditional flags, spoke/hub duplicates, per-reserve swap semantics). The purpose is front-loaded in the first sentence, and the trade-off against response size ('hundreds of kilobytes') justifies behavior rather than padding prose.

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 carries the full burden of explaining return values — and it does: row shape under 'reserves', paired supplyApyPct/borrowApyPct fields, per-version fields (suppliable/borrowable vs availableLiquidity/totalSuppliedUsd), the user param's row additions (walletBalance, youCanSupply, youCanBorrow), and chain coverage metadata. For a 21-chain, two-version listing tool with no output schema, this is complete.

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

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

Schema coverage is 100% with already-strong param descriptions, so the baseline is 3. The description adds genuine cross-parameter semantics: passing symbols changes v3 coverage from Ethereum-only to all chains, omitting chainId triggers the chainsCovered/chainsNotCovered metadata, and the Pct-suffix naming convention. This is additive, but the schema still carries most per-parameter load, so not a 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+scope: 'List Aave markets/reserves (symbol, APY, caps, liquidity) on v3, v4, or both.' It names the entities, the data dimensions, and the version axis, and it differentiates from siblings by explicitly contrasting canSwapFrom with what get_swappable_tokens answers per chain.

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 when-to-use directives with conditions: 'to compare one asset across chains, pass symbols and no chainId', 'Pass it [user] whenever the question is about what someone can actually do rather than what the rates are', and the symbols param's 'Strongly preferred when you know the asset' guidance. It also warns when NOT to trust results ('an empty result for one of them is not an answer about that chain') and names the alternative tool (get_swappable_tokens).

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 mark the tool as read-only and non-destructive. The description adds useful behavioral context beyond annotations by specifying the v4-only constraint, the item-level scope, and the returned data concepts: principal, accrued interest, and withdrawable amount.

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

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

The description is compact, front-loads the critical 'v4 only' constraint, and every sentence earns its place by conveying scope, data contents, and a required parameter source.

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, but the description enumerates the key returned fields (principal, accrued interest, withdrawable) and connects the main parameter to its source tool. Minor details like the default side are left to the schema, which is acceptable given full schema coverage.

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

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

Schema coverage is 100%, so the schema fully documents user, spokeId, side, and version. The description reinforces the spokeId source but does not add significant parameter meaning beyond what the schema already provides.

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

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

The description uses a specific verb and resource: 'Get individual position items' and 'the individual supplies or borrows inside one v4 spoke.' It clearly differentiates itself from get_user_positions by stating the per-spoke aggregate 'cannot show' item-level details.

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

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

It explicitly says this is v4 only, tells the agent to obtain 'spokeId' from get_user_positions, and explains that the per-spoke aggregate cannot show this level of detail. This makes the selection between this tool and get_user_positions unambiguous.

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 already carry readOnlyHint=true and destructiveHint=false, and the description does not contradict them, so this is not a mere annotation echo. It adds substantial behavioral context beyond annotations: the Pct-suffix percent convention ('3.32' means 3.32%), the v4 hub-wide sharing of utilisation and the rate curve, the warning that collateralFactorPct is the liquidation boundary itself, and the double-counting warning for liquidityFeePct (supplyApy = borrowApy x utilisation x (1 - liquidityFee)). These are exactly the non-obvious facts 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 long (~300 words), but nearly every sentence carries a non-obvious fact an agent could not infer from names like 'collateralFactorPct' or 'liquidityFeePct'. It front-loads the core purpose and scoping first, then layers the field interpretations. It could trim the parenthetical 'if you want to check' formula, but overall the density of useful content earns its length.

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

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

With no output schema, the description carries the burden of explaining the return data, and it does so extensively: percent units, v4 hub-wide behaviour, the two ambiguous v4 fields, and the price fields with their source. Minor gaps remain — it does not enumerate every v3 vs v4 difference or describe the cap structure in the same depth as the risk parameters — but for a 5-parameter, zero-output-schema tool with substantial domain complexity, it is close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter-related contribution is thin: it explains the v3/v4 selector pattern and that version is optional when the selector is unambiguous, but the schema itself already documents each parameter (including 'copied verbatim' for reserveId). Most of the description's semantic depth concerns output fields, not parameters, so it does not exceed the schema-covered 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 opens with a specific verb and resource: 'Deep detail for a single reserve (rates, caps, risk parameters, utilisation, the interest-rate curve, token addresses) on v3 or v4.' This immediately distinguishes it from sibling list-style tools like get_markets, and the sentence 'get_markets quotes no price at all, so what an asset is worth on Aave is answered here' explicitly separates its scope from a sibling.

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

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

Explicit when-to-use and sequencing guidance is present: 'Use get_markets first to get the reserveId (v4) or market+token (v3).' It also gives an exclusion rule ('get_markets quotes no price at all') and warns about the collateralFactorPct misunderstanding ('do not look for one'). This is exemplary when/not-when guidance.

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

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

The description 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?

Beyond the readOnlyHint and non-destructive annotations, the description reveals that the tool is non-custodial, returns what the user signs, commits nothing, and that optional argument applicability is driven by the originating quote. It also discloses backend version behavior, adding meaningful operational context.

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

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

Every sentence carries a distinct and useful rule, and there is no filler. The middle sentence is a long run-on with multiple clauses, which slightly hurts readability, but the key constraints are still front-loaded and precise.

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

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

For a prepare-only tool with no output schema, the description covers the major behavioral traps: backend version, quote-driven optional arguments, unsolicited signatures, and non-custodial behavior. It relies on the schema for exact parameter descriptions and route defaults, which is acceptable given 100% schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable conditional semantics: permitSignature and permitDeadline are only valid after the quote explicitly offers a bySignature permit, and the transaction route accepts no signatures. This helps an agent decide parameter combinations rather than just reading individual 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?

States a specific verb and resource: prepare an order as typed data or a transaction to sign, sourced from a quoteId. It clearly distinguishes the signature-based and transaction-based routes, but it does not explicitly name sibling prepare_* tools to disambiguate from cancel/claim/action preparation.

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 conditional usage guidance: bySignature permits require permitSignature + permitDeadline, transaction route applies only to SwapByTransaction native-token sells, and signature arguments should never be sent unsolicited. It does not explicitly route to alternatives such as prepare_cancel_order or submit_signed_order, so it stops short of full when-vs-alternatives 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?

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?

Annotations already mark this as read-only and non-destructive, but the description adds substantial behavior beyond that: it commits nothing, reports the position's own limits rather than token allowances, and warns that a clean simulation does not mean no approval step remains. It also precisely defines the meaning of 'warnings' and its consequence for the prepare step.

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 justifiably so for an 11-parameter tool with two protocol versions and no output schema. It is front-loaded with the core purpose and usage rule, then organized into parameter routing, return-shape differences, and edge-case caveats. Every sentence carries operational information; there is 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 fully documents return values for both versions: healthFactorBefore/After, v4-only metrics, rewards fields, and warnings semantics. It also covers prerequisite data sourcing (fetch reserveId/market before first call), amount unit conventions, and sender requirements, so an agent has everything needed 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 already 100%, but the description meaningfully enriches the parameters: amount must be in MAIN units with an explicit base-unit conversion example, reserveId must be copied verbatim from session data and cannot be constructed, spokeId is explicitly rejected, market cannot be recalled from memory, sender must be the user-named wallet, and native's failure mode is explained. This is far beyond the schema text.

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

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

States a specific verb ('Simulate'), the concrete action set (supply/borrow/withdraw/repay), the evaluated resource (a wallet's position), and the key constraint (WITHOUT executing, on v3 or v4). The title and first sentence also make it immediately distinguishable from prepare_action and other sibling tools.

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

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

Gives an explicit rule: 'Always do this before a borrow or a withdraw' and 'Simulate first even when you intend to build immediately.' It also tells the agent what to do when simulation fails ('fix the inputs rather than building it'), which is an implicit when-not for proceeding to prepare/execute.

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.

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

Beyond the annotations, the description discloses that the operation is state-changing, that the server never signs (so the signature must come from the user), and that there is no version argument because all orders use v4. These are meaningful behavioral details not present in the annotations and they align with readOnlyHint=false.

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

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

The description is four short sentences, each carrying distinct information: version scope, what to relay, state-change effect, and server signing behavior. There is no filler or redundancy; the most important scoping note 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 two-parameter tool with no output schema, the description covers the essential operational context: prerequisite, inputs, state-change, and a critical server-side behavior. It omits what the response contains (e.g., order id or error conditions), which is a minor gap for an agent executing the call.

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

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

Schema coverage is 100%, so the parameters are already fully documented. The description mostly repeats the schema's origin info ('quoteId + signature from prepare_order's PreparedOrder') and adds no new semantic detail beyond that. A baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses specific verbs ('Relay', 'posts') with a clear resource ('an order') and explicitly distinguishes this from prepare_order by referencing 'quoteId + signature from prepare_order's PreparedOrder'. The version note ('every order runs on the v4 backend') further scopes the tool's behavior, leaving no ambiguity about what it does.

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

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

The description clearly establishes the prerequisite: use this after prepare_order, relaying the user's signed order. It does not explicitly name alternatives or state when not to use it, but the reference to prepare_order and the lack of other submit tools among siblings makes the intended usage obvious.

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