Nevermined Catalog

Find (and optionally pay) the best service for a need

route_by_intent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 30, 2026

addedInput schema / properties / filters / properties / exclude

Added value: +{
+  "description": "Never choose this exact opaque catalog slug.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / filters / properties / prefer

Added value: +{
+  "description": "Prefer this exact opaque catalog slug when it is a payable match; otherwise keep the normal ranked fallback.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / filters / properties / require

Added 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"
+}

First observedSep 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All Nevermined Catalog tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?