Top up many Telegram accounts with GRAM

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

With no annotations, the description must carry full behavioral disclosure. It does reveal that the tool 'Builds ONE order' and 'returns messages[] to sign', indicating an intermediate step rather than a direct execution. But it omits other behavioral traits such as prerequisites (wallet setup, recipient validation), reversibility, failure modes, and any side effects beyond creating an order.

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 three short sentences, each adding essential information: the action and scope, the return value, and the coin restriction. It is front-loaded and contains no filler or repetition, making it highly concise and well-structured.

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?

Given the absence of annotations and an output schema, the description provides necessary core information (order creation, return of messages to sign). However, it lacks context about the wallet parameter, the role of referrer, and the overall flow (e.g., that messages must be signed and possibly confirmed via hoton_confirm). This is a moderate-complexity tool, so the description is not fully complete for an agent to use it confidently.

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 low (25%, only referrer described). The description partially compensates by clarifying that 'the same GRAM amount each' applies to recipients, aligning with amountEach and the 1–10 limit. However, it does not explain the wallet object or referrer beyond the schema, leaving significant semantic gaps for optional 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 uses a specific verb ('Build ONE order') with a clear resource ('toping up 1–10 Telegram accounts') and a specified coin ('GRAM (native chain coin)'). It also distinguishes from sibling tools by emphasizing the bulk nature and 'GRAM only', contrasting with star/premium operations.

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 implies when to use this tool (for bulk GRAM topups of 1–10 accounts) and provides output usage guidance ('Returns messages[] to sign with @ton/mcp'). However, it does not explicitly name alternatives (e.g., hoton_topup_gram for a single account) or state exclusions like 'not for buying stars'.

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