No output schemas documented for any tool. Agents cannot see what fields to expect in responses, cannot plan tool chaining, and must infer structure from execution. This breaks downstream planning and increases hallucination risk.
Critical parameters lack type constraints and validation rules. Examples: 'amount_sats' has no bounds (0-21M BTC max); 'fee_rate_sat_per_vb' has no range; 'expiry_secs' has no min/max. LLMs cannot validate input and will pass absurd values (negative amounts, epoch timestamps as fee rates).
Document output schemas for all 28 tools. For each tool, add a 'returns' section in the definition describing the response object fields, types, and what each field means. Example: 'Returns: { channel_id: string (unique channel identifier), balance_msat: number (millisatoshis), counterparty_node_id: string (hex-encoded public key), state: enum(Active|PendingClose|Closed) }'
Add min/max constraints to all numeric parameters. Examples: amount_sats: integer, minimum: 1, maximum: 2100000000000; fee_rate_sat_per_vb: integer, minimum: 1, maximum: 1000; expiry_secs: integer, minimum: 60, maximum: 86400. Document these in parameter descriptions as well.
Add format and length constraints to hex string parameters. Examples: node_pubkey: 'hex-encoded 33-byte public key (66 hex characters, lowercase)'; signature: 'hex-encoded signature (128 hex characters)'. Use JSON Schema pattern field with regex (^[0-9a-f]{66}$ for pubkeys).
For mutually exclusive parameters (description vs description_hash in bolt11_receive), add explicit notes: 'description and description_hash are mutually exclusive, pass one or the other, not both.'
Add dry-run or confirmation patterns to irreversible operations. Examples: Add optional 'confirm: boolean' param to onchain_send, bolt11_send, open_channel. Document: 'If confirm=false, returns estimated outcome without executing. If confirm=true, executes irreversibly.'
Document pagination behavior and limits for list tools. Example: 'Returns up to 50 results per page. Pass page_token from response to fetch next page. Total count included in response. Maximum 500 results per request.'
Score history
Overall score trend
↓ 31 points across a rubric change (v1 → v2)
13/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
13
2026-07-28+
v2
2026-03-09
F
44
2024-11-05+
v1
Mutually exclusive parameters not documented. Example: bolt11_receive has 'description' and 'description_hash' marked mutually exclusive in risk metadata, but LLM won't see this constraint in parameter descriptions. LLMs will pass both, causing silent failures.
Destructive and irreversible operations (onchain_send, bolt11_send, bolt12_send, open_channel, force_close_channel) lack confirmation or dry-run guidance in descriptions. Descriptions do not warn agents about irreversibility or suggest confirmation steps.
List/pagination tools (list_channels, list_payments, list_forwarded_payments, graph_list_channels, graph_list_nodes) accept page_token and limit but do not document result caps, total counts, or when pagination is required. No guidance on batch size limits.
Parameters requiring hex-encoded strings (node_pubkey, node_id, message, public_key, signature) lack format hints. Descriptions say 'hex-encoded' but do not specify case sensitivity, length constraints, or validation. LLMs frequently mangle hex inputs.
No error recovery guidance. Tool descriptions do not explain failure modes or recovery paths. Example: if open_channel fails, should the agent retry, check balance, or ask the user? No guidance given.
Enums not declared for constrained parameters. Examples: 'announce_channel' is boolean but 'force_close_reason' is a free-form string (should be enum). 'network' in config can be bitcoin|testnet|testnet4|signet|regtest but no schema validation.
open_channelforce_close_channel
Add error guidance to descriptions of risky operations. Examples: 'If balance insufficient, call get_balances first. If peer offline, call list_channels to verify connection. If channel not found, peer may have closed it, check list_channels.'
Declare enums for constrained string parameters. Examples: force_close_reason should accept specific values (PeerManagementDecision, CounterpartyCoopClosedUnfairlyExpanded, OutdatedChannelManager, etc.). Document allowed values in schema.
Document which parameters are required vs optional with defaults. Example: 'expiry_secs defaults to 86400 (1 day) if omitted. fee_rate_sat_per_vb defaults to estimated network rate if omitted.'
Add tool composition examples in descriptions. Example for open_channel: 'Prerequisites: peer must be online (call connect_peer first). On-chain funds required (call get_balances to verify).'
Document idempotency guarantees for each tool. Which tools can be safely retried? Example: 'get_node_info is idempotent (read-only). onchain_send is NOT idempotent, will send twice if called twice.'
Add risk/cost warnings to monetary operations. Example for onchain_send: 'WARNING: Irreversible on-chain transaction. Network fees apply (fee_rate_sat_per_vb). Verify address and amount before confirming.'
Document timeout behavior and retry guidance. Example: 'If no response after 30s, the operation may still be pending. Check list_payments to verify payment status before retrying.'