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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a specific verb and resource: it retrieves a wallet's Aave transaction history, enumerating the transaction types (supply, borrow, repay, withdraw, collateral changes) and the version scope (v3, v4, or both). It also differentiates itself from the closest sibling by explicitly saying use get_user_positions, not this, for holdings, so an agent can tell them apart without opening either schema.

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

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

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

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