suggest_order_size

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

With no annotations, the description carries the full burden, and 'Free, offline' is a meaningful disclosure that this is a local, costless, non-networked computation rather than a live chain query. It also exposes data provenance via the measurement date (2026-09-30) and the per-transfer constants, which hints at staleness risk, but never states outright that it is read-only and side-effect free.

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?

Three sentences with no filler, and the punchy 'Free, offline.' lead is front-loaded before the purpose and the prerequisite. The parenthetical figures are dense but earn their place by quantifying the parameter distinction.

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?

The computation and its inputs are fully specified, but there is no output schema and the description never says what is returned — energy units, a TRX cost equivalent, or an object with both. For a sizing tool whose entire value is the returned number, that return-shape gap is the remaining hole.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the distinction between recipients that already hold USDT and those with a zero balance is tied to concrete energy costs (64,285 vs 130,285 per transfer), explaining why the two counts are separate parameters.

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 names the exact quantity being produced ('How much energy to order for N USDT transfers') and enumerates the two input dimensions that drive it, so the agent knows precisely what computation this performs. It stops short of explicitly distinguishing itself from the closest sibling, estimate_contract_call, which could also be read as an energy estimator.

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?

It gives a concrete prerequisite and ordering rule: 'Use get_address_resources first to know which case a recipient is,' which tells the agent the tool must be fed with classified recipients rather than raw addresses. There is no explicit when-not-to-use or comparison against alternatives like estimate_contract_call.

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