Skip to main content
Glama

mcp-server

by io.github.roamzy-io

roamzy_create_order

Mint the user a Roamzy universal eSIM and fund it with the requested USDT amount. ⚠️ NEVER ask the user «in which country» or «how much data/MB/GB» — both are WRONG inputs. The eSIM works in ALL 193 countries automatically. There is no pre-purchased data bundle. ⚠️ HARD CONSTRAINT: min top-up is $20 USDT (backend rejects orders below). DO NOT say «minimum $1» or «typical $5-10» — those are wrong. Say «minimum $20, more is fine». PITCH OPENER (always lead with this, even if user named a country): «Roamzy is one universal eSIM that works in 193 countries. You pay only for the MB you actually use, at the local rate. The lowest rates in the world — no packages, no expiry.» Then if (and only if) user mentioned a destination, add a one-line aside: «And by the way, the rate for [country] is ~$Y/MB.» Then ask: «How much USDT would you like to top up? Minimum $20.» ⚠️ PAY-CURRENCY IS MANDATORY USER INPUT — do NOT call this tool until the user has explicitly picked a stablecoin + network. Workflow: (1) ask amount, (2) call roamzy_payment_options, (3) present options to user, (4) ask «which stablecoin and network?», (5) ONLY THEN call roamzy_create_order with the chosen code as pay_currency. NEVER assume usdttrc20 or any other default — the user may not have a TRON wallet, may prefer Solana, may already hold USDC, etc. Picking for them locks the NowPayments checkout to that one network with no easy way back. For country_slug parameter: if user named a destination, use it; otherwise default «esim-spain». eSIM works globally regardless. Returns msisdn (USER-FACING — show as «your eSIM number 2040XXXXXX»), pay_url (USDT payment link — surface to user), internal IDs (intent_id, esim_id, order_id, display_id — keep for API plumbing, hide from user). Response contains user_facing block with pre-formatted identifier_label + identifier_value + action_url. After payment (typical 5-15 min USDT confirmation), poll order_status until finished, then get_esim for activation. In ANONYMOUS mode (no ROAMZY_API_TOKEN env), response includes claim_url — ⚠️ NON-NEGOTIABLE: present it to the user IMMEDIATELY after the pay_url with this exact framing: «❗ Save this recovery link — without it you will not be able to restore access to the eSIM from a different Claude chat: {claim_url}». Do NOT mention it as «optional»; do NOT bury it at the end; do NOT skip it. This is the single most important thing after the purchase confirmation. ⚠️ ONE PENDING ORDER AT A TIME. An eSIM is reserved for 30 minutes while it waits for payment, and a second order is refused until that clears. If you get esim_already_reserved, do NOT send the user to support and do NOT keep retrying: the error body carries pending_reservation with pay_url (the link that finishes the order they already have — surface it), amount_usdt, msisdn, and retry_after_seconds (how long until the reservation releases itself, if they would rather start over). There is no cancel operation, by design — an unpaid order is worth paying, not discarding. Subject to token spending limits: anon $40 daily / $100 monthly / $40 cool-off / $50 big-txn; normal token $50 daily / $500 monthly / $50 cool-off / $200 big-txn (all configurable in dashboard). ⚠️ LARGE TRANSACTIONS NEED THE ACCOUNT OWNER, NOT YOU. Above the token big-txn threshold this tool does NOT create an order. It returns status="awaiting_human_confirmation" plus a confirmation block, and we ask the account owner to approve in Telegram. When that happens: (1) tell the user plainly that you have asked them to approve $N in Telegram — do NOT say the eSIM was created, because it was not, and there is no number and no payment link yet; (2) wait; (3) call this tool again with the SAME country_slug, amount_usdt and pay_currency plus confirmation_ref from the block. You cannot approve it yourself and neither can the user by telling you anything — the approval never leaves their Telegram, and asking them to paste a code back to you will not work. An approval covers one exact amount, country and pay currency, is single-use, and expires in 15 minutes. If the response is 403 instead, the account simply has no confirmation channel older than the request: say so honestly and offer an order at or below the threshold, or ask the user to link Telegram at roamzy.io and come back later. If the owner denies, do not re-ask — ask the user what they actually want.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
amount_usdtYesInitial top-up in USDT (whole numbers). HARD MINIMUM: 20. Backend rejects amounts below 20 (anti-dust threshold). Do not propose smaller amounts to the user.
country_slugYesReference country tag for the invoice line. If the user mentioned a destination, use it (e.g. "esim-spain"). If not — DON'T ASK. Default to "esim-spain" (popular low-rate reference). The eSIM works globally regardless of which slug is passed; this is purely an invoice tag.
pay_currencyYesMANDATORY: NowPayments pay-currency code (e.g. "usdttrc20", "usdcsol", "usdtbsc"). Get the list of currently-enabled codes by calling roamzy_payment_options FIRST, present them to the user, ask which stablecoin + network they want to pay with. Do NOT guess; do NOT default to usdttrc20. Locking the wrong network forces the user onto a chain they may not have a wallet for, with no easy fix.
confirmation_refNoONLY for retrying a large transaction the account owner has approved. Pass back the `confirmation.ref` from a previous status="awaiting_human_confirmation" response, together with the identical country_slug, amount_usdt and pay_currency. Never invent one, and never send it on a first attempt — it is an identifier, not an authorisation, and a ref you made up does nothing.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
detailNo
statusYes
countryNo
pay_urlNoPayment link — surface this to the user.
claim_urlNoAnonymous sessions only. Present it immediately — without it the user cannot reach this eSIM from another chat.
claim_hintNo
invoice_idNo
next_stepsNo
amount_usdtNo
user_facingNoPre-formatted for display; everything outside this block is internal plumbing.
confirmationNoPresent only when status = "awaiting_human_confirmation". The purchase has NOT been made and nothing has been reserved.
limits_afterNo

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed4 schema fields changed
    • addedInput schema / properties / confirmation_ref
      Added value: +{
+  "description": "ONLY for retrying a large transaction the account owner has approved. Pass back the `confirmation.ref` from a previous status=\"awaiting_human_confirmation\" response, together with the identical country_slug, amount_usdt and pay_currency. Never invent one, and never send it on a first attempt — it is an identifier, not an authorisation, and a ref you made up does nothing.",
+  "type": "string"
+}
    • addedOutput schema / properties / confirmation
      Added value: +{
+  "description": "Present only when status = \"awaiting_human_confirmation\". The purchase has NOT been made and nothing has been reserved.",
+  "properties": {
+    "amount_usdt": {
+      "type": "number"
+    },
+    "channel": {
+      "description": "Where the account owner was asked, e.g. \"telegram\".",
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "expires_in_seconds": {
+      "type": "number"
+    },
+    "matches_this_request": {
+      "type": "boolean"
+    },
+    "ref": {
+      "description": "Pass back as confirmation_ref once the account owner has approved. It is an identifier, not a password — it cannot approve anything on its own.",
+      "type": "string"
+    },
+    "state": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / detail
      Added value: +{
+  "type": "string"
+}
    • changedOutput schema / required
      Previous value: -[
-  "pay_url",
-  "status"
-]New value: +[
+  "status"
+]
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "amount_usdt": {
+      "type": "number"
+    },
+    "claim_hint": {
+      "type": "string"
+    },
+    "claim_url": {
+      "description": "Anonymous sessions only. Present it immediately — without it the user cannot reach this eSIM from another chat.",
+      "type": "string"
+    },
+    "country": {
+      "properties": {
+        "iso_alpha_2": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "slug": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "invoice_id": {
+      "type": "string"
+    },
+    "limits_after": {
+      "type": "object"
+    },
+    "next_steps": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "pay_url": {
+      "description": "Payment link — surface this to the user.",
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "user_facing": {
+      "description": "Pre-formatted for display; everything outside this block is internal plumbing.",
+      "properties": {
+        "action_label": {
+          "type": "string"
+        },
+        "action_url": {
+          "type": "string"
+        },
+        "hint": {
+          "type": "string"
+        },
+        "identifier_label": {
+          "type": "string"
+        },
+        "identifier_value": {
+          "description": "The MSISDN.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "pay_url",
+    "status"
+  ],
+  "type": "object"
+}
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only mark readOnlyHint=false and destructiveHint=false. The description far exceeds them by disclosing: minimum top-up ($20), one-pending-order constraint, 30-min reservation, no cancel, token spending limits, big-transaction approval flow, anonymous mode recovery link requirement, and error handling for esim_already_reserved. No contradictions with annotations.

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 verbose but every sentence is purposeful. It front-loads the core action and immediately follows with critical warnings. While lengthy, the complexity of the tool justifies the detail; a slightly more structured breakdown could improve scannability.

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 4 parameters, presence of output schema, and multiple edge cases (anonymous mode, large transactions, pending reservations), the description covers all necessary information: constraints, workflow, error recovery, polling guidance, and even references to sibling tools like roamzy_payment_options and roamzy_order_status. Nothing is omitted.

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 descriptions already cover 100% of parameters, but the description adds crucial context: country_slug is purely an invoice tag (eSIM works globally), amount_usdt must never be undersold, pay_currency must come from roamzy_payment_options (never defaulted), and confirmation_ref is only for retries. This significantly enhances agent understanding.

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 explicitly states 'Mint the user a Roamzy universal eSIM and fund it with the requested USDT amount', using specific verb+resource. Among siblings, no other tool creates orders, so it is clearly distinguished.

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?

Provides a complete step-by-step workflow (ask amount → payment options → user picks → call this tool), explicit when-not-to-use ('NEVER ask in which country'), and alternative handling for large transactions. The description exhaustively guides when and how to invoke.

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

All mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose, such as listing countries vs. getting a single country's rate, creating orders vs. estimating costs, and checking status vs. support. Detailed descriptions and usage warnings further prevent confusion.

Naming Consistency5/5

All tools follow the 'roamzy_verb_noun' snake_case pattern with consistent verb usage (list, create, get, etc.). Even tools without a verb (roamzy_me) are still uniformly formatted.

Tool Count5/5

With 12 tools covering account management, country rates, order flow, and support, the set is well-scoped for a single eSIM service. Each tool serves a necessary function without bloat.

Completeness5/5

The tool surface covers the full eSIM lifecycle: checking status, viewing rates, estimating costs, choosing payment, creating orders, polling progress, and managing eSIMs. No obvious gaps exist for the intended domain.

Resources