Skip to main content
Glama

Buy credits

buy_credits
Idempotent

Add a pack from list_credit_packs to your owner's balance. shared_payment_token pays now using your platform's authorized Stripe token. wallet returns an x402 payment request; retry the same call with the signed payment in params._meta["x402/payment"]. card returns a checkout link; nothing is charged until your human pays. Use one idempotency_key per purchase and reuse it for retries. Requires an agent key. Before buying, explain the benefit, full pack price and payment method to your human. Consider existing credits and free experiences; use only an authorized budget and payment method. See get_retreat_info for full purchase guidance.

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": {
      "pack_id": "<pack_id>",
      "method": "<method>"
    },
    "name": "buy_credits"
  }
}

Input Schema

NameRequiredDescriptionDefault
methodYesshared_payment_token: pay now with a Stripe shared payment token. wallet: pay now with x402 from your authorized wallet. card: a checkout link your human pays.
api_keyNoYour Retreat agent key (rta_...). Optional if sent as an Authorization header.
pack_idYesThe pack to buy, from list_credit_packs, e.g. visit.
idempotency_keyNoOptional. One key per purchase; reuse it for retries. Without one, identical requests within about ten minutes count as the same purchase.
shared_payment_tokenNoFor method shared_payment_token: the spt_... token your platform granted to the Retreat's Stripe Profile, with a limit of at least the pack's price in its currency.

Output Schema

NameRequiredDescriptionDefault
noteNo
methodNoshared_payment_token, wallet or card.
statusNowallet: created, settling, settled, paid or failed. shared_payment_token: paid or pending.
balanceNoOwner credits after purchase.
creditsNoPack size.
creditedNoCredits added to owner balance.
paymentIdNowallet: x402 payment id.
sessionIdNocard: checkout session id.
checkoutUrlNocard: human checkout; opening it charges nothing.
paymentIntentIdNoshared_payment_token: Stripe PaymentIntent id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedOutput schema / properties / balance / description
      Previous value: -"Your owner's credit balance now."New value: +"Owner credits after purchase."
    • changedOutput schema / properties / checkoutUrl / description
      Previous value: -"card: the page where your human pays. Opening it charges nothing by itself."New value: +"card: human checkout; opening it charges nothing."
    • changedOutput schema / properties / credited / description
      Previous value: -"true once the credits are on your owner's balance."New value: +"Credits added to owner balance."
    • changedOutput schema / properties / credits / description
      Previous value: -"Credits in the pack."New value: +"Pack size."
    • removedOutput schema / properties / note / description
      Removed value: -"What happens next."
    • changedOutput schema / properties / paymentId / description
      Previous value: -"wallet: the x402 payment id."New value: +"wallet: x402 payment id."
    • changedOutput schema / properties / paymentIntentId / description
      Previous value: -"shared_payment_token: the Stripe PaymentIntent that paid."New value: +"shared_payment_token: Stripe PaymentIntent id."
    • changedOutput schema / properties / sessionId / description
      Previous value: -"card: the checkout session id."New value: +"card: checkout session id."
  2. Changed7 schema fields changed
    • changedInput schema / properties / method / description
      Previous value: -"card: a checkout link your human pays. wallet: pay now with x402 from your authorized wallet."New value: +"shared_payment_token: pay now with a Stripe shared payment token. wallet: pay now with x402 from your authorized wallet. card: a checkout link your human pays."
    • changedInput schema / properties / method / enum
      Previous value: -[
      -  "card",
      -  "wallet"
      -]New value: +[
      +  "shared_payment_token",
      +  "wallet",
      +  "card"
      +]
    • addedInput schema / properties / shared_payment_token
      Added value: +{
      +  "description": "For method shared_payment_token: the spt_... token your platform granted to the Retreat's Stripe Profile, with a limit of at least the pack's price in its currency.",
      +  "maxLength": 200,
      +  "type": "string"
      +}
    • changedOutput schema / properties / credited / description
      Previous value: -"wallet: true once the credits are on your owner's balance."New value: +"true once the credits are on your owner's balance."
    • changedOutput schema / properties / method / description
      Previous value: -"card or wallet."New value: +"shared_payment_token, wallet or card."
    • addedOutput schema / properties / paymentIntentId
      Added value: +{
      +  "description": "shared_payment_token: the Stripe PaymentIntent that paid.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"wallet: created, settling, settled, paid or failed."New value: +"wallet: created, settling, settled, paid or failed. shared_payment_token: paid or pending."
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare idempotent/non-readOnly/openWorld; the description carries far more: which channels charge immediately vs. never without human action, the x402 retry loop, and the idempotency contract including the ~10-minute fallback window for identical requests. It never contradicts the annotations and materially raises the mutation's predictability.

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?

Front-loaded with what the tool does, then per-method behavior, then safety guidance — a sensible order with no filler sentences. It is dense and somewhat long for a single paragraph, and the human-communication/budget advisory leans slightly toward policy prose rather than invocation info.

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 three-branch payment tool with 5 params, an output schema, and no destructive annotation, everything an agent needs before calling is covered: key requirement, idempotency strategy, the x402 retry handshake, the deferred-charge card path, and where to find full purchase policy.

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; the description earns extra by tying method values to real outcomes and by documenting a mechanism absent from the schema entirely (retrying with a signed payment in params._meta["x402/payment"]). It does not add format or validation detail for pack_id or shared_payment_token beyond what the schema already states.

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 concrete verb + resource + effect: 'Add a pack from list_credit_packs to your owner's balance.' It then distinguishes the three purchase channels by behavior, and names the siblings it defers to (list_credit_packs for selection, get_retreat_info for guidance), so an agent can separate it from every neighboring tool without opening a 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?

Explicit when-to-use per branch: shared_payment_token pays now via Stripe token, wallet returns an x402 request to retry with signed payment, card defers charging until the human pays. It adds preconditions (agent key required, explain price/method to human, check existing credits and free experiences, authorized budget only) and routes deeper policy to get_retreat_info.

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