Discover and pay for services from the Nevermined Catalog using a spend-capped budget.
Scored across 12 tools
Most tools have clearly distinct purposes, and descriptions go out of their way to draw boundaries (e.g. route_by_intent vs search_services, quote_service's live price vs get_service's static quote, get_budget vs list_payments vs payment_summary, wallet_balance vs get_budget). The remaining overlaps are in the financial-read cluster (get_budget, list_payments, payment_summary, wallet_balance) and the discovery cluster, where an agent could still hesitate, but descriptions disambiguate.
Nearly all names are snake_case with a verb_noun shape (get_budget, get_service, list_categories, list_payments, pay_service, quote_service, search_services, setup_delegation). Minor deviations exist: payment_summary and wallet_balance are noun-only, and route_by_intent drops the noun-object pattern, but overall the convention is predictable and readable.
12 tools is squarely in the well-scoped range for a paid-service catalog and payment router. Each tool maps to a real stage of the workflow (discover, price, pay, delegate, reconcile) and no tool looks redundant or filler.
The surface covers the full lifecycle: discovery (search_services, list_categories, get_service, route_by_intent), pricing (quote_service), payment (pay_service), funding (setup_delegation, wallet_balance, get_budget), and reconciliation (list_payments, payment_summary, get_payment_result). Minor gaps include no tool to list or revoke an existing delegation and no endpoint-level health/availability check beyond catalog metadata.
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. 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: read-only ('costs nothing and charges nothing'), auth requirement (Nevermined API key on Authorization), and the non-obvious edge case that no_active_delegation also covers exhausted/expired budgets. It further warns that returned figures include routing fees and rounding and must be relayed 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?
Front-loaded with the purpose and safety facts, and virtually every clause earns its place. It is dense and long, with the cents/routing-fee caveat bundled into one heavy run of clauses, but no filler sentences.
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, but the description names the return fields (capCents, spentCents, remainingCents, message), states the unit (cents, four decimals), and gives the invariant spentCents + remainingCents = capCents. Nothing an agent needs to call or interpret this tool 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 already documents delegationId's default behavior, so the description's restatement is partly redundant. However, it adds genuine semantics beyond the schema: that omission only surfaces budgets that can still pay, and that no_active_delegation masks spent/expired budgets. That edge-case behavior is real added value over baseline 3.
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 precise verb and resource — reads the spending budget pay_service spends from — and enumerates exactly what it returns (cap, spent, remaining, payment count/limit, expiry). An agent can distinguish it from siblings like wallet_balance or payment_summary 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 explicit triggers: 'whenever the human asks how much is left, or before a run of paid calls.' It also resolves the delegationId alternative (omit for the default budget vs. pass an earlier pay_service delegationId to read a specific one).
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 its slug with metadata and a requestShape block. Read each endpoint's payServiceArgs before pay_service, replacing any pathParams placeholders. Some endpoints carry a checked invoke contract: invokePath (the example's invoke path, possibly empty; payServiceArgs.path uses it only for a paid-run/challenge example — for a docs example it is that example's value, not the path to send), requestExample (a body, query or headers that worked), responseFields (where the useful data sits in the response) and exampleEvidence: paid-run when a real paid call returned that shape, challenge when a gateway that validates before pricing accepted the request (the response is unobserved), docs when it comes from provider documentation and is unverified (contractEvidence is the older paid-run/fixture form). Only a paid-run or challenge example is pre-filled into payServiceArgs; a docs example is a reference to adopt deliberately. When pathParams is non-empty and payServiceArgs.path is already filled, the values are the example's: substitute your own. An endpointCheck (unpaid-route-403 / unpaid-route-404 with checkedAt) records that an unpaid call to that endpoint through the Router failed on that date, so the example is not confirmed to work. An endpoint may carry requestSchema, the merchant-declared JSON Schema of its request (properties.query → search, properties.body → body; sanitised, not verified — see requestSchemaSource), or noParameters: true; endpoints with neither and no checked example require provider documentation. An endpoint's quote, when present, is the merchant's live per-call price on the rail and network the Router pays it on (amountAtomic in the asset's decimals); it excludes the Router's routing fee, which the budget is also charged. An endpoint may publish maxRequestBytes: a larger body is refused before any payment. An unknown slug returns an error. Discovery only; no payment. For the live, fee-inclusive total of one specific call before paying, call quote_service.
| 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?
With no annotations provided, the description carries the full burden and does so extensively: it explains the returned requestShape fields, evidence types, pathParams substitution rules, requestSchema semantics, quote pricing scope, maxRequestBytes enforcement, and that an unknown slug returns an error. It also states the tool is discovery-only and involves no payment.
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 bulk is a dense, run-on paragraph packed with nested conditional explanations. While much of the content is technically relevant because there is no output schema, the overall length and density are excessive for a single-parameter 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?
Given the absence of annotations and an output schema, the description is unusually complete: it explains return fields, evidence semantics, path substitution, pricing scope, request limits, and the error behavior for an unknown slug. Nothing essential for correct invocation appears to be 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%: the single slug parameter already has a schema description pointing to search_services. The description adds no additional format or syntax details for the slug, 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?
The first sentence states a specific verb and resource: 'Fetch one catalog service by its slug with metadata and a requestShape block.' It distinguishes this discovery tool from pay_service and points to quote_service for live pricing, so an agent can tell it apart 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 gives clear context: discovery only, no payment, and explicitly names quote_service as the alternative for a live fee-inclusive total. It also tells the agent to read payServiceArgs before pay_service, though it does not explicitly contrast with search_services beyond the schema note that the slug comes from there.
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 was observed; flag a non-zero count to the user. This reports numbers of payments, not money: for what has been spent or what is left 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?
No annotations, so the description carries the full burden and does: it discloses that reads are free ('Reading costs nothing'), that an API key must be supplied on the Authorization header, that counts are uncapped unlike list_payments, and what chargedNotDelivered means and implies. This is unusually rich behavioral disclosure for a read tool.
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 what is counted, then the return shape, then the semantic caveat, then routing and auth. Every clause earns its place; nothing is redundant padding.
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 compensates by explaining the three returned fields (total, series with date/value, chargedNotDelivered) plus auth and cost. Nothing needed to call or interpret 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 both parameters (to/from, ISO-8601 inclusive bounds) are fully documented there. The description refers to 'the period' but adds no syntax or format detail 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: 'not money... use get_budget... for amounts per payment use list_payments.' An agent can identify this tool versus 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?
Explicit routing: use get_budget for spend/remaining, list_payments for per-payment amounts, and this tool for counts. It also gives a downstream action rule ('flag a non-zero count to the user'), which is usage guidance beyond mere selection.
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. 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. {"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 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). 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). | |
| headers | No | Extra headers for the vendor call. | |
| 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 provided, the description carries the full behavioral burden and does so: it declares that real funds are charged, explains idempotency and de-duplication semantics, async polling behavior, and per-outcome effects (which errors cost nothing vs. which may have charged). This is far beyond typical behavioral disclosure.
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 is front-loaded and most sentences carry distinct operational weight, but the description is a very dense wall of text with some overlapping idempotency/error discussion (fresh, requestId, already_paid appear across several passages). It is justified by tool complexity but not maximally 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?
For a 10-parameter, no-output-schema payment tool, it covers return value shape (paid, upstreamStatus, response, budget, delegationId), every actionable outcome, and auth requirements. Nothing an agent needs to invoke or interpret it 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 cross-tool meaning the schema cannot: it tells the agent where to source path/method/body values (get_service's requestShape.endpoints[].payServiceArgs), how to substitute pathParams, and how requestId/delegationId feed the derived idempotency key. That context justifies a step above baseline.
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 ('Pay for a catalog service from your spend-capped delegation and return the vendor response'), and the body repeatedly distinguishes this tool from siblings like get_service, get_payment_result, and list_payments. An agent can tell exactly what this does versus the other eleven tools 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 ('Call get_service FIRST'), names alternatives for specific outcomes (use get_payment_result for pending, list_payments for indeterminate), and states exclusions ('Leave fresh off the submit and off any retry of a call whose outcome is unsure'). When-not guidance is as strong as when-to guidance.
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 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 with the same arguments, the quoted delegationId, and maxTotalCents set to that figure as a number, so a price rise between the quote and the call is refused instead of paid (the ceiling is whole cents, so a rise within the same cent is still paid). 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). 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). | |
| 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 discloses that the request really reaches the service (so side-effecting methods execute), that a quote consumes the same per-service rate limit as a payment, that it checks neither budget nor wallet balance, and that the Nevermined API key must be on the Authorization header. It also enumerates every failure outcome (`quote_unavailable`, `quote_failed`, `credential_refused`, `service_not_found`, `catalog_unavailable`, `delegation_lookup_failed`) with retryability semantics.
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 and the no-charge guarantee are front-loaded in the first sentence, and most of the dense remainder (rate-limit warning, delegation semantics, error outcomes, maxTotalCents ceiling) earns its place for a tool this intricate. It loses a point for being a single unscannable wall of text with no line breaks or grouping, when the error-outcome list in particular would read far better as a list.
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 takes on the return contract itself, naming `protocol`, `settlement`, `fee.capChargedCents`/`capChargedMicros`, `paymentRequired`, `upstreamStatus`, `nextTool` and the error codes. Combined with the auth requirement, the no-side-effect caveats and the pay_service handoff, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: it tells the agent to pass exactly what pay_service would receive, explains that `delegationId` selects the priced delegation for API-key callers while OAuth callers are always quoted for the approved grant, and that the result names the delegation actually priced. That is value the schema alone does not convey.
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 precise verb+resource+scope: price ONE service call without paying it, and immediately enumerates what it does not do (charges nothing, signs nothing, reserves no budget). It explicitly distinguishes itself from the `quote` field on a get_service endpoint (stale last-observed price, fee excluded) and from pay_service, so an agent can route correctly 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 names the alternatives and the exact conditions that select them: use this for a live fee-inclusive price, use get_service's `quote` for the last observed price, fall back to pay_service `maxTotalCents` when `quote_unavailable`. It also gives when-not guidance (do not poll, the quote spends the same rate limit as a payment; take care quoting methods with side effects) and the concrete next step including argument mapping to pay_service.
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 and the rankingSource used (semantic or lexical). 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 provided, the description carries the full burden and delivers richly: it discloses deterministic ranking via Nevermined's own signals, a fail-closed payability gate, return fields (chosen, shortlist, rankingSource, result.status, result.payment.status), auth requirements (API key header, delegationId vs OAuth), and exact outcome statuses (no_fundable_match, missing_autopay_fields, payment_indeterminate, already_paid). This is exceptional transparency for a complex payment-routing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then expands into detailed behavior and outcomes. It is dense but every sentence adds needed information for a complex tool with 13 parameters and payment flows. It could be more scannable with structure, but it avoids fluff and earns its length.
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 high complexity, absence of annotations, and no output schema, the description covers return shapes, payment status meanings, failure modes, authentication requirements, and next steps comprehensively. An agent has everything needed to invoke 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 description coverage is 100%, so the schema already documents all 13 parameters in detail. The description largely repeats those semantics (e.g., autoPay requirements, requestId idempotency, delegationId vs OAuth) and adds only limited operational nuance beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.
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+resource: it finds and optionally pays the single best payable catalog service from a plain-language need. It distinguishes itself from siblings by naming search_services and explaining it returns a pick instead of a list. An agent can tell exactly what this tool does 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?
It explicitly says to use it instead of search_services when you want the right service for a task rather than a list to browse. It also distinguishes autoPay:false (pick only, no charge) from autoPay:true (pays and returns the upstream call), and outlines next steps such as get_service on chosen.slug then pay_service.
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. 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. | |
| 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?
No annotations are provided, so the description carries the full burden and does so well: it discloses the hybrid-then-lexical fallback when embeddings are unavailable, the included return fields, and the important limitation that pageToken cannot be passed back so only the first page is reachable.
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 action and ranking behavior, and every sentence carries substantive information. It is somewhat long and repeats a few schema-level facts (pageSize cap), but nothing is 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?
Despite having no output schema, the description names the returned fields and the pagination constraint, and covers auth/payment expectations. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters thoroughly, including the tag/category widening interaction and the protocol enum. The description's parameter notes (query required, pageSize up to 100) largely restate 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 (Search) and resource (Nevermined Agent Services Catalog) and specifies the ranking behavior (hybrid semantic+lexical, relevance-ordered). It explicitly distinguishes itself from the sibling route_by_intent, which handles the opposite selection mode.
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?
Clearly frames this as discovery-only with no payment, and names the alternative route_by_intent for when the platform should pick/pay for a service instead. When-to-use versus alternatives is explicit.
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. 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 provided, the description carries the full behavioral burden and does so thoroughly: reading is free, no on-ramp exists, the wallet cannot be topped up, an API key is required, and null atomic/formatted values mean the read failed rather than a zero balance. It also explains rail-specific behavior, including when BCK.ROUTER.0009 surfaces and when it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and information-dense, with clear sections for what it does, what it does not cover, and rail-specific behavior. It is lengthy for a one-parameter tool, though most sentences earn their place by covering real diagnostic nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description is remarkably complete: it explains return states such as null balances and per-chain error entries, authentication requirements, rail-specific behavior, and stop conditions. An agent has enough context to call and interpret the tool correctly without needing to infer missing semantics.
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%, and the schema explains the network parameter in detail. The description adds operational meaning beyond the schema by stressing that the agent must read the chain the merchant quoted and that a healthy balance on one chain says nothing about another.
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: reading the balances of the agent's own personal wallet, the funding source that pay_service pulls from. It clearly differentiates this wallet from an organization-backed wallet and from card delegations, so an agent can distinguish it from sibling 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?
It explicitly says when to use the tool, including reading before payment on x402 and interpreting pre-checks on MPP. It also states when it does not apply, such as card delegations and organization-backed delegations, and warns that a genuine shortfall is a stop condition rather than something to retry.
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.
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.