Wallet Balances & History

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing behavioral on top — no rate-limit or credit-cost notes, no pagination behavior despite cursor/limit/after/before parameters, and no indication of how expensive the nine actions are relative to each other.

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 short sentences, front-loaded with the resource scope followed by the usage rule, with no filler or repetition. It is efficient, though the brevity is partly under-specification rather than discipline given the tool's breadth.

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 nine-action, twenty-parameter tool with no output schema and very low schema description coverage, two sentences are not enough to call it correctly. The agent is left guessing action selection, parameter applicability, and pagination semantics with no compensating 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?

With 20 parameters and only 15% schema description coverage, the description carries the burden of explaining parameters but only loosely gestures at "balances, holdings, identity and history" with no mapping to actions or fields like mint, slot, detail, showNfts, showZeroBalance, or addresses. An agent still cannot infer which parameters apply to which action, which is the largest gap in this definition.

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 resource domains (balances, holdings, identity, history) but uses a noun-phrase list with no verb and never enumerates the nine actions in the `action` enum, so an agent cannot tell from the text that transfers, funded-by, batch identity, or historical-slot queries are supported. It does distinguish itself conceptually from raw token accounts, but the scope of the mega-tool stays fuzzy.

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?

"Use for portfolio views, not raw token accounts" gives one when-to-use case and one exclusion, which is real guidance. However, the exclusion does not name a concrete sibling tool (heliusAsset or heliusTransaction), and no guidance is given for choosing between the nine actions, which is the actual routing decision an agent faces.

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