Quartermaster eSIM

Purchase a quoted plan

purchase

Idempotent

Buy the plan in a quote and receive the eSIM. Use it after get_quote, before the quote expires and only when mandate_precheck allows it. Returns the order (status, and the eSIM delivery payload with the activation code or QR/LPA) and a signed receipt, and debits the principal's USD wallet. Example: {quote_id: "qt_...", idempotency_key: ""}. Details: it enforces the mandate and the wallet policy, holds the amount in the principal's wallet, orders from the supplier, debits the wallet, and returns the order with the eSIM delivery payload and a signed receipt. If the wallet is short, fails with WALLET_INSUFFICIENT_FUNDS and a ready top-up link for the principal. idempotency_key is required: reusing it returns the original order and never charges twice; while the original call is still running it answers ORDER_IN_PROGRESS (retryable, retry_after_seconds, order_id: repeat the same call later or poll order_status). QUOTE_PRICE_CHANGED (retryable): the plan's price went up since the quote (error.details.quoted_price and current_price); nothing was held or charged, get a new quote. If the supplier's answer is unknown (timeout, network error), the order stays "processing" with supplier_outcome "unknown" and the price held, not debited: poll order_status and do not buy again with a new key. Only SUPPLIER_FAILURE with retryable=true calls for a new quote and key. PRINCIPAL_FROZEN (not retryable): a top-up was reversed after its credit was spent, or the operator froze the principal; get_topup_link still works and the next credit settles the debt first.

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": {
      "quote_id": "<quote_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "purchase"
  }
}

Input Schema

Name	Required	Description
`agent_id`	No	Your agent id (or X-Agent-Id header)
`quote_id`	Yes	quote_id from get_quote (quote.quote_id); one quote buys once and expires at quote.expires_at
`agent_key`	No	Secret returned by register_agent (or X-Agent-Key header)
`principal_id`	No	The principal you act for (or X-Principal-Id header)
`idempotency_key`	Yes	Unique per purchase attempt, 8-128 characters, for example a UUID; repeat the same value only to retry that same attempt

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 9, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Unique per purchase attempt, e.g. a UUID"New value: +"Unique per purchase attempt, 8-128 characters, for example a UUID; repeat the same value only to retry that same attempt"

addedInput schema / properties / quote_id / description

Added value: +"quote_id from get_quote (quote.quote_id); one quote buys once and expires at quote.expires_at"

Changed4 schema fields changedNov 4, 2026
- addedInput schema / properties / agent_id / pattern
```
Added value: +"^[A-Za-z0-9._:-]{3,128}$"
```
- addedInput schema / properties / agent_key / maxLength
```
Added value: +256
```
- addedInput schema / properties / principal_id / pattern
```
Added value: +"^[A-Za-z0-9._:@-]{3,128}$"
```
- addedInput schema / properties / quote_id / maxLength
```
Added value: +128
```
First observedNov 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations, it discloses the full financial and supplier side effects: wallet hold, supplier order, wallet debit, signed receipt, idempotent retry behavior, and specific error handling such as WALLET_INSUFFICIENT_FUNDS, QUOTE_PRICE_CHANGED, ORDER_IN_PROGRESS, and PRINCIPAL_FROZEN. This is unusually complete for a mutating financial operation.

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 description is front-loaded with the core action and usage, then organized into returns, mechanics, and error behavior. It is dense and slightly repetitive in the 'Details' section, but nearly every sentence carries operational value for this complex purchase flow.

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 complex, side-effect-heavy financial purchase with no output schema, the description covers when to call it, what it returns, what it charges, idempotency guarantees, and how to interpret the main failure modes. An agent has enough information to invoke it correctly and recover from common errors.

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 schema already documents all five parameters. The description still adds meaningful semantics beyond the schema by explaining that quote_id buys once and expires, and that idempotency_key must be unique per attempt and reused only for retries of the same attempt.

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 description states a specific verb and resource: buying the plan in a quote and receiving the eSIM. It clearly distinguishes the tool from get_quote by saying it runs after get_quote and from order_status by directing polling there for uncertain outcomes.

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?

It gives explicit prerequisites and timing: after get_quote, before expiration, and only when mandate_precheck allows it. It also names alternatives and conditions for retrying, polling order_status, or getting a new quote.

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

All Quartermaster eSIM 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.