Agentic Kingdoms

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

Input Schema

Name	Required	Description
`sku`	Yes	the pack's sku, from shop_packs
`context`	No	optional short note on why you are buying, kept with the purchase
`sale_id`	No	a limited-time sale id, when buying the pack at a sale price
`sections`	No	optional list of the Snapshot's top-level keys to return with the purchase, overriding snapshot; now is always included
`snapshot`	No	how 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_message`	No	optional message shown with the gift
`x402_payment`	No	an x402 PaymentPayload object, if your client can't put it in _meta["x402/payment"]
`payment_token`	No	a 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_credential`	No	an MPP credential object {challenge, payload}, if your client can't put it in _meta["org.paymentauth/credential"]
`gift_to_account_id`	No	buy the pack as a gift for this account_id (from find_players) instead of for yourself

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already flag destructive and openWorld, but the description adds genuinely non-obvious behavior: an unauthenticated call returns a payment-required isError with dual x402/MPP challenges, and success places the receipt in _meta. It does not warn that a successful retry will charge again (idempotentHint=false), which matters for a real-money mutation.

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?

The purpose is front-loaded, but the remainder is two very dense run-on sentences packing protocol names, header keys, and CLI flags together. Every element is relevant, yet the wall-of-text structure hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, real-money, dual-protocol tool, it covers auth, gift routing, sandbox behavior, the challenge/retry cycle, and receipt locations. Only the sibling-selection guidance for store credit is missing.

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

Parameters3/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 reinforces provenance for sku ('from shop_packs'), gift_to_account_id ('from find_players'), and explains the payment_token/proof arguments' purpose, but adds little beyond what the schema descriptions already say.

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 first sentence names a specific action and resource ('buy a shop pack with real money'), including the self-vs-gift scope, which cleanly separates it from buy_pack_with_store_credit. An agent can identify the tool from the opening clause alone.

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?

It states prerequisites explicitly ('Log in with register or login first (guest accounts can't buy)') and lays out the two-step token/proof flow with the alternative protocols. The one gap is that it never says to use buy_pack_with_store_credit instead when the buyer has store credit, leaving the closest sibling unrouted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Agentic Kingdoms tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?