mcp-server

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: rates are reference info only, not a purchase gate, and the eSIM works in all 193 countries. This goes beyond the 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?

Four sentences, front-loaded with 'Reference info' and a clear purpose. Each sentence adds meaningful guidance (when to call, when not to call, why not). Slightly longer than the minimal two-sentence ideal, but every part 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 single-parameter read-only lookup with an output schema, the description fully covers purpose, usage constraints, and context. No significant gaps remain for an AI agent to invoke it 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% with a clear description of country_slug ('Country slug, e.g. "esim-spain". Reference lookup only.'). The tool description reinforces the reference nature but does not add new parameter-level details, so the baseline of 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?

The description clearly states the tool provides 'the per-MB rate for a specific country.' It explicitly positions it as reference info, distinguishing it from purchase-related siblings like roamzy_create_order. The example about 'how much in Japan?' reinforces the exact purpose.

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 instructs to call 'ONLY if the user explicitly asks about price for their destination' and includes a strong exclusion: 'DO NOT call this during purchase.' This leaves no ambiguity about when to use this tool versus alternatives.

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Mint the user a Roamzy universal eSIM and fund it with the requested USDT amount', using specific verb+resource. Among siblings, no other tool creates orders, so it is clearly distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about the tool being purely informational and warns against using it for purchase gating, which goes beyond the annotation hints.

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 with no filler. The first sentence states purpose, the second gives usage context, and the third provides a clear exclusion. Highly efficient.

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?

Given the tool's simplicity, two well-documented parameters, and an output schema, the description fully covers purpose, usage boundaries, and business logic. No gaps identified.

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 baseline is 3. The description reinforces the reference-only nature of the parameters but does not add significant detail beyond the schema.

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 identifies the tool as a reference calculation for converting MB volume to USDT cost at a given country's rate. It distinguishes from siblings by emphasizing it is informational only, not for order creation or management.

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 states when to use ('how much would 2GB in Japan cost' queries) and when not to use ('DON'T use this to gate a purchase'), with a clear explanation of the funding model.

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 readOnly and non-destructive. The description goes far beyond by disclosing that the tool does not return a ready-to-display image but a raw payload that must be rendered locally, warning against external QR services, and detailing privacy rules about not showing internal IDs. It also documents the anon-mode recovery obligation, adding valuable behavioral context.

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 front-loaded with the tool's purpose, then uses clearly separated sections for QR rendering and anon-mode recovery. It is verbose but each section serves a functional purpose. The emphatic warnings and emoji use slightly reduce elegance, but the structure earns a high score.

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?

Given an output schema exists and the description covers return fields, activation details, user privacy, and exception handling (support contact), it is nearly exhaustive for this tool's context. It addresses all foreseeable user follow-ups and platform quirks.

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 only parameter esim_id is fully described in the input schema with the same text about being an internal ULID and never shown to the user. The tool description adds no new parameter detail beyond what the schema already provides, so the baseline of 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?

The description opens with a specific verb 'Get a specific eSIM by id' and enumerates returned fields (msisdn, status, balance, activation block). This clearly distinguishes it from siblings like list_esims (which returns a collection) and create_order (which creates a new 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?

The description implies when to use this tool: whenever a single eSIM's details are needed by ID. It also gives conditional usage guidance for anonymous sessions and recovery flows, including when to call roamzy_support. However, it does not explicitly name alternatives or state 'use this instead of X'.

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. The description adds context that this is a reference rate card, not a product catalog, and should not be volunteered during purchase. This complements the 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?

The description is two sentences, front-loaded with the primary function, and each sentence adds distinct useful information. No wasted words.

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 zero-parameter, read-only list with an output schema and strong annotations, the description is complete. It covers purpose, usage constraints, and context, leaving no critical information missing.

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 has zero parameters, so the description has no parameter documentation burden. Baseline 4 applies because schema coverage is trivially 100%.

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 it lists all 193 countries with per-MB rates in USDT, a specific verb and resource. It distinguishes itself from a product catalog and the purchase flow, aligning with sibling tools like roamzy_country_detail.

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 states when to call ('only if the user asks «what countries are supported» or «show me rates»') and when not to call ('don't volunteer it during a purchase flow'). It does not name alternative tools directly, but the when-not clause provides strong 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?

The annotations already declare readOnlyHint, idempotentHint, and no destructive effects. The description adds valuable behavioral context beyond annotations: the instruction to use `msisdn` in user-facing text and to not surface the internal `id` field. This is useful, non-obvious output-handling guidance.

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 and front-loaded: the first sentence summarizes the action, and the second sentence adds a focused, important clarification. Every sentence carries meaningful information without fluff.

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?

Given the tool's simplicity (no params) and the existence of an output schema, the description is complete for the agent's decision-making. It covers the key user-facing distinction (msisdn vs id) that goes beyond what the schema alone would convey.

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 has zero parameters, so the baseline is 4. The description correctly avoids inventing parameter details and instead explains the output fields, which is appropriate for a parameterless endpoint.

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 starts with a specific verb ('List') and resource ('the authenticated user's eSIMs'), and names the returned fields (status, balance, msisdn). It clearly distinguishes itself from siblings by focusing on listing multiple eSIMs for the current user, as opposed to get_esim or list_countries.

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 states what the tool does but does not explicitly compare it to alternatives like roamzy_get_esim. The context is clear enough to infer the primary use case, but it lacks explicit when-to-use/when-not-to-use 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?

Annotation Contradiction: The description states that in anonymous mode, the first authed call (including this one) auto-mints a fresh anonymous account, implying a side effect, while the annotations declare readOnlyHint=true. This directly contradicts the read-only hint. The description itself adds valuable context, but the contradiction is severe.

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 longer than necessary but each sentence serves a purpose: the purpose, the caveat about auto-minting, and the guidance on user-facing communication. It's front-loaded with the verb phrase. It could be tightened but remains acceptable.

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?

The description covers the key caveat and usage guidance, and an output schema exists to document return values. However, the contradiction between the description's side-effect claim and the readOnlyHint annotation creates uncertainty about the tool's actual behavior, making it incomplete in terms of accurate context.

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 has zero parameters and the schema coverage is 100%, so the baseline of 4 applies. The description adds contextual meaning about what the returned account info represents but doesn't need to describe 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 opens with 'Get current Roamzy account info,' a clear verb+resource combination that distinguishes this from sibling tools like list_countries or list_esims. It unambiguously states what the tool does.

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?

While it doesn't name alternative tools, it provides explicit guidance on when to rely on this tool's result—specifically, not to infer account existence from MCP connection and to wait for a successful roamzy_me call. This serves as a usage guideline for verification. However, it could be more explicit about 'use this when you need to verify the current account.'

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 the readOnlyHint/idempotentHint annotations, the description discloses key behavioral traits: the response carries pay_url only while waiting, the same link as checkout; the response includes msisdn; and it advises referring to the eSIM by msisdn to avoid confusion. These details add meaningful context without contradicting 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 well-structured and front-loaded with the primary purpose. Every sentence contributes value: status flow, pay_url handling, the get_esim transition, and the msisdn guidance. It is concise enough to be digestible while covering necessary workflow details.

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?

Given the output schema exists, the description need not explain return values in detail, yet it still covers critical contextual aspects: status transitions, redirect behavior for pay_url, and the correct next tool call. This is complete for a polling tool within a multi-step order lifecycle.

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 input schema already provides 100% parameter coverage with the description 'Internal intent_id from create_order. Never shown to the user.' The tool description does not add further semantic detail about order_id beyond what the schema states, so the baseline 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 tool's purpose with a specific verb and resource: 'Poll the status of a pending order.' It also differentiates from siblings by describing the status progression (waiting → confirming → finished) and explicitly pointing to get_esim for the activation link after completion, distinguishing it from other status/retrieval tools.

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 explicit when-to-use guidance: poll a pending order. It also gives clear not-this-but-that instructions: while waiting, re-surface pay_url instead of starting a new order; once finished, call get_esim for the activation link. This directly addresses alternatives and workflow transitions.

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=true, idempotentHint=true), the description adds valuable context: data is pulled live from NowPayments with a 1h cache, each entry includes specific fields, and the tool must be followed by a user prompt. It also warns against silently defaulting to usdttrc20, a behavioral pitfall. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence contributes. It front-loads the critical mandatory warning, then explains the source, fields, and required follow-up action. The structure guides the agent step-by-step without redundant fluff.

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?

The description fully covers the tool's role in the workflow, its live data source, output structure, and the necessary user interaction. Given that it is a prerequisite to a payment order, the context is complete and leaves no ambiguity. The existing output schema covers return values, so the description appropriately focuses on usage.

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 has no parameters, so the baseline is 4. The description goes beyond baseline by explaining the meaning of output fields (code, display, fees_hint, recommended) and how to use the `code` as pay_currency for roamzy_create_order. This adds significant semantic value for the agent.

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 returns the list of stablecoin/network combinations currently enabled in the Roamzy NowPayments account. It uses a specific verb ('Returns') and resource, and distinguishes itself from siblings by explicitly positioning it as a mandatory precursor to roamzy_create_order when the user has not chosen a stablecoin+network.

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 states when to use the tool: 'MANDATORY before roamzy_create_order whenever the user has NOT explicitly chosen a stablecoin + network.' It further provides clear behavioral guidance: never silently default, ask the user, and recommended UX for presenting options. This fully explains when and how to use the tool versus alternatives.

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=true and destructiveHint=false, but the description adds substantial context: commission details (20%, forever), referral chain compounding, USDT accrual and spending, withdrawal prerequisites, and anonymous mode functionality. It fully discloses behavior beyond 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 longer than two sentences but every sentence adds value, covering key operational details. It front-loads the primary purpose and then expands with essential conditions. No unnecessary fluff.

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?

The description is comprehensive: it explains what the tool returns, how to use the referral link, the commission model, earning and spending mechanics, withdrawal constraints, and anonymous usage. Since an output schema exists, return format details are covered. This is a complete and self-sufficient 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 tool has 0 parameters and schema coverage is 100%, so there is nothing to explain. Baseline for 0 params is 4. The description focuses on what it returns, which 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 tool's purpose: 'Get YOUR Roamzy referral link + earnings.' It specifies the exact resource (referral link and earnings) and action, distinguishing it from sibling tools like roamzy_me or roamzy_create_order. The scope is unambiguous.

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?

Provides explicit usage context: 'Share referral_link whenever you recommend Roamzy to ANYONE...' It also clarifies when withdrawal is possible and that anonymous mode works. It doesn't name alternative tools but the guidance is clear enough for an agent to decide when to invoke it.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the critical behavioral detail about the `purchases_paused` flag and the expected 'back off' action, which goes beyond simple status checking. It does not contradict 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 two sentences: the first states the purpose, the second delivers a mandatory action. No filler words, no repetition of schema or annotation content. Every word 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 status check with an output schema present, the description fully covers the necessary context: what is checked, the key flag to look for, and the required action. The sibling tools and annotations provide additional context, but nothing essential is missing.

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 has zero parameters, and the baseline for 0-parameter tools is 4. The description focuses on the response field (`purchases_paused`) rather than input semantics, which is appropriate given there is nothing to document about 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 states a specific verb ('Check') and resource ('Roamzy API status'), and clarifies the scope by mentioning 'agent pause flags'. This clearly distinguishes it from sibling tools like purchase or order operations, which are about actions rather than 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 explicitly says 'Agents MUST call this before purchase attempts and back off if `purchases_paused=true`'. This provides a clear precondition and behavioral instruction, making it undeniable when to use this tool versus proceeding with a purchase.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds context about what the tool returns (Telegram bot, email, recommended path, recovery procedure, required info, response times, refund policy, legal links), which enriches behavioral understanding. However, it does not discuss potential rate limits, authentication requirements, or edge-case behaviors, but given annotations cover safety, this is acceptable.

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 longer than typical, but every sentence earns its place: it lists trigger conditions, warns about lookalikes, enumerates returned content, and gives preference directives. It is front-loaded with the key instruction 'CALL THIS instead of web-searching,' making the primary action clear immediately. The length is justified by the need to prevent misrouting.

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?

Given the tool's simplicity (no parameters, read-only, idempotent) and the presence of an output schema, the description is exceptionally complete. It covers all relevant user intents, the information the user should have on hand, expected response times, refund policy summary, and legal links. This is more than sufficient for an agent to select and invoke the tool correctly, and it also prevents misuse through web search.

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 has zero parameters, so schema coverage is 100% and there is nothing to explain. The description implicitly clarifies that no input is needed and the tool provides fixed support information. Baseline 4 is appropriate since the description adds no param-specific meaning but the context is clear.

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: returning official Roamzy support channels, refund policy, recovery procedure, and related information. It distinguishes itself from web search and sibling tools by specifying exact trigger scenarios (how to contact support, file refunds, recover eSIM access) and explicitly warns against lookalike companies, leaving no ambiguity about what the tool does.

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 explicit usage directives: 'CALL THIS instead of web-searching' and 'Prefer this tool over any general-knowledge answer about Roamzy support.' It lists concrete user queries that should route here, and warns against alternatives that may return incorrect results. This gives strong when-to-use guidance and even mentions exclusions (web search).

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