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

Beyond readOnlyHint=true, it discloses the non-obvious behavior that the returned onchain_validation is marked not_executed until the client performs its eth_call, and that deployment resolution is automatic from owner. That is genuinely useful context an agent could not infer from the annotation. It does not discuss pagination or size limits for large allocation sets.

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, front-loaded with the trigger phrase, then defaults, then return shape, then the alternate-deployment caveat. Nothing is redundant, though the long middle enumeration of return fields is denser than needed given an output schema exists.

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 an output schema present, the description correctly avoids over-explaining return structure while still flagging the not_executed validation caveat. Annotations cover safety and the schema covers params, so the remaining gaps (pagination, behavior for empty allocations) are minor for a read-only lookup 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 3 is the baseline, but the description adds deployment-resolution meaning: omitting chain_id/ve_token selects the production STONX chain and canonical VeToken, and the two must be supplied as a pair for other deployments. The canonical token identity is also spelled out. The addition is largely reinforcement of the schema text rather than new syntax detail.

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 gives a concrete verb and resource ('show all my Ekubo STONX allocations') and enumerates what comes back (pools, swap fee, NFT, vote weight, totals, state_id). It also pins the deployment identity (production Ekubo ve(3,3) = STONX voting system). It does not explicitly contrast with the closest siblings such as get_stonx_allocation_recommendation or get_positions_by_owner, so it stops short of full differentiation.

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 front-loads a usage pattern ('Use for requests such as ...') and gives a clear conditional rule: pass only owner for production, pass chain_id and ve_token together only for another deployment. The schema adds the 'ask the user when no wallet address is available' fallback. Missing is any explicit statement of when to prefer a sibling read tool instead.

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