SatsDNS

Status of an account order's invoice (free, API key or signature)

order_status

Free: the invoice's state (paid, fulfilled, expired, ...) and, after fulfilment, the result. A new object's token (and TSIG key) is shown once, only to a nip98 call, within 1 hour of fulfilment; an api_key sees the state only, and only of invoices for objects in its scope (invoice_not_found otherwise). Called without nip98 it returns signature_required: the exact URL, method and body to sign, the body's sha256 and an unsigned kind 27235 event template (with proof of work for accounts without a paid order). Sign that, then call again with the same arguments plus nip98. Each signed event works once, within 60 s. Secrets that are ours to receive: object tokens, account API keys (jdk_), signed NIP-98 events; never a private key (nsec or 64 hex characters), wallet connection string or seed words. A raw hex key or seed words inside a sentence cannot be caught here.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "invoice_id": "<invoice_id>"
    },
    "name": "order_status"
  }
}

Input Schema

Name	Required	Description
`nip98`	No	The signed NIP-98 event (base64 of its JSON) for exactly the request the signature_required answer of the same call named. Sign it with your own Nostr signer (local key, NIP-46 bunker or a signer tool); never send the private key itself, in any form (nsec, hex or seed words).
`api_key`	No	A scoped account API key (jdk_...) made in the dashboard. It passes through your model context and transcript: treat it like a password. Key model: a key reads (or, with write access, changes) only the objects in its scope, and sees only their invoices; every key reads the account view (limits and counts); a key never orders new objects and never receives a new object's shown-once token.
`invoice_id`	Yes	The invoice id (inv_...) from account_order.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 28, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Rich disclosure beyond the annotations: the one-time token display limited to nip98 within 1 hour of fulfilment, invoice_not_found for out-of-scope keys, single-use signed events valid for 60 s, and the proof-of-work condition for accounts without a paid order. These are exactly the non-obvious side effects (a read that reveals a shown-once secret and consumes a nonce) that annotations like readOnlyHint=false and idempotentHint=false only hint at.

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?

It is one dense run-on block of colon-delimited clauses, and the leading "Free:" fragment is a weak front-load relative to the tool's main purpose. Nearly every sentence carries information, but the closing secret-handling warning (nsec, wallet strings, seed words) is partly boilerplate that could be compressed. Structure is serviceable, not efficient.

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

Completeness4/5

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

For a 3-parameter read-ish tool with no output schema, it covers the auth modes, the error paths, the token-once timing and the scope rules the caller must respect. The remaining softness is that "the result" after fulfilment is never characterized, so the agent does not know what the fulfilled payload actually looks like. That gap keeps it at 4.

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 100%, so the baseline is 3, but the description adds cross-parameter meaning: nip98 must sign exactly the request the signature_required answer named and be the same arguments, api_key is scoped to objects and yields invoice_not_found outside it, and invoice_id comes from account_order. It does not add format or example details beyond the schema, so 4 rather than 5.

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

Purpose4/5

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

The opening clause names the resource and the returned value precisely: "the invoice's state (paid, fulfilled, expired, ...) and, after fulfilment, the result." The title adds the account-order scope, and the invoice_id param description cross-references account_order, so an agent can tell this apart from the ordering sibling. It stops short of explicitly naming when to prefer this over account_order/zone_status, keeping it at 4.

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?

It lays out the actual call flow: a free call returns state, an api_key sees state only within its scope, and a call without nip98 returns signature_required with the exact URL, method, body, sha256 and event template, then you sign and call again. That is real when/how guidance including a successful two-step path. It does not tell the agent which of the three auth modes to prefer in a given situation, so it falls short of 5.

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

All SatsDNS tools Inspect

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

Need Help?