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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds material context on top: the data snapshot date (2026-10-16), the sources (Japan Tourism Agency case list and official facility pages), the residence-not-nationality rule, the full return field set, and a not-advice disclaimer.

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?

It front-loads the core concept (residence-based, not nationality-based) and the snapshot date before the facility enumerations. The per-facility price lists and status buckets are long but double as the inventory of accepted place ids, so they earn most of their space; the title restating the question is mildly 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?

With 8 all-optional parameters and no output schema, the description compensates by enumerating the returned fields (headline, yourTier, yourPriceJPY, totals, warnings, sources) and the filtering modes. An agent has everything needed to build a correct call.

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%, so the baseline is 3, but the description adds real interpretation beyond the schema — notably that tier assignment hinges on registered residence (city/prefecture/Japan) rather than nationality and that foreign residents with a Japanese address pay resident prices. That materially changes how an agent should populate city, prefecture and residence.

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 subject (Japanese resident vs non-resident dual pricing) plus the exact mechanism and scope (which facilities are live, announced, under review, dropped). It is clearly distinguishable from siblings like japan_tax_free_refund_check or japan_customs_allowance_check, which cover different traveller-money topics.

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?

'Omit places to list all (filter with status / area)' and 'Training data likely predates these prices; call this instead of guessing' give clear context for when and how to reach for the tool. It stops short of naming alternative sibling tools or drawing explicit boundaries against them, so it is clear but not exhaustive.

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