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

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

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

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

Three tight sentences deliver the core scope, parameter provenance, and the key alternative tool without repetition or filler. The most important constraint ('v4 only') is front-loaded, and every sentence earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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