build_payment_unsigned

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

No annotations are provided, so the description carries the full burden. It states the tool does not sign ('Never signs'), returns unsigned JSON plus instructions and preflight, and defaults to testnet. This reveals key behavioral traits (no mutation, preflight validation, network default). It could be improved by explicitly stating it does not modify state or require special authorization, but it is still informative.

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?

Two concise sentences containing all essential information. Front-loaded with purpose and key behavior. No extraneous words.

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 no output schema and 5 parameters, the description adequately outlines the output (unsigned JSON + offline signing instructions + payload preflight) and the default network. It could be more specific about the structure of the returned JSON or what 'preflight' entails, but it is reasonably complete for a tool among many build_*_unsigned siblings.

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 only 20% (only amountDrops has a description). The description adds minimal parameter context: it states amounts are in drops (which schema already indicates) and mentions offline signing instructions, but does not explain account, destination, or destinationTag beyond schema basics. Baseline for low coverage is that description should compensate; it does not sufficiently elaborate parameter meanings.

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 action ('Assemble an UNSIGNED XAH Payment'), the resource (XAH Payment), and key attributes (amount in drops, returns unsigned JSON + offline signing instructions + payload preflight, never signs, testnet default). This distinguishes it from sibling tools like build_sethook_unsigned or build_claimreward_unsigned.

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 mentions 'Never signs; testnet by default,' which implies when to use (for preparing unsigned payments) but lacks explicit when-not-to-use or comparisons with alternatives. Sibling tools are not referenced, so guidance is limited to implied context from the tool name.

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