Discover and pay for services from the Nevermined Catalog using a spend-capped budget.
Scored across 14 tools
Most tools target a distinct resource+action (pay, quote, discover, read result, set up delegation). The ambiguity clusters are the three 'read my money' tools (get_budget vs wallet_balance vs get_subscription_checkout) and the three discovery tools (search_services vs list_categories vs route_by_intent), but the descriptions deliberately cross-reference and contrast each other, so an agent can resolve them with careful reading.
The set is overwhelmingly snake_case verb_noun (get_budget, list_payments, pay_service, quote_service, search_services, setup_delegation, top_up_credits, route_by_intent). Two names break the pattern into noun_noun with no verb: payment_summary and wallet_balance, which are minor deviations but noticeable in an otherwise predictable scheme.
14 tools is well within a healthy range and each maps to a real step in the pay-per-call lifecycle: discovery, pricing, payment, budget, results, reconciliation, subscription/credits. Nothing looks padded; even the aggregation tool (payment_summary) covers a need list_payments explicitly does not (uncapped counts).
The surface covers discovery → quote → pay → result → reconcile → budget/delegation/credits end to end, with no obvious dead ends. Minor gaps: no way to close a payment channel or withdraw locked deposits, no tool to inspect or revoke an existing delegation, and search_services cannot paginate (pageToken is not re-passable), all of which agents must work around.
Read the spending budget pay_service spends from: its cap, what has been spent, what remains, how many payments were made (and the limit, if any), and when it expires. Reading costs nothing and charges nothing. Use it whenever the human asks how much is left, or before a run of paid calls. Money is in CENTS: capCents is whole cents; spentCents and remainingCents can carry up to four decimals because the budget is charged per call at 1/10,000 of a cent (e.g. "1.632" = 1.632¢), and spentCents + remainingCents = capCents while the budget is within its cap. Tell the human message as it stands and never substitute a figure of your own: the budget includes routing fees and rounding, so adding up your calls will not match it. With no delegationId it reads the budget pay_service would use; that only includes budgets that can still pay, so {"status":"no_active_delegation"} also covers a budget that ran out or expired — pass the delegationId from an earlier pay_service result to read that one anyway. On a deployment that reports it, spentByDeliveryStatusCents splits the spend by what each payment delivered (delivered, charged_not_delivered, charged_unconfirmed, not_charged, not_delivered, pending, the deliveryStatus values list_payments uses), and unattributedSpentCents is spend no payment record itemizes; a non-zero charged_not_delivered is what was spent on calls that delivered nothing although the merchant charged (the merchant charge plus any routing fee not given back), so tell the human. not_delivered is held for calls the merchant answered with an error: not a confirmed charge; the reserve stays held until reconciliation decides whether the merchant charged after confirmed cancellation or authorization expiry (an older deployment reports it inside pending). lockedInChannels, when present, is money the wallet this budget pays from has deposited into payment channels with merchants that charge per call (per token, as in wallet_balance). It is that WALLET's total, shared by every budget paying from it, not a figure of this budget's own: it is NOT spent and NOT charged to this budget, it can pay further calls only to the merchant holding each channel, and what is unused comes back to that wallet when the channel closes, after 15 minutes without use; message then says so. An empty list means nothing is locked; null means it could not be read, and message then says that too. sessionChannels, when present, is the history behind that: each payment channel this budget used, newest first, with the merchant, its status, what was deposited (deposit, or depositAtomic in raw units when symbol is null), what came back (refund, null until the channel has closed and the refund is confirmed) and openedAt/closedAt. It is what explains money leaving the wallet and coming back when no payment shows it: a payment record carries one call's price, never the deposit. sharedWithOtherBudgets means the wallet's channel also served another budget, so its figures are not this budget's alone, and depositConfirmed: false means the open is not confirmed, so the deposit may not have landed. sessionChannelsTruncated: true means the list holds only the newest channels and older ones exist; message then says so. An empty list means none was used; null means it could not be read, and message then says so. Absent means this reader cannot see them: a budget owned by someone else, or an older deployment. Inventory fields creditsCoverage and creditsCoverageMessage describe public catalog eligibility, even when this caller has no subscription access or credit consent. Relay the message when present; absent means unavailable, never zero. A get_service endpoint carries subscription when credits can pay it. When you have a Nevermined Subscription the result also carries subscription (creditsLeft, a digit string of every unexpired credit; resetsAt, when the allowance expires and, unless cancelAtPeriodEnd, the next period's is granted; status, suspended and plan) and subscriptionMessage to relay as it stands; subscription.subscribed: false means none. Whether or not you subscribe, it also carries credits (null: could not be read, which is not the same as none): total, spendable (what can pay a call now), parts (kind allowance | welcome | topup | sla, credits, expiresAt — null never expires — and frozen: null, renewal_overdue for allowance credits frozen until a renewal payment goes through, dispute for every credit while a card dispute holds them) and nextExpiry, with creditsMessage to relay as it stands. Every amount is a digit string. Never count credits yourself. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| delegationId | No | A specific delegation to read (every paid pay_service result carries one). Omit it to read the budget pay_service spends by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past readOnlyHint=true: it states that reading is free and charges nothing, that an API key is required on the Authorization header, that figures include routing fees and must not be recomputed, and how to interpret no_active_delegation, null vs absent vs empty lists. It also pre-empts a likely agent error ("never substitute a figure of your own") and explains which output fields demand relaying message verbatim.
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?
A single undifferentiated block of roughly 500 words with no bullets or headings, mixing cost, units, error semantics, delivery-status breakdowns, channel accounting, credit inventory and subscription rules. The purpose is front-loaded in sentence one, but the remaining content is dense enough that an agent must parse a paragraph to find any one rule, and much of it is output documentation for a tool with no output schema.
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 a single optional parameter, no output schema and a very rich return payload, the description carries the entire burden of documenting what comes back, and it does so exhaustively — units and decimal precision, status values, absent vs null vs empty, and relaying message. Nothing needed to call it correctly or to interpret the result 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 does not: omission reads the default budget and silently excludes budgets that can no longer pay, so no_active_delegation conflates exhausted, expired and never-delegated. That nuance is genuinely useful for interpreting results, though it does not add syntax or format detail.
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 sentence names a specific verb and resource plus the exact fields returned (cap, spent, remaining, payment count/limit, expiry), which is far beyond a restatement of the name. It implicitly separates itself from wallet_balance (channel money is "that WALLET's total... NOT this budget's own") and from payment_summary, but never explicitly names a sibling to prefer for the closest overlapping question.
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?
Gives a concrete trigger in "Use it whenever the human asks how much is left, or before a run of paid calls", and adds a second decision rule for the delegationId case (pass the id to read a budget that can no longer pay). It stops short of naming alternatives or exclusions, e.g. when to prefer payment_summary or get_payment_result instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the result of a paid call, by its paymentId. Use it when pay_service answered {"status":"pending"} (the service was still working when the Router stopped waiting — a payment was attempted, the call keeps running and its outcome is not known yet), or to recover a result whose response you lost. Reading costs nothing and charges nothing. Every answer with a state carries payment.status. state: "Pending" — still running, call again in a few seconds. state: "Ready" — status is the service's HTTP status and body its response (bodyEncoding says whether it is parsed JSON, text, or base64). state: "Failed" — the call ended without a response; failureReason says why. That does not prove nothing was charged, so check deliveryStatus in list_payments before paying again. {"status":"not_available"} — nothing to return: results are kept for 24 hours for the account that paid, and only then. Do NOT call pay_service again to get a pending result: that does not return a new one. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| paymentId | Yes | The `paymentId` a pay_service result returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, and the description goes well beyond that: it says reading costs nothing, that results are retained 24 hours for the paying account only, that a Failed state does not prove nothing was charged, and that a Nevermined API key is required on the Authorization header. It also fully explains the state machine of return values and what to do on Pending.
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 verb and resource, and the per-state explanation is organized rather than rambling. It is dense and long for a single-parameter read tool, though nearly every clause carries operational value.
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 describe return values — and it does: state values Pending/Ready/Failed, payment.status, body, bodyEncoding, failureReason, and the not_available case. Nothing an agent needs to call it and interpret the response 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% and the single paymentId parameter is already documented with format and pattern, so the schema does the heavy lifting. The description restates that the ID comes from a pay_service result but adds no new syntax or retrieval semantics for the parameter itself.
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 ('Read the result of a paid call, by its paymentId') and implicitly separates itself from pay_service and list_payments. An agent can tell immediately this is a result-retrieval tool, not a payment-initiation one.
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?
Gives explicit triggers: use it when pay_service answered {"status":"pending"} or to recover a lost response. It also states a clear prohibition ('Do NOT call pay_service again to get a pending result') and routes to list_payments for deliveryStatus checks before re-paying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one catalog service by slug with metadata and a requestShape block. Read the endpoint's payServiceArgs before pay_service, replacing every pathParams placeholder. A checked invoke contract may include invokePath, requestExample, merchant-authored responseSchema/responseExample, and exampleEvidence: paid-run records a paid response, challenge proves only the request shape, and docs is unverified provider documentation. Only paid-run and challenge examples are pre-filled into payServiceArgs; adopt a docs example deliberately. Each endpoint also carries requestExampleQuality, grading how well it publishes the way to call it (not a callability verdict) — proven (a usable example earned against the real endpoint, including a concrete invokePath that fills a templated path), docs (a usable example from documentation, unverified), no-input (takes no request input, callable as-is), or none (no stored example — form the request from requestSchema if one is published). Merchant response shapes are sanitised, and harvested examples are published only when they validate against their schema. An endpointCheck records a dated unpaid failure. An endpoint with auth: "siwx" is not paid: it is a follow-up (a job or result poll) that only the wallet which paid an earlier call to the same service can read, so call it with pay_service after that call, filling its pathParams with the id the paid response returned; the Router signs the wallet challenge and charges nothing. A requestSchema is the merchant-declared JSON Schema of its request and is sanitised, not verified. A quote excludes the Router fee, which the budget must also cover. An unknown slug returns an error. Discovery only; no payment. Call quote_service for the live fee-inclusive total before paying.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The service slug (from search_services). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond `readOnlyHint`, the description discloses substantial behavior: what blocks may appear in the response, how example evidence is classified, that merchant schemas and responses are sanitised, that harvested examples are validated, that unknown slugs return an error, and that no payment occurs. This gives an agent unusually rich context for interpreting the result.
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 core purpose is front-loaded in the first sentence, but the rest is a dense, single-paragraph block covering many nested concepts such as `exampleEvidence`, `requestExampleQuality`, sanitisation, `auth: "siwx"`, and Router fees. Much of that context is useful, but the volume and packing make it harder to scan than necessary for a one-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 explain the response structure, and it does so thoroughly: `requestShape`, invoke contract fields, example evidence, quality grades, `endpointCheck`, and sanitisation. It also covers the key failure mode (unknown slug) and payment boundaries, leaving little an agent needs to infer.
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 already documents the single `slug` parameter at 100% coverage, including that it comes from `search_services`. The description adds the behavioral note that an unknown slug returns an error, but does not add further meaning about the slug format or sourcing beyond what the schema provides.
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 sentence names a specific verb and resource: fetching one catalog service by slug, including the returned metadata and `requestShape` block. It is clearly distinguishable from siblings like `search_services` and `pay_service`, so an agent can identify the tool without opening its 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 explicitly routes the agent: read `payServiceArgs` before calling `pay_service`, use `quote_service` for the fee-inclusive total before paying, and it states that this tool is discovery-only with no payment. It also explains the special `auth: "siwx"` follow-up case and when to call it with `pay_service`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read your personal subscription balance and get the link the human opens to subscribe or manage their allowance when credits are short. Charges nothing and never starts a paid checkout. topUpAvailable says whether the human can buy a pack of never-expiring credits from the dashboard (dashboardUrl) now, which also switches on automatic top-ups or resumes paused ones; the message mentions top-ups only when it is true. An existing subscriber gets the dashboard and reset date. After the human finishes checkout, use get_budget to verify the credits, then retry pay_service. OAuth commerce connections must explicitly grant Nevermined credits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond readOnlyHint=true by asserting 'charges nothing and never starts a paid checkout' and by disclosing an OAuth scope requirement ('commerce connections must explicitly grant Nevermined credits') — both are non-obvious behavioral facts. Minor deduction because part of the no-side-effect claim restates the annotation, and the clause about switching on/resuming automatic top-ups is ambiguous about whether the tool or the human's dashboard action causes it.
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 and the no-charge guarantee are front-loaded, but the sentence about topUpAvailable is a run-on with a tangled relative clause ('which also switches on automatic top-ups or resumes paused ones') whose referent is unclear. Information density is high but readability suffers.
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 (topUpAvailable, dashboardUrl, reset date for existing subscribers), plus the follow-up workflow and auth requirement. It stops short of describing the full payload or what is returned when no subscription exists.
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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate; it instead spends its words on return fields (topUpAvailable, dashboardUrl, reset date). Correctly silent on parameter syntax because none exists.
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 — read the personal subscription balance and return the human's subscribe/manage link — and separates itself from sibling tools by name (get_budget, pay_service). An agent can tell this is a read of subscription state, not a purchase, without opening any 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?
Gives a clear trigger ('when credits are short'), a post-checkout workflow ('use get_budget to verify the credits, then retry pay_service'), and an auth prerequisite. It does not explicitly exclude or contrast the sibling top_up_credits tool, so the agent must infer that distinction from the dashboard-based wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the categories of paid services in the Nevermined Agent Services Catalog, with a count per category. Discovery only; no payment.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered; the description reinforces this with 'Discovery only; no payment' and usefully discloses the return shape (a count per category) despite there being no output 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?
Two short, front-loaded sentences with no filler: the action and scope come first, the read-only constraint second.
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 zero-parameter, read-only discovery tool with no output schema, the description covers purpose, safety, and the shape of the result. Minor gaps remain (e.g., ordering of categories), but nothing essential for correct invocation 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?
The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond the absence of filtering inputs.
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 (List) and resource (categories of paid services), names the catalog, and adds scope detail (count per category). 'Discovery only; no payment' implicitly separates it from transactional siblings like pay_service and quote_service.
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 phrase 'Discovery only; no payment' gives implied usage context and a soft exclusion against payment tools, but it never states when to pick this over siblings such as search_services or route_by_intent, nor any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your Router payments: the unified ledger across every service and delegation, newest first, at most 1000 records. Each record carries its id (the paymentId get_payment_result takes), createdAt, status, protocol, network, requestId, delegationId and amount in the asset's smallest unit (see assetDecimals), not in cents. Each row also carries deliveryStatus: delivered (request settled), charged_not_delivered (request failed and the merchant charge was observed), charged_unconfirmed (charge observed; delivery unconfirmed), not_charged (reconciliation recorded no merchant charge, including unreadable write-offs; not conclusive proof that no money moved), not_delivered (the merchant answered with an error, so nothing was delivered, and no charge has been seen: the amount stays reserved until reconciliation decides, after confirmed cancellation or payment authorization expiry, whether the merchant charged; it is not a confirmed charge), or pending (charge outcome unknown). Issued + pending means the charge outcome is unknown: neither payment nor no charge is established. On SPT and card rails, pending is not proof of no charge; those rows are never decided on chain. merchantSettlementObservedAt records an observed merchant charge; null is not, on its own, proof of no charge. Flag both charged states to the user. Each record also carries fundingSource, the funding it used: delegation, or subscription for your Nevermined credits, with or without a subscription. On a subscription row, deliveryStatus and merchantSettlementObservedAt describe what Nevermined paid the merchant, not a charge to you: what the call cost you is creditsCharged, and creditsStatus says whether that stands (Committed spent, Reserved held or marked for refund, Refunded returned). Do not report a charged state on such a row as a charge to the user. Pass requestId to look up the one payment with that id: the answer is then {"presence":…,"payments":[…]}, it ignores the other filters and the 1000-record limit, and presence: "absent" means no payment carries that id. Use this tool to reconcile an uncertain payment or find a paymentId; it does not return service responses (use get_payment_result) or the remaining budget (use get_budget, whose figures include fees and rounding). Reading costs nothing. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO-8601 upper bound on `createdAt`, inclusive. An unparseable value is an error. | |
| from | No | ISO-8601 lower bound on `createdAt`, inclusive. An unparseable value is an error. | |
| requestId | No | The `requestId` a pay_service or route_by_intent result gave you, matched exactly. Finds that one payment wherever it sits in the ledger; the other filters are ignored. | |
| delegationId | No | Only payments charged to this delegation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=true it adds cost ('Reading costs nothing'), the auth requirement ('Nevermined API key on the Authorization header'), the 1000-record cap, and how requestId bypasses filters and the limit. It also warns about interpretation pitfalls, e.g. that 'not_charged' is not conclusive proof no money moved and that subscription rows are not charges to the user — context annotations cannot express.
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 first sentence is well front-loaded, but the description then runs into a long, dense enumeration of deliveryStatus and creditsStatus values, plus nested caveats, that is hard to scan and partly duplicates schema-documented field names. It is justified by the absence of an output schema, yet the presentation is not tight.
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 record fields, status enums, and the requestId response shape must be documented here, and they are. Authorization, limits, cost, and response-shape changes are all covered, leaving nothing an agent needs in order 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 meaning the schema lacks: requestId yields a different response envelope with a 'presence' field and 'absent' semantics, and it overrides the other filters and limit. The from/to and delegationId semantics are left to the schema, which is adequate.
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 verb and resource plus scope: 'List your Router payments: the unified ledger across every service and delegation, newest first, at most 1000 records.' It also explicitly separates itself from get_payment_result and get_budget in the closing sentences.
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?
States when to use it ('reconcile an uncertain payment or find a paymentId') and when not to, naming the alternatives for service responses (get_payment_result) and budget (get_budget). The requestId single-lookup mode is called out as a distinct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count your Router payment requests: total is how many there were in the period (uncapped, unlike list_payments) and series is that count per day (date, value), oldest first. chargedNotDelivered is the count of failed payments in the period whose merchant charge reconciliation observed on-chain (a failed payment not yet reconciled is not counted); this is the confirmed failed-and-charged count only. countsByDeliveryStatus exposes all six ledger delivery states, including charged_unconfirmed, not_delivered and pending, with zero counts included. The latter two have unknown charge outcomes: do not count them as confirmed charges. Flag both charged buckets and explain unresolved outcomes to the user. These buckets include calls paid with your Nevermined credits, so check fundingSource and creditsStatus in list_payments before telling the user they were charged. This reports numbers of payments, not money: for what has been spent or what is left, and how much of it was charged without delivery, use get_budget, and for amounts per payment use list_payments. Reading costs nothing. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO-8601 upper bound on `createdAt`, inclusive. An unparseable value is an error. | |
| from | No | ISO-8601 lower bound on `createdAt`, inclusive. An unparseable value is an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare `readOnlyHint`; the description adds that reads are free, a Nevermined API key on the Authorization header is required, `series` is oldest-first, zero counts are included, and `charged_unconfirmed`/`not_delivered`/`pending` are unresolved charge outcomes not to be counted as confirmed. It also discloses credit-funded calls and directs verification in `list_payments`.
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 purpose and key caveats are front-loaded, and nearly every sentence carries operational meaning. The dense prose block contains several nuanced warnings that could be more scannable, but there is little outright waste.
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, but the description explains every reported field, what is included/excluded in counts, and the required auth/cost context. It also covers ambiguous delivery-status buckets and sibling alternatives, so an agent has enough to call and interpret the tool 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%, and the schema already documents `to`/`from` as inclusive ISO-8601 bounds with parse errors. The description only refers to 'the period' and adds no further constraint or format meaning for these parameters, 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?
States a specific verb ('Count') and resource ('Router payment requests') and enumerates the returned fields (`total`, `series`, `chargedNotDelivered`, `countsByDeliveryStatus`). It explicitly distinguishes itself from `list_payments` (uncapped vs capped) and `get_budget` (numbers vs money), so an agent can select it 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?
Explicitly routes money questions to `get_budget` and per-payment amounts to `list_payments`, and warns to check `fundingSource`/`creditsStatus` in `list_payments` before telling the user they were charged. This supplies clear when-to-use and when-not-to-use conditions tied to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pay for a catalog service from your spend-capped delegation and return the vendor response. This charges real funds. Paid calls can take several seconds, including payment verification, service work and settlement; longer tasks can take more. Call get_service FIRST: its requestShape.endpoints[] lists the callable paths with their HTTP method and price, and each payServiceArgs is the slug/path/method to pass here, after replacing any pathParams placeholder in path with a real value. A bare slug reaches the service base URL, which for a multi-endpoint API answers 404 instead of a payment challenge; only a single-endpoint service is called by slug alone. Send the endpoint's payServiceArgs: they carry an example only when it is paid-run or challenge. A docs example (and its invokePath) is unverified — use it only deliberately, filling any path parameter with the entity you want; otherwise build body from the endpoint description or the provider's docs. method may be omitted: it is taken from the catalog endpoint matching path (POST when the catalog names none) and echoed back under request. To accept a live quote, pass its quoteId before expiresAt with the exact same call arguments; the Router uses that cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling. Repeating an identical call (same arguments, no fresh) charges nothing new: on a deployment running API 1.48 or later it is answered within 24 hours from the first call's stored result, or its pending answer; on an older deployment it comes back as already_paid. For an ASYNC service, where you submit once and then poll a status endpoint with the same id, set fresh: true on every poll INCLUDING THE FIRST: otherwise each later poll reuses the first poll's idempotency key and gets the first poll's stored answer (or already_paid) back, so the status never advances. fresh makes each poll a distinct, separately billed call (the merchant charges per status call). Leave fresh off the submit and off any retry of a call whose outcome is unsure, because with fresh a retry is not de-duplicated and is charged again. A completed call returns paid, upstreamStatus (the vendor's HTTP status) and response (its body). paid: true means a payment was attempted, not that it settled, so read payment.status (Settled, Issued or Failed): Issued is not confirmed yet, which is neither a failure nor a reason to retry, and Failed does not prove nothing was charged, so check deliveryStatus in list_payments before paying again. With a non-2xx upstreamStatus it may still have cost the merchant price. Outcomes to act on: {"status":"pending"} means a payment was attempted and the service is still working, so whether it went through is not known yet; call get_payment_result with its paymentId every few seconds instead of calling pay_service again. {"status":"already_paid"} means this call's idempotency key already carries a payment whose result is not replayed here (the original call failed, its 24-hour result expired, the requestId was reused for a different request, or the deployment predates result replay, API 1.48); nothing new was charged, and it does not by itself say whether the original succeeded. Read the original with get_payment_result (paymentId) or list_payments (pass its requestId). A new requestId starts a separate, separately charged purchase: use one only after that read shows the original failed and the human still wants the result. {"error":"payment_indeterminate"} means the charge may or may not have landed: check list_payments first, and to retry reuse the returned requestId verbatim without fresh so the retry stays idempotent. {"error":"per_call_max_exceeded"} means no charge; raise maxTotalCents only after a deliberate decision and retry with the same requestId. quote_not_found, quote_expired, and quote_mismatch are named no-charge quote refusals; quote again rather than paying unpinned. {"error":"payment_failed"} is a definite decline (see code, message and retryable). These charge nothing: {"payable":false} (not payable via the Router; no upstream URL is ever returned), service_not_found (wrong slug), catalog_unavailable and delegation_lookup_failed (transient; retry later), payment_not_started (too little time remained to start a payment; retry with the same arguments), no_delegation (call setup_delegation), router_controls_unavailable (the API behind this server is too old to enforce search, quoteId or maxTotalCents; tell the human instead of retrying without them) and credential_refused (re-authorize). A paid result also carries delegationId and budget, the spending budget after this call (capCents/spentCents/remainingCents, cents with up to four decimals), so to say what has been spent or what is left, repeat budget rather than adding up your calls yourself; budget: null means it could not be read this time, not that it is zero (call get_budget). FUNDING (funding): omit it and the call is paid with your Nevermined credits when you hold credits that can pay it (a Nevermined Subscription allowance, welcome or top-up credits) and the endpoint carries a credits tariff (Nevermined pays the merchant; the call costs the tariff in credits, returned if the service does not answer successfully), otherwise from your delegation; pass "subscription" or "delegation" to choose. The price ceiling, and the credits left of a subscriber in good standing, are checked only when the call is made: a credits call refused for them (insufficient_credits, subscription_cap_reached, subscription_ceiling_exceeded) charges nothing and is NOT switched to your delegation, so follow its alternative. Without a subscription in good standing, your spendable credits are checked before the call, and a call they cannot cover (when no automatic credit pack would) is paid from your delegation, with fundingCode saying why. Every result that mentions funding states which funding was chosen: a subscription call returns funding: "subscription" with creditsCharged, creditsStatus and creditsLeft (a digit string read after the call; null means unavailable, not zero) (Committed = spent, Reserved = held or marked for refund, Refunded = returned) and no budget, plus topUp (credits, amountUsd) and topUpMessage when the call ran out of credits and charged one credit pack to the saved card to cover itself (credit top-ups on, and only on a call made with your own API key: a call made through an OAuth connection never charges a pack) — relay topUpMessage to the user, since their card was charged (it comes alone, without topUp, when the pack could not be read); quoteId, maxTotalCents and delegationId apply only to a delegation. already_paid states no funding: it answers for an earlier payment, which may have been funded either way, and a retry that lands on the other funding gets it even when the original succeeded and its result is still kept. To see which funding that payment used, read fundingSource from list_payments with its requestId. Subscription refusals charge nothing and no credits (unless they carry topUps: "bought", below): subscription_unavailable, no_active_subscription, subscription_not_eligible (see reason), subscription_rail_unsupported, subscription_ceiling_exceeded, insufficient_credits, credits_frozen (every credit frozen by a card dispute; on a call with funding omitted and no delegation it names setup_delegation), subscription_cap_reached, credit_daily_limit_exceeded (wait until midnight UTC or ask the human to change their limit), credit_budget_unavailable (retry later) and subscription_payment_refused. Neither daily-budget refusal switches to a delegation; credit_daily_limit_exceeded carries dailyLimitCredits (number), usedCredits, remainingCredits (digit strings) and resetsAt. Other refusals say in alternative when the delegation can pay instead. With credit top-ups on, insufficient_credits on a call made with your own API key carries topUps, and a credit pack may have been charged even though the call was refused (no credits were spent on it); on a call made through an OAuth connection it carries none and no pack was charged: paused (a pack was declined; buying one from the Nevermined dashboard resumes them), limitReached (the monthly top-up limit), pending (a pack is being charged and may already be; retry in a moment), unavailable (no pack was charged; retry later) or bought (this call charged a pack but other calls spent it first; on code BCK.SUBSCRIPTION_ROUTER.0009 retry, otherwise follow message). credits_frozen can carry topUps: "bought" too: a pack was charged, then frozen with the rest by a dispute. Any refusal with topUps: "bought" also carries topUpMessage and the pack’s purchaseId: relay topUpMessage to the user, since their card was charged. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request payload sent to the vendor. | |
| path | No | Router suffix appended to the service base. Read `get_service`'s `requestShape.endpoints[].payServiceArgs.path`: a checked `invokePath` may be empty even when the display path is not. Replace every `pathParams` placeholder. Put query parameters in `search`, never in `path`. | |
| slug | Yes | The service slug to pay for. | |
| fresh | No | Set true on every POLL of an async status endpoint, including the first: each call mints a fresh idempotency key so the poll advances, instead of later polls reusing the derived key and getting the first poll's stored answer (or, before API 1.48, `already_paid`) back. Trade-off: with `fresh` a retry is NOT de-duplicated and WILL be charged again — use it to advance a poll, never to retry a call whose outcome you are unsure of. Leave unset for ordinary calls so a genuine retry stays idempotent. Ignored when you pass an explicit requestId. | |
| method | No | HTTP method for the vendor call. Omit to use the method the catalog records for the endpoint matching `path`; falls back to POST when the catalog records none. | |
| search | No | Query string without ?, for a slug-routed GET (e.g. flight_iata=AA217). | |
| funding | No | How to pay: `subscription` (your Nevermined credits) or `delegation` (your spend-capped delegation). Omit it to use your credits when the endpoint carries a credits tariff and they are accepted for it (without a subscription in good standing, only when they cover the call), else the delegation; a credits call refused when it is made, because too few credits are left or by the price ceiling, is NOT switched to the delegation. The result says which was chosen. | |
| headers | No | Extra headers for the vendor call. | |
| quoteId | No | Opaque short-lived quote id returned by quote_service. Pass it only with the exact same call before expiresAt; the Router then pays the cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling. | |
| requestId | No | Idempotency key. Leave unset — a retry of the same call is de-duplicated automatically. Only set a NEW value if you intend a genuinely separate, additional charge. To poll an async status endpoint, prefer `fresh: true` over minting your own value. | |
| delegationId | No | Delegation to charge when you authenticate with an API key; defaults to your active one. An OAuth-connected caller always spends from the grant it approved, so a value here does not choose the delegation; it still feeds the derived idempotency key when you omit `requestId`, so keep it the same across retries of one call. The result's `delegationId` names the delegation actually charged. | |
| maxTotalCents | No | Maximum whole cents this call may cost, including the buyer fee (compared exactly, so rounding alone never exceeds it). The price the service quotes on its 402 can differ from the catalog price label. | |
| requireProtocol | No | Force the payment rail. Set it only when you must pay on one rail — for example a wallet that holds funds on a single chain. If the service offers both rails the Router uses this one; if the service does not offer it the call is refused (`payment_failed` with code BCK.ROUTER.0045, nothing charged) rather than paid on the other rail. Omit it to let the Router auto-select (it prefers mpp). A `quoteId` that was quoted on the other rail is refused (`quote_mismatch`); quote again with the same `requireProtocol`. | |
| validateRequestBody | No | Opt-in safety check (default off). When true, and the request body provably fails the endpoint's published request schema, the Router refuses the call BEFORE anything is signed, minted or charged (`payment_failed` with code BCK.ROUTER.0046, nothing charged) — instead of paying and letting the merchant reject a malformed body. Leave it unset to let a questionable body through to the merchant unchecked. Only a provably-invalid body is refused; a missing or unverifiable schema still pays. Fix the body to match the endpoint's published requestSchema (see `get_service`), or drop this flag. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=true) convey mutation risk, but the description adds substantial beyond-schema behavior: real funds movement, multi-second latency including settlement, 24h idempotent result replay on API 1.48+, `already_paid` on older deployments, `pending`/`payment_indeterminate` semantics, funding selection rules, and that `paid: true` means attempted not settled. This directly supports the destructive annotation rather than contradicting it.
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 opening sentence is front-loaded and clear, but the body is an extremely long run-on block that enumerates dozens of error codes and funding branches in a single wall of text, with heavy repetition of idempotency and topUp caveats. Much of this duplicates schema parameter descriptions (e.g. `fresh`, `requestId`, `quoteId`, `funding`) and would be far more usable split into a short overview plus linked sections or delegated to the error-code reference.
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 14-parameter, destructive payment tool with no output schema, the description covers every decision an agent needs: prerequisites, idempotency, async polling, funding selection, quote pinning, and per-error recovery actions with no-charge vs may-have-charged classification. The return shape (`paid`, `upstreamStatus`, `response`, `payment.status`, `budget`, `creditsCharged`) is described precisely enough to substitute for a missing output schema.
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 already 100%, but the description adds real semantic guidance beyond it: how `path` must be derived from `payServiceArgs` with pathParams replaced, why slug-only reaches a 404 on multi-endpoint APIs, how `method` is resolved and echoed, how `quoteId` must be paired with identical args before `expiresAt`, and how `fresh` interacts with derived idempotency keys on async polls.
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 first sentence gives a specific verb+resource+outcome: 'Pay for a catalog service from your spend-capped delegation and return the vendor response', and immediately flags that it charges real funds. It is clearly distinguishable from siblings like quote_service, get_service, and get_payment_result, which are named as prerequisite/follow-up tools.
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?
Explicitly states when to call it vs alternatives: call `get_service` FIRST for requestShape, use `get_payment_result` with a paymentId on pending instead of re-calling, use `list_payments` to inspect indeterminate/already_paid outcomes, use quote_service for pinned totals, and setup_delegation for `no_delegation`. When-not guidance is also present (don't use `fresh` to retry an unsure call; a new requestId only starts a separate purchase).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price ONE call to a catalog service WITHOUT paying it: it charges nothing, signs nothing and reserves no budget. Pass exactly what you would pass to pay_service (the same slug, path, method, search, headers, body and delegationId): the Router sends that request to the service unpaid, reads the price it asks for, and returns an opaque quoteId, its short expiresAt, the rail (protocol), the network and merchant amount (settlement) and the fee-inclusive total (fee.capChargedCents, whole cents rounded up; fee.capChargedMicros exact, in 1/10,000 of a cent). Unlike the quote on a get_service endpoint (the last merchant price the catalog observed, routing fee excluded), this is priced live for your exact request and includes the fee. Because the request really reaches the service, a service that does not charge for it performs it, so take care quoting a method with side effects; and a quote spends the same per-service rate limit as a payment, so quote once per decision rather than polling. It prices the delegation pay_service would charge (optionSet: "delegation", naming its delegationId), or, with no delegation set up, what a personal crypto delegation would select (optionSet: "deployment"); in that case nextTool is setup_delegation: set one up and quote again before paying, since the delegation you create can select a different rail and price. It checks neither your remaining budget nor your wallet balance (see get_budget and wallet_balance). Next step (nextTool: "pay_service"): if fee.capChargedCents fits what you planned to spend, call pay_service before expiry with the same arguments, the quoted delegationId, quoteId, and maxTotalCents set to that figure as a number. The quote id fixes the exact challenge and fee-inclusive total while maxTotalCents remains an independent ceiling. paymentRequired: false means the service did not ask for payment for this request; upstreamStatus is its answer, and a non-2xx usually means the path, method or body is wrong. The service response itself is never returned. Outcomes, all charging nothing: {"payable":false}, service_not_found, catalog_unavailable and delegation_lookup_failed as in pay_service; quote_unavailable (no quote can be made here and retrying will not change that, so bound the price with pay_service maxTotalCents instead); quote_failed (the Router refused to price the call, or did not answer; see code, message and retryable); credential_refused (re-authorize). FUNDING (funding): chosen as pay_service would choose it. When you hold Nevermined credits that can pay it (a Nevermined Subscription allowance, welcome or top-up credits) and the endpoint carries a credits tariff the answer is {"funding":"subscription","credits":…,"tariffVersion":…}: the credits one call costs from the published tariff (the service is not contacted, and there is no quoteId or cent total); then call pay_service with the same arguments. The price ceiling, and the credits left of a subscriber in good standing, are checked only when pay_service makes the call, so this answer does not promise the call will be paid with credits. Pass funding: "delegation" to price the delegation instead. Subscription refusals are named as in pay_service. When settlement.scheme is session, the merchant is paid out of a deposit in a payment channel, and sessionDeposit says what this call would do to it: action is open (the first call locks a deposit), top_up (it locks more), none (no new money leaves the wallet), closing (the call would be refused, nothing moves; quote again once it has closed) or null (what the call would do could not be stated, and pay_service may refuse it); approxCents is how much would move into the deposit, in cents, the network fee not included, and basis says whether that is sized for this budget and wallet or an upper_bound. That money can far exceed the price. It is locked, not spent, it is not charged to the budget, and what the merchant does not take comes back when the channel closes, idleCloseSeconds after its last use. Tell the human before paying. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | The request payload you would send; some services price by it. | |
| path | No | The same `path` you would pass to pay_service: read `get_service`'s `requestShape.endpoints[].payServiceArgs.path` and replace every `pathParams` placeholder. Put query parameters in `search`. | |
| slug | Yes | The service slug to quote. | |
| method | No | HTTP method. Omit to use the method the catalog records for the endpoint matching `path` (POST when it records none), exactly as pay_service does. | |
| search | No | Query string without ?, for a slug-routed GET (e.g. flight_iata=AA217). | |
| funding | No | What to price: `subscription` (your Nevermined credits) or `delegation` (the fee-inclusive money total). Omit it to price the funding pay_service would use. | |
| headers | No | The extra headers you would send to the vendor. | |
| delegationId | No | The delegation you would pay with, when you authenticate with an API key; defaults to the one pay_service would use. A card or organization-wallet delegation can select a different rail, and so a different price. An OAuth-connected caller is always quoted for the grant it approved, so a value here does not choose the delegation; the result names the one priced. | |
| requireProtocol | No | Price (and pin the returned quote to) one payment rail. Pass the same value you will pass to pay_service: the quote prices that rail, and the quoteId it returns is only payable on it. If the service does not offer the pinned rail the quote is refused (`quote_failed` with code BCK.ROUTER.0045, nothing charged) rather than priced on the other one. Omit to let the Router auto-select (it prefers mpp). A subscription-credit quote (`funding: "subscription"`) is rail-agnostic — it prices the published credit tariff, so the pin does not change it and is not applied here; the subsequent paid call still enforces the pin and can be refused if the service does not offer it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but the description says the unpaid request really reaches the service and that a non-charging service performs it, warning the agent to take care with methods that have side effects. That is a direct contradiction of the read-only annotation, so this dimension scores 1 despite the otherwise rich behavioral detail.
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 first sentence is front-loaded and clear, but the remainder is a dense multi-clause block covering outcomes, funding, session deposits, and next steps. The content is relevant, yet it is far longer than needed and would be easier to scan if structured more tightly.
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 complex payment-quoting tool with no output schema and minimal annotations, the description covers return fields, outcomes, funding modes, sessionDeposit behavior, authentication, and the next step. It is complete enough for an agent to act correctly despite the annotation conflict.
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 already 100%, so the baseline would be 3. The description adds cross-tool meaning beyond the schema: it says to pass the same arguments as pay_service, that quoteId fixes the challenged total while maxTotalCents remains an independent ceiling, that requireProtocol pins the rail, and that funding and delegationId change what is priced.
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 states a specific verb (price) and resource (one call to a catalog service) and immediately excludes payment. It also names pay_service and the get_service quote as alternatives, so the agent can distinguish it from siblings.
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 explicitly tells the agent to call this before pay_service, pass the same arguments, use the quoteId before expiry, and avoid polling because it consumes the same rate limit. It also routes delegation setup to setup_delegation and budget or wallet checks to get_budget and wallet_balance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a plain-language description of what you need, find, and optionally pay in the same call, the single best payable catalog service, so you do not have to pick among listings yourself. Use it instead of search_services when you want the right service for a task rather than a list to browse: it ranks candidates on Nevermined's own relevance and quality signals (deterministic; no model reads the merchant listings), applies a fail-closed payability gate (listed, healthy, moderated, x402/mpp, not flagged unpayable), and returns the winner as chosen (with its opaque invoke handle, never a raw host) plus a ranked shortlist; every shortlist item carries a closed matchReason, gateReason, per-item rankingSource, and one scale-specific score. With autoPay:false (the default) it returns the pick only and charges nothing; the next step is normally get_service on chosen.slug, then pay_service with the endpoint you need. With autoPay:true it also pays the winner through the same path as pay_service and returns the upstream call in result: result.status and result.body are the vendor's answer, and result.paid: true means a payment was attempted, not that it settled, so read result.payment.status (Settled, Issued or Failed). autoPay calls the winner at its base URL plus any path you pass, and you only learn the winner from this call, so it suits single-endpoint services; a multi-endpoint winner typically answers 404 at its base URL. autoPay requires requestId; an API-key caller must also pass delegationId, while an OAuth-connected caller spends from the grant it approved and needs none. Outcomes: no listed, payable match → {"status":"no_fundable_match"} (broaden the intent or filters; nothing charged), never a wrong pick; missing_autopay_fields (nothing charged); on autoPay, payment_indeterminate (check list_payments, and retry only with the same requestId) and already_paid (this requestId already carries a payment, see paymentId; nothing new billed, and it does not by itself say whether the original succeeded). Every pick and each of these outcomes carries an instructions string with the next step; a payment the Router declines on autoPay comes back as a tool error carrying the API's message. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body for the paid call (autoPay only). | |
| path | No | Subpath appended to the winner when paying (autoPay only). | |
| limit | No | Shortlist size to return (1–20, default 5). | |
| intent | Yes | Plain-language description of the service you need (e.g. "translate English to German"). | |
| method | No | HTTP method for the paid call (autoPay only). | |
| search | No | Query string (no leading ?) for the paid call (autoPay only). | |
| autoPay | No | When true, also pay and relay the winner in the same call (same path as pay_service); requires requestId, plus delegationId when you authenticate with an API key. Default false → return the pick only, no charge. | |
| filters | No | Optional structured narrowing; all fields optional. | |
| headers | No | Extra headers for the paid call (autoPay only). | |
| requestId | No | Idempotency key — REQUIRED when autoPay is true. | |
| delegationId | No | Delegation to charge on autoPay. Required when you authenticate with an API key; an OAuth-connected caller spends from the grant it approved, so it can omit this (a value there does not choose the delegation). | |
| maxTotalCents | No | Refuse a paid quote above this (fee-inclusive), before purchase (autoPay only). | |
| credentialHeader | No | Header the Router should carry the minted payment credential in on the paid hop (autoPay only). Send it only when the winning service needs its own auth AND a payment credential (e.g. "Payment"). Ignored when autoPay is false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=true; the description goes far beyond that by disclosing exactly what can be destroyed (money) and under which conditions (autoPay:true, gated by maxTotalCents and a fail-closed payability gate). It spells out idempotency semantics (requestId required, retry only with the same requestId), the difference between 'payment attempted' and 'settled' via result.payment.status, and the auth requirement (API key on the Authorization header, delegationId for API-key callers).
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?
It is front-loaded: purpose, the sibling contrast, and the two modes come before the outcome enumeration, and nearly every sentence carries non-redundant information (gates, failure codes, next steps). The cost is density — several sentences are long multi-clause run-ons that an agent must parse carefully, which keeps it out of 5 territory.
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 13-parameter tool with a nested filters object, no output schema, and a destructive payment path, the description covers the outcome space explicitly: no_fundable_match, missing_autopay_fields, payment_indeterminate, already_paid, and router-declined payments, each with a note on whether money moved. It also states that every response carries an instructions string, closing the loop on what to do next.
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 real meaning on top: autoPay's charge/no-charge consequences, why requestId matters for idempotent retries, and the delegationId distinction between API-key and OAuth callers. It does not explain path/method/search/headers beyond what the schema already says, which is why it stops short of 5.
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 first sentence states a specific verb and resource ('find, and optionally pay... the single best payable catalog service') plus the scope constraint ('so you do not have to pick among listings yourself'). It immediately contrasts itself with the sibling search_services, so an agent can route between browsing and selecting without opening either 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?
It gives an explicit selection rule ('use it instead of search_services when you want the right service for a task rather than a list to browse') and a second decision rule for autoPay true vs false, naming the default and the normal follow-up path (get_service on chosen.slug, then pay_service). It also names when autoPay is a poor fit: single-endpoint vs multi-endpoint winners that 404 at their base URL.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Nevermined Agent Services Catalog for paid services, ranked by ARD HYBRID relevance — semantic (meaning) matches merged with lexical (keyword) matches, most relevant first — falling back to pure lexical when the embedding provider is unavailable. Each result includes a closed matchReason, a per-item rankingSource, and one scale-specific score. A query is required; the other filters are optional. Returns matching listings (vendor, protocol, headlinePriceLabel, endpoints). headlinePriceLabel is derived from endpoint prices; "from" means prices vary. Budget against the selected endpoint price and quote before paying. Only the first page is returned: the pageToken in the result cannot be passed back to this tool, so to see other matches narrow the query or filters, or raise pageSize (up to 100). Discovery only; no payment. To have the platform PICK (and optionally pay) the single best service for a need instead of choosing yourself, use route_by_intent.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Restrict to services carrying this catalog tag (e.g. a protocol or domain keyword from a listing's `tags`). Combined with `category` it widens the match to either value rather than narrowing it. | |
| query | Yes | What you need, in plain language. REQUIRED. Ranked semantically AND lexically (hybrid), most relevant first — a query describing the need ("translate documents to German") matches on meaning, not only exact words, and also keyword-matches title, descriptions and tags. Falls back to keyword-only ranking when the embedding provider is unavailable. | |
| prefer | No | Move this opaque catalog slug to the front when it matched the returned page; if it did not match, keep the normal ranked fallback. | |
| exclude | No | Never return this opaque catalog slug in the result page. | |
| funding | No | Only services with at least one endpoint payable with Nevermined credits. Local catalog only. Check get_service: the specific endpoint carries subscription when credits can pay it; this does not check your balance. | |
| category | No | Restrict to services carrying this catalog tag — it filters on tags exactly like `tag`. The category names `list_categories` returns are not stored as tags, so passing one here matches nothing; put a category name in `query` instead. Given together, `category` and `tag` match a service carrying either one. | |
| pageSize | No | Page size, 1–100 (a size of 0 is meaningless and is rejected). | |
| protocol | No | Restrict to a payment protocol. Only x402 and mpp are payable via the Router. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, and the description is consistent with a read-only search while adding real behavior: ranking degradation to keyword-only when the embedding provider is unavailable, and the significant constraint that the returned pageToken cannot be fed back in. The price-label semantics ("from" means prices vary) and the warning to budget against the selected endpoint price are useful operational context. Slightly short of 5 only because it does not describe result ordering edge cases or empty-result behavior beyond the fallback note.
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 ranking model, then constraints, then the sibling alternative — a sensible order with no filler sentences. It is a dense single paragraph, however, and the return-field and pagination details could be split out for faster scanning.
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 carries the return shape and does so (vendor, protocol, headlinePriceLabel, endpoints, matchReason, rankingSource, score). Combined with the annotation, the pagination limitation, and the payment boundary, an agent has everything needed to call it correctly and interpret results.
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 still adds cross-parameter meaning — that pageSize caps at 100 and is the lever for seeing more matches, and that query is required while the rest are optional. It does not elaborate on prefer/exclude/funding/category/tag, which remain fully documented in 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 ("Search the Nevermined Agent Services Catalog for paid services") plus the ranking model (ARD HYBRID semantic+lexical, with lexical fallback). It explicitly contrasts itself with the sibling route_by_intent, so an agent can pick between them without opening either 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?
Names the alternative and the exact condition that selects it ("To have the platform PICK... use route_by_intent"), and states the boundary "Discovery only; no payment." It also gives concrete guidance for the pagination limitation (narrow the query or filters, or raise pageSize up to 100).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the spending-delegation ceremony and return ONE URL for a human to open. Use this when pay_service returns {"error":"no_delegation"} — it is the way out of that state. It sets up a stablecoin (crypto) delegation that spends from the human's personal wallet, so that wallet also needs funds on the network a service settles on (see wallet_balance); it does not enroll a card or create a card delegation. The human sets the currency, spending cap, duration and transaction limit themselves in the browser; you CANNOT set them and must not ask the human to pass them to you. Returns {"status":"human_action_required","url":…} — relay the url, wait for the human to confirm, then simply call pay_service again. {"status":"already_active"} means a usable spending budget is in place — for an OAuth commerce caller it is the grant approved on the consent screen — and nobody needs to do anything: tell the human message as it stands (it states the cap, spent, remaining and expiry the API reports, in a voice written to be relayed), then follow instructions and call pay_service. The url embeds a short-lived session token, so treat it as sensitive and give it only to the account owner. Other outcomes: delegation_setup_unavailable (this deployment cannot run the ceremony) and delegation_setup_failed (the session could not be started) produce no URL; return_url_not_allowed means drop or fix returnUrl; a human_action_required answer with delegationCheck: "failed" means an existing budget could not be ruled out, so follow its instructions and try pay_service first. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| returnUrl | No | Where the human's browser should land after they authorise. Only a localhost callback (http://127.0.0.1:<port>/…) or an origin this Nevermined deployment has allow-listed is accepted; a rejected value is reported back rather than silently dropped. OMIT THIS unless you actually have somewhere to receive the redirect — without it the page just shows a confirmation and the human closes the tab, which is the normal case in a chat host. Validated by the Nevermined API rather than here, deliberately: a second validator in this schema could refuse a URL the API would have accepted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only providing readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: it returns a single URL with a short-lived session token that must be treated as sensitive, requires a Nevermined API key on the Authorization header, explains that the human sets parameters in the browser, and enumerates the distinct response statuses and their meanings. It also discloses that other outcomes produce no URL.
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 long and dense, but it is front-loaded with the purpose and trigger, then proceeds through outcomes and prerequisites in a logical order. Each sentence carries operational detail, though the volume of outcome handling could have been formatted more scannably.
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 complex setup tool with no output schema, one optional parameter, and only minimal annotations, the description compensates by explaining return statuses, the URL relay workflow, the already_active path, failure modes, and the required auth header. Nothing an agent needs to call it 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% and the single optional parameter returnUrl is documented thoroughly in the schema, so the baseline is 3. The description adds meaningful semantics beyond the schema: it invokes returnUrl again in the 'return_url_not_allowed' outcome and clarifies that currency, spending cap, duration and transaction limit are not parameters and must not be solicited from the human.
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 — 'Start the spending-delegation ceremony and return ONE URL for a human to open' — and immediately distinguishes it from pay_service by naming the exact error state it resolves ('no_delegation') and clarifying it does not enroll a card or create a card delegation. An agent can identify it from siblings without opening any 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?
It gives explicit trigger conditions ('Use this when pay_service returns {"error":"no_delegation"}'), describes the negative case ('already_active' means nobody needs to do anything, just call pay_service), and routes the caller to the correct next action for each outcome. It also tells the agent what not to do (must not ask the human for currency, cap, duration, transaction limit).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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`). |
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.
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.
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.
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.
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.
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.
Read the balances of YOUR OWN PERSONAL wallet — the funding source the crypto rails PULL from when pay_service charges a PERSONAL delegation. It answers how much do I have, and on which chain. Reading costs nothing and charges nothing. WHAT IT DOES NOT COVER, so you do not mis-diagnose: a delegation backed by an ORGANIZATION wallet is paid from that wallet, not this one; and a CARD delegation has no wallet at all — there BCK.ROUTER.0009 is the card ISSUER declining, with nothing to top up, so this tool does not apply and the answer is a different card. BY RAIL: on MPP the wallet is checked BEFORE anything is signed, and the BCK.ROUTER.0009 you get back already names the wallet and the chain — what it never says is HOW MUCH is there, which is what this tool supplies. On x402 there is NO balance pre-check and BCK.ROUTER.0009 is never raised: the credential is minted, budget is reserved, and a short wallet only surfaces when the merchant's on-chain transfer fails — by which point your budget is already committed, and the reserve comes back only once the reconciler has seen the authorization expire unconsumed. So on that rail read the balance BEFORE you pay, not after. By default this reports EVERY network this deployment settles on, and you must read the one the merchant quoted: a healthy balance on one chain says NOTHING about the other, and most services settle on only one of them. Pass network (a chain id) to read a single chain. A token whose atomic/formatted is null was NOT READ (the on-chain read failed) — that is not a zero balance, and reporting it as empty is wrong; a chain that could not be read at all comes back as an entry with error instead of balances. This tool diagnoses and fixes nothing: there is no on-ramp and you cannot top your own wallet up, so a genuine shortfall is a stop condition — report the network and the amount to your human, and do not retry the payment. Each entry with balances also carries lockedInChannels when the API reports it, per token (atomic in the token's smallest unit, formatted, symbol): money your payer wallet (the one the Router signs MPP payments with, which is this wallet once your account is migrated) has deposited into payment channels with merchants that charge per call over an MPP session, held in the channel's escrow. It is NOT part of balances and it is NOT spent: it is still the human's. It can pay further calls only to the merchant holding that channel, never anyone else, and what is unused comes back to that wallet when the channel closes, after 15 minutes without use. Report it beside the balance, never as spending, and never count it toward paying any other merchant. Here a null symbol/decimals/formatted means a token Nevermined does not recognise, NOT an unread amount: report atomic as raw units of token. An empty list means nothing is locked; lockedInChannels: null means it could not be read, which is not the same as nothing locked. When you have a Nevermined Subscription the result also carries subscription (the credits left, reset date and plan, as in get_budget), and whenever you hold credits, subscribed or not, credits (total, spendable and by kind and expiry, as in get_budget): credits are not held in this wallet and are not money; calls paid with credits are paid by Nevermined, not from this wallet. Requires your Nevermined API key on the Authorization header.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Chain id to read. OMIT IT to see every network this deployment serves, which is what you want unless the merchant already told you which chain it settles on. A chain id this deployment does not serve is not refused: the result then lists the deployment's primary network (its own chain id, not the one you asked for) with a `warning` saying the requested chain is not served, so those balances say nothing about the chain you asked about. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description goes far beyond, confirming 'reading costs nothing and charges nothing,' disclosing that null atomic/formatted means an unread (not zero) balance, that an unreadable chain returns an `error` entry, that lockedInChannels is escrowed-but-unspent money tied to one merchant, and that credits are held by Nevermined rather than the wallet. Auth requirement (Nevermined API key on Authorization) is also stated.
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 verb and resource, then organized into distinct decision blocks (what it does not cover, by rail, default network behavior, null semantics, lockedInChannels, subscription/credits). It is long, and the twice-repeated 'as in get_budget' cross-reference plus the channel escrow explanation are denser than strictly needed, but nearly every sentence maps to a real mis-diagnosis an agent could otherwise make.
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-shape semantics — and it does: top-level `balances` vs `error` entries, per-token atomic/formatted/symbol, `lockedInChannels` with its own null semantics, plus optional `subscription` and `credits` fields. Nothing an agent needs to interpret a response or decide a next action 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% and the single `network` param is already richly documented, so the baseline is 3. The description adds operational meaning beyond the schema: by default it reports every network, and the agent must read the one the merchant quoted because a healthy balance on one chain says nothing about another. That is a decision rule, not a restatement of 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 ('Read the balances of YOUR OWN PERSONAL wallet') and immediately scopes it to the funding source the rails pull from. It explicitly carves out what it is NOT (organization wallet, card delegation with no wallet) so an agent can distinguish it from pay_service and get_budget without opening schemas.
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?
Gives rail-specific when-to-use rules: on x402 there is no balance pre-check, so read before paying; on MPP the wallet is named in BCK.ROUTER.0009 but the amount is missing, which is exactly what this tool supplies. It also states a stop condition (shortfall = report to human, do not retry) and names the alternative consumer of that budget signal.
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.
list_payments1 field changedInput schema / properties / requestIdAdded value: +{
+ "description": "The `requestId` a pay_service or route_by_intent result gave you, matched exactly. Finds that one payment wherever it sits in the ledger; the other filters are ignored.",
+ "minLength": 1,
+ "type": "string"
+}pay_service2 fields changedInput schema / properties / funding / descriptionPrevious value: -"How to pay: `subscription` (your Nevermined credits) or `delegation` (your spend-capped delegation). Omit it to use your credits when the endpoint carries a credits tariff and they are accepted for it (without a subscription in good standing, only when they cover the call), else the delegation; a credits call refused when it is made, because too few credits are left or by the price ceiling, is NOT switched to the delegation. The result says which paid."New value: +"How to pay: `subscription` (your Nevermined credits) or `delegation` (your spend-capped delegation). Omit it to use your credits when the endpoint carries a credits tariff and they are accepted for it (without a subscription in good standing, only when they cover the call), else the delegation; a credits call refused when it is made, because too few credits are left or by the price ceiling, is NOT switched to the delegation. The result says which was chosen."Input schema / properties / validateRequestBodyAdded value: +{
+ "description": "Opt-in safety check (default off). When true, and the request body provably fails the endpoint's published request schema, the Router refuses the call BEFORE anything is signed, minted or charged (`payment_failed` with code BCK.ROUTER.0046, nothing charged) — instead of paying and letting the merchant reject a malformed body. Leave it unset to let a questionable body through to the merchant unchecked. Only a provably-invalid body is refused; a missing or unverifiable schema still pays. Fix the body to match the endpoint's published requestSchema (see `get_service`), or drop this flag.",
+ "type": "boolean"
+}search_services1 field changedInput schema / properties / fundingAdded value: +{
+ "description": "Only services with at least one endpoint payable with Nevermined credits. Local catalog only. Check get_service: the specific endpoint carries subscription when credits can pay it; this does not check your balance.",
+ "enum": [
+ "subscription"
+ ],
+ "type": "string"
+}pay_service1 field changedInput schema / properties / requireProtocolAdded value: +{
+ "description": "Force the payment rail. Set it only when you must pay on one rail — for example a wallet that holds funds on a single chain. If the service offers both rails the Router uses this one; if the service does not offer it the call is refused (`payment_failed` with code BCK.ROUTER.0045, nothing charged) rather than paid on the other rail. Omit it to let the Router auto-select (it prefers mpp). A `quoteId` that was quoted on the other rail is refused (`quote_mismatch`); quote again with the same `requireProtocol`.",
+ "enum": [
+ "x402",
+ "mpp"
+ ],
+ "type": "string"
+}quote_service1 field changedInput schema / properties / requireProtocolAdded value: +{
+ "description": "Price (and pin the returned quote to) one payment rail. Pass the same value you will pass to pay_service: the quote prices that rail, and the quoteId it returns is only payable on it. If the service does not offer the pinned rail the quote is refused (`quote_failed` with code BCK.ROUTER.0045, nothing charged) rather than priced on the other one. Omit to let the Router auto-select (it prefers mpp). A subscription-credit quote (`funding: \"subscription\"`) is rail-agnostic — it prices the published credit tariff, so the pin does not change it and is not applied here; the subsequent paid call still enforces the pin and can be refused if the service does not offer it.",
+ "enum": [
+ "x402",
+ "mpp"
+ ],
+ "type": "string"
+}pay_service1 field changedInput schema / properties / funding / descriptionPrevious value: -"How to pay: `subscription` (your Nevermined Subscription credits) or `delegation` (your spend-capped delegation). Omit it to use the subscription when you hold an active one and the endpoint carries a subscription tariff, else the delegation; a credits call refused because too few credits are left this month or by the price ceiling is NOT switched to the delegation. The result says which paid."New value: +"How to pay: `subscription` (your Nevermined credits) or `delegation` (your spend-capped delegation). Omit it to use your credits when the endpoint carries a credits tariff and they are accepted for it (without a subscription in good standing, only when they cover the call), else the delegation; a credits call refused when it is made, because too few credits are left or by the price ceiling, is NOT switched to the delegation. The result says which paid."quote_service1 field changedInput schema / properties / funding / descriptionPrevious value: -"What to price: `subscription` (credits from your Nevermined Subscription) or `delegation` (the fee-inclusive money total). Omit it to price the funding pay_service would use."New value: +"What to price: `subscription` (your Nevermined credits) or `delegation` (the fee-inclusive money total). Omit it to price the funding pay_service would use."top_up_creditsget_budget1 field changedInput schema / additionalPropertiesRemoved value: -falseget_payment_result2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / paymentId / patternAdded value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"get_service1 field changedInput schema / additionalPropertiesRemoved value: -falselist_payments1 field changedInput schema / additionalPropertiesRemoved value: -falsepay_service3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / headers / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / maxTotalCents / maximumAdded value: +9007199254740991payment_summary1 field changedInput schema / additionalPropertiesRemoved value: -falsequote_service2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / headers / propertyNamesAdded value: +{
+ "type": "string"
+}route_by_intent4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / filters / additionalPropertiesRemoved value: -falseInput schema / properties / headers / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / maxTotalCents / maximumAdded value: +9007199254740991search_services1 field changedInput schema / additionalPropertiesRemoved value: -falsesetup_delegation1 field changedInput schema / additionalPropertiesRemoved value: -falsewallet_balance2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / network / maximumAdded value: +9007199254740991get_subscription_checkoutpay_service1 field changedInput schema / properties / fundingAdded value: +{
+ "description": "How to pay: `subscription` (your Nevermined Subscription credits) or `delegation` (your spend-capped delegation). Omit it to use the subscription when you hold an active one and the endpoint carries a subscription tariff, else the delegation; a credits call refused because too few credits are left this month or by the price ceiling is NOT switched to the delegation. The result says which paid.",
+ "enum": [
+ "subscription",
+ "delegation"
+ ],
+ "type": "string"
+}quote_service1 field changedInput schema / properties / fundingAdded value: +{
+ "description": "What to price: `subscription` (credits from your Nevermined Subscription) or `delegation` (the fee-inclusive money total). Omit it to price the funding pay_service would use.",
+ "enum": [
+ "subscription",
+ "delegation"
+ ],
+ "type": "string"
+}pay_service1 field changedInput schema / properties / quoteIdAdded value: +{
+ "description": "Opaque short-lived quote id returned by quote_service. Pass it only with the exact same call before expiresAt; the Router then pays the cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling.",
+ "type": "string"
+}route_by_intent3 fields changedInput schema / properties / filters / properties / excludeAdded value: +{
+ "description": "Never choose this exact opaque catalog slug.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / filters / properties / preferAdded value: +{
+ "description": "Prefer this exact opaque catalog slug when it is a payable match; otherwise keep the normal ranked fallback.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / filters / properties / requireAdded value: +{
+ "description": "Require this exact opaque catalog slug. It is returned only if payable and healthy; otherwise the Router fails closed with BCK.ROUTER.0031 and never substitutes another service.",
+ "minLength": 1,
+ "type": "string"
+}search_services2 fields changedInput schema / properties / excludeAdded value: +{
+ "description": "Never return this opaque catalog slug in the result page.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / preferAdded value: +{
+ "description": "Move this opaque catalog slug to the front when it matched the returned page; if it did not match, keep the normal ranked fallback.",
+ "minLength": 1,
+ "type": "string"
+}get_budgetget_payment_resultget_servicelist_categorieslist_paymentspay_servicepayment_summaryquote_serviceroute_by_intentsearch_servicessetup_delegationwallet_balanceFind services, request single purchases and read budgets. Testnet only.
Discover and pay for APIs with USDC credits. No wallet, no gas, MCP-native marketplace.
Search, negotiate and buy resource access with x402 test USDC on Ethereum Sepolia.
Procure governed AI capabilities: machine-readable price, scope, trust, gateway-delegation terms.
Add one secure layer between your agents and this server.