Nevermined Catalog

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

route_by_intent

Destructive

Given a plain-language description of what you need, find, and optionally pay in the same call, the single best payable catalog service, so you do not have to pick among listings yourself. Use it instead of search_services when you want the right service for a task rather than a list to browse: it ranks candidates on Nevermined's own relevance and quality signals (deterministic; no model reads the merchant listings), applies a fail-closed payability gate (listed, healthy, moderated, x402/mpp, not flagged unpayable), and returns the winner as chosen (with its opaque invoke handle, never a raw host) plus a ranked shortlist; every shortlist item carries a closed matchReason, gateReason, per-item rankingSource, and one scale-specific score. With autoPay:false (the default) it returns the pick only and charges nothing; the next step is normally get_service on chosen.slug, then pay_service with the endpoint you need. With autoPay:true it also pays the winner through the same path as pay_service and returns the upstream call in result: result.status and result.body are the vendor's answer, and result.paid: true means a payment was attempted, not that it settled, so read result.payment.status (Settled, Issued or Failed). autoPay calls the winner at its base URL plus any path you pass, and you only learn the winner from this call, so it suits single-endpoint services; a multi-endpoint winner typically answers 404 at its base URL. autoPay requires requestId; an API-key caller must also pass delegationId, while an OAuth-connected caller spends from the grant it approved and needs none. Outcomes: no listed, payable match → {"status":"no_fundable_match"} (broaden the intent or filters; nothing charged), never a wrong pick; missing_autopay_fields (nothing charged); on autoPay, payment_indeterminate (check list_payments, and retry only with the same requestId) and already_paid (this requestId already carries a payment, see paymentId; nothing new billed, and it does not by itself say whether the original succeeded). Every pick and each of these outcomes carries an instructions string with the next step; a payment the Router declines on autoPay comes back as a tool error carrying the API's message. Requires your Nevermined API key on the Authorization header.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "intent": "<intent>"
    },
    "name": "route_by_intent"
  }
}

Input 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.

Changed4 schema fields changedOct 21, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / filters / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / headers / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
- addedInput schema / properties / maxTotalCents / maximum
```
Added value: +9007199254740991
```

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?

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes far beyond that by disclosing exactly what can be destroyed (money) and under which conditions (autoPay:true, gated by maxTotalCents and a fail-closed payability gate). It spells out idempotency semantics (requestId required, retry only with the same requestId), the difference between 'payment attempted' and 'settled' via result.payment.status, and the auth requirement (API key on the Authorization header, delegationId for API-key callers).

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

Conciseness4/5

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

It is front-loaded: purpose, the sibling contrast, and the two modes come before the outcome enumeration, and nearly every sentence carries non-redundant information (gates, failure codes, next steps). The cost is density — several sentences are long multi-clause run-ons that an agent must parse carefully, which keeps it out of 5 territory.

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

Completeness5/5

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

For a 13-parameter tool with a nested filters object, no output schema, and a destructive payment path, the description covers the outcome space explicitly: no_fundable_match, missing_autopay_fields, payment_indeterminate, already_paid, and router-declined payments, each with a note on whether money moved. It also states that every response carries an instructions string, closing the loop on what to do next.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning on top: autoPay's charge/no-charge consequences, why requestId matters for idempotent retries, and the delegationId distinction between API-key and OAuth callers. It does not explain path/method/search/headers beyond what the schema already says, which is why it stops short of 5.

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

Purpose5/5

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

The first sentence states a specific verb and resource ('find, and optionally pay... the single best payable catalog service') plus the scope constraint ('so you do not have to pick among listings yourself'). It immediately contrasts itself with the sibling search_services, so an agent can route between browsing and selecting without opening either schema.

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

Usage Guidelines5/5

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

It gives an explicit selection rule ('use it instead of search_services when you want the right service for a task rather than a list to browse') and a second decision rule for autoPay true vs false, naming the default and the normal follow-up path (get_service on chosen.slug, then pay_service). It also names when autoPay is a poor fit: single-endpoint vs multi-endpoint winners that 404 at their base URL.

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

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?