Skip to main content
Glama

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. To accept a live quote, pass its quoteId before expiresAt with the exact same call arguments; the Router uses that cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling. 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. quote_not_found, quote_expired, and quote_mismatch are named no-charge quote refusals; quote again rather than paying unpinned. {"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, quoteId 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). FUNDING (funding): omit it and the call is paid with your Nevermined Subscription credits when you hold an active subscription and the endpoint carries a subscription tariff (Nevermined pays the merchant; the call costs the tariff in credits, returned if the service does not answer successfully), otherwise from your delegation; pass "subscription" or "delegation" to choose. The credits left in your monthly allowance and the price ceiling are checked only when the call is made: a credits call refused for them (insufficient_credits, subscription_cap_reached, subscription_ceiling_exceeded) charges nothing and is NOT switched to your delegation, so follow its alternative. Every result that mentions funding states which paid it: a subscription call returns funding: "subscription" with creditsCharged and creditsStatus (Committed = spent, Reserved = held or marked for refund, Refunded = returned) and no budget; quoteId, maxTotalCents and delegationId apply only to a delegation. Subscription refusals charge nothing and no credits: subscription_unavailable, no_active_subscription, subscription_not_eligible (see reason), subscription_rail_unsupported, subscription_ceiling_exceeded, insufficient_credits, subscription_cap_reached and subscription_payment_refused; each says in alternative when the delegation can pay instead. funding_undetermined means the funding could not be decided; nothing was charged, so retry. 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).
fundingNoHow to pay: `subscription` (your Nevermined Subscription credits) or `delegation` (your spend-capped delegation). Omit it to use the subscription when you hold an active one and the endpoint carries a subscription tariff, else the delegation; a credits call refused because too few credits are left this month or by the price ceiling is NOT switched to the delegation. The result says which paid.
headersNoExtra headers for the vendor call.
quoteIdNoOpaque short-lived quote id returned by quote_service. Pass it only with the exact same call before expiresAt; the Router then pays the cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling.
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. Changed1 schema field changed
    • addedInput schema / properties / funding
      Added value: +{
      +  "description": "How to pay: `subscription` (your Nevermined Subscription credits) or `delegation` (your spend-capped delegation). Omit it to use the subscription when you hold an active one and the endpoint carries a subscription tariff, else the delegation; a credits call refused because too few credits are left this month or by the price ceiling is NOT switched to the delegation. The result says which paid.",
      +  "enum": [
      +    "subscription",
      +    "delegation"
      +  ],
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / quoteId
      Added value: +{
      +  "description": "Opaque short-lived quote id returned by quote_service. Pass it only with the exact same call before expiresAt; the Router then pays the cached challenge and exact fee-inclusive total. Keep maxTotalCents as an independent ceiling.",
      +  "type": "string"
      +}
  3. 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, the description carries the full burden and does: it discloses that real funds are charged, how idempotency/dedup works (24-hour replay, API 1.48 gate, `already_paid`), the async poll/fresh billing trade-off, the requirement for a Nevermined API key on the Authorization header, and the full funding/precedence logic. It also enumerates no-charge vs charge-possible error outcomes, which is exactly the behavioral context an agent needs before a paid write.

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?

Purpose and the monetary warning are front-loaded, and nearly every sentence carries actionable behavior (error taxonomy, idempotency rules, funding precedence) rather than filler. It is nonetheless very dense and long, and the exhaustive error enumeration could be tightened without losing meaning.

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?

No output schema exists, so the description must describe returns itself — and it does: `paid`, `upstreamStatus`, `response`, `delegationId`, `budget` (with null semantics), `funding`, `creditsCharged`/`creditsStatus`. Combined with the error/outcome taxonomy, an agent has everything needed to call this correctly and interpret the result.

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 already 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning not in the schema: the interplay of `quoteId`/`maxTotalCents`/`delegationId`, the `funding` omit-rules and refusal behavior, and why `fresh` must not be used on an unsure retry. It stops short of 5 only because most per-parameter syntax is duplicated from the schema descriptions.

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?

Opens with a specific verb+resource+payment source: 'Pay for a catalog service from your spend-capped delegation and return the vendor response.' It also immediately signals the destructive/monetary nature ('This charges real funds'), distinguishing it from siblings like quote_service and get_payment_result.

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?

Explicitly routes to alternatives and gives when/when-not rules: call `get_service` FIRST, use `get_payment_result` instead of re-calling pay_service on `pending`, quote again after `quote_not_found`, call `setup_delegation` on `no_delegation`. Prerequisite ordering (get_service → pay_service, quoteId before expiresAt) is spelled out.

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