roamflat Flat configurator

Start secure checkout

start_checkout

Read-onlyIdempotent

Use only once the customer has decided to buy ("I'll take it", "how do I buy?"): the checkout handoff. Returns the buy_url to give the customer, the final price and a ready-to-send checkout block (next_step, payment_methods, delivery) — on the page they press the buy button (buy_button, e.g. "Get your Flat" in English) and pay securely. No account needed; the eSIM is delivered on screen and by email within seconds of payment. No in-chat order tracking, no discount codes. For prices while the customer is still comparing, use quote_flat.

Input Schema

Name	Required	Description
`days`	Yes	Days of mobile data (1–30).
`flat`	No	Optional: which Flat of the country, as get_flats numbers them. Omit = the cheapest Flat that allows the speed.
`mbps`	No	Maximum speed in Mbps (5, 10, 25, 50; default 5). Data is unlimited at that speed. 25 Mbps and up need a 5G network.
`bucket`	No	Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language.
`currency`	No	Optional ISO 4217 override for prices.
`language`	No	ISO language of the conversation, e.g. en, de, ja. Localizes country names and sets the language/currency of links and prices.
`networks`	No	Optional: operator names from get_flats that must be included (the cheapest Flat holding all of them is used). Ignored when flat is given.
`destination`	Yes	Country in ANY language or its ISO code, e.g. "Japan", "Japon", "jp". Map a city to its country first. One country per Flat.

Output Schema

Name	Required	Description
`iso`	No	ISO 3166-1 alpha-2, lower case.
`data`	No
`days`	No	Days booked, counted from the first connection in the destination country.
`flat`	No	Which Flat of the country (1 = cheapest network only; higher numbers include more networks). Pass it back to quote the same Flat.
`name`	No	The Flat's name as the shop shows it: "Flat · Vodafone + O2" or "Flat · all 4 networks".
`note`	No	Present when something about the request had to be adjusted (a step up for the speed, an unknown network) — read it to the customer.
`price`	Yes	FULL price of this configuration in currency — the amount paid. Not per day.
`topup`	No	How the customer adds days to this Flat later (not through the tools).
`has_5g`	No	A 5G network is included.
`starts`	No
`buy_url`	Yes	The roamflat card preset to exactly this configuration. Use verbatim.
`hotspot`	No
`message`	No	A ready-to-send line for the customer.
`currency`	Yes
`delivery`	No	How and when the eSIM arrives.
`networks`	No	Operator names included, as the shop states them.
`next_step`	Yes	What the customer does now: open buy_url, press "Get your Flat", pay.
`buy_button`	No	The label of the buy button on the page, in the language of the customer: name it exactly so.
`speed_mbps`	No	The chosen maximum speed. Data is unlimited at this speed.
`destination`	No	Resolved country name (localized).
`price_basis`	No
`all_networks`	No
`price_per_day`	No	For comparison only. Never multiply it yourself.
`price_is_final`	No
`payment_methods`	No
`networks_unmatched`	No	Present when a requested network does not exist in this country: those names. The quote then uses the Flat listed in networks.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 29, 2026

addedOutput schema / properties / buy_button

Added value: +{
+  "description": "The label of the buy button on the page, in the language of the customer: name it exactly so.",
+  "type": "string"
+}

Changed3 schema fields changedOct 20, 2026

addedOutput schema / properties / networks_unmatched

Added value: +{
+  "description": "Present when a requested network does not exist in this country: those names. The quote then uses the Flat listed in networks.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / note

Added value: +{
+  "description": "Present when something about the request had to be adjusted (a step up for the speed, an unknown network) — read it to the customer.",
+  "type": "string"
+}

addedOutput schema / properties / topup

Added value: +{
+  "additionalProperties": true,
+  "description": "How the customer adds days to this Flat later (not through the tools).",
+  "properties": {
+    "how": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "days"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed5 schema fields changedOct 17, 2026

addedOutput schema / properties / delivery

Added value: +{
+  "description": "How and when the eSIM arrives.",
+  "type": "string"
+}

addedOutput schema / properties / message

Added value: +{
+  "description": "A ready-to-send line for the customer.",
+  "type": "string"
+}

addedOutput schema / properties / next_step

Added value: +{
+  "description": "What the customer does now: open buy_url, press \"Get your Flat\", pay.",
+  "type": "string"
+}

addedOutput schema / properties / payment_methods

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / required

Added value: +[
+  "buy_url",
+  "price",
+  "currency",
+  "next_step"
+]

Changed34 schema fields changedOct 17, 2026

changedInput schema / properties / bucket / description

Previous value: -"Optional language-region bucket the customer shops in, e.g. \"en-gb\", \"de-de\". Wins over language; prices and links are quoted in it."New value: +"Optional language-region bucket the customer shops in, e.g. en-gb, de-de (sets currency and link locale). Defaults from language."

changedInput schema / properties / currency / description

Previous value: -"Optional ISO 4217 code. Every price in the result is quoted in it."New value: +"Optional ISO 4217 override for prices."

changedInput schema / properties / days / description

Previous value: -"Number of days to buy. Must be one of the Flat's durations; omit to buy the duration product_id stands for. When the exact count is not offered, the next longer duration is chosen and reported in days."New value: +"Days of mobile data (1–30)."

addedInput schema / properties / days / maximum
```
Added value: +30
```

addedInput schema / properties / destination

Added value: +{
+  "description": "Country in ANY language or its ISO code, e.g. \"Japan\", \"Japon\", \"jp\". Map a city to its country first. One country per Flat.",
+  "type": "string"
+}

addedInput schema / properties / flat

Added value: +{
+  "description": "Optional: which Flat of the country, as get_flats numbers them. Omit = the cheapest Flat that allows the speed.",
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / language / description

Previous value: -"ISO language of the conversation, e.g. en, de, ja. Titles, labels and country names come back in it when available. Bare \"en\" is quoted in en-us / USD."New value: +"ISO language of the conversation, e.g. en, de, ja. Localizes country names and sets the language/currency of links and prices."

addedInput schema / properties / mbps

Added value: +{
+  "description": "Maximum speed in Mbps (5, 10, 25, 50; default 5). Data is unlimited at that speed. 25 Mbps and up need a 5G network.",
+  "enum": [
+    5,
+    10,
+    25,
+    50
+  ],
+  "type": "integer"
+}

addedInput schema / properties / networks

Added value: +{
+  "description": "Optional: operator names from get_flats that must be included (the cheapest Flat holding all of them is used). Ignored when flat is given.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedInput schema / properties / product_id

Removed value: -{
-  "description": "Product id of the Flat (any of its durations).",
-  "type": "integer"
-}

changedInput schema / required

Previous value: -[
-  "product_id"
-]New value: +[
+  "destination",
+  "days"
+]

addedOutput schema / properties / all_networks
```
Added value: +{
+  "type": "boolean"
+}
```

removedOutput schema / properties / app_links

Removed value: -{
-  "additionalProperties": true,
-  "description": "Store links of the free roamflat app (android, ios) — the Flat works without it.",
-  "type": "object"
-}

changedOutput schema / properties / buy_url / description

Previous value: -"The exact product page to send the customer to. Use verbatim."New value: +"The roamflat card preset to exactly this configuration. Use verbatim."

addedOutput schema / properties / data
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / days / description

Added value: +"Days booked, counted from the first connection in the destination country."

addedOutput schema / properties / destination

Added value: +{
+  "description": "Resolved country name (localized).",
+  "type": "string"
+}

addedOutput schema / properties / flat

Added value: +{
+  "description": "Which Flat of the country (1 = cheapest network only; higher numbers include more networks). Pass it back to quote the same Flat.",
+  "type": "integer"
+}

addedOutput schema / properties / has_5g

Added value: +{
+  "description": "A 5G network is included.",
+  "type": "boolean"
+}

addedOutput schema / properties / hotspot
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / iso

Added value: +{
+  "description": "ISO 3166-1 alpha-2, lower case.",
+  "type": "string"
+}

removedOutput schema / properties / message

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / name

Added value: +{
+  "description": "The Flat's name as the shop shows it: \"Flat · Vodafone + O2\" or \"Flat · all 4 networks\".",
+  "type": "string"
+}

addedOutput schema / properties / networks

Added value: +{
+  "description": "Operator names included, as the shop states them.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedOutput schema / properties / per_day

Removed value: -{
-  "type": "number"
-}

removedOutput schema / properties / presentation
```
Removed value: -{
-  "type": "string"
-}
```

changedOutput schema / properties / price / description

Previous value: -"Same as total."New value: +"FULL price of this configuration in currency — the amount paid. Not per day."

addedOutput schema / properties / price_per_day

Added value: +{
+  "description": "For comparison only. Never multiply it yourself.",
+  "type": "number"
+}

removedOutput schema / properties / pricing_bucket
```
Removed value: -{
-  "type": "string"
-}
```

removedOutput schema / properties / product

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / product_id

Removed value: -{
-  "description": "The product id of the chosen duration.",
-  "type": "integer"
-}

addedOutput schema / properties / speed_mbps

Added value: +{
+  "description": "The chosen maximum speed. Data is unlimited at this speed.",
+  "type": "integer"
+}

addedOutput schema / properties / starts
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / total

Removed value: -{
-  "description": "TOTAL price for the chosen days — the amount paid.",
-  "type": "number"
-}

Changed16 schema fields changedOct 15, 2026

addedInput schema / properties / bucket

Added value: +{
+  "description": "Optional language-region bucket the customer shops in, e.g. \"en-gb\", \"de-de\". Wins over language; prices and links are quoted in it.",
+  "type": "string"
+}

addedInput schema / properties / currency

Added value: +{
+  "description": "Optional ISO 4217 code. Every price in the result is quoted in it.",
+  "type": "string"
+}

addedInput schema / properties / days

Added value: +{
+  "description": "Number of days to buy. Must be one of the Flat's durations; omit to buy the duration product_id stands for. When the exact count is not offered, the next longer duration is chosen and reported in days.",
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / language / description

Previous value: -"ISO language of the conversation. Sets the language/currency of the payment page."New value: +"ISO language of the conversation, e.g. en, de, ja. Titles, labels and country names come back in it when available. Bare \"en\" is quoted in en-us / USD."

changedInput schema / properties / product_id / description

Previous value: -"WooCommerce product id to buy."New value: +"Product id of the Flat (any of its durations)."

addedOutput schema / properties / app_links / additionalProperties
```
Added value: +true
```

changedOutput schema / properties / app_links / description

Previous value: -"Optional links to the free roamflat app (android/ios) for tracking data usage after setup. Mention only when present."New value: +"Store links of the free roamflat app (android, ios) — the Flat works without it."

addedOutput schema / properties / days
```
Added value: +{
+  "type": "integer"
+}
```
addedOutput schema / properties / per_day
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / presentation
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / price / description

Previous value: -"Full fixed price in currency; not per-day."New value: +"Same as total."

addedOutput schema / properties / price_basis

Added value: +{
+  "enum": [
+    "total"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / price_is_final
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / pricing_bucket
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / product_id

Added value: +{
+  "description": "The product id of the chosen duration.",
+  "type": "integer"
+}

addedOutput schema / properties / total

Added value: +{
+  "description": "TOTAL price for the chosen days — the amount paid.",
+  "type": "number"
+}

First observedSep 13, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description explains WHY that is coherent: the purchase happens on the hosted page the customer is handed to, with no account required. It also discloses post-payment behavior (eSIM delivered on screen and by email within seconds) and explicit non-capabilities. Some of that surfaces return-value detail that the output schema already encodes, keeping it just short of a 5.

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 the gating condition, then the return payload, then scope exclusions. Dense but each clause earns its place; the parenthetical enumeration of output fields (next_step, payment_methods, delivery) is mild redundancy against the existing output schema.

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?

With 8 parameters at full schema coverage, rich annotations, and an output schema, the description supplies exactly the missing layer: the conversational moment to invoke, the alternative for pre-decision pricing, and what the agent should do with the result (hand the customer the URL). Nothing needed to call it correctly is absent.

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 description coverage is 100%, including enums, ranges, defaults and cross-references to get_flats, so the schema carries parameter meaning fully. The description itself names no parameters or formats (currency, bucket, flat selection), contributing nothing beyond the structured fields — baseline 3 applies.

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?

Specific verb and resource: 'the checkout handoff' that 'Returns the buy_url to give the customer, the final price and a ready-to-send checkout block'. It also explicitly separates itself from the pricing sibling by naming quote_flat, so an agent can route 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?

Gives both the trigger condition and concrete customer utterances ('I'll take it', 'how do I buy?') and the negative condition ('For prices while the customer is still comparing, use quote_flat'). It adds further exclusions — no in-chat order tracking, no discount codes — so the boundary is unambiguous.

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

All roamflat Flat configurator 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?