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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond that: it is a reference lookup with no purchase-gate side effects, and it notes the eSIM works in all 193 countries. It doesn't discuss return format or errors, but the output schema covers that.

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 core purpose, but it uses four sentences and repeats 'reference info' in the first and last sentences. The guidance is clear and not overly long, though slightly redundant.

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 single-parameter reference lookup with a rich annotation set and an output schema, the description is complete: it states what the tool returns, when it should be invoked, and why it is not part of the purchase flow. No critical context 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?

Schema coverage is 100%, with country_slug already described as 'Country slug, e.g. "esim-spain". Reference lookup only.' The description adds no new parameter semantics beyond what the schema provides, so baseline 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 opens with 'Reference info: the per-MB rate for a specific country,' a specific verb/resource combination. It clearly distinguishes this from purchase flow tools by saying 'rates are reference info, not a purchase gate' and from list-style siblings by focusing on one country.

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 'Call ONLY if the user explicitly asks about price for their destination' and 'DO NOT call this during purchase — the user does not need to pick a country to buy.' This provides both when-to-use and when-not-to-use, even naming a concrete example.

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 description discloses many behaviors beyond annotations: minimum top-up $20, one-pending-order rule, 30-minute reservation, no cancel operation, anonymous-mode claim_url requirement, token spending limits, and error handling for esim_already_reserved. This adds substantial context that annotations (which only set readOnly=false, openWorld=true, idempotent=false) do not provide. 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 excessively long and unstructured, containing extensive warnings, pitch scripts, and repeated admonitions. While every sentence carries information, the lack of organization and verbosity makes it harder to parse. It could be condensed and sectioned for better readability.

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 exhaustive for the tool's complexity: it covers the full purchase workflow, payment options, post-payment polling, anonymous mode handling, reservation conflicts, and spending limits. With an output schema present and the description detailing return fields, 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 input schema already provides thorough descriptions for all three parameters (100% coverage), including minimums and defaults. The description goes further by specifying workflow constraints (e.g., pay_currency must come from roamzy_payment_options, never default to usdttrc20) and the rule not to ask for country when unspecified. This adds critical usage semantics above 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 opens with a specific verb and resource: 'Mint the user a Roamzy universal eSIM and fund it with the requested USDT amount.' This clearly distinguishes it from sibling tools like roamzy_payment_options or roamzy_order_status, and it explicitly states the tool's core function.

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 an explicit step-by-step workflow: ask amount, call roamzy_payment_options, present options, ask for stablecoin/network, then call this tool. It also states when not to use it (before user picks currency) and warns against asking country/data. It references alternatives like payment_options and order_status.

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, so the safety profile is covered. The description adds valuable behavioral context: the tool is purely informational, depends on country-specific rates, and must not be used as a sales gate. 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?

The description is three sentences with the core purpose front-loaded in the first sentence. The second and third sentences deliver crucial usage constraints without redundancy. Every sentence earns its place, making it both concise and well-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?

With an output schema, rich annotations, and a clear behavioral boundary (informational only), the description is fully complete for an agent to select and invoke the tool correctly. It covers what, when, and why-not, leaving no significant 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?

Both parameters are fully described in the input schema (100% coverage), with examples. The description does not add new parameter-level meaning beyond reinforcing the 'reference' nature, so the baseline of 3 is appropriate given schema coverage.

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 performs a reference calculation: estimating the USDT cost of a given MB volume at a country's rate. It uses a specific verb ('calculation') and explicitly differentiates from sibling tools by noting it's informational and not a purchase gate. This leaves 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 when-to-use guidance ('ONLY for informational queries') and when-not-to-use guidance ('DON'T use this to gate a purchase'), with the underlying rationale about the user's funding model. This is exemplary alternative/contextual direction for an agent.

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 indicate read-only and idempotent behavior, but the description adds critical behavioral detail: 'This tool does NOT return a ready-to-display image. Instead, qr_payload contains the LPA URI string.' It further discloses that lpa_url is only for same-phone installation and explains the recovery flow for anonymous sessions. This goes beyond the annotations and is consistent with 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 very long, with multiple paragraphs and warnings. While it is well-structured and each section serves a purpose, it is not concise; it could be trimmed by moving some instructions to separate documentation. The front-loaded purpose is good, but overall length detracts.

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 every edge case an agent might encounter: QR rendering, LPA fallback, anonymous session recovery, lost claim_url, and support escalation. Even with an output schema present, this additional context is essential and 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?

The input schema fully describes the single parameter esim_id as 'Internal eSIM ULID returned by list_esims or create_order. Never shown to the user.' The description adds no new semantic information about this parameter beyond the schema, but it reinforces that internal IDs should not be shown to the user. Given 100% schema coverage, 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 opens with a clear statement: 'Get a specific eSIM by id, including msisdn, status, balance, and the activation block (qr_payload + lpa_url).' This specifies the verb, resource, and scope. However, it does not explicitly contrast with sibling tools like roamzy_list_esims, so it misses the full distinction criterion.

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 instructions: when to generate QR locally, when to use lpa_url as a fallback, when to re-surface claim_url, and when to call roamzy_support. It also explicitly says 'call roamzy_support, not web search' for support follow-ups, giving clear 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context about the tool being a 'reference table' and the universal eSIM model, which goes beyond annotations without contradicting them. It does not describe output format, but the output schema covers that.

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, front-loaded with the primary action and scope. Every phrase adds value: the rate card nature, the 193 countries, the USDT currency, and the usage guardrails. No redundancy or 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?

For a no-parameter, read-only list tool with an output schema, the description fully covers scope (all 193 countries), semantics (per-MB rates, USDT), and usage intent. It also provides the 'universal eSIM' context, making the tool's role clear in the broader product flow.

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 baseline is 4. The description appropriately focuses on the tool's purpose rather than parameters, as there is nothing to clarify. No parameter documentation needed.

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 lists all 193 countries with Roamzy per-MB rates in USDT, using specific verbs ('List') and resource ('countries with rates'). It also distinguishes itself from a product catalog, making its purpose unambiguous and differentiated from siblings like list_esims.

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 when to call ('what countries are supported' or 'show me rates') and when not to ('don't volunteer it during a purchase flow'), providing clear usage context and exclusions. This is a model example of usage 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, establishing it as a safe read operation. The description adds valuable behavioral context beyond these annotations: it instructs the agent on how to present eSIMs in user-visible text (use msisdn, not the internal id), preventing misuse of identifiers. This is meaningful additional transparency for agent behavior, though it stops short of describing pagination or ordering.

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 succinct and front-loaded with the core action, then adds a critical usage note in an 'IMPORTANT' callout. Each sentence earns its place: the first states the function and output fields, the second and third provide crucial user-interface guidance. No redundancy or filler.

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 list operation with no parameters and an output schema present, the description is complete. It names the key output fields (status, balance, msisdn) and provides necessary context about which identifier to surface. The annotations cover safety and idempotency, and the output schema presumably details the full response. The description leaves no significant gaps for an agent to invoke and present results 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?

The input schema has zero parameters, and the description adds no parameter-specific details, but none are needed. The baseline for 0 parameters is 4. The description does clarify output field semantics (msisdn vs id), but that falls outside parameter semantics. Since there are no parameters to explain, the description adequately complements 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 states a specific action and resource: 'List the authenticated user's eSIMs' and includes the returned attributes (status, balance, msisdn). This distinguishes it from sibling tools like roamzy_get_esim (which presumably fetches a single eSIM) and roamzy_me (user profile). The verb 'List' plus the resource 'eSIMs' leaves no ambiguity about the tool's function.

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: it lists all eSIMs for the authenticated user, which is appropriate when a user needs an overview of their eSIMs. However, it does not explicitly state when to prefer this over roamzy_get_esim or other siblings, nor does it mention any exclusions or prerequisites. The guidance is implicit rather than explicit.

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 description discloses a critical side effect: in anonymous mode, the first authed call auto-mints a new account. This directly contradicts the annotation readOnlyHint: true, which implies the tool performs no writes. The annotation and description conflict, so per the rubric this is an annotation contradiction and scores 1.

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 three sentences, with the purpose in the first sentence and the two necessary warnings in the following sentences. Every sentence provides essential value and there is no redundant detail. The structure is front-loaded and well-organized.

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 tool has an output schema, so explaining return values is unnecessary. The description covers the one non-obvious behavior (anonymous account auto-minting) and provides clear usage context. Given the tool's simplicity and the output schema, the description is adequately 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?

The tool has zero parameters and the schema is empty, so the baseline is 4. The description doesn't need to explain parameters, but it does add behavioral context around the no-parameter call by explaining that the first call may create an account. No parameter information is missing.

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 begins with 'Get current Roamzy account info', a specific verb+resource statement that clearly distinguishes this tool from siblings like roamzy_status (which reports system status) and roamzy_list_countries (which lists country data). The purpose 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?

The description explicitly warns that MCP connectivity does not imply an existing Roamzy account, and instructs the agent to wait until roamzy_me or roamzy_create_order returns successfully before telling the user they're a customer. This provides clear when-to-use and when-not-to-use guidance, naming an alternative 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 indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context beyond that: the status progression sequence, the presence of pay_url during waiting, the instruction to call get_esim after finished, and the msisdn guidance. 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 front-loaded with the core purpose, followed by a compact but information-rich workflow. It is three sentences and every sentence adds value, though it could be slightly more structured. Still highly concise for the amount of guidance packed in.

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 an output schema present, return values are covered elsewhere. The description completes the picture by explaining the status lifecycle, the pay_url special case, the handoff to get_esim, and how to refer to the eSIM. It leaves no critical gaps for a polling 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 coverage is 100% and the order_id parameter is already described as 'Internal intent_id from create_order. Never shown to the user.' The description does not add much about the parameter itself, though it reminds not to use intent_id when referencing the order to the user. Baseline 3 applies since schema handles the semantics.

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+resource: 'Poll the status of a pending order.' It clearly distinguishes the tool's purpose from siblings by focusing on the order status workflow and even references get_esim as a downstream action. This is not a vague restatement of the tool name.

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 when-to-use and alternatives: while waiting, re-surface pay_url instead of starting a new order; once status=finished, call get_esim. It also tells the agent how to use the response (refer to msisdn). This fully guides selection and next steps.

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 and non-destructive hints. The description adds behavioral context beyond that: it is pulled live from NowPayments with a 1h cache and returns specific fields (code, display, fees_hint, recommended). This provides useful operational detail not available in annotations, though it doesn't cover all edge-case behaviors.

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?

Although the description is long, every sentence carries necessary information: a mandatory-use warning, purpose, output details, and post-call instructions. The structure front-loads the critical 'MANDATORY' caveat and flows logically through purpose, data, and usage.

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 complexity (zero parameters, but critical role in a multi-step flow), the description is complete. It covers when to use it, what it returns, how to present results, and how to proceed. An output schema exists, so the description need not repeat return schemas in detail.

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 does not need to add parameter details; it instead explains the output fields, which is appropriate for a no-argument tool.

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 returns the list of stablecoin/network combinations enabled in the account, with specific examples (USDT on TRON, USDC on Solana). It distinguishes from siblings by framing itself as a prerequisite for roamzy_create_order, making the tool's purpose 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?

Explicit guidance is provided: 'MANDATORY before roamzy_create_order whenever the user has NOT explicitly chosen a stablecoin + network.' It also dictates the follow-up behavior—asking the user and never defaulting—and states when it is not needed (when the user has already chosen).

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 description adds substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: the 20% commission structure, forever duration, compounding referral chains, USDT accrual, spending on eSIM traffic, withdrawal identity requirement, and anonymous mode. These details give the agent a full understanding of the tool's behavior and 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?

The description is a dense paragraph but front-loads the core purpose. Each sentence contributes new information (commission, sharing, earnings, withdrawal, anonymous mode, returns). While longer than a two-sentence ideal, the complexity of the referral program justifies the length. No redundant or filler content.

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 tool's purpose, usage, return fields, earning mechanics, withdrawal requirements, and anonymous mode. It also explains the meaning of can_withdraw. With an output schema present and annotations providing safety hints, this description is fully complete for an agent to invoke 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?

The input schema has zero parameters and schema coverage is vacuously 100%, so the baseline is 4. The description usefully explains return values (e.g., can_withdraw, balance_usdt) which adds semantic meaning, but no parameter clarification is needed since there are no 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 explicitly states the tool's function with a specific verb+resource: 'Get YOUR Roamzy referral link + earnings.' It clearly differentiates from sibling tools like roamzy_status or roamzy_me by focusing on referral and earnings, and enumerates the return fields.

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 clear guidance on when to use the tool: 'Share referral_link whenever you recommend Roamzy to ANYONE.' It gives context for both human users and AI agents, but does not explicitly state when not to use it or name alternative tools for exclusion.

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?

While annotations already indicate read-only and non-destructive behavior, the description adds critical operational context: the presence of a 'purchases_paused' flag and the required backup behavior. This goes beyond the annotations and tells the agent how the API status affects downstream actions.

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 long, front-loaded with the main purpose, and the second sentence provides a mandatory usage rule. Every word earns its place; there is no fluff or repetition of schema/annotation data.

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 that this is a simple status-check tool with no parameters, an output schema (not shown but mentioned), and annotations covering safety, the description provides all necessary context: what it checks, a critical usage requirement, and the exact flag behavior. It is fully complete for an agent to invoke 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?

The tool has zero parameters, so the schema provides full coverage by default. The description adds no parameter-specific information because none exists. Baseling score of 4 is appropriate; no deduction is needed since there is nothing to clarify.

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 and resource: 'Check Roamzy API status.' It further clarifies the scope by mentioning 'agent pause flags,' which distinguishes this tool from sibling tools like roamzy_list_countries or roamzy_create_order. The purpose is clear and 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?

The description explicitly states when the tool must be used: 'Agents MUST call this before purchase attempts.' It also provides a conditional action: 'back off if purchases_paused=true.' This gives clear context for when to invoke this tool and what to do with its result, which is more than typical usage 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial context about what the tool returns (Telegram bot, email, recovery steps, required user info, response times, refund policy) and why it is preferred over web search. 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 dense and front-loaded with a clear directive. While long, each sentence contributes meaningful guidance, from the explicit call-to-action to the detailed list of returned data. Minor redundancy exists between 'CALL THIS instead of web-searching' and 'Prefer this tool over any general-knowledge answer'.

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 strong annotations, the description is exceptionally complete. It covers all user intents, warns about lookalikes, and enumerates the exact information returned, making it sufficient for an agent to select and invoke 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?

The tool has zero parameters, so parameter semantics is not applicable. The description fully compensates by explaining what information the tool provides, which is the relevant semantic content.

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 the tool's purpose: returning official Roamzy support channels, refund process, recovery procedure, and related details. It distinguishes itself from web search and sibling tools by specifying exactly when to use it (contact, refund, customer-service channel, eSIM recovery).

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 clear when-to-use guidance: 'CALL THIS instead of web-searching' for support-related queries and warns against using general-knowledge answers. It explicitly mentions alternatives (web search) and explains why they are unreliable due to lookalike companies.

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