Skip to main content
Glama

Buy a pack (real money)

buy_pack
Destructive

Buy a shop pack with real money, for yourself or as a gift (gift_to_account_id, from find_players; a gift arrives 3 days after payment). Log in with register or login first (guest accounts can't buy). By card, the simple way: get a card token (spt_...) for the pack's charge_cents and shop_packs' payment.card.network_id from your owner's Stripe Link agent wallet (link-cli spend-request create --credential-type shared_payment_token), or from sandbox_payment_token when the server is a sandbox, and call buy_pack {sku, payment_token}. Without a proof the call returns a payment-required result (isError) that offers two protocols at once: x402 (USDC on Base) in the result itself (x402Version, accepts), and MPP (Machine Payments Protocol: a card or USDC on Tempo) as challenges in _meta["org.paymentauth/payment-required"]. Pay one and call buy_pack again with the same arguments plus the proof: an x402 PaymentPayload in _meta["x402/payment"] or x402_payment, or an MPP credential in _meta["org.paymentauth/credential"] or mpp_credential. On success the pack is in your kingdom and the receipt is in _meta ("x402/payment-response" or "org.paymentauth/receipt") and in the result's payment field.

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": {
      "sku": "<sku>"
    },
    "name": "buy_pack"
  }
}

Input Schema

NameRequiredDescriptionDefault
skuYesthe pack's sku, from shop_packs
tokenNothe token your login returned; pass it when a call answered not_logged_in after you logged in
contextNooptional short note on why you are buying, kept with the purchase
sale_idNoa limited-time sale id, when buying the pack at a sale price
sectionsNooptional list of the Snapshot's top-level keys to return with the purchase, overriding snapshot; now is always included
snapshotNohow much of the Snapshot to return after the purchase: none (default) no snapshot; changes only what the purchase changed (diamonds, items), in a changes field; city only now, config_hash, map_size, player, city, marches, rallies and notices; full the whole Snapshot
gift_messageNooptional message shown with the gift
x402_paymentNoan x402 PaymentPayload object, if your client can't put it in _meta["x402/payment"]
payment_tokenNoa card token (spt_...) for this purchase: from your owner's Stripe Link agent wallet, or from sandbox_payment_token in a sandbox. Pays in one call.
mpp_credentialNoan MPP credential object {challenge, payload}, if your client can't put it in _meta["org.paymentauth/credential"]
gift_to_account_idNobuy the pack as a gift for this account_id (from find_players) instead of for yourself

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / token
      Added value: +{
      +  "description": "the token your login returned; pass it when a call answered not_logged_in after you logged in",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare destructive/openWorld/non-idempotent; the description goes far beyond by disclosing that real money moves, that gifts arrive 3 days after payment, that the proof is a payment token or an x402/MPP credential, and exactly where the receipt lands (_meta and the payment result field). It also explains the failure surface (payment-required isError result carries two protocol offers), which no annotation conveys.

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

Conciseness3/5

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

Purpose and gifting are front-loaded correctly, but the payment protocol detail is packed into one very long run-on paragraph mixing CLI flags, _meta keys, and protocol names, which makes it hard to scan mid-call. Nearly every clause is load-bearing, yet the density and lack of segmentation cost it readability.

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 real-money, 11-parameter, destructive tool with nested objects, the description covers preconditions, both payment protocols, the retry loop, gift timing, and receipt location; an output schema exists so return values need no further explanation. Nothing an agent needs to complete a purchase correctly appears to be 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; the description still adds provenance the schema lacks, e.g. that gift_to_account_id comes from find_players, that payment_token is an spt_ token tied to the pack's charge_cents and card network_id from shop_packs, and that x402_payment/mpp_credential exist as fallbacks when _meta can't be set. It does not add much for sku, context, sale_id, or sections, which is a minor gap.

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 and resource ('Buy a shop pack with real money') and immediately scopes the two modes: for yourself or as a gift via gift_to_account_id. The 'real money' framing implicitly separates it from the sibling buy_pack_with_store_credit, and the gift variant is distinguished from gift_pack/gift_code_pack by the account_id mechanism.

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

Usage Guidelines4/5

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

States the prerequisite chain explicitly ('Log in with register or login first (guest accounts can't buy)') and the retry condition for the not_logged_in path. It gives a concrete when-to-use branch (no proof → payment-required result → pay → retry with proof). It stops short of naming buy_pack_with_store_credit as the alternative when the agent has credit, leaving that inference to the agent.

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