Use NimBooks MCP as a read-only assistant for a Nimiq address: inspect balances, history, statements, staking, validators, rewards, and draft payment/stake links without signing or sending anything.
Get account summaries with balance and money in/out over a chosen window.
List classified transactions with kind, counterparty, memo, and reference.
Generate day-by-day tax-style statements with USD prices where available.
Draft payment request links and check whether a request has been paid.
List saved invoices from a NimBooks backup file, without accessing cashlink secrets.
Read staking positions, validator pools, expected yields, and earned rewards.
Project potential staking yield year by year.
Draft stake links pre-filled for the NimBooks app, without selecting a validator or sending a transaction.
An MCP server that gives an AI assistant read access to your Nimiq books — balances, classified history, tax-basis statements — and lets it draft payment requests and stake links.
It runs on your machine, reads the public chain, and cannot spend a single Luna.
you: "How much came in last month, and who from?"
you: "Draft a request for 25 NIM for the September retainer."
you: "Has anyone paid request a1b2c3d4e5 yet?"This is the part to read first.
It never signs anything. There is no key handling in this package at all — nothing
generates, stores, reads, derives or asks for a private key, a seed phrase or a
passphrase. create_payment_request and draft_stake return links. A link is a
request or a pre-filled draft, never a signature. Only the payer's wallet can move
money, and only when its owner approves the payment there.
It never sends anything. No transaction is built, broadcast or queued. Nothing is marked paid — not on chain, and not in your app's own books.
It has no server. The only hosts this process contacts are rpc.nimiqwatch.com
(the public Nimiq RPC the NimBooks app already uses), v2.nimiqwatch.com (Nimiq Watch's
public analytics API, the same endpoint the app reads for staking rewards and for the
validator record that confirms who paid them),
validators-api-main.je-cf9.workers.dev (the validator list the NimBooks app reads:
names, fees, reliability) and api.coingecko.com (public daily prices, for statements).
It never calls nimbooks.subimpact.net. The links it
mints contain that address, the way a printed invoice carries a street address:
that is data, not a request.
It writes nothing. Every tool is a read or a pure function. The backup file you point it at is opened read-only.
It is not a wallet, and not a replacement for one. It reads what the chain already says in public about an address you name.
Not sure? The whole server is seven files under src/, about 3,400 lines. src/index.ts
is the tool surface; there is nothing else to audit.
Related MCP server: dero-mcp-server
Node 20 or newer. Nothing to clone — from npm:
npx -y nimbooks-mcp --helpOr from source, if you would rather build and audit it yourself:
git clone https://github.com/subimpact/nimbooks-mcp
cd nimbooks-mcp
npm install
npm run build # → dist/index.jsclaude_desktop_config.json → Settings → Developer → Edit Config:
{
"mcpServers": {
"nimbooks": {
"command": "npx",
"args": [
"-y", "nimbooks-mcp",
"--address", "NQ82 6GYU NXUU 05DM 1M7F 0SJJ D42E NUNS KELR"
]
}
}
}Restart Claude Desktop. The eleven tools appear under the tools icon.
claude mcp add nimbooks -- npx -y nimbooks-mcp \
--address "NQ82 6GYU NXUU 05DM 1M7F 0SJJ D42E NUNS KELR"Built from source instead? Point both commands at
node /absolute/path/to/nimbooks/mcp/dist/index.js in place of npx -y nimbooks-mcp.
Flag | What it does |
| The account tools use when a call doesn't name one; the server tells the assistant about it, so questions like "how are my books looking?" work without repeating your address. Optional — every tool also takes an address argument. |
| A NimBooks backup file. Only |
Getting a backup file: the app keeps your payment requests on the device, not on a
server — so a file is the only way to show them here. In NimBooks: Backup → Copy,
then paste into a file, e.g. ~/nimbooks-backup.json, and pass it with --backup.
Without it, list_invoices says so and points at check_request_paid, which asks the
chain instead.
A backup also contains your cashlink shelf, and those entries hold the private keys of links that may still hold NIM. Keep the file as carefully as a wallet. This server never opens that part of it — not "reads it and drops the field": it is discarded at the door, and a test asserts it can never reach the output.
Tool | Answers |
| Balance now, plus money in/out, fees, rewards and transaction counts over a window. Nimiq Pay's round trips through its own contracts are reported apart, as internal. |
| Classified rows — kind, direction, counterparty, memo, hash. |
| Day-by-day in/out for a year or month, priced at each day's CoinGecko UTC close, with Nimiq Pay's internal round trips in their own columns. |
| Drafts a request and returns a shareable link. Signs nothing. |
| Drafts a stake link that opens the app's stake panel pre-filled. Signs nothing. |
| Whether a payment tagged with a request's reference has landed. |
| Requests stored in your backup file. |
| The staked position: active, cooling down, retired, the pool, fee, net yield, an unstake clock, and a first-year estimate. |
| The validator pools in the app's neutral order (producing first, best net yield first, nothing pinned), with fees, yields and the median. |
| What staking an amount might earn, year by year, with its assumptions spelled out. |
| The rewards earned in a window, per pool, with an actual yield over the trailing 30 days. |
Defaults and limits, stated plainly:
get_summary and get_statement read up to the newest 1000 transactions;
check_request_paid scans the newest 200. When a cap is hit, the answer says so.
Nimiq Pay wallets: Pay moves your NIM through its own contracts (HTLCs) and most of
it comes back. Like the app (its Hide internal switch), get_summary and
get_statement keep those round trips out of money in/out and report them as
internalIn/internalOut; net counts both. To tell a contract that still holds your
NIM, or that staked it from inside Pay, the server reads each contract you funded that
has not paid it all back (two RPC calls each, at most 40 contracts, kept for 5 minutes).
A busy Pay wallet's first answer can take 15 to 25 seconds. If a contract cannot be
read, payContractsNote says so: NIM still in it may then be counted as sent.
get_summary windows default to all available history → now. since/until take
YYYY-MM-DD or ISO 8601, read as UTC.
list_transactions returns 50 rows by default, 500 at most.
Balance is the live basic-account balance, not the balance at the end of a window. Staked NIM lives in the staking contract, so it is reported separately.
Statements exclude failed transactions, count fees on outgoing transactions only, and
price each UTC day at that day's CoinGecko close. A day with no close available comes
back null rather than a guess — and the USD totals are withheld entirely rather
than summed from a partial year.
CoinGecko's public API only serves the last 365 days of prices. Ask for an older year and the NIM figures are still exact, but the USD columns come back empty — and the answer says so, in those words. The NimBooks app has the same ceiling. A paid CoinGecko key would lift it; this server does not take one, because taking one would mean holding a credential.
Addresses may be typed NQ82 6GYU …, flat, lower-case, or as 40 hex characters. They
are checksum-validated: a typo is refused, never quietly looked up.
Amounts come back in both Luna (integer, exact) and NIM (exact decimal string). No float arithmetic touches money anywhere in this package.
list_validators returns 50 pools by default (1 to 50); non-producing pools are
included unless you ask otherwise. The validator list is fetched at most once per
10 minutes.
get_rewards only sees restaking (compounding) pools: a direct-payout pool's rewards
arrive as ordinary incoming transactions and show up in list_transactions. The
public rewards data starts January 2025 and can lag by a day; per-day rows are
capped at the newest 400. Only validators pay rewards: the public feed also lists a
stake made in Nimiq Pay (it travels through a contract) as a "restake", so each payer
is checked against Nimiq Watch's validator record and anything that is not a
validator is left out, as in the app since v1.40.0. A payer whose record cannot be
read is kept.
Yield figures are labelled as projections: emission falling with the supply curve is modelled, the network's total stake is held at today's level, and none of it is a promise.
What's the balance, and how much came in during August?
Show me the last 20 transactions — anything that wasn't a plain payment?
Statement for September 2026, with the USD close for each day.
Draft a payment request for 12.5 NIM, memo "September retainer", expiring in 7 days.
Has request a1b2c3d4e5 been paid?
List my saved payment requests and tell me which are still open.
What is my stake earning?
Which pools pay the most right now?
If I stake 1,000 NIM for 3 years, what might I earn?
What rewards did I earn this year, and from which pool?A link drafted here must be the same bytes the NimBooks app would have produced, or it
won't open when someone taps it. Parity is enforced in the NimBooks app repository: its
test suite imports the app's real invoice encoder and compares the two across every
combination of amount (1, 0.5, 12.5, 100000, and 0.000001, which both sides
must refuse, being finer than a Luna), memo (ASCII, emoji/CJK, none) and expiry (none,
set), with and without a named payer, then round-trips each link back through the app's
own decoder. Transaction classification and statement aggregation are pinned the same
way, row for row, including the cashlink tag, the nimbooks:invoice:<id> reference, the
Nimiq Pay netting (tx by tx against the app's own module, on a real Pay wallet's history), and
the staking legs.
npm test # offline: backup parsing, including malformed entries and the cashlink-secret fence
npm run smoke # opt-in: drives the built server against a live demo wallet over stdionpm run typecheck covers src/. The cross-checks against the app's own modules
(invoice and stake-link byte-parity, classification fixtures, statement aggregation,
stdio round trip)
run in the app repository on every release.
MIT.
Looks for a payment tagged with a request’s reference (nimbooks:invoice:) in the address’s transactions — the same match the NimBooks app uses to mark a request paid. Read-only: it reports what the chain says and changes nothing, here or in the app. Scans the newest 200 transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The request id, as returned by create_payment_request. | |
| address | No | The payee address the request was made for. Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this without merely repeating it ('reports what the chain says and changes nothing, here or in the app'). The genuinely valuable addition is the disclosure that it scans only the newest 200 transactions, which tells the agent a negative result is not proof of non-payment. It stops short of describing the response shape, which matters since no output schema exists.
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?
Three tight sentences, front-loaded with the matching mechanism, followed by the safety profile and the scan limit. Every sentence carries distinct information with no repetition of the title or annotations.
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?
For a two-parameter read-only lookup with full annotation coverage, the description covers mechanism, safety, and the main accuracy caveat. The notable gap is the return value: with no output schema, an agent cannot tell whether it gets a boolean, a matching transaction, or a confirmation count.
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 coverage is 100%, so the baseline is 3; the description earns a bump because it explains how the id parameter is actually used — transformed into the nimbooks:invoice:<id> reference tag that the search keys on — which the schema alone does not convey. The address parameter's default behavior is left entirely to the schema.
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?
States a specific verb and resource ('looks for a payment tagged with a request's reference') and names the exact tag format (nimbooks:invoice:<id>), so the agent knows precisely what matching logic runs. It also implicitly distinguishes itself from create_payment_request by consuming that tool's id, and from generic listing tools like list_transactions by being a targeted lookup.
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?
It gives clear context for when this is the right call (verifying whether a payment request has been settled, using the app's own matching rule) but never states exclusions or names the alternative to use when the payment is older than the scanned window — e.g. falling back to list_transactions or get_statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DRAFTS a payment request and returns a shareable link. This never signs anything, never sends anything, and never marks anything paid — the whole request rides inside the link, and only the payer’s wallet, with their approval, can actually move money. The link opens in the NimBooks app; the payment it produces carries the reference nimbooks:invoice:, which check_request_paid looks for later. Note: inside the link, the payload field amountNim is denominated in Luna by the app’s link format; this tool’s own output reports amountNim in NIM and amountLuna in Luna.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Fixed request id, for reproducible links. Generated when omitted. | |
| memo | No | What the request is for, up to 80 characters. Travels in the link, not on chain. | |
| payee | No | Address to be paid. Optional; defaults to the server’s configured address. | |
| expiry | No | When the request stops being valid: "1h", "24h", "7d", "none" (default), or an ISO 8601 timestamp. | |
| amountNim | Yes | Amount in NIM, as a decimal string — "12.5". Up to 5 decimals (1 NIM = 100000 Luna). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond them: it explains that the entire request is encoded in the link, that no signing/sending/settlement occurs, and that only the payer's wallet can move funds. It also discloses the reference format nimbooks:invoice:<id> and a unit subtlety between the link payload and this tool's output.
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 key action and its non-effects are front-loaded in the first two sentences, and each sentence carries real information. The closing unit note is dense and slightly convoluted to parse on first read, which keeps it from a 5.
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?
Though there is no output schema, the description explains what comes back (a shareable app link), where the payload lives, how the resulting payment is identifiable later, and a unit pitfall that could otherwise cause a wrong-amount request. 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds genuine value by pre-empting a dangerous unit confusion: it clarifies that amountNim inside the link is Luna-denominated per the app's link format while this tool's output reports NIM and Luna separately. It does not walk through the other params (id, memo, payee, expiry), but the schema already documents those thoroughly.
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?
States a specific verb and resource ('DRAFTS a payment request') plus the immediate result ('returns a shareable link'), and explicitly contrasts with what it does not do (sign, send, mark paid). The follow-up relationship to check_request_paid is named, so an agent can place it in the workflow without opening the schema.
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 makes the use case clear (produce a link that a payer's wallet can act on) and names the downstream consumer check_request_paid, which gives context for sequencing. What's missing is an explicit when-not-to-use or a named alternative sibling (e.g., list_invoices for existing requests), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DRAFTS a stake and returns a link only. This never signs anything and never sends anything: the link opens the NimBooks app with the stake panel pre-filled, and you check the amount and validator there and confirm in your own wallet. No validator is recommended, ranked or chosen for you, and there is no default validator. The link is the deliverable, exactly like create_payment_request: nothing is built, broadcast or queued here, and nothing is marked as staked. Notes explain what the app will do with the values, including a cap to the free balance and the 100 NIM first-stake minimum.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | The staker account, used only to read the current delegation and liquid balance for notes. Optional; defaults to the server’s configured address. | |
| amountNim | No | Amount in NIM, decimal, at most 5 decimals. An omitted or invalid amount is left out of the link with a note. | |
| validator | No | A validator NQ address, or a validator name (exact, or a unique part of the name). There is no default validator. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: nothing is signed, sent, built, broadcast, queued, or marked as staked; no default or ranked validator; and notes disclose the free-balance cap and the 100 NIM first-stake minimum. That is exactly the mutation-adjacent behavior an agent would otherwise misjudge from a 'draft' name.
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 key fact (draft only, link is the deliverable) is front-loaded, and the sentences are purposeful. There is mild redundancy between 'never signs anything and never sends anything' and 'nothing is built, broadcast or queued here', but the emphasis is defensible for a tool whose name could mislead.
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, so the description must state the return value and does: the link, with notes explaining the app's handling of values. All three parameters are covered by the schema, and the critical post-call workflow is described. Nothing an agent needs to call this correctly 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: an omitted or invalid amount is left out of the link with a note, the amount is capped to the free balance, and the 100 NIM minimum applies. It adds constraint-level semantics on top of the field docs rather than restating them.
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 specific verb, resource, and deliverable ('DRAFTS a stake and returns a link only'), which is exactly the distinction an agent needs. It also differentiates itself from the sibling create_payment_request by naming the analogous behavior, and makes clear this is not the staking action itself.
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?
It clearly frames the workflow: the link opens the NimBooks app pre-filled, the user checks amount and validator there and confirms in their own wallet. It states no validator is recommended or defaulted, implying list_validators is the discovery path. It stops short of explicitly naming when to prefer get_staking or list_validators, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Staking rewards for an address over a window: the total (Luna and NIM), the reward days, the first and last reward date, and the breakdown per paying pool, plus an actual yield over the trailing 30 days measured against the current active stake and the current validator's estimate for comparison. Read-only, never signs and never sends. Important: only restaking (compounding) pools show up in this data; a direct-payout pool's rewards arrive as ordinary incoming transactions and are found with list_transactions instead. The public rewards data starts January 2025, so earlier asks come back empty, and it can lag by a day. A year Nimiq Watch did not answer is named in the answer, never silently dropped.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Start of the window, YYYY-MM-DD or ISO 8601 (UTC). Default: the start of the public rewards data. | |
| until | No | End of the window, YYYY-MM-DD or ISO 8601 (UTC). Default: now. | |
| address | No | Nimiq address (NQ form, spaced or flat, or 40 hex characters). Optional; defaults to the server’s configured address. | |
| includeDays | No | Include the per-day reward rows, newest first, at most 400. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations cover safety hints, the description provides deep operational behavior: data limitation ('only restaking pools'), data start date ('January 2025'), potential delays ('can lag by a day'), and data quality ('naming unanswered validators'). This significantly enhances the agent's operational awareness.
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 highly dense and lengthy, prioritizing information over brevity. While every sentence is packed with value, its sheer volume prevents a higher score for structure and conciseness.
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 complex nature of staking data, the description is exhaustively complete. It handles edge cases, data limitations, expected format (total vs. per-day), and naming conventions for missing data, leaving no high-level ambiguity.
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?
The schema coverage is 100%, setting a baseline of 3. The description elevates this by defining the scope of the data retrieved (Luna and NIM, breakdown per pool) and how the time window functions, adding necessary context to the abstract parameters.
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 purpose is extremely clear: calculating staking rewards for an address over a specified time window. It goes beyond just stating the resource by specifying the types of data returned (total, breakdown, yield) and directly addresses the 'why' of the tool.
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?
It provides critical usage instructions regarding alternatives. Specifically, it tells the user that 'direct-payout pool' rewards are *not* found here, but must instead be found using `list_transactions`, offering perfect guidance on when to use this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A Nimiq address's staking position: active staked, inactive (cooling down after an unstake), retired (ready to withdraw) and total, plus the pool it is staked to with its fee, net yield and payout type, an unstake clock (a retire only becomes valid one full epoch after deactivation), and a first-year rewards estimate at the pool's current net yield. Read-only: reads the public chain and the public validators list, never signs and never sends. Never staked reads as staked: false, never as a failed lookup; a failed lookup is an error that says so.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | Nimiq address (NQ form, spaced or flat, or 40 hex characters). Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that it reads the public chain and public validators list, never signs and never sends, and clarifies error semantics for failed lookups. It also explains the unstake clock timing rule, which is meaningful behavioral context not captured by annotations.
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 front-loaded with the core purpose and then layers on return details and edge cases. It is dense but every sentence carries useful information; minor length is justified by the breadth of returned data.
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?
With no output schema, the description adequately explains what is returned, including staking states, pool metadata, unstake timing, and reward estimates. It also covers the optional address default and the never-staked-versus-error distinction, leaving no critical gap for correct invocation.
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 coverage is 100% and the single optional address parameter is fully described in the schema, including accepted formats and the server-configured default. The description adds no further parameter semantics, so the baseline 3 is appropriate.
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: it reads a Nimiq address's staking position and enumerates exactly what is returned (active, inactive, retired, total, pool details, unstake clock, rewards estimate). This is far more specific than the title and lets an agent distinguish it from siblings like get_rewards or project_yield.
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?
It clearly establishes the read-only context and explains the key edge case: never staked returns staked:false rather than a failed lookup. However, it does not explicitly name when to prefer this tool over siblings such as get_rewards, project_yield, or list_validators, leaving some routing inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Day-by-day money in and out for a year (or one month of it), priced at the CoinGecko daily close in USD for each UTC day — the same basis the NimBooks tax statement uses. Read-only: never signs, never sends. Failed transactions are excluded and fees are counted on outgoing transactions only. Staking rewards (restaking payouts) are included as in-day income; moving NIM into or out of the staking contract is not a fiat flow, so it is excluded, exactly like the app’s statement. Nimiq Pay’s round trips through its own contracts go in internalInNim/internalOutNim, not in or out, as in the app. Days with no price available come back with closeUsd: null rather than a guess.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Calendar year, UTC — e.g. 2026. | |
| month | No | Optional month 1–12. Omit for the whole year. | |
| address | No | Nimiq address (NQ form, spaced or flat, or 40 hex characters). Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantive behavior beyond them: failed transactions excluded, fees counted on outgoing only, staking rewards treated as in-day income, staking-contract transfers excluded as non-fiat flow, and Nimiq Pay round trips routed to internalInNim/internalOutNim. It also discloses the null-price fallback ('closeUsd: null rather than a guess'), which is exactly the kind of edge-case behavior an agent needs.
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 definition is front-loaded with purpose before the accounting-detail caveats, and nearly every clause carries information (exclusion rules, pricing basis, null handling). It is dense and slightly long — a few sentences bundle multiple rules — but there is no filler.
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?
With no output schema, the description carries the burden of return-shape disclosure and does so: it names closeUsd, internalInNim/internalOutNim, and the null case for missing prices. Combined with the read-only annotations and fully described params, an agent has everything needed to call it correctly.
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 coverage is 100%, so the schema already documents year, month, and address including the UTC calendar-year meaning and the address default. The description reinforces the month-omission behavior and UTC-day basis but adds little parameter-level syntax beyond what the schema states, so the baseline 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 opening clause names a specific verb and resource — 'day-by-day money in and out for a year (or one month of it)' — and pins the valuation basis to CoinGecko daily close in USD. The daily granularity and fiat pricing distinguish it from an aggregate sibling like get_summary without needing to name it.
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 context is implied through the year/month scoping ('omit for the whole year') and the repeated reference to 'the same basis the NimBooks tax statement uses,' which tells the agent when this tool is the right one for tax/statement work. However, no sibling is named and no explicit when-not-to-use condition or alternative (e.g. get_summary, get_rewards) is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Balance and money in/out for a Nimiq address over a window. Read-only: never signs, never sends. Defaults to the full history the public index returns (up to 1000 transactions, newest first). Balance is the live account balance now, not the balance at the end of the window; any staked NIM is reported separately because it lives in the staking contract. Money out includes transfers into the staking contract and out of it — the same treatment as the app’s statement; validator rewards arrive through a separate channel and are reported as their own line (rewardsReceivedNim). Nimiq Pay’s round trips through its own contracts are the wallet’s own money and are reported as internalIn/internalOut, not as money in or out, the same split the app makes; netNim counts both.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Start of the window, YYYY-MM-DD or ISO 8601 (UTC). Default: no start. | |
| until | No | End of the window, YYYY-MM-DD or ISO 8601 (UTC). Default: now. | |
| address | No | Nimiq address — "NQ82 6GYU …", the flat form, or 40 hex characters. Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real context: the 1000-transaction cap, newest-first ordering, live vs. window-end balance semantics, staked NIM living in a separate contract, and how staking transfers and internal round trips are classified. These are non-obvious behaviors an agent could not infer from the schema or annotations.
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?
Front-loaded with purpose and the read-only guarantee before diving into accounting semantics. The internal-transfer sentence is dense and hard to parse, and repeats 'the same treatment as the app' phrasing twice, but nearly every sentence carries information an agent needs.
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?
With no output schema, the description carries the burden of explaining returns and does so for rewardsReceivedNim, internalIn/internalOut, and netNim, plus the transaction cap. It stops short of enumerating the full response shape or confirming whether a transaction list is included alongside the aggregates.
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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the window constrains money in/out but explicitly does not affect the reported balance, and the default window is full indexed history. Address and date formats are left entirely to the schema.
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?
States a specific verb and resource: balance plus money in/out for a Nimiq address over a window. It is clearly distinguishable from mutation tools like draft_stake or create_payment_request, but it never explicitly names get_statement or list_transactions, which are the closest read-side alternatives.
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 only implied: it explains that the window defaults to full history and that balance is live rather than window-end. There is no explicit statement of when to prefer this over get_statement or list_transactions, and no exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Payment requests stored in a NimBooks backup file (the app keeps them on the device; there is no server holding them). Requires the server to be started with --backup . Read-only: the file is never written to, and the cashlink shelf inside it — which holds link private keys — is never opened.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | The account whose requests to list. Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds real value beyond them: the file is never written to, and the embedded cashlink shelf holding link private keys is never opened. That security/scope disclosure is exactly the kind of context annotations cannot carry. It stops short of describing ordering, filtering, or result shape.
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?
Three compact sentences, each carrying distinct information (storage model, prerequisite, safety guarantees), with no filler. The lead is a bare noun phrase rather than the action, but nothing is redundant.
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?
For a single-optional-parameter read tool with no output schema and read-only annotations, the description covers storage location, activation prerequisite, and mutation/secret exposure boundaries. Only the return shape and any result limits are left unstated, which is a minor gap at this complexity.
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?
With one optional parameter and 100% schema description coverage, the schema already explains that 'address' selects the account and defaults to the server's configured address. The description adds nothing about this parameter, so the baseline 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 makes clear that the resource is payment requests stored in a device-local NimBooks backup file, which is specific enough to distinguish it from siblings like create_payment_request or get_statement. It never states an explicit verb and never resolves the name/title mismatch ('list_invoices' vs 'payment requests'), but the noun phrase plus the file-location detail leaves little ambiguity about what is returned.
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?
It gives a hard precondition — the server must have been started with --backup <path> — which effectively defines when this tool is usable at all. It does not name alternatives or state when not to use it (e.g., for live/server-side requests), so routing to siblings still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Classified transactions for a Nimiq address, newest first. Read-only: never signs, never sends. Each row carries the kind the NimBooks app shows (payment, stake, unstake, reward, swap, vesting), the counterparty, and the memo — a cashlink’s protocol tag reads as "Cashlink" rather than raw bytes, and a nimbooks:invoice:<id> memo is the reference that ties a payment to a request.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return. Default 50. | |
| since | No | Only transactions at or after this date (YYYY-MM-DD or ISO 8601, UTC). | |
| until | No | Only transactions at or before this date (YYYY-MM-DD or ISO 8601, UTC). | |
| address | No | Nimiq address (NQ form, spaced or flat, or 40 hex characters). Optional; defaults to the server’s configured address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring read-only/idempotent/non-destructive behavior, the description adds useful context about returned rows: transaction kinds, counterparty, memo handling, cashlink tag normalization, and invoice references. It reinforces safety ("never signs, never sends") but does not cover pagination behavior or the full row shape.
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?
Two sentences, front-loaded with the tool's purpose, followed by efficient detail about read-only behavior and return-row semantics. The memo and cashlink details earn their place because they clarify non-obvious return content.
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?
No output schema exists, so the description must explain return values; it does so for kind, counterparty, and memo, but omits amount, timestamp, status, and pagination details. Given fully documented parameters and safety annotations, it is mostly complete but leaves some return-shape gaps.
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 coverage is 100%, so limit, since, until, and address are already documented. The description only reinforces that address is a Nimiq address and that results are newest first; it adds no parameter syntax or filtering details beyond the schema, so the baseline 3 is appropriate.
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?
States a specific verb and resource: "List transactions for a Nimiq address," plus ordering ("newest first") and the classified nature of the rows. It does not explicitly contrast itself with siblings like get_statement or list_invoices, but the resource is unambiguous.
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 no explicit when-to-use, when-not-to-use, or sibling alternative guidance. It only notes read-only behavior and ordering, leaving the agent to infer that this is for transaction history rather than statements, invoices, or staking summaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Nimiq validator pools of the current epoch, ranked neutrally, exactly as the NimBooks app ranks them: producing pools first (those with a reliability score this epoch), best net annual yield first within them, pools that publish no yield last, then the non-producing pools, and the name as the final stable tiebreak. Nothing is pinned first. Read-only: one call to the public validators list, never signs and never sends. netYieldPercent is the net annual yield on the network's total stake after the pool's fee, the Nimiq wallet's convention; it moves as emission falls and as stake moves.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Pools to return, 1 to 50. Default 50. | |
| includeNonProducing | No | Include pools with no reliability score this epoch (they earn nothing right now). Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: it quantifies the cost ("one call to the public validators list"), states it never signs or sends, and explains that netYieldPercent is a fee-adjusted yield on total network stake that drifts with emission and stake, which is non-obvious. It does not describe pagination or the full pool record, so it is not exhaustive.
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 resource and ranking rule are front-loaded in the first sentence, and the read-only and netYieldPercent notes follow logically. The tiebreak enumeration and the yield explanation are dense but each carries information an agent cannot get from the schema; only the "Nothing is pinned first" clause feels slightly redundant with the ranking sentence.
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?
With no output schema, the description does the work of explaining return ordering and the meaning of the key yielded field (netYieldPercent), which is what an agent needs to interpret results. It stops short of enumerating the other pool fields or pagination behavior, which is a modest gap for a two-parameter list tool.
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% with only two simple parameters, so the baseline is 3. The description adds a little meaning to includeNonProducing by explaining where non-producing pools sit in the ranking, but it says nothing about limit or default truncation behavior beyond what the schema already states.
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 definition names a precise resource and scope — the Nimiq validator pools of the current epoch — and spells out the ordering so it is clearly the neutral listing rather than a stake/yield projection tool. It is a nominal phrase rather than an explicit verb, and it never names a sibling such as get_staking or project_yield to contrast against, so it stops just short of full differentiation.
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?
"Ranked neutrally, exactly as the NimBooks app ranks them" and "Nothing is pinned first" imply the use case (mirroring the app's display order), and the note that non-producing pools are listed last implies when includeNonProducing matters. There is no explicit statement of when to prefer this over get_staking or project_yield, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Projects what staking an amount of NIM might earn, year by year. With an explicit rate it is a pure offline calculation. Read-only, never signs and never sends. Rate resolution, in order: an explicit annualRatePercent, then the named pool's current net yield, then the median of the producing pools. Compounding follows the pool's payout type (direct pools pay out, the rest restake) unless an explicit compound choice is given. Returns per-year rewards, cumulative rewards and balance, plus its assumptions: emission falls along the protocol supply curve, the network's total stake is held at today's level, and it is a projection, not a promise.
| Name | Required | Description | Default |
|---|---|---|---|
| years | No | Horizon in years, 1 to 10. Default 1. | |
| compound | No | Restake rewards as they arrive (true) or pay them out (false). Default: the pool's payout type, else true. | |
| amountNim | Yes | Amount to stake, in NIM, as a decimal string, e.g. "1000". At most 5 decimals. | |
| validator | No | A pool: its NQ address, exact name, or a unique part of the name (list_validators has them). | |
| annualRatePercent | No | Explicit annual rate in percent, more than 0 and at most 100. Wins over any pool's or the typical rate, and makes the call work offline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint=false, yet the description still adds real value: it states the call never signs or sends, discloses compounding behavior driven by pool payout type, and lists the projection assumptions (emission decay, static total stake, projection-not-promise). It does not cover failure modes like an ambiguous or unmatched pool name, which keeps it below a 5.
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?
Front-loaded with the core purpose, then resolution order, compounding, and returns in a logical sequence. Dense but every sentence carries information; only the 'never signs and never sends' clause mildly overlaps the annotations.
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?
No output schema exists, and the description compensates by naming the return contents (per-year rewards, cumulative rewards and balance, plus assumptions). Combined with the disclosed rate/compounding rules, an agent has everything needed to call it correctly.
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 coverage is 100% so the baseline is 3, but the description adds semantics the schema cannot: the precedence ordering governing annualRatePercent vs validator, and how compound defaults derive from the pool's payout type. That goes meaningfully beyond the per-field descriptions.
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?
States a specific verb and resource ('Projects what staking an amount of NIM might earn, year by year') and is clearly distinguishable from siblings like get_staking (current state) and draft_stake (creates a transaction). An agent can tell this is a forward-looking simulation tool without opening the schema.
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?
Explains the rate-resolution order (explicit annualRatePercent > named pool's net yield > median of producing pools) and that the explicit rate makes the call offline, which effectively tells the agent when to supply which parameter. It stops short of explicitly naming alternatives such as get_staking for a live rate lookup, so it is clear but not exhaustively routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0get_summary1 field changedInput schema / properties / address / descriptionPrevious value: -"Nimiq address — \"NQ43 Y1RH …\", the flat form, or 40 hex characters. Optional; defaults to the server’s configured address."New value: +"Nimiq address — \"NQ82 6GYU …\", the flat form, or 40 hex characters. Optional; defaults to the server’s configured address."v0.1.0check_request_paidcreate_payment_requestdraft_stakeget_rewardsget_stakingget_statementget_summarylist_invoiceslist_transactionslist_validatorsproject_yieldScored across 11 tools
Most tools have clearly distinct purposes: payment requests, transaction listing, summaries, statements, staking position/rewards, validators, and yield projection are separate. The main overlap is between get_summary and get_statement, and somewhat between get_rewards and the reward entries in list_transactions, but the descriptions draw explicit boundaries.
All tools use snake_case with a predictable action_resource pattern: create_payment_request, list_transactions, get_summary, draft_stake, check_request_paid, etc. The verb choices vary appropriately by operation but remain consistent and readable throughout.
Eleven tools is well-scoped for a Nimiq accounting and staking assistant. Each tool earns its place by covering a distinct analytical, listing, or draft-link workflow without excessive breadth.
Core read-only accounting, payment-request, staking-position, rewards, validator, and yield-projection workflows are covered. There are minor lifecycle gaps for staking actions such as drafting an unstake or withdrawal, and payment requests lack cancellation/update operations, but the main read and draft-link surface is strong.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only MCP server: verify credentials and browse escrows on the Stellar testnet contract.
Personal, family and business books over fiat and crypto. Reads and records; it cannot pay.
