Build an eSIM plan
build-planBuild an eSIM plan to the traveller's liking for one destination: how much data, for how many days, optionally which network it runs on and whether calls and texts are bundled. Returns the one real plan that matches, with its id and live price, never a made-up combination: a shape nobody sells is snapped to the nearest one that is, one axis at a time, and every change is spelled out in adjustments so you can read it back. Use it when the traveller knows what they want ("10 GB on Docomo for two weeks"); use plan-trip when they want a recommendation or the trip has several countries. To buy, pass plan.id to get-checkout-link when a person is paying, or to create-checkout-session when you are. Read-only: it reserves nothing and charges nothing.
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": {
"country_code": "<country_code>",
"data_mb": "<data_mb>",
"validity_days": "<validity_days>"
},
"name": "build-plan"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| voice | No | Optional. True to require a plan that bundles calls and texts. Defaults to false, data only. If no such plan exists the answer is data only and says so. | |
| data_mb | Yes | Data allowance wanted, in megabytes: 1 GB is 1024 MB, so 5 GB is 5120. Pass 0 for an unlimited plan. Snapped to the nearest size sold when no plan has exactly this size. | |
| network | No | Optional. The mobile network the plan should run on, by carrier name as `options.networks` lists them, e.g. "NTT Docomo" or "au". Matching is case-insensitive and a single carrier of a multi-network plan is enough. Omit for the cheapest network. | |
| currency | No | Optional. ISO 4217 three-letter code the price is quoted in, e.g. "USD", "EUR", "GBP". Defaults to EUR. An unknown code falls back to EUR rather than failing. | |
| country_code | Yes | ISO 3166-1 alpha-2 code of the destination, e.g. "JP". Look it up with list-destinations rather than guessing. | |
| validity_days | Yes | How many days the plan should stay valid, 1 to 365. Snapped to the nearest length sold for the chosen size. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | The plan built: the same shape get-plan returns. Its `id` is what you buy with. Null when nothing was found. | |
| built | Yes | The specification of the plan actually built, after any adjustment. Null when nothing was found. | |
| found | Yes | True when a plan was built. False when the destination sells nothing at all, in which case `plan` is null. | |
| options | Yes | What else could be asked for, so a follow-up question can be answered without another call. | |
| requested | Yes | The specification exactly as it was asked for. | |
| adjustments | Yes | Every way the built plan differs from what was asked, one sentence each, written to be read to the traveller. Empty when the plan matches the request exactly. |