Give your AI assistant hands on the eSIMfly Business API. With this Model Context Protocol server, Claude, Cursor, ChatGPT and other MCP clients can search eSIM plans with your wholesale prices, check balances and usage, diagnose "no data" problems from live network data — and, if you enable it, place orders and top-ups with an explicit confirmation step.
Read-only by default. Nothing can spend your balance unless you opt in.
Two-step writes. Every write tool returns a preview (what, cost, balance) until called with confirm: true.
Built on the official @esimfly/sdk — signing, retries and error codes handled.
Ships two prompts: the complete integration guide and an eSIM diagnosis workflow.
Docs: https://docs.esimfly.net · Credentials: Business Dashboard → Settings → API Keys.
The server runs locally over stdio; your API key never leaves your machine.
claude_desktop_config.json → mcpServers:
{
"mcpServers": {
"esimfly": {
"command": "npx",
"args": ["-y", "@esimfly/mcp"],
"env": {
"ESIMFLY_ACCESS_CODE": "esf_...",
"ESIMFLY_SECRET_KEY": "sk_..."
}
}
}
}claude mcp add esimfly -e ESIMFLY_ACCESS_CODE=esf_... -e ESIMFLY_SECRET_KEY=sk_... -- npx -y @esimfly/mcp.cursor/mcp.json (or the client's equivalent):
{
"mcpServers": {
"esimfly": {
"command": "npx",
"args": ["-y", "@esimfly/mcp"],
"env": { "ESIMFLY_ACCESS_CODE": "esf_...", "ESIMFLY_SECRET_KEY": "sk_..." }
}
}
}docker build -t esimfly-mcp .
docker run -i --rm -e ESIMFLY_ACCESS_CODE=esf_... -e ESIMFLY_SECRET_KEY=sk_... esimfly-mcpAdd "ESIMFLY_MCP_ALLOW_WRITES": "true" to env. Without it the ordering, top-up, cancel,
suspend, SMS and webhook tools are not even registered.
Related MCP server: PikaSim
"Find the cheapest 5 GB plan for Turkey and tell me my margin at €9.99."
"Which of my eSIMs are active and below 200 MB?"
"ICCID 8948010010036785060 says no data — diagnose it." (uses the diagnose_esim prompt)
"Set up webhooks for installed / status / low-data events at https://my.app/hooks." (write tool, previews first)
"Build me a Node.js integration." (uses the esimfly_integration_guide prompt)
Tool | What it does | Mode |
| Catalogue search by destination / type with your cost price | read |
| Account (or enterprise) balance | read |
| Your eSIMs with status, data left, validity | read |
| Stored usage for one eSIM (cheap) | read |
| Live status from the network: install state, last network, device, usage | read (expensive) |
| Last 7 days of attach / data-session events, wrong-network flag | read |
| Daily usage by country and operator (up to 90 days) | read |
| Order history and one order with its eSIM | read |
| Top-up options for one eSIM | read |
| Webhook URL, events, recent deliveries | read |
| Buy eSIMs — preview → | write |
| Add data to an eSIM — preview shows package and cost | write |
| Cancel an unused eSIM and refund to balance | write (destructive) |
| Block / restore network access | write |
| Text the device holding the eSIM | write |
| Configure webhook URL and events | write |
Prompts: esimfly_integration_guide (optional stack), diagnose_esim (iccid).
Read-only unless ESIMFLY_MCP_ALLOW_WRITES=true.
Write tools are two-step: a call without confirm returns a preview and makes no mutable API call;
create_order additionally requires the idempotency_key from its own preview, so an agent
cannot place the same order twice.
Tool annotations mark reads as readOnlyHint and cancel/suspend as destructiveHint, so hosts
that ask for user approval on risky tools do so.
The server never logs credentials and never writes to stdout except the MCP protocol.
Give the agent a dedicated API key with the smallest rate limits you are comfortable with, and rotate it from the dashboard if in doubt.
Variable | Required | Description |
| yes | API access code ( |
| yes | API secret key ( |
| no |
|
| no | Override the API base URL |
import { createEsimflyMcpServer } from '@esimfly/mcp';
const server = createEsimflyMcpServer({ config: { accessCode, secretKey }, allowWrites: false });
// connect it to any MCP transportBump version in package.json, server.json and MCP_VERSION in src/server.ts, add a
CHANGELOG entry, push, then publish a GitHub Release tagged vX.Y.Z — the workflow publishes to
npm with Trusted Publishing (OIDC).
Current prepaid balance (or enterprise balance) and currency.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false, so the agent knows this is a safe read. The description adds that it covers both prepaid and enterprise balances, which is useful scoping context. It does not describe what happens when no balance exists or whether a currency conversion applies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the resource and covering both account types and currency. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A zero-param read tool with full annotation coverage; the description tells the agent what comes back (balance and currency) for both account types. No output schema, so naming the returned fields is a plus. Minor gap: no note on account-type selection or empty-state behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline is 4. Nothing more the description could add here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (current prepaid/enterprise balance) plus currency. Clear verb-less resource retrieval is fine for a zero-param getter. Doesn't differentiate from siblings, but none of them share this resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no mention of alternatives. Implied usage from the name only. For a simple read tool this is a minor but real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LIVE status straight from the mobile network: lifecycle status, profile install state, last network (operator, country, MCC/MNC, 4G/5G), device model and IMEI, activation and last-usage dates, data used. Expensive — use for diagnosis ("no data", "is it installed?"), not routinely.
| Name | Required | Description | Default |
|---|---|---|---|
| iccid | Yes | ICCID of the eSIM (19-20 digits) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/openWorld/idempotent/non-destructive, so the safety profile is free. The description adds genuinely new context: the data comes from a live mobile-network query and is expensive, which is a cost/latency trait an agent needs. It could say more about failure modes or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the value proposition front-loaded and the cost caveat at the end where it belongs. The field enumeration is somewhat long but each item maps to real returned data, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations handling safety, 100% schema coverage on the sole parameter, and no output schema, the description's enumeration of returned fields is exactly the compensation needed. An agent has everything required to decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single ICCID parameter is fully documented in the schema (length constraints, format). The description adds no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('get LIVE status straight from the mobile network') and enumerates the returned fields (lifecycle status, install state, last network, IMEI, usage dates, data used). This clearly distinguishes it from list_esims and get_esim_usage, which are not network queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives when-to-use ('diagnosis: "no data", "is it installed?"') and when-not ('not routinely'), plus the cost signal 'Expensive'. Strong guidance, though it doesn't name a cheaper sibling alternative to fall back on.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stored data usage and validity for one eSIM (cheap; fresh as of the last sync). Identify by ICCID or order reference.
| Name | Required | Description | Default |
|---|---|---|---|
| iccid | No | ||
| order_reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new traits not in the annotations — cost profile and data freshness ('fresh as of the last sync') — which shape an agent's decision to call it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with what is returned and scoped by 'one eSIM'. No padding or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema read tool, the description names the returned fields (data usage, validity), the unit of operation, and the identifying keys. Only the interaction between the two optional identifiers and expected return shape details remain unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema alone says nothing about the two params. The description compensates by stating both can identify the eSIM ('by ICCID or order reference') and, via required=false, that neither is mandatory. It does not clarify precedence when both are supplied or expected formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Stored data usage and validity for one eSIM') and pinpoints the identifying key. The word 'Stored' plus sibling name get_esim_live_status makes the boundary clear to an agent without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'cheap; fresh as of the last sync' implicitly signals this cached read as the lightweight choice, but no alternative is named and no when-not condition is given. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach and data-session events for one eSIM, newest first, each flagged is_allowed. wrong_network_count > 0 means the device latched onto a network outside the plan — the usual cause of "connected but no data" (fix: airplane-mode toggle or manual network selection).
| Name | Required | Description | Default |
|---|---|---|---|
| iccid | Yes | ICCID of the eSIM (19-20 digits) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, read-only, idempotent operation. Beyond that, the description adds useful behavioral detail: events are returned newest first, each event carries an is_allowed flag, and wrong_network_count indicates a device attached outside the plan with a suggested fix. It does not cover pagination or rate limits, but it exceeds annotation coverage meaningfully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the event type and ordering. The first sentence is a fragment rather than a complete statement, but the content is not padded or repetitive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description explains the return ordering and a key diagnostic field, which helps the agent interpret results. It omits the 7-day window from the description body, relying on the title, but otherwise covers what is needed to call and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single iccid parameter is already fully documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description name a specific resource, network events, scoped to one eSIM and the last 7 days. It also states the return ordering and a key field, so it is clearly distinct from sibling tools like get_esim_usage or get_esim_live_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides diagnostic meaning for wrong_network_count and mentions remediation, which implies troubleshooting 'connected but no data' scenarios. However, it does not explicitly state when to choose this tool over alternatives such as get_esim_live_status or get_esim_usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One order by reference, including its eSIM (ICCID, install links, pending state).
| Name | Required | Description | Default |
|---|---|---|---|
| order_reference | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful payload context (the response includes the eSIM's ICCID, install links, and pending state), but says nothing about error behavior for an unknown reference or any auth constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core action and resource, with no filler. It is arguably too terse for the tool's needs, but as a structural matter every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with annotations covering the safety profile and no output schema, the description conveys the key return content (eSIM details), which is what the agent most needs. Only the missing-reference/error case and identifier format are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single order_reference parameter, so the description carries the burden: 'by reference' signals that this is an identifier lookup key. That is helpful but thin — no format, example, or validity rules are given to compensate for the undocumented schema field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieve one order, keyed by reference, with the notable side benefit of the attached eSIM data. This is clearly distinct from the plural list_orders sibling. It stops short of naming a sibling explicitly, so it sits just under the top mark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'One order by reference' implies a single-record lookup as opposed to the sibling list_orders, so usage is implied rather than stated. There is no explicit when-to-use, when-not-to-use, or named alternative, leaving the agent to infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top-up options for ONE eSIM (they depend on its provider and location), with your price. Returns ESIM_NOT_TOPPABLE when the eSIM state does not allow top-ups.
| Name | Required | Description | Default |
|---|---|---|---|
| iccid | Yes | ICCID of the eSIM (19-20 digits) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuine value by disclosing the ESIM_NOT_TOPPABLE failure condition tied to eSIM state, which the annotations cannot express. It stops short of describing pagination or the limit parameter's effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, front-loaded with the resource and scope, then the error condition. No wasted words, though the parenthetical could be integrated more cleanly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden; 'with your price' hints at the payload and the error code is given, but list shape, ordering, and how limit affects results are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% — iccid is documented but limit is not. The description says nothing about either parameter beyond 'ONE eSIM', so it fails to compensate for the undocumented limit/cap behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (top-up packages for an eSIM), scopes it to ONE eSIM, and notes the dependency on provider and location. This distinguishes it from catalog-wide siblings like search_packages, though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'ONE eSIM' framing and the provider/location dependency imply when this tool is appropriate versus a broad package search, and the ESIM_NOT_TOPPABLE note signals an eligibility precondition. However, no alternative tool is named and no explicit when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily data usage for one eSIM over the last N days (default 7, max 90) with per-country and per-operator breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| iccid | Yes | ICCID of the eSIM (19-20 digits) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine behavioral context beyond that: the default window, the hard 90-day cap, and the breakdown dimensions returned. It does not mention rate limits or response size, keeping it 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tightly packed sentence with the resource, scope, default/cap, and return granularity front-loaded. Nothing is wasted and nothing important is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description covers the missing parameter constraint and describes the shape of the result (per-country and per-operator breakdown), which is what an agent needs since returns are not otherwise documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: iccid is documented in the schema, but days is not. The description compensates by stating the default (7) and maximum (90) for days, which is exactly the missing semantic. Minor gap in not explaining the ICCID format requirement, though the schema handles that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (daily usage for one eSIM) plus scope and granularity (per-country/per-operator breakdown). It is clear what the tool returns, but it does not differentiate itself from the sibling get_esim_usage, which plausibly overlaps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies operational constraints (default 7 days, max 90) which hint at when it is appropriate, but gives no explicit when-to-use or when-not-to-use guidance relative to get_esim_usage or get_esim_live_status. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configured webhook URL, subscribed events, available events and the last deliveries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds substantive context by disclosing the shape of the response payload (URL, subscriptions, available events, deliveries), which is valuable given there is no output schema. It does not, however, cover auth requirements or behavior when no webhook exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with no filler, front-loading the resource before listing contents. The lack of a verb makes it read as a fragment, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only source of return-value information, and it enumerates four meaningful fields. For a no-parameter, read-only getter this is close to complete; only prerequisites and empty-state behavior are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the specific resource (webhook settings) and enumerates the content it exposes: configured URL, subscribed events, available events, and last deliveries. No sibling tool covers webhooks, so no differentiation is required, but the description is a noun phrase rather than a clear verb+resource statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool, no prerequisites (e.g. whether a webhook must already be configured), and no mention of alternatives. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eSIMs on the account with status, data left and validity. Search by ICCID, package name or code; filter by status.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | Default 20 | |
| search | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so safety is covered. The description adds that each result carries status, remaining data and validity, which is useful, but it says nothing about pagination behavior or result ordering for a paginated endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Roughly two clauses, front-loaded with the resource and what the rows contain, then the search/filter capabilities. Efficient with no wasted words, though the second clause is slightly terse for the amount of behavior it is conveying.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description does well to name status, data left and validity as returned fields. However, for a paginated, 4-parameter listing endpoint it omits pagination semantics, ordering, and how the search/status filters combine, leaving real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (just limit's default of 20), so the description must compensate. It usefully explains that the search term accepts ICCID, package name or code and that status is a filter, but leaves the page parameter entirely undocumented and gives no format hints for status values beyond the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource (eSIMs on the account) and previews the returned fields (status, data left, validity), which is more than a restatement of the name. It does not, however, distinguish this list tool from siblings like get_esim_usage or get_esim_live_status, so an agent must infer which eSIM view to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Search by ICCID, package name or code; filter by status" implies how to use the tool but never states when to choose it over the sibling eSIM/usage tools. Usage is implied rather than contrasted with alternatives, so it clears the minimum-viable bar but no more.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Order history with filters (status, date range ISO 8601, search by reference / package) and a revenue summary.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | Default 20 | |
| search | No | ||
| status | No | ||
| to_date | No | ||
| from_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that a revenue summary is returned, but doesn't mention pagination behavior or default limits beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core action, and compactly lists key features. No wasted words, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema and low parameter coverage, the description covers the main functionality but omits pagination details, default limits, and the exact fields in the revenue summary. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 17%, with only 'limit' having a description (Default 20). The description mentions filters (status, date range ISO 8601, search by reference/package), which helps clarify intended use of parameters, but doesn't fully document all six parameters. Adds some value but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource (list orders) with scope details: filters and a revenue summary. However, it doesn't distinguish itself from the sibling get_order, leaving some ambiguity about listing vs single retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or mention of alternatives like get_order. The description only lists capabilities, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find eSIM data packages you can sell, with your wholesale price. Filter by destination name (search), type (local / regional / global) and page. Returns compact rows; use limit up to 100.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| type | No | ||
| limit | No | Default 20 | |
| search | No | Country or region name, e.g. "Turkey", "Europe" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only a light behavioral note ('returns compact rows', limit cap of 100) and the wholesale-price visibility, without describing pagination end conditions or result volume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences with no filler: the first establishes purpose and value, the second enumerates filters and return shape. Efficient, though the 'use limit up to 100' clause partially repeats an explicit schema constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter, zero-required read tool with full annotation coverage and no output schema, the description gives enough to call it correctly: filters, pagination hint, and return shape. The only gap is the absence of any routing guidance against the sibling package/order tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% — 'search' and 'limit' are documented, but 'page' and 'type' are not. The description compensates by explaining that 'search' is a destination name (local/regional/global type) and that 'limit' can go up to 100, covering most of the documentation gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find eSIM data packages you can sell') and adds a distinguishing scope detail — wholesale pricing — that identifies it as the reseller catalog rather than a consumer lookup. It does not explicitly name or contrast with the sibling get_topup_packages, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (browse sellable packages, filter by destination/type/page) and notes the return shape, but it never states when to prefer this over alternatives such as get_topup_packages, nor any exclusions or prerequisites. Usage is inferable but not specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1get_balanceget_esim_live_statusget_esim_usageget_network_eventsget_orderget_topup_packagesget_usage_reportget_webhook_settingslist_esimslist_orderssearch_packagesScored across 11 tools
Tools are mostly distinct by resource and action. The main potential confusion is among usage-related tools (get_esim_usage, get_esim_live_status, get_usage_report), but their descriptions clearly differentiate stored summary, live network diagnosis, and daily reporting.
All tools use consistent snake_case with predictable verb_noun patterns: get_*, list_*, search_*. The convention is uniform throughout the set.
11 tools is well-scoped for an eSIM reseller management server. Each tool maps to a useful query or monitoring operation without excessive redundancy.
The server covers read/monitoring well: packages, top-ups, eSIMs, usage, orders, balance, and webhook settings. However, it lacks any write/mutation operations such as creating orders, purchasing top-ups, configuring webhooks, or activating eSIMs, which are notable gaps for the domain.
Search, order, and manage eSIM data packages for 190+ countries.
Travel eSIM catalog: search plans, check availability, and get exact quotes with checkout links.
Search, recommend & buy travel eSIM data plans for 190+ destinations via AI agents.
Travel eSIMs: unlimited data, pick your days, top up existing eSIMs, card checkout, no API key.
