Get Balances

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so safety is covered. The description adds valuable behavioral context beyond annotations: the server serves both Obyte networks, network defaults to mainnet, and output amounts are raw integers in smallest units. It also warns against showing raw integers, which is exactly the kind of behavioral trap an agent needs 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 structured into clear paragraphs: purpose and alternative, network handling, and decimal semantics. Every sentence carries operational value, and the most important scoping information is front-loaded. It is long enough to be useful but not padded.

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 still prepares the agent for critical response semantics by mentioning raw integers, display_total fields, and decimal resolution steps. It covers network ambiguity, limits, and alternative tool routing. No required context for a correct call appears to be missing.

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 0%, so the description must compensate. It fully explains the network parameter including defaults and the need for user confirmation. It mentions the 1-to-20 address limit for the addresses parameter but does not describe address format or constraints beyond what the schema already encodes. Given the schema is silent, this is a meaningful but not complete compensation.

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 verb and resource: "Fetches balances for 1 to 20 addresses" and labels itself a raw hub read. It clearly distinguishes itself from obyte_get_portfolio_summary by offering that sibling as the agent-friendly alternative. This leaves no ambiguity about what the tool does.

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?

Explicitly directs agents to use obyte_get_portfolio_summary when summaries with decimals-adjusted display totals are preferred. It also gives actionable network-selection guidance and instructs the agent to confirm the network with the user when it is not explicit. This is strong when-to-use and routing guidance.

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