Get Portfolio Summary

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

Annotations already mark the call as read-only, idempotent, non-destructive, and open-world, and the description adds substantial behavioral context beyond those hints: it explains the return shape (raw balances plus totals_by_asset), how display totals are divided by 10^decimals, the network default, and the raw integer unit convention. There is no contradiction with 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 longer than one sentence, but every sentence earns its place: the first paragraph gives the purpose and sibling distinction, the second gives a critical network-handling rule, and the third prevents harmful unit misinterpretation. The layout with short labeled paragraphs keeps it easy to scan.

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

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

Given no output schema, the description compensates by stating the return fields, the decimals/display-total behavior, and the raw integer units. It also covers the dual-network constraint and tells the agent when to call other helpers to resolve decimals. This is sufficiently complete for correct invocation and safe user-facing use.

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 0%, so the description carries the burden of explaining parameters. It does well: it clarifies network choice and default, resolve_symbols's effect on registry lookups, and the 20-address limit for addresses. However, token_registry_address is only indirectly referred to via 'registry lookups' and is not explicitly explained.

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 ('summarizing balances for up to 20 addresses') and explicitly distinguishes this tool from raw get_balances, recommending it for user-facing balance explanations. This gives an agent clear signal about what the tool does and how it differs from its most similar 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?

It explicitly says to use this tool for user-facing balance explanations, not raw get_balances, and gives a concrete cap of 20 addresses. It also instructs the agent to confirm the network with the user when it is not explicit, which is important because the server serves both mainnet and testnet.

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