Nevermined Catalog

Top up credits

top_up_credits

Destructive

Buy one credit pack on the card your human enrolled, within the monthly top-up limit they set — no new human approval. This CHARGES the human’s card. Pass forCallCredits: the credits the call you are about to make will spend. A pack is charged only when your spendable credits are below that — the recorded consent charges a pack “each time your credits are not enough for a call you make”, so state what that call needs (from a quote or your plan’s per-call cost); when your credits already cover it, nothing is charged (not_needed). Pass a requestId you choose as an idempotency handle: a NEW value for each top-up you intend, the SAME value only to re-send a call that may not have completed (a retry returns the pack already charged, never a second one). Read status: bought added credits (creditsAdded) — unless replayed is true, which means this requestId had already bought one and nothing new was charged (use a new id next time); pending means YOUR pack was charged and is awaiting confirmation (read the balance shortly); busy means another top-up is already being charged — nothing was charged for THIS request, so check your balance shortly and re-send the SAME requestId only if you still need one; limit_reached means this UTC month’s top-up limit is used up (no charge — do not retry until next month); not_needed means your credits already cover the call (no charge); needs_attention means the card was declined or needs 3-D Secure, a card payment to Nevermined is disputed, a human must finish setting top-ups up, a prior top-up is stuck, or a prior top-up’s outcome is unconfirmed (it may have been charged) — hand the human operatorUrl, never try to confirm it yourself, and do not start a new top-up until they act; disabled means a human must turn top-ups on first (give them operatorUrl); unavailable means nothing was charged — retry with a NEW requestId (reusing this one keeps returning the same settled result). monthlyLimitUsd/boughtThisMonthUsd/packPriceUsd are the human-set limit and this month’s spend. Requires your Nevermined API key on the Authorization header; a commerce OAuth grant must have enabled credit top-ups at consent.

Input Schema

Name	Required	Description	Default
`requestId`	Yes	An idempotency handle you choose (8–200 chars, letters/digits/._:-). Use a NEW value for each top-up you intend; reuse the SAME value only to re-send a call that may not have completed.
`forCallCredits`	Yes	The credits the call you are about to make will spend. A pack is charged only when your spendable credits are below this; when they already cover it, nothing is charged (`not_needed`).

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The description is consistent with `destructiveHint: true` and `readOnlyHint: false`, explicitly warning that it charges the human's card. It adds substantial context beyond annotations: monthly limit consent, idempotency/retry semantics, per-status outcomes, auth requirements (Nevermined API key, OAuth grant enabling top-ups), and when a human must intervene.

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

Conciseness4/5

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

It is long, but the length is largely justified by the number of payment statuses and retry rules. The critical warning ('This CHARGES the human's card') is front-loaded; however, the dense single-paragraph enumeration of statuses reduces scanability.

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

Completeness5/5

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

With no output schema, the description fully carries the burden of explaining return statuses and fields (`bought`, `creditsAdded`, `replayed`, `pending`, `busy`, `limit_reached`, `not_needed`, `needs_attention`, `disabled`, `unavailable`). It also covers auth prerequisites and the human-set limit context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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

Schema coverage is 100%, so both parameters are already documented. The description still adds meaning about where `forCallCredits` should come from (a quote or the plan's per-call cost) and reinforces requestId reuse rules beyond the schema, though much of the idempotency explanation mirrors the schema.

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

Purpose5/5

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

The opening sentence states a specific verb and resource: 'Buy one credit pack on the card your human enrolled,' and immediately flags that it 'CHARGES the human's card.' This is unmistakable and distinct from read-only siblings like wallet_balance or get_budget.

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

Usage Guidelines5/5

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

It explicitly says when to pass forCallCredits, when no charge occurs (`not_needed`), when to retry with the same requestId (`busy`), when not to retry (`limit_reached`), and when to escalate to a human with `operatorUrl` (`needs_attention`, `disabled`). Alternatives and exclusions are spelled out rather than inferred.

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

All Nevermined Catalog tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?