ワットク（Wattoku）

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by disclosing that calculations are approximate, cashback expected values are site estimates, and construction costs/availability vary by building. It also explains the behavioral nuance that expected value can reverse face-value rankings, which is valuable 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 front-loaded with the primary function in the first sentence, followed by a concise disclaimer paragraph. Every sentence earns its place, and the caveats are brief yet relevant. No redundant or filler content exists.

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 4 parameters and no output schema, the description covers the purpose, key inputs indirectly, and important limitations. It does not explicitly state the return format, but for a comparison tool the output is generally implied. Overall, it provides sufficient context 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?

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds semantic value by listing the comparison dimensions such as set discounts, which clarifies why mobile_lines and mobile_carrier are needed. It reinforces the purpose of plan_slugs without redundant detail.

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 'compares 2-5 Hikari plans' including detailed factors such as real total cost, cashback receipt conditions, cancellation fees, and set discounts. This specific verb+resource scope distinguishes it from generic compare_plans and search/simulation 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 clear context by specifying the exact number of plans (2-5) and the Hikari-specific scope, which signals when to use this tool. It does not explicitly name alternatives or exclusion conditions, but the disclaimer about checking official sites adds a limitation note.

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, and non-destructive hints. The description adds valuable behavioral context: estimates are approximate and may differ due to fuel adjustment, usage, and discount conditions; final terms must be verified on official websites; and affiliate compensation is disclosed. This goes well 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 well-structured: purpose in the first sentence, usage instruction in the second, and necessary disclaimers in a separate paragraph. Every sentence earns its place; the disclaimer could be slightly tighter but is legally and contextually necessary.

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?

Without an output schema, the description lists the key aspects covered by the comparison, supplies usage prerequisites, and includes accuracy caveats and affiliate disclosure. This gives an agent sufficient understanding of the tool's functionality and limitations.

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 3. The description repeats the plan_ids source instruction already present in the schema but offers no new parameter semantics. All parameters are thoroughly described in the schema with defaults, enums, and constraints.

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 uses the specific verb '詳細比較します' (compares in detail) and enumerates the comparison dimensions: annual estimate, cancellation fees, fuel cost adjustment method, point rewards, and set discounts. This clearly differentiates it from siblings like search_plans and simulate_cost, establishing a unique 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?

The description explicitly instructs that plan IDs should come from search_plans/simulate_cost results, providing a clear workflow. It does not explicitly state when not to use this tool versus alternatives, but the multi-plan comparison scope implicitly distinguishes it from single-plan simulation tools.

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 context that the service does not handle applications and includes an affiliate disclosure, which is useful beyond annotations. However, it does not describe behavioral traits like side effects, link validity, or whether the call creates a tracking event, despite annotations indicating non-read-only and idempotent behavior.

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 first sentence is front-loaded with the core purpose, followed by category support and user responsibility. The disclaimer section is somewhat verbose but provides necessary legal context, so it is mostly concise with minor extras.

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, and the description implies the output is a link but does not specify format or structure. It also does not clarify that slug is required for non-electric categories (though the schema does). For a simple link generator, it is adequate but has gaps in return value and exact invocation requirements.

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 each parameter (slug, plan_id, category, campaign_id) already has a detailed description. The tool description adds no additional parameter semantics, 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?

The description clearly states the tool's action: 'Issues a link to the application page for the selected plan' with a specific verb (発行) and resource. It also enumerates the supported categories, distinguishing it from sibling search/compare/simulate 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 implies the tool is used after plan selection ('選んだプラン') and clarifies that the user must apply themselves, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The context is clear but not fully 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 mark this as read-only/idempotent, but the description goes further by detailing the calculation methodology: usage-based rates, 12-month accumulation accounting for seasonal winter bias, and sorting by estimated annual cost. It also discloses important limitations—raw material cost adjustment varies monthly, government discounts are excluded, and official verification is required—adding significant behavioral 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 well-structured with a front-loaded purpose sentence, followed by a concise methodology note and a compact disclaimer paragraph. Every sentence carries relevant information without fluff. The disclaimer is slightly long but justified given the approximate nature of the tool, so it earns a 4 rather than a 5.

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 there is no output schema, the description compensates by stating that results are sorted by estimated annual cost. It also explains the seasonal adjustment and provides caveats about estimate accuracy and support discounts. This is sufficient for a search/comparison tool, though it could mention the plan list structure more explicitly. Overall, it is complete enough for an agent to set expectations.

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 each parameter described, so the baseline is 3. The description adds the 'or' relationship between household_size and monthly_m3, but this is already implied by the schema descriptions (e.g., household_size used when usage is unknown). The seasonal variation explanation is a behavioral rationale, not a semantic enhancement of the parameters themselves. Thus it meets the baseline but does not elevate parameter clarity.

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 pair: '都市ガスの供給区域と世帯人数（または月間使用量m³）から、ガス料金プランを年間コスト試算つきで検索します' — clearly stating it searches city gas plans by region and household size/usage, with annual cost estimates. It distinguishes itself from siblings by explicitly focusing on gas (vs. hikari/other energy plans) and mentions sorting by annual estimate.

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 context for when to use this tool: for searching gas plans with cost estimation, using region and household size or monthly usage. It also sets expectations that results are approximate and should be verified on official sites. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions despite the sibling 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context that the estimates are approximate, the cashback expected value is not a measured rate, and that final conditions must be verified on official sites. 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 front-loaded with the core purpose and formula, followed by important disclaimers. It is slightly verbose but every sentence contributes useful information, so it earns a 4 rather than a 5.

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 explains what the tool returns (sorted plans, effective total, cashback expected value, and total if not received) and includes necessary caveats. Given no output schema, this is sufficient for an agent to understand the tool’s behavior and output, though it leaves some details to the schema.

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 each parameter already has a clear description. The tool description adds the overarching cost formula but does not provide additional detail for individual parameters beyond the schema, making the baseline score of 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 description clearly states that the tool searches optical line plans (光回線プラン) by building type, mobile carrier, and number of lines, and sorts them by effective total cost using a specific formula. This specificity distinguishes it from generic siblings like search_plans and compare_hikari_plans.

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 context for when to use the tool (searching optical line plans with specific criteria) and includes caveats about final verification. However, it does not explicitly mention alternatives or exclusion cases, so it falls slightly short of a 5.

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 annotation, the description discloses important behavioral details: prices are tax-inclusive and discount-free, conditional discounts are returned as separate notes, and the distinction between auto-determined and pre-selected capacity plans. It also warns about rate revisions and directs users to official websites, which is valuable transparency.

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 into a main explanation and a caveat paragraph. It is somewhat redundant in reiterating the tax-inclusive, no-discount pricing, but each sentence adds clarity. It is appropriately sized for the tool's complexity.

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?

Without an output schema, the description effectively explains the return behavior: plans sorted by price, conditional discounts separated, and the auto vs. pre-selected capacity distinction. It also covers exclusions and the need for verification. This is a complete and self-sufficient description for an agent.

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 100% coverage with descriptions for all three parameters, including examples for monthly_data_gb. The description adds context about how data usage drives plan selection but does not significantly enhance understanding of limit or unlimited beyond the schema. 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 searches (検索します) mobile rate plans based on monthly data usage, sorted by price ascending. It specifies the resource type (mobile plans) and distinguishes from sibling tools like search_hikari_plans and search_gas_plans. It also describes the comparison scope and the handling of conditional discounts, making the 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?

The description provides clear context for when to use the tool: when the user needs mobile plan comparisons by data usage. It does not explicitly name alternatives or exclusions, but the resource-specific wording (携帯料金プラン) differentiates it from siblings. No explicit when-not-to-use guidance is given, so a small deduction.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context: results are sorted by estimated cost, estimates are approximate, users should verify with official sites, and the service may receive affiliate compensation. This goes beyond the annotation-provided safety profile.

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 in the first sentence, followed by necessary caveats and affiliate disclosure. While somewhat lengthy, every sentence serves a purpose (estimating accuracy, verification, legal disclosure), so structure is justified.

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 purpose, input criteria, output ordering, and important caveats. There is no output schema, so the lack of return format detail is acceptable. It could mention edge cases like no matching plans, but overall the tool's behavior is adequately described for an agent.

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 100% parameter coverage with detailed descriptions, so the baseline is 3. The description adds a key semantic connection by noting that household size and monthly kWh are alternative inputs ('または'), which is not specified in the schema. This clarifies the relationship between 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?

Description uses specific verb '検索' with a clear resource ('家庭向け電気料金プランの候補') and specifies input criteria (area, amperage, household size/kWh) and output ordering (ascending estimated cost). This clearly distinguishes it from siblings like compare_plans, get_switch_link, and simulate_cost.

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 the usage context (searching for electricity plans with cost estimates) and explains which inputs are relevant. However, it does not explicitly mention when not to use this tool or mention alternatives, so it lacks exclusions.

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, idempotentHint, destructiveHint false), the description discloses that the calculation is approximate, may differ due to fuel cost adjustments and discount conditions, and that the service participates in an affiliate program. This adds valuable context about result reliability and potential bias.

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 efficiently structured: the first sentence states purpose, the second gives usage guidance, and the disclaimer is concise and necessary. It front-loads the core function and contains no redundant information.

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 9 parameters and no output schema, the description explains the main workflow and caveats. It could mention the output structure more explicitly, but the read-only annotation and clear purpose make it sufficiently complete. The auto-selection of plan_ids when omitted is covered in the schema.

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?

With schema description coverage at 89%, the schema already documents most parameters. The description adds the key semantic relationship: monthly_kwh and current_monthly_bill_yen are alternative inputs, and plan_ids originates from search_plans. This clarifies selection logic not present in 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 the tool's function: calculating the annual cost of each plan and the difference from the current contract, using either monthly kWh or back-calculation from the monthly bill. It uses a specific verb '試算する' and resource, distinguishing it from sibling tools like compare_plans and search_plans.

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 parameter guidance (use monthly_kwh if usage is known, current_monthly_bill_yen otherwise), but it does not explicitly say when to use this tool versus alternatives like compare_plans or get_switch_link. Usage context is implied rather than contrasted with 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 read-only, idempotent, and non-destructive. The description adds valuable caveats: estimates are approximate, fuel cost adjustment rates vary monthly, government support is excluded, and users should confirm final rates on official sites. It also discloses that set discounts are conditional and shown as a separate total, adding transparency 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 concise and front-loaded, with the main purpose in the first sentence, followed by key comparison details and a clearly marked disclaimer paragraph. Every sentence adds necessary information, and the structure is logical.

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 simulation tool with no output schema and two parameters, the description covers the tool's behavior, comparison outputs, and limitations thoroughly. It indicates what the output contains (comparison totals and discounted set-total) and provides sufficient context for an 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?

The input schema already provides descriptions for both parameters with 100% coverage. The description adds operational context by explaining that the gas supply area is automatically mapped to a corresponding power area and that household size is used for usage estimation, which helps the agent understand how parameters affect results.

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 estimates combined annual electricity and gas costs when reviewing both together ('電気とガスをまとめて見直した場合の合算年間コストを試算します'). It specifies the comparison logic between cheapest plans and major regulated rates, and explains how set discounts are handled separately, distinguishing it from sibling simulation tools like simulate_cost and simulate_hikari_cost.

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 the use case: when a user wants a combined electricity+gas estimate. It explains the tool's scope and what it does not include (set discounts are not in the cheapest total, shown separately). However, it does not explicitly name alternatives or exclusions for electricity-only/gas-only simulations, so it falls short of full explicit 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 the operation as read-only and idempotent. The description adds behavioral context by explaining the three cashback scenarios, monthly breakdown, and clearly stating that the calculation is an estimate with caveats about construction costs and official-site confirmation. 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 concise and front-loaded, stating the core purpose in the first sentence, then elaborating on the cashback scenarios. The disclaimer is necessary for an estimation tool but is slightly lengthy; overall it is well-structured without 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?

With no output schema, the description explains the return concept (three total amounts with monthly breakdown). It also covers the estimation caveats. However, it doesn't explicitly describe the output format for the monthly breakdown or how parameters like months/mobile_lines influence the calculation, but the schema covers those details. Given the tool's complexity, this is reasonably 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?

All four parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description reinforces the plan_slug source but does not add new semantic details about months, mobile_lines, or mobile_carrier that aren't already in the schema. It doesn't need to compensate, so a 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 simulates the real total cost of a specified hikari plan (光回線プラン) with a monthly breakdown, and explicitly references the required plan_slug from search_hikari_plans. It distinguishes from sibling tools like compare_hikari_plans and search_hikari_plans by focusing on cost simulation for a single plan.

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 indicates the prerequisite of using search_hikari_plans to obtain a plan_slug, giving clear context for when to invoke this tool. It does not explicitly state exclusions or name alternative tools for comparison or switching scenarios, so it falls short of the highest rating.

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 idempotent behavior; the description goes further by disclosing that the calculation is approximate, cashback expectations are site estimates, construction fees vary, and it explicitly reports if not switching is better. This adds meaningful limitations 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 core functionality is front-loaded in the first sentence, and the second sentence explains the result behavior. The disclaimer paragraph is longer but contains essential caveats. No redundant fluff; every sentence contributes.

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 calculation tool with no output schema, the description explains the return value (total difference), behavioral handling when staying is better, and key limitations. Parameter coverage is fully handled by the schema. It could specify the exact output format more concretely, but overall it is 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 description coverage is 100%, with each of the 8 parameters well-documented in the schema. The description groups penalty/construction/removal costs but does not add new semantic meaning beyond the schema's per-parameter descriptions, 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?

The description clearly states a specific verb and resource: it returns the total cost difference between switching and staying, using current contract penalty/construction/removal costs and monthly fee. It distinguishes itself from siblings like search_hikari_plans (search) and compare_hikari_plans (comparison) by focusing on the switch-cost integration.

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?

Usage is implied: use when a user has current contract costs and wants a switching vs. staying comparison. However, there is no explicit guidance on when not to use it or which sibling to choose instead (e.g., simulate_hikari_cost). The disclaimer adds context but no selection criteria.

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