Nevermined Catalog

Set up a spending delegation

setup_delegation

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "setup_delegation"
  }
}

Input Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 21, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
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 annotations only providing readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: it returns a single URL with a short-lived session token that must be treated as sensitive, requires a Nevermined API key on the Authorization header, explains that the human sets parameters in the browser, and enumerates the distinct response statuses and their meanings. It also discloses that other outcomes produce no URL.

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

Conciseness4/5

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

The description is long and dense, but it is front-loaded with the purpose and trigger, then proceeds through outcomes and prerequisites in a logical order. Each sentence carries operational detail, though the volume of outcome handling could have been formatted more scannably.

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

Completeness5/5

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

For a complex setup tool with no output schema, one optional parameter, and only minimal annotations, the description compensates by explaining return statuses, the URL relay workflow, the already_active path, failure modes, and the required auth header. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100% and the single optional parameter returnUrl is documented thoroughly in the schema, so the baseline is 3. The description adds meaningful semantics beyond the schema: it invokes returnUrl again in the 'return_url_not_allowed' outcome and clarifies that currency, spending cap, duration and transaction limit are not parameters and must not be solicited from the human.

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

Purpose5/5

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

The description states a specific verb and resource — 'Start the spending-delegation ceremony and return ONE URL for a human to open' — and immediately distinguishes it from pay_service by naming the exact error state it resolves ('no_delegation') and clarifying it does not enroll a card or create a card delegation. An agent can identify it from siblings without opening any schema.

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

Usage Guidelines5/5

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

It gives explicit trigger conditions ('Use this when pay_service returns {"error":"no_delegation"}'), describes the negative case ('already_active' means nobody needs to do anything, just call pay_service), and routes the caller to the correct next action for each outcome. It also tells the agent what not to do (must not ask the human for currency, cap, duration, transaction limit).

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

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?