lightning_create_invoice

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

With no annotations at all, the description carries the full burden, yet it says nothing about prerequisites (e.g., whether the Lightning wallet must be created or unlocked), invoice expiry, or whether the returned invoice reserves funds. It only identifies the tool as a receiving operation.

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 first sentence is efficient and front-loaded. The second sentence is a promotional pointer to an unrelated tool and does not help an agent invoke this one, which weakens the structure.

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?

There is no output schema and no annotations, so the description should at least indicate the return shape (a BOLT-11 string) and operational prerequisites. Those gaps leave an agent without enough context to call this confidently in a complex wallet ecosystem.

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 100% for both amountSats and memo, so the schema already explains both parameters. The description adds no additional parameter meaning such as units or constraints beyond what is structured, so the baseline of 3 applies.

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 states a specific verb and resource: create a BOLT-11 Lightning invoice that receives payment into the embedded Lightning wallet. That is enough to distinguish it from lightning_pay_invoice, though it does not explicitly differentiate itself from the similarly named sibling lightning_create.

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?

Usage is implied by 'can receive a payment' but there is no explicit statement of when to use this versus alternatives such as lightning_create (wallet setup) or lightning_pay_invoice (sending). The closing tip about earning_opportunities does not provide guidance for invoking this tool.

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