esimfly-mcp

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

The description discloses the two-step confirm behavior ('confirm: true to execute'), which is valuable beyond the annotations. It also clarifies the effect (restoring network access) and the dependency on prior suspension. Annotations already mark it as mutating but not destructive, so no contradiction 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?

Two short sentences deliver purpose, prerequisite, and execution flow without any filler. The most important information is front-loaded, and every sentence 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 tool with only two parameters and no output schema, the description is sufficiently complete: it names the prerequisite, the intended action, and the confirmation step. Minor details such as response format or behavior if already active are absent, but they are not critical for selecting or invoking the tool 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 description coverage is 100%, and the description only restates the confirm behavior already present in the schema. It adds no additional meaning about the iccid parameter beyond what the schema provides, so the baseline score of 3 is 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?

States a specific verb and resource ('Restore network access') and ties the action to its prerequisite state ('after suspend_esim'). The title and description clearly distinguish it from siblings like suspend_esim and cancel_esim by situating it in the suspend/reactivate lifecycle.

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 explicitly provides the context for use: only after suspend_esim. It does not list exclusions such as 'do not use for canceled eSIMs', but the lifecycle framing makes the appropriate use case clear enough for an agent to select it over the listed siblings.

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

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

Annotations already mark the tool as destructive and not read-only. The description adds valuable context: it cancels all eligible eSIMs in the same order and requires a confirm step. This goes beyond the structured annotations without contradicting them.

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?

Three short sentences, each carrying distinct information: what is cancelled, eligibility/refund, bulk behavior, and the confirmation step. No filler or redundancy.

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?

Adequately covers the core behaviors: eligibility, refund, bulk scope, and two-step confirmation. Given there is no output schema, slightly more detail about post-cancellation effects or order could improve completeness, but it is largely sufficient.

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 already describes iccid and confirm (including preview vs. execute). The description restates the confirm behavior but adds no new parameter-level detail beyond what the schema provides.

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 description clearly states the tool cancels eSIMs that have never been installed/activated and refunds to balance. It includes the bulk behavior ('Cancels EVERY eligible eSIM') and a two-step execution, making it easily distinguishable from siblings like suspend_esim or activate_esim.

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 gives a clear eligibility condition: use for eSIMs never installed or activated. It does not explicitly name alternatives or exclusions (e.g., 'for active eSIMs use suspend_esim'), but the condition is specific enough to guide selection.

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

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

Annotations indicate a write operation (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds the two-step execution model and the balance-spending aspect, which are not captured in annotations. It also includes the user-facing instruction to disclose cost, which is a behavioral requirement beyond the structured data.

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 two sentences, tightly packed with essential information: the action, the two-step flow, and the cost disclosure requirement. No filler or redundancy, and the critical steps are front-loaded.

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 write operation with no output schema, the description explains the essential flow, the required idempotency_key, and the cost disclosure. It does not cover error handling or return values, but those are less critical for invocation. The sibling context is clear, and the tool can be used correctly based on this description.

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 schema covers 75% of parameters, with confirm and idempotency_key already documented. The description adds the relationship between these two (preview then confirm with the key), which is helpful but not extensive. Quantity and package_code are adequately covered by the schema. Overall, the description complements the schema without over-explaining.

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 description clearly states the action: 'Buy one or more eSIMs of a package from the account balance.' This is a specific verb (buy) + resource (eSIMs) + context (from balance), and it distinguishes the tool from siblings like topup_esim (topping up an existing eSIM) and search_packages (finding packages).

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 explicitly outlines the two-step process: first call returns a preview with idempotency_key, then call again with confirm:true and that key to execute. It also instructs to tell the user the cost before confirming. This gives clear sequencing and prerequisites, leaving no ambiguity about how to use the tool.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already indicate the tool is not read-only and not idempotent. The description adds the two-step confirmation behavior (confirm: true to send) and the 500-character limit, which are not captured by annotations. It does not contradict annotations and provides useful behavioral context beyond the structured fields.

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 two short sentences with no redundant words. It front-loads the primary action and then adds the critical two-step detail. Every sentence 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 send operation, the description is mostly complete but lacks any information about the response format or error conditions (no output schema). The two-step nature is only partially explained; the schema provides the 'preview' detail, but the description does not. Given the simplicity, it is adequate but has 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 67%: iccid and confirm have descriptions, while message only has maxLength. The description repeats the 500-character limit (already in schema) and mentions confirm: true to send (also in schema). It adds no new semantic meaning beyond the schema, so a baseline score of 3 is 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 description clearly states the action: sending a text to the device holding an eSIM. It specifies the resource (eSIM) and the verb (send), and distinguishes from all sibling tools (e.g., topup_esim, suspend_esim) which perform different operations. The max length detail adds precision.

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 when to use the tool (to send an SMS to an eSIM) but provides no explicit guidance on when not to use it or which alternative to choose. There is no mention of prerequisites like an active eSIM or contrast with other messaging tools. The usage is clear from context but not explicitly stated.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description adds critical behavioral details: the response contains the signing secret shown only once, and the operation requires a two-step confirmation. This is valuable context not captured by annotations. It does not describe side effects like whether old webhooks are invalidated, but the disclosed information is substantial.

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 concise (two sentences) and front-loaded with the primary action. The first sentence states the purpose and key output, and the second explains the confirmation step. Every sentence adds value without redundancy.

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 tool with 3 parameters, one required, and no output schema, the description covers essential behavior: it explains the two-step confirmation, the one-time secret, and the core action. It does not describe the exact response structure beyond the secret, nor the full set of events (though the schema provides enums). Given the moderate complexity, the description is mostly complete but could benefit from noting what happens on rotation.

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 33% (only 'confirm' is described in the schema). The description does not elaborate on 'webhook_url' or 'events', nor does it provide additional semantics for them. The mention of 'configure' and 'two-step' partially reinforces the confirm parameter but adds little beyond the schema. Given the low coverage, the description fails to compensate for the undocumented parameters.

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 description clearly states the tool's purpose: configure or rotate the webhook URL and subscribed events. It uses a specific verb 'configure' with a clear resource, and distinguishes itself from the sibling 'get_webhook_settings' by implying a write operation. The mention of 'Two-step: confirm: true to apply' further clarifies the action.

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 context by contrasting 'configure' with the likely read-only sibling 'get_webhook_settings', and explicitly instructs on the two-step confirmation process. However, it does not explicitly state 'use this when you need to change webhook settings' or mention alternatives, so it stops short of full guidance.

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

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

Annotations already cover destructiveHint=true and readOnlyHint=false, so the mutation is already clear. The description adds valuable behavior beyond annotations: the operation is reversible and requires a two-step confirm ('Two-step: confirm: true to execute'). No contradiction with annotations is present.

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 sentences with no filler. The core action is front-loaded ('Block network access'), followed by the key behaviors (reversibility and confirmation requirement). Every phrase 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 two-parameter mutation tool with strong annotations and full schema coverage, the description covers the essential behavior: what it does, that it is reversible, and that confirmation is required to execute. No output schema exists, so return-value explanation is not needed.

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 parameters are already fully documented in structured form. The description's mention of 'confirm: true to execute' largely echoes the schema's own parameter description and does not add new semantic meaning beyond what the schema provides.

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 description states a specific verb and resource: 'Block network access for an eSIMfly-network eSIM'. It also distinguishes itself from the sibling activate_esim by noting the operation is 'reversible with activate_esim', so an agent can tell suspension apart from activation or cancellation.

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 clearly implies when to use the tool: when network access needs to be blocked for an eSIM. It provides context about the two-step confirm flow and points to activate_esim as the reversal path, though it does not explicitly list exclusions or contrast with cancel_esim.

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

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

Annotations show this is a mutating, non-idempotent operation, and the description adds genuinely useful behavioral detail by revealing the two-step behavior: omitting confirm returns a preview with package name, cost, and balance, while confirm=true executes. It doesn't cover post-execution details, but it adds meaningful context beyond the annotations.

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-loaded: one sentence defines the core action, and the next sentence conveys the two-step mechanics with no filler or redundant restatement.

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 three-parameter tool with full schema coverage and no output schema, the description covers the essential usage flow and the preview return. It omits what the execution step returns and doesn't explicitly point to get_topup_packages in the description, but the schema covers that dependency, so the context is largely complete.

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 baseline is already 3. The description goes slightly beyond the schema by explaining the behavioral difference between omitting confirm and passing true, which adds semantic value for the confirm parameter beyond the schema text.

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 description states a specific action ('Add a package to an existing eSIM') and the title adds 'spends balance,' which distinguishes it from activation, cancellation, or suspension. It doesn't explicitly name a sibling alternative, so it stops short of a 5.

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 when to use it: to add a package to an existing eSIM, and the two-step flow is explained. However, it never explicitly contrasts it with siblings like get_topup_packages or create_order, so usage guidance is largely implicit.

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