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),
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", "NQ43 Y1RH P1K7 JH78 LRTS 95RY GAUU UBDK FFGX"
]
}
}
}Restart Claude Desktop. The eleven tools appear under the tools icon.
claude mcp add nimbooks -- npx -y nimbooks-mcp \
--address "NQ43 Y1RH P1K7 JH78 LRTS 95RY GAUU UBDK FFGX"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. |
| 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. |
| 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.
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 NQ43 Y1RH …, 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.
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, 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. 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?
Beyond the annotations, the description discloses important behavior: failed transactions are excluded, fees are counted only on outgoing transactions, staking rewards are included as income, staking contract movements are excluded, and missing prices return closeUsd: null instead of a guess. These details materially affect interpretation of the results.
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 in behavioral details in a logical order. It is somewhat dense but every sentence contributes to understanding the statement output.
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 read-only reporting tool with no output schema, the description covers pricing basis, inclusion/exclusion rules, and null handling well. It stops short of detailing the returned fields beyond closeUsd, but the behavioral picture is largely complete.
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. The description adds useful context about UTC days and monthly granularity, but does not add parameter-specific meaning beyond the schema 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?
The description states a specific verb and resource: day-by-day money in/out for a year or month, priced at the CoinGecko daily close in USD. It also differentiates itself from general transaction listing by tying the output to the NimBooks tax statement basis.
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 implies the tool is for annual or monthly statement-style reporting (e.g. tax statement basis), but it does not explicitly name alternatives such as list_transactions or get_summary or state when not to use it. The usage context is clear but left implicit.
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).
| 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 — "NQ43 Y1RH …", 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, yet the description still adds substantial context: it explains the 1000-transaction cap and newest-first ordering, that the reported balance is live rather than window-end, that staked NIM is reported separately because it sits in the staking contract, and that validator rewards arrive as their own rewardsReceivedNim line. These are exactly the semantics an agent cannot infer from annotations or 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?
Purpose is front-loaded in the first clause and no sentence is filler, but the single dense paragraph packs several distinct facts (ordering, live balance, staking treatment, reward channel) into one block that would read better split. Slightly long for a three-optional-parameter read tool.
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 carry return semantics — and it does, naming the balance, money-in/out, separate staked NIM, and the rewardsReceivedNim line, plus the transaction cap. An agent knows what it will get back and how the numbers are defined.
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%, so since/until/address are already fully documented and the baseline is 3. The description adds only that the default window is the full history the index returns (capped at 1000, newest first), which clarifies defaults rather than parameter syntax or address-format edge cases beyond 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?
Opens with a specific noun-and-resource statement ("Balance and money in/out for a Nimiq address over a window"), which immediately separates it from payment-request, invoice and transaction-list siblings. It gestures at get_statement ("the same treatment as the app's statement") but never states when to call this instead of that sibling, so the differentiation is implied rather than stated.
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 implied by the description of what the tool returns and its default full-history behaviour, but there is no explicit "use this when… / use get_statement or get_staking when…" routing. Given the sibling set contains get_statement and get_staking, which clearly overlap, an explicit boundary would have real value.
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.
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, and the descriptions draw sharp lines between statements, summaries, transactions, rewards, and staking views. There is still some potential confusion among the financial-history tools (get_statement, get_summary, list_transactions, get_rewards), though their scopes are differentiated once read.
All tool names follow a consistent snake_case verb_noun pattern: get_statement, create_payment_request, check_request_paid, list_invoices, get_staking, list_validators, get_summary, list_transactions, project_yield, get_rewards, draft_stake. The verb choices are predictable and the noun forms are readable despite some singular/plural variation.
Eleven tools is well within the ideal range and each tool appears to earn its place by covering a distinct read-only query or draft-link action. The surface is neither bloated nor thin for a Nimiq wallet/books companion server.
The read-only reporting surface is broad, covering statements, summaries, transactions, staking positions, validators, rewards, yield projection, and payment-request checking. However, the staking lifecycle is notably incomplete: draft_stake exists, but there is no draft_unstake or withdraw action even though get_staking exposes cooling-down and retired states, and payment requests have no cancel/update path.
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.
