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

No annotations are provided, so the description carries the transparency burden. It discloses that the call is free, that proof of npub ownership is required, and explains why it is required (preventing credit-grant front-running). This meaningfully informs the agent 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?

The description is compact and front-loaded with the core purpose. Every sentence adds value: the what, the when, the cost, and the authentication requirement. No filler or redundancy.

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 rich input schema, output schema presence, and clear usage context, the description covers all essential operational knowledge: what the tool does, when to call it, its cost, and the required proof. Return values are already covered by the output schema, so no further detail is missing.

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% and each parameter already has detailed documentation, including the non-base64 dpop_token framing. The description adds minor context by linking invoice_id to purchase_credits and explaining the security rationale, but it does not need to compensate for schema gaps.

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 opens with a clear, specific verb-resource pair: 'Check the payment status of a Lightning invoice.' It further distinguishes itself from sibling check tools by tying the invoice to purchase_credits, making the tool's unique role immediately identifiable.

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 gives explicit when-to-use guidance: 'Call after paying the invoice from purchase_credits.' It also states the free cost and the npub ownership prerequisite. It does not explicitly describe when not to use it or name alternatives, but the sequencing and conditions are clear.

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