Create invoice

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

Adds real behavior beyond the annotations: it discloses what the call returns (a payment_url), that the exchange rate is locked at creation in USD mode, the 10 USD floor, and that reusing order_id returns the existing invoice rather than creating a duplicate. This usefully qualifies the flat idempotentHint=false annotation by explaining conditional idempotency; the slight tension is reconcilable rather than contradictory. Not disclosed: rate-limit/auth needs or invoice expiry default behavior beyond the schema's own note.

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 tight sentences: purpose/return first, then the mode selection rule, then the constraint and idempotency tip. No filler and every clause carries information an agent needs before calling.

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 9-parameter mutation with no output schema, the description covers the essentials: what is created, what comes back (payment_url), how the two pricing modes differ, the minimum amount, and idempotency via order_id. The remaining parameters are fully described in the schema, so nothing critical is missing, though a note on expiry semantics would close the last gap.

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% and the schema already documents each field, so baseline is 3. The description adds the mutually exclusive either/or relationship between price_usd and token+amount and the 10 USD minimum, which the schema does not state, but leaves tokens, success_url, metadata, and expires_in_minutes entirely to the schema.

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+resource ('Create a payment request') and immediately names the concrete artifact produced ('hosted payment page (payment_url)'). This is clearly distinguishable from the read/cancel siblings (get_invoice, list_invoices, cancel_invoice) without opening any schema.

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 routes between the two pricing modes: 'Either price_usd (customer picks TRX or USDT, rate locked) or token + amount (fixed coin amount)', and gives a business constraint (minimum 10 USD) plus the order_id idempotency/find-later pattern. It stops short of naming sibling alternatives (e.g. use get_invoice/find_invoice_by_order to retrieve instead of re-creating), so it is clear context without full exclusion guidance.

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