Discover and pay for services from the Nevermined Catalog using a spend-capped budget.
Scored across 12 tools
Each tool targets a distinct aspect of the payment lifecycle (discovery, pricing, payment, budget/wallet, ledger), and the descriptions go to great lengths to cross-reference and distinguish them. The main overlap is route_by_intent with autoPay, which duplicates pay_service plus discovery in a single call, and search_services vs route_by_intent, though the descriptions explicitly steer the agent between them.
Most tools follow a clean verb_noun snake_case pattern (get_budget, get_service, list_payments, pay_service, quote_service, search_services, setup_delegation). Two tools, payment_summary and wallet_balance, are noun-only and deviate from the dominant convention, a minor inconsistency.
12 tools is a well-scoped set for a paid-service catalog with payments, budgets, and discovery. Each tool earns its place with no obvious redundancy or filler.
The surface covers discovery (list_categories, search_services, get_service, route_by_intent), pricing (quote_service), payment (pay_service, get_payment_result), funding setup (setup_delegation), and accounting (get_budget, wallet_balance, list_payments, payment_summary). Minor gaps exist, such as no tool to close/refund a payment channel or cancel a subscription, but core workflows are fully supported.
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, 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. 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. When you have a Nevermined Subscription the result also carries subscription (creditsLeft, a digit string of credits spendable now; resetsAt, when they expire and, unless cancelAtPeriodEnd, the next period's are granted; status, suspended and plan) and subscriptionMessage to relay as it stands; subscription.subscribed: false means none. 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?
With no annotations, the description carries the full burden and does so: it states reading is free and charges nothing (safety profile), requires an API key on the Authorization header (auth), explains the no_active_delegation status and that it can also mean a depleted/expired budget, and clarifies that lockedInChannels belongs to the wallet, is not spent, and returns after 15 minutes. It also explains the rounding/routing-fee caveat and instructs the agent to relay 'message' verbatim rather than recompute figures.
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 usage are front-loaded, which is good, but the body is a dense multi-clause wall of text packing output-field semantics, subscription rules, and channel mechanics into single sentences. Given there is no output schema much of the detail is justified, yet the size and nesting of clauses make it harder to scan than it needs to be.
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 return values, and it covers the budget fields, delivery-status breakdown, unattributed spend, lockedInChannels states (empty/null), and the subscription block including the subscribed:false case. An agent has everything needed to call and interpret the result.
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% with a single optional parameter, so the baseline is 3, but the description adds genuine meaning beyond the schema: it tells the agent where a delegationId comes from ('every paid pay_service result carries one') and what omitting it excludes. This is more than the schema's restated default.
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 names a specific verb and resource ('Read the spending budget pay_service spends from') and enumerates exactly what is returned: cap, spent, remaining, payment count and limit, expiry. It is clearly distinct from siblings like wallet_balance, list_payments, and payment_summary, which the agent can rule out 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 triggers: 'Use it whenever the human asks how much is left, or before a run of paid calls.' It also explains the delegationId omission case and its side effect (only budgets that can still pay are included), routing the agent on behavior rather than naming an alternative tool outright. No explicit 'prefer X over Y' statement keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 — the payment is made and the call keeps running), or to recover a result whose response you lost. Reading costs nothing and charges nothing. 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. {"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 returns the same pending answer. 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?
With no annotations to lean on, the description carries the full burden and does so: it discloses that reading is free, that results are retained 24 hours only for the paying account, and requires the Nevermined API key on the Authorization header. The state machine (Pending/Ready/Failed/not_available) and their meanings are spelled out, which is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose and the primary use case, then answers the state semantics in compact labeled form ('state: X' — meaning). Every sentence carries information, though the paragraph is denser than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description fully compensates by explaining the returned fields (`state`, `status`, `body`, `bodyEncoding`, `failureReason`) and the failure/empty cases. Nothing an agent needs to interpret a call 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?
Only a single parameter with 100% schema coverage, so the schema already documents `paymentId` as a UUID from a pay_service result. The description adds only the minor nuance that the value originates from a pay_service result, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read the result of a paid call') scoped by `paymentId`, and clearly distinguishes itself from the sibling `pay_service` it complements. An agent can tell exactly what this returns 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 names the two triggering conditions ('when pay_service answered pending' and 'to recover a result whose response you lost') and adds an explicit when-not ('Do NOT call pay_service again to get a pending result'). This is textbook routing guidance.
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. 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?
No annotations exist, so the description carries the full burden and does so richly: sanitisation of merchant response shapes, examples published only when they validate, endpointCheck as a dated unpaid failure, siwx endpoints being non-paid follow-ups readable only by the paying wallet, and unknown slugs returning an error. These are non-obvious traits an agent could not infer from structured fields.
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 and virtually every sentence carries distinct operational information. It is dense and jargon-heavy, but not padded; the length is warranted by the amount of contract detail conveyed.
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?
Despite having no output schema or annotations, the description explains what the response contains (metadata, requestShape, invoke contract fields, exampleEvidence kinds) and the error case. An agent has everything needed to call it correctly and interpret the result.
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?
Single required param with 100% schema coverage, so the schema already documents slug ('from search_services'). The description adds only indirect context via pathParams placeholders for downstream pay_service calls, which is baseline-3 territory.
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 ('Fetch one catalog service by slug') plus what is returned (metadata and a requestShape block). It cleanly distinguishes itself from search_services (discovery list) and pay_service/quote_service (payment), and explicitly closes with 'Discovery only; no payment.'
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 sequencing and alternatives: read payServiceArgs before pay_service, call quote_service for the live fee-inclusive total before paying, and for siwx endpoints call with pay_service after the earlier paid call. The when/when-not conditions are named, not implied.
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?
No annotations are provided, so the description carries the full disclosure burden. It does state the read-only, no-payment nature of the call, which is useful, but says nothing about authentication requirements, rate limits, or catalog freshness/caching. Adequate but thin for a tool with zero annotation coverage.
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 tight sentences, front-loaded with the action and resource, then the return detail, then the scope restriction. No filler, no repetition of the title.
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 trivial zero-param read tool with no annotations and no output schema, the description covers both what is returned (categories with counts) and the safety profile (discovery only, no payment). Only the absence of any auth/pagination context keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. No misleading parameter hints are present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the categories of paid services'), names the catalog it scopes to, and adds the return shape ('a count per category'). The closing clause 'Discovery only; no payment' separates it from the payment-oriented siblings (pay_service, quote_service, get_payment_result) without needing 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?
'Discovery only; no payment' gives an implied usage boundary against the payment tools, but no explicit when-to-use or when-not-to-use statement and no alternatives are named (e.g., search_services vs get_service). An agent can infer the intent but must fill in the comparison itself.
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 proved no merchant charge), or pending (charge outcome unknown). On SPT and card rails, pending is not proof of no charge; flag charged_not_delivered to the user. 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. | |
| delegationId | No | Only payments charged to this delegation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and delivers: auth requirement (API key on Authorization header), cost ('Reading costs nothing'), limit ('at most 1000 records'), ordering ('newest first'), detailed return field semantics, deliveryStatus meanings, and a critical caveat about 'pending' on SPT/card rails. Comprehensive and transparent.
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 scope; the dense single paragraph is justified by the complexity (no output schema requires explaining return fields and status codes). Every sentence contributes, though slightly better structure could improve 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?
Given no annotations and no output schema, the description must explain return values and usage context. It fully describes record fields, deliveryStatus meanings, cost, auth, and alternatives. The only minor omission is pagination behavior, but the stated 1000-record cap suggests completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are fully documented in the input schema. The description adds no additional parameter-level semantics beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List your Router payments: the unified ledger across every service and delegation') with scope and ordering. Explicitly names siblings get_payment_result and get_budget as alternatives, allowing an agent to distinguish it 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 explicit when-to-use ('reconcile an uncertain payment or find a paymentId') and when-not ('does not return service responses... or the remaining budget'), and names the alternative tools for each case. Nothing is left to inference.
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); flag a non-zero count to the user. 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?
With no annotations, the description carries the full burden and delivers: 'Reading costs nothing' (cost), 'Requires your Nevermined API key on the Authorization header' (auth), and the non-obvious reconciliation rule for chargedNotDelivered (a failed-but-unreconciled payment is not counted). These are exactly the traits annotations would otherwise supply.
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-loads the core purpose, then field semantics, then sibling routing, then auth — a sensible order with little waste. The chargedNotDelivered sentence is densely nested and takes a re-read, which keeps it short of perfect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain return values, and it does for all three fields (total, series shape and ordering, chargedNotDelivered). Auth, cost, and sibling routing are all covered, so an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so `from` and `to` are already fully documented as inclusive ISO-8601 bounds. The description only implies the period concept ('in the period') and adds no syntax or default behavior beyond the schema, 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+resource ('Count your Router payment requests') and immediately scopes it against siblings by noting the count is uncapped 'unlike list_payments'. An agent can distinguish this from list_payments and get_budget 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?
Explicitly routes: use get_budget for 'what has been spent or what is left' and list_payments for 'amounts per payment'. It also gives a behavioral instruction ('flag a non-zero count to the user') for the chargedNotDelivered case, leaving nothing to inference.
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. 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 with a non-2xx upstreamStatus may still have cost the merchant price. Outcomes to act on: {"status":"pending"} means the payment was made and the service is still working; 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. 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), 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 Subscription credits when you hold an active subscription and the endpoint carries a subscription 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 credits left in your monthly allowance and the price ceiling 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. Every result that mentions funding states which paid it: a subscription call returns funding: "subscription" with creditsCharged and creditsStatus (Committed = spent, Reserved = held or marked for refund, Refunded = returned) and no budget; quoteId, maxTotalCents and delegationId apply only to a delegation. Subscription refusals charge nothing and no credits: subscription_unavailable, no_active_subscription, subscription_not_eligible (see reason), subscription_rail_unsupported, subscription_ceiling_exceeded, insufficient_credits, subscription_cap_reached and subscription_payment_refused; each says in alternative when the delegation can pay instead. funding_undetermined means the funding could not be decided; nothing was charged, so retry. 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 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. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does: it discloses that real funds are charged, how idempotency/dedup works (24-hour replay, API 1.48 gate, `already_paid`), the async poll/fresh billing trade-off, the requirement for a Nevermined API key on the Authorization header, and the full funding/precedence logic. It also enumerates no-charge vs charge-possible error outcomes, which is exactly the behavioral context an agent needs before a paid write.
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 monetary warning are front-loaded, and nearly every sentence carries actionable behavior (error taxonomy, idempotency rules, funding precedence) rather than filler. It is nonetheless very dense and long, and the exhaustive error enumeration could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe returns itself — and it does: `paid`, `upstreamStatus`, `response`, `delegationId`, `budget` (with null semantics), `funding`, `creditsCharged`/`creditsStatus`. Combined with the error/outcome taxonomy, an agent has everything needed to call this correctly and interpret the result.
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 is 3, but the description adds genuine cross-parameter meaning not in the schema: the interplay of `quoteId`/`maxTotalCents`/`delegationId`, the `funding` omit-rules and refusal behavior, and why `fresh` must not be used on an unsure retry. It stops short of 5 only because most per-parameter syntax is duplicated from the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+payment source: 'Pay for a catalog service from your spend-capped delegation and return the vendor response.' It also immediately signals the destructive/monetary nature ('This charges real funds'), distinguishing it from siblings like quote_service and get_payment_result.
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 to alternatives and gives when/when-not rules: call `get_service` FIRST, use `get_payment_result` instead of re-calling pay_service on `pending`, quote again after `quote_not_found`, call `setup_delegation` on `no_delegation`. Prerequisite ordering (get_service → pay_service, quoteId before expiresAt) is spelled out.
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 an active Nevermined Subscription and the endpoint carries a subscription 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 credits left in your monthly allowance and the price ceiling 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. 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` (credits from your Nevermined Subscription) 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it charges nothing, signs nothing and reserves no budget, but the request really reaches the service (side effects), it spends the same per-service rate limit as a payment, it ignores budget/wallet balance, and it needs the Nevermined API key on Authorization. Mutation/side-effect and cost semantics are fully disclosed.
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 decisive constraint (price without paying) and organized by topic (args, returns, outcomes, funding). It is very dense and long, packing outcome enumerations and error codes into one paragraph, but nearly every sentence carries actionable information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description supplies return fields, next-tool routing, all refusal outcomes, subscription funding behavior and auth requirements. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the prose adds real meaning: parameters mirror pay_service's contract, `delegationId` may be ignored for OAuth callers while the result names the delegation priced, and `funding` selects what is priced. It stops short of restating every field, but the added context exceeds 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 gives a precise verb and resource ('Price ONE call to a catalog service WITHOUT paying it') and immediately contrasts it with `pay_service` and the `quote` on a get_service endpoint. An agent can distinguish it from every sibling without opening a 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?
Explicit routing: pass exactly the pay_service arguments, call pay_service next if `fee.capChargedCents` fits, quote once per decision rather than polling, use `maxTotalCents` instead when `quote_unavailable`, and `setup_delegation` first when `nextTool` says so. When-to-use, when-not-to-retry and alternatives are all stated.
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 was already paid, see paymentId; nothing new billed). 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?
With no annotations, the description carries the full burden and does so richly: deterministic ranking with no model reading listings, a fail-closed payability gate with its criteria, that autoPay pays through the same path as pay_service, and that result.paid only means a payment was attempted so payment.status must be read. It enumerates outcome shapes (no_fundable_match, missing_autopay_fields, payment_indeterminate, already_paid) and the API-key vs OAuth delegation distinction.
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 but densely packed and front-loaded, leading with the core purpose and the routing decision before drilling into autoPay mechanics and outcome codes. Every sentence conveys actionable information; it is verbose but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 13-parameter payment tool with no output schema and no annotations, the description supplies everything needed: ranking behavior, gate criteria, mode semantics, follow-on tools, auth requirements, and the full set of outcome and error shapes. An agent would not need additional context to invoke it safely.
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 genuine meaning beyond the schema: it explains that autoPay requires requestId and delegationId for API-key callers, that OAuth callers need none, and that credentialHeader only applies when the winner needs its own auth plus a payment credential. This contextualizes parameters rather than restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('find, and optionally pay ... the single best payable catalog service') from a plain-language intent. It explicitly distinguishes itself from the sibling search_services ('Use it instead of search_services when you want the right service for a task rather than a list to browse'), so an agent can select it correctly without opening a 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 explicit when-to-use vs search_services, describes the default vs autoPay modes and which to choose, and names the normal follow-on steps (get_service on chosen.slug, then pay_service). It even advises that single-endpoint services suit autoPay while multi-endpoint winners tend to 404 at 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, price label, endpoint). 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. | |
| 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?
With no annotations, the description carries the full burden and does well: it discloses hybrid ranking, the lexical fallback when embeddings are unavailable, the result shape (matchReason, rankingSource, one scale-specific score), and a real limitation (only the first page; pageToken cannot be passed back). It does not address auth, rate limits, or cost/auth prerequisites for catalog access, leaving that gap.
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 behavior and then the pagination constraint and sibling routing, with no wasted sentences. It is somewhat dense with internal jargon (ARD HYBRID, matchReason, rankingSource) that lengthens the prose without helping an agent decide whether to call it.
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 returns — and it does (vendor, protocol, price label, endpoint, plus ranking metadata). Combined with the ranking fallback and single-page limitation, an agent has everything needed to call and interpret this 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 description coverage is 100%, so the schema already documents all seven parameters including the tag/category OR-widening quirk and the protocol enum. The description mostly restates (query required, pageSize up to 100) rather than adding new semantics, so the baseline of 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?
Names a specific verb and resource (search the Nevermined Agent Services Catalog for paid services) and scopes it as discovery-only. It explicitly distinguishes itself from the sibling route_by_intent, which PICKs/pays instead of letting the caller choose.
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 the required input and that all other filters are optional, gives the explicit alternative ('use route_by_intent' when you want the platform to pick and pay), and explains the pagination workaround (narrow the query or raise pageSize) because pageToken cannot be reused. When-to-use and when-not-to-use are both covered.
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 no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses that the human sets currency, cap, duration and transaction limit; that the wallet needs funds; that the returned URL contains a short-lived sensitive token; required Authorization header; and exact status payloads and follow-up actions.
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 dense and long, but mostly earns its length by covering distinct states and outcomes, with purpose and trigger condition front-loaded. It could be more scannable with structure, but there is little pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema, no-annotation, complex human-in-the-loop tool, the description covers triggers, return contract, error outcomes, follow-up steps, sensitivity, and auth. Nothing an agent needs in order to call and recover correctly appears 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 description coverage is 100% and the single returnUrl parameter is already richly documented in the schema. The description adds only indirect guidance via return_url_not_allowed, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: start the spending-delegation ceremony and return one URL for a human. It explicitly distinguishes this from card delegation and positions itself as the recovery path from pay_service's no_delegation error, so an agent can select it correctly against 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 gives an explicit trigger condition: use this when pay_service returns {"error":"no_delegation"}. It also explains what to do after already_active and several failure outcomes, including when to try pay_service first, leaving little inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 in your monthly allowance, reset date and plan, as in get_budget): that allowance is not held in this wallet and is not money; subscription calls 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?
With no annotations, the description carries the full burden and does so: it discloses that reading is free, that there is no on-ramp and no self-top-up, that a shortfall is a stop condition, that null atomic/formatted means unread rather than zero, that an entry may carry `error` instead of `balances`, and that a Nevermined API key is required on the Authorization header.
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 the key stop-condition are reasonably front-loaded, but the body is enormously long for a one-parameter read tool, with heavy repetition around lockedInChannels, null semantics, and rail behavior. Much of the channel/subscription detail is genuinely useful, but the text could be cut substantially without losing agent-relevant meaning.
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 and no annotations, so the description must define the return shape itself — and it does: `balances`, `error` entries, `lockedInChannels` with atomic/formatted/symbol, and the `subscription` block. Nothing an agent needs to interpret the response or act on a shortfall 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 schema already documents the `network` chain id and the not-served warning behavior, so a baseline of 3 applies. The description rises above baseline by explaining why the default (all networks) is usually right, why a healthy balance on one chain says nothing about another, and that balances are per-settlement-network.
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 ('Read the balances of YOUR OWN PERSONAL wallet') and immediately delimits scope against other wallets and against the card-delegation case. An agent can distinguish it from get_budget and pay_service 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 when-to-use guidance by rail ('on x402 read the balance BEFORE you pay, not after'; on MPP the wallet is checked before signing) and explicit when-NOT-to-use cases (organization-backed delegations, card delegations with BCK.ROUTER.0009). It also names the alternative interpretation of the same error code.
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.
pay_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_balanceDiscover and pay for APIs with USDC credits. No wallet, no gas, MCP-native marketplace.
Procure governed AI capabilities: machine-readable price, scope, trust, gateway-delegation terms.
Discover machine-payable APIs, probe x402 payment terms, and run seller operations. Non-custodial.
Agentic workflow budget approvals with usage receipts.
Add one secure layer between your agents and this server.