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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value beyond that: it defines the semantics of 'available' vs 'pending' and specifies the unit convention ('base unit, cents for AUD'), which the agent cannot infer from the empty schema. Auth requirements and rate limits are not mentioned, keeping it below 5.

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?

One information-dense sentence plus the endpoint, with the resource and its two components front-loaded. Every clause adds meaning — the pending definition and the unit convention both matter to correct interpretation.

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 no output schema, the description carries the burden of describing return values, and it does cover the key shape (available, pending, per currency, base units). It stops short of specifying whether the response is keyed by currency or an array, which is the only real omission for a zero-parameter read 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?

The tool takes zero parameters, so the baseline is 4. The description reinforces this with 'per currency' and the bare 'GET /balance' endpoint, making clear no filters or IDs are accepted.

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?

States a specific resource (the Pin Payments account balance) with its two components, available and pending, and defines what each means. The parenthetical definitions and the 'per currency' scope make it unmistakable against siblings like get_charge or get_transfer, which all operate on a resource ID.

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?

Usage is only implied — an agent reading 'current account balance' can infer it's for checking funds before a transfer, but the description never says when to reach for it or names any related tool (e.g. list_transfers) as an alternative. There is no alternative tool for balance, which softens the gap, but no explicit context is given.

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