get_balance

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

With no annotations, the description carries the full burden and does well: it reveals testMode behavior, the closed-loop nature of coins (not cash/withdrawable), and instructs not to spend if the wallet is frozen. It omits potential error conditions, but the key behavioral constraints are disclosed.

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 front-loaded with the core purpose and triggers, but it becomes crowded with product-answer policies like 'Quote prices as N коинов' and 'do NOT say «тестовые коины» in every product answer,' which are tangential to invoking get_balance. Each sentence has some value, but the structure is less crisp than the best examples.

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 zero-parameter, no-output-schema read tool, the description covers the return fields, when to call it, and important edge cases such as testMode and a frozen wallet. It does not describe errors or what happens if the wallet is unconnected, but the mention of verify_connection supplies the main prerequisite.

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 has zero parameters, and the schema fully documents this with an empty properties object and additionalProperties false. The description needs to add no parameter semantics, and the baseline for zero-parameter tools is 4.

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 clearly states the tool retrieves the agent's AgentPay wallet and lists the returned fields (testMode, testBalance, realBalance), so the verb and resource are specific. It does not explicitly contrast with sibling tools like get_limits or get_spending_policy, but the balance focus is evident from the trigger phrases and return values.

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?

Explicit trigger conditions are provided: it should be called when the user asks about balance/budget in Russian or after verify_connection. However, it does not state when not to use this tool or name alternatives, so it falls slightly short of the highest bar.

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