Skip to main content
Glama
Sign In

noden

by com.getnoden
OverviewDiscussionsAdmin

purchase_skill

Purchase a skill. Validates input against the listing's schema and the caller's spend cap/allowlist, then, unless the account has enough prepaid credits (see below), returns a Lightning invoice for the exact price of one call; once the invoice is paid the skill runs and the result is checked against the listing's output schema. If the account has enough prepaid credits for the call, they are used automatically: the response has paid_with_credits true, credits_charged and credits_remaining, and no invoice — just poll check_order_status. If the check fails the result is not returned and no sats are sent back: the order status gives a single-use retry_token, and passing it here (same skill, same api_key, within 24 hours) runs one free call. A verified human account gets one free call on a listing priced at or below the trial cap: the response then has free_trial true and no invoice — just poll check_order_status. Every other purchase returns a Lightning invoice. Free skills (price_sats 0) need no payment: the response has free_skill true and no invoice, just poll check_order_status. 'input' (the skill's required input, matching its input schema) is required, and so is a key: pass 'api_key' (your operator API key), or set it once as an 'Authorization: Bearer ' header on this MCP connection. Spend-cap enforcement needs to know which operator is calling. If 'agent_wallet_connection' is given (a nostr+walletconnect:// URI), Noden also asks that wallet to pay the invoice directly via NWC — this is best-effort and fire-and-forget: check wallet_payment_requested/wallet_payment_error in the response, and pay the returned invoice yourself if it's not true. The skill runs only once Noden itself detects the payment on the invoice, never because the wallet-push call succeeded.

Input Schema

NameRequiredDescriptionDefault
inputYesInput matching the skill's input JSON Schema
api_keyNoYour operator API key. Optional if the connection sends it as an Authorization: Bearer header
skill_idYes
retry_tokenNoA retry_token from a failed order of this same skill: runs one free call instead of returning an invoice
agent_wallet_connectionNoOptional nostr+walletconnect:// URI — if given, Noden asks this wallet to pay the invoice

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Your operator API key"New value: +"Your operator API key. Optional if the connection sends it as an Authorization: Bearer header"
    • addedInput schema / properties / retry_token
      Added value: +{
+  "description": "A retry_token from a failed order of this same skill: runs one free call instead of returning an invoice",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "skill_id",
-  "input",
-  "api_key"
-]New value: +[
+  "skill_id",
+  "input"
+]
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full behavioral burden and does so thoroughly: validation against listing schema and spend cap/allowlist, automatic prepaid-credit consumption, no-refund-on-schema-check-failure semantics, the single-use 24-hour retry token, the free-trial eligibility rule, and the fact that NWC payment is best-effort and fire-and-forget while execution only triggers on Noden-detected payment. Authentication requirements and the exact response flags (paid_with_credits, free_trial, free_skill, wallet_payment_requested) are also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and primary invoice flow are front-loaded, but the bulk is a single dense paragraph of chained parentheticals covering five mutually exclusive outcomes, which makes it harder to parse than a short bulleted or segmented structure would be. Most sentences earn their place, but the packing hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, multi-branch payment-and-execution tool with no output schema and no annotations, the description covers what an agent needs to call it correctly and interpret the response: auth options, all payment outcomes, failure/retry behavior, and the response flags to branch on. 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.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, and the description adds real meaning beyond it: 'input' must match the skill's input schema, api_key can be supplied per-call or once as a Bearer header (and is needed for spend-cap attribution), retry_token is scoped to the same skill/api_key within 24 hours, and agent_wallet_connection triggers an optional best-effort wallet push whose result must be verified. skill_id is left to the schema, but that gap is minor given the rest of the coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('Purchase a skill'), and the rest of the description makes the multi-branch purchase flow explicit: invoice path, prepaid-credit path, retry-token path, free-trial path, and free-skill path. It also names the sibling tool to use afterward ('poll check_order_status'), so an agent can distinguish it from status-checking and listing tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear conditional guidance on which outcome to expect and explicitly routes the agent to check_order_status after every no-invoice case. It does not explicitly state when to use get_skill or search_skills instead (e.g., previewing or finding a listing before purchasing), so the sibling routing is incomplete rather than absent.

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

All noden toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources