Draft a payment request

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond them: it explains that the entire request is encoded in the link, that no signing/sending/settlement occurs, and that only the payer's wallet can move funds. It also discloses the reference format nimbooks:invoice:<id> and a unit subtlety between the link payload and this tool's output.

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 key action and its non-effects are front-loaded in the first two sentences, and each sentence carries real information. The closing unit note is dense and slightly convoluted to parse on first read, which keeps it from a 5.

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?

Though there is no output schema, the description explains what comes back (a shareable app link), where the payload lives, how the resulting payment is identifiable later, and a unit pitfall that could otherwise cause a wrong-amount request. Nothing material is missing for correct invocation.

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 would be 3, but the description adds genuine value by pre-empting a dangerous unit confusion: it clarifies that amountNim inside the link is Luna-denominated per the app's link format while this tool's output reports NIM and Luna separately. It does not walk through the other params (id, memo, payee, expiry), but the schema already documents those thoroughly.

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 ('DRAFTS a payment request') plus the immediate result ('returns a shareable link'), and explicitly contrasts with what it does not do (sign, send, mark paid). The follow-up relationship to check_request_paid is named, so an agent can place it in the workflow without opening the 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?

The description makes the use case clear (produce a link that a payer's wallet can act on) and names the downstream consumer check_request_paid, which gives context for sequencing. What's missing is an explicit when-not-to-use or a named alternative sibling (e.g., list_invoices for existing requests), so it falls short of a 5.

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