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

With no annotations, the description carries the responsibility for behavioral disclosure. While it implies a read operation by describing a balance, it doesn't explicitly state that it is read-only, whether it requires authentication, or how it handles missing parameters. The additional note about ledger entries and tiny payments is more about the hub's economics than the tool's behavior, adding little transparency about execution semantics.

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 two sentences, with the first sentence front-loading the core purpose (balance, held, spendable, address). The second sentence provides extra context about the hub's ledger nature, which is somewhat tangential but brief. It is concise and efficient, with no redundant wording.

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 simple query tool with 2 parameters and no output schema, the description covers what it returns (balance, reserved, spendable, address) but lacks details like return format, behavior when asset is omitted, and whether it is read-only. It doesn't mention any side effects or prerequisites. Given the low complexity, this is adequate but still leaves gaps an agent might need.

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 50% (owner has a description, asset only has an enum). The description does not elaborate on the asset parameter (e.g., what happens if omitted, default asset, or how it affects results) nor on the owner parameter beyond the schema's 'Your agent id'. Since coverage is only 50%, the description should compensate but does not, leaving parameter meaning mostly to the schema.

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 that the tool retrieves balance information, including what is held against open tasks, spendable funds, and a top-up address. This goes beyond a tautology and distinguishes it from related tools like wallet_movements (which tracks movements) and wallet_statement (which likely provides ledger details). However, it could be more explicit that it is a query for balance, and it doesn't name sibling differentiators.

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?

There is no guidance on when to use this tool versus alternatives. It doesn't mention conditions like 'use this to check current balance' or 'for transaction history, use wallet_movements.' The description relies entirely on the tool name and the user's inference.

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