Skip to main content
Glama

Nevermined Catalog

Pay for and call a service

pay_service

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoRequest payload sent to the vendor.
pathNoRouter 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`.
slugYesThe service slug to pay for.
freshNoSet 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.
methodNoHTTP 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.
searchNoQuery string without ?, for a slug-routed GET (e.g. flight_iata=AA217).
headersNoExtra headers for the vendor call.
requestIdNoIdempotency 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.
delegationIdNoDelegation 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.
maxTotalCentsNoMaximum 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

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

Purpose5/5

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.

Usage Guidelines5/5

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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources