balance

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description reinforces this with 'never pays.' Beyond annotations, it adds rich context about the two identity modes (delegated ArisPay agent vs self-custody key-derived address), what data is returned, and the concept of spend-mandate limits, so an agent knows what behavior to expect.

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 sentences with no filler: the first establishes safety and output scope, the second gives concrete use cases. Every clause contributes information and the critical 'Read-only / never pays' signal is front-loaded.

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 tool with one optional parameter, rich annotations, and no output schema, the description covers safety, returned content, and when to use it. The only notable gap is the exact default behavior when the agent parameter is omitted, which would make the identity-selection semantics fully unambiguous.

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?

The schema already covers the optional agent parameter with 100% coverage. The description adds meaning by relating a stored agent to delegated custody and the PAYAGENT_PRIVATE_KEY to self-custody, which helps clarify the parameter's role. However, it does not explicitly state what happens when the agent parameter is omitted versus provided.

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 starts with 'Read-only: shows the active payment identity' and enumerates exactly what is returned: USDC deposit address, on-chain balance, and spend-mandate limits. It also links the tool to concrete tasks like finding where to send USDC and confirming a deposit, making it easy to distinguish from siblings such as pay, history, or check_payment_signal.

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?

The description explicitly gives three trigger conditions: find where to send USDC, confirm a deposit landed, and diagnose a failed payment. It does not name alternative sibling tools or state when not to use it, so it falls short of a 5, but the usage context is clear and actionable.

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