Skip to main content
Glama

Get spending budget

get_budget
Read-only

Read the spending budget pay_service spends from: its cap, what has been spent, what remains, how many payments were made (and the limit, if any), and when it expires. Reading costs nothing and charges nothing. Use it whenever the human asks how much is left, or before a run of paid calls. Money is in CENTS: capCents is whole cents; spentCents and remainingCents can carry up to four decimals because the budget is charged per call at 1/10,000 of a cent (e.g. "1.632" = 1.632¢), and spentCents + remainingCents = capCents while the budget is within its cap. Tell the human message as it stands and never substitute a figure of your own: the budget includes routing fees and rounding, so adding up your calls will not match it. With no delegationId it reads the budget pay_service would use; that only includes budgets that can still pay, so {"status":"no_active_delegation"} also covers a budget that ran out or expired — pass the delegationId from an earlier pay_service result to read that one anyway. On a deployment that reports it, spentByDeliveryStatusCents splits the spend by what each payment delivered (delivered, charged_not_delivered, charged_unconfirmed, not_charged, not_delivered, pending, the deliveryStatus values list_payments uses), and unattributedSpentCents is spend no payment record itemizes; a non-zero charged_not_delivered is what was spent on calls that delivered nothing although the merchant charged (the merchant charge plus any routing fee not given back), so tell the human. not_delivered is held for calls the merchant answered with an error: not a confirmed charge; the reserve stays held until reconciliation decides whether the merchant charged after confirmed cancellation or authorization expiry (an older deployment reports it inside pending). lockedInChannels, when present, is money the wallet this budget pays from has deposited into payment channels with merchants that charge per call (per token, as in wallet_balance). It is that WALLET's total, shared by every budget paying from it, not a figure of this budget's own: it is NOT spent and NOT charged to this budget, it can pay further calls only to the merchant holding each channel, and what is unused comes back to that wallet when the channel closes, after 15 minutes without use; message then says so. An empty list means nothing is locked; null means it could not be read, and message then says that too. sessionChannels, when present, is the history behind that: each payment channel this budget used, newest first, with the merchant, its status, what was deposited (deposit, or depositAtomic in raw units when symbol is null), what came back (refund, null until the channel has closed and the refund is confirmed) and openedAt/closedAt. It is what explains money leaving the wallet and coming back when no payment shows it: a payment record carries one call's price, never the deposit. sharedWithOtherBudgets means the wallet's channel also served another budget, so its figures are not this budget's alone, and depositConfirmed: false means the open is not confirmed, so the deposit may not have landed. sessionChannelsTruncated: true means the list holds only the newest channels and older ones exist; message then says so. An empty list means none was used; null means it could not be read, and message then says so. Absent means this reader cannot see them: a budget owned by someone else, or an older deployment. Inventory fields creditsCoverage and creditsCoverageMessage describe public catalog eligibility, even when this caller has no subscription access or credit consent. Relay the message when present; absent means unavailable, never zero. A get_service endpoint carries subscription when credits can pay it. Its estimatedCreditsPerCall is an estimate from the last price seen, since credits follow the service’s live price; quote_service gives the exact credits of a request. When you have a Nevermined Subscription the result also carries subscription (creditsLeft, a digit string of every unexpired credit; resetsAt, when the allowance expires and, unless cancelAtPeriodEnd, the next period's is granted; status, suspended and plan) and subscriptionMessage to relay as it stands; subscription.subscribed: false means none. Whether or not you subscribe, it also carries credits (null: could not be read, which is not the same as none): total, spendable (what can pay a call now), parts (kind allowance | welcome | topup | sla, credits, expiresAt — null never expires — and frozen: null, renewal_overdue for allowance credits frozen until a renewal payment goes through, dispute for every credit while a card dispute holds them) and nextExpiry, with creditsMessage to relay as it stands. Every amount is a digit string. Never count credits yourself. 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": "get_budget"
  }
}

Input Schema

NameRequiredDescriptionDefault
delegationIdNoA specific delegation to read (every paid pay_service result carries one). Omit it to read the budget pay_service spends by default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • removedInput schema / additionalProperties
      Removed value: -false
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only readOnlyHint, while the description adds substantial behavior: reading costs nothing and charges nothing, an API key is required, default delegation selection has caveats, money is in cents with fractional spent/remaining values, and message fields must be relayed as-is. It also documents channel locks, delivery-status spend, and edge cases like no_active_delegation covering exhausted or expired budgets.

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 main purpose and usage guidance are front-loaded, and most of the long output explanation earns its place because there is no output schema. However, the definition is a very dense block with some repetition around 'message then says so' and an out-of-scope aside about get_service.

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 the lack of an output schema and the complexity of budget, credits, subscription, and channel data, the description supplies extensive return-field semantics, units, status meanings, and edge-case behavior. An agent has enough context to invoke the tool and interpret the result correctly.

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

Parameters5/5

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

Schema coverage is 100%, and the single delegationId parameter is already documented, but the description adds important semantics beyond the schema: omitting it reads the default budget pay_service would use, while passing a prior delegationId reads that specific budget even if it can no longer pay.

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: read the spending budget pay_service spends from, and enumerates its cap, spend, remainder, payment count, and expiry. It also distinguishes its role from quote_service for exact request credits and list_payments for deliveryStatus values.

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 says to use it whenever the human asks how much is left or before a run of paid calls. It also explains the default delegation behavior, when to pass a delegationId, and that quote_service gives the exact credits of a request.

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