nwc_pay_keysend

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

No annotations are provided, so the description carries full burden. It discloses no payment hash receipt, weaker safety surface, and the full safety pipeline (read-only gate, allowlist, budget cap, optional two-step confirmation). This is rich behavioral context beyond the schema.

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, front-loaded with the core purpose, then caveats and safety details. Every sentence adds unique value without waste.

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 complexity of a payment tool with no annotations and no output schema, the description covers the essential aspects: default-off toggle, safety pipeline, invoice comparison, and what to expect (no payment hash). It is sufficiently complete for an agent to decide and invoke correctly.

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 description need not elaborate on parameters. It does add minor value by mentioning TLV records usage examples (e.g., podcasting 2.0 metadata), but the schema already documents all fields well. This meets the baseline for high schema coverage.

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 'Send sats directly to a node pubkey via keysend (spontaneous payment, no invoice),' which specifies the exact action, resource, and method. It distinguishes from siblings like nwc_pay_invoice and nwc_pay_lightning_address by emphasizing pubkey-based, no-invoice payments.

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 provides usage context: 'Default-off — must be opt-in via NWC_KEYSEND_ENABLED=true' and 'Use bolt11 invoices when available.' This tells when to use the tool and when to prefer alternatives, plus notes it's a power-user feature.

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