Gachi Data API — Japan Station & Accessibility Data

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

Annotations already convey readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the data source (JMA official), the specific alert types covered, the fields returned (level, affected area, summary, issue time), and a disclaimer that it is not a life-safety system, going 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 core purpose. It uses four sentences, each adding value: purpose/exclusions, coverage details, parameter explanation, and a disclaimer. It is dense but not overly lengthy, with no 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?

Given the tool has one optional parameter, strong annotations, and an output schema, the description sufficiently covers the data source, alert types, returned fields, filtering option, and important caveats. This is complete for an AI 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% for the single `area` parameter, so the baseline is 3. The tool description repeats the filter functionality and examples (13 = Tokyo) but adds little beyond the schema's own description, which already explains the parameter is optional and examples are given.

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 'Live river flood forecasts and landslide alerts for Japan (JMA official)' with explicit exclusions ('NOT general weather warnings... and NOT earthquakes'), distinguishing it from sibling tools like get_station_alerts. The verb 'get' plus specific resource and scope makes 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?

Provides clear context for when to use: it covers JMA river flood and landslide alerts, and explicitly excludes other warning types and earthquakes. It also describes the optional area filter and the service's role as a relay, not a life-safety system. However, it does not name alternative tools or state 'use this when...' beyond 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?

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it promises 'official values only' with no judgment, indicates a single aggregated call ('one call'), and specifies a data range for vacancy. It does not discuss rate limits or pagination, but the output schema covers return structure.

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 concise sentences, each serving a distinct purpose: scope/data categories, behavioral promise, and input format. No filler or redundancy, with key facts front-loaded.

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

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

Given an output schema exists and annotations cover safety, the description fully supports tool selection and invocation. It covers what the tool offers, how to specify the municipality, the optional fields concept, and the raw-data nature, making it complete for correct 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?

Schema coverage is 100% and both parameters are well-described. The description adds useful semantic context by explaining what the data fields mean (e.g., vacancy years 2003–2023, nearest-station ridership trend) and gives input examples, although the examples duplicate the schema description. This enriches parameter understanding 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 states it provides official Japanese government data for municipalities, listing specific data categories (vacancy, ridership, hazard, land price, livability). It distinguishes itself from sibling station/toilet tools by focusing on municipality-level official data, and the 'No scores, no judgment' note clarifies its non-analytical nature.

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 strong context for when to use it: for official municipal data on multiple topics. It does not explicitly mention alternatives or when not to use it (e.g., for station-specific alerts), but the scope is clear enough given the sibling list.

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, openWorldHint, idempotentHint, and destructiveHint. Beyond that, the description discloses important behavioral details: nationwide coverage of 612 municipalities, a cap of 50 results for large cities, and locale-specific input handling. These add meaningful context and are consistent 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 two tight sentences that front-load the primary purpose and then efficiently cover important scope and usage details. Every sentence provides value, with zero 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 single-parameter read-only tool with an output schema and rich annotations, the description is complete. It covers the resource, return fields, geographical scope, result limits, and input-language nuance. No return-format explanation is needed because the output schema exists.

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

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

The schema description for 'city' already covers the meaning, examples, and the prefecture-prefix tip, so the tool description largely repeats this information. It adds no new parameter-level semantic detail 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 clearly states the action and resource: 'List public toilets in a Japanese municipality' and enumerates the data returned (wheelchair / baby-seat / ostomate flags, address, coordinates). It distinguishes from sibling get_toilet_by_station by focusing on municipality-level lookup.

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 (municipality-level query) and practical guidance on input format ('Municipality names accept Japanese... prefixing the prefecture improves accuracy'). It does not explicitly name alternatives such as get_toilet_by_station, but the city versus station distinction is implicit.

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 openWorldHint. The description adds valuable context beyond this: the prefecture-level matching (station master is Greater Tokyo), the fact that it's a 'Relay of official JMA facts' (not original analysis), and that it excludes general warnings. These traits meaningfully shape agent expectations.

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 sentences, each earning its place: what it is, how to query, and scope/caveat. The dash for exclusion is efficient. No padding.

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

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

For a one-parameter tool with an output schema, the description covers content type, query language, matching scope, and source. It gives the agent enough to decide when to use it and what to expect, without needing to inspect the output 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 coverage is 100%, and the description reinforces the Japanese/romaji format. It also adds the nuance that the station_name is used for a prefecture-level match, which is extra meaning beyond the schema's simple 'station name' definition. This justifies a score above the baseline 3.

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 'Live JMA river flood forecasts and landslide alerts affecting a station's prefecture' and explicitly excludes 'general weather warnings', distinguishing it from likely siblings like get_active_alerts. The verb 'Live' and resource 'JMA alerts' are specific 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?

It gives clear usage context: ask by station name in Japanese or romaji, and notes the prefecture-level match. It explicitly says 'NOT general weather warnings', which provides a when-not scenario. However, it does not name alternative tools directly, so it falls short of full 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context by specifying the data source (same official municipality data) and what is excluded ('no scores'), which goes beyond the structured annotations. It does not mention rate limits or error handling, but for a read-only lookup this is sufficient.

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 key reference to get_municipality_context. Every sentence adds meaningful information (input options, output type, data policy) without redundancy.

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

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

Given an output schema exists and annotations cover safety, the description explains the core use case well. It clearly indicates how to specify input (station name or ID) and what the output represents. It omits hypothetical edge cases, but overall it is complete for a tool of this complexity.

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 covers 100% of parameters with descriptions, providing a baseline of 3. The tool description adds valuable examples (Shinjuku / 新宿 / Musashi-Kosugi and st_00001) and clarifies the mutual exclusivity implicit between station_name and station_id, enriching the schema's bare parameter descriptions.

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 official municipality context resolved from a station, with specific input examples (station name or station_id). It also distinguishes from get_municipality_context and clarifies 'no scores', making its 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?

It explicitly references get_municipality_context and explains the key difference—resolved from a station—which tells when to use this tool. It gives clear input instructions, though it does not explicitly state when not to use it or name alternative tools beyond the municipality counterpart.

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 readOnly, openWorld, idempotent, and non-destructive nature. The description goes further by disclosing that landslide and tsunami data are license-restricted and return available:false with a link to official maps, and that the tool returns official values as-is with no composite score or judgment. This adds valuable behavioral context about data availability and interpretation 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 moderately sized and front-loaded with the core purpose. Each sentence provides substantive information (source, categories, licensing, return semantics, input format, usage caveat), though the input format sentence is redundant with the schema and could be trimmed without loss. Overall, the structure is clear and information-dense.

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 doesn't need to explain return values, but it still addresses key contextual elements: data source, specific hazard categories, licensing limitations, output semantics, input format, and appropriate usage. This makes the tool's behavior and limitations clear for an AI agent, especially for a niche Japanese data source.

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

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

The schema fully documents the single parameter 'station_name' with examples in Japanese and romaji, achieving 100% coverage. The description repeats this input format but adds no semantic detail beyond the schema, so it meets the baseline but does not exceed it.

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: returning official disaster-risk categories at a Japanese train station from the MLIT Real Estate Information Library. It specifies the exact categories (flood inundation-depth rank, landform/liquefaction classification, storm-surge presence) and distinguishes itself from siblings like get_station_alerts and get_station_context by focusing on hazard categories rather than alerts or general context.

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 ('For research/analytics') and explicitly warns against using it as a substitute for official government hazard maps or evacuation decisions. However, it does not explicitly name alternative tools or state when NOT to use this tool in favor of a sibling, though the distinct subject matter implies appropriate use cases.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the data source (Tokyo Bureau of Social Welfare), station coverage, and the special in-station layer grouped by ticket gate and railway operator for major stations. This gives the agent a clear picture of edge-case 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?

Three sentences, each earning its place: the first states the core purpose and output fields; the second defines coverage and special behavior for major stations; the third specifies input formats with examples. No fluff, well front-loaded, and 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?

Given the tool's simplicity (one parameter), the description covers all essential aspects: what it retrieves, the geographic scope, data source, input varieties, and special grouping behavior for major stations. An output schema exists, so return-value details are already structured. The description is complete for safe and correct invocation.

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

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

The schema covers the single parameter with 100% coverage, providing the baseline of 3. The description enhances this by explaining accepted formats (Japanese and romaji), providing examples, and clarifying that romaji is only for major stations. This adds practical guidance for correctly filling the parameter.

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 a specific verb ('look up') and clearly identifies the resource: wheelchair-accessible/multipurpose toilets inside train stations. It enumerates details (floor, gender, equipment, nearest exit) and distinguishes itself from sibling tools like get_public_toilet_by_city, which focuses on city-level public toilets.

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: it works for 526 Tokyo stations and major stations outside Tokyo with a different grouping behavior. It also specifies acceptable input formats (Japanese/romaji) and hints that romaji is only for major stations. However, it does not explicitly state when NOT to use it or name alternative tools, so it stops short of a full 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 annotations (read-only, idempotent), the description discloses the status enum (normal/delayed/suspended/resumed), how cause text is handled (English summary for known patterns, else original text + null), and credits ODPT as the data source with license. This adds real behavioral detail 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?

Four concise sentences packed with relevant information — purpose, usage, enum, data source. No filler words. Front-loaded with the most important part.

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 a single query parameter, a read-only action, and an output schema. The description covers purpose, usage, result format (status enum and cause handling), and data provenance. There's no gap that would hinder an agent from using 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 documents query as 'Line or station name (English or Japanese)'. The description repeats this and adds an example query. With 100% schema coverage, the baseline is 3; the description adds minimal extra semantic meaning beyond the schema, so 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 'Live train service status for Tokyo-area lines' — a specific verb (get status), resource (Tokyo-area train lines), and scope (delays, suspensions, resumptions). It clearly distinguishes from sibling tools like get_station_alerts or station_search by focusing on line-level running status rather than station facilities or alerts. The example phrasing solidifies 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?

It gives concrete usage context (ask by line or station name, English or Japanese) and a natural-language example ('is the Yamanote Line running?'). It does not explicitly name alternatives or exclusions, so it earns 4 rather than 5. The context alone makes it clear when to use 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. The description adds valuable context beyond this: it is lightweight, requires no auth, and returns specific fields (server identity, deploy version, tool count, station coverage, update times) to confirm 'freshness, not just liveness'. This fully discloses behavior and return value scope.

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 key action ('call this first'), and every clause adds useful detail: what it returns, the no-auth/lightweight nature, and the distinction between liveness and freshness. No filler or redundancy.

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

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

For a zero-parameter, read-only health check, the description fully covers purpose, usage, and output expectations. It even notes the update times for realtime layers, which is more than necessary given the output schema exists. It is complete for an agent to decide when and how to invoke it.

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, so there is nothing to describe beyond stating 'no arguments', which the description does. Baseline for 0 params is 4, and the description reinforces the schema. There is no missing parameter information.

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 'Connection test / health check' and specifies 'call this first to confirm the server is reachable', giving a specific verb and resource. It clearly distinguishes itself from sibling data-retrieval tools by focusing on server health and returning aggregated metadata rather than domain data.

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 'call this first' to confirm reachability, establishing it as the initial check before using other tools. It also mentions 'No auth, no arguments, lightweight', implying it is the low-cost entry point. The description makes the usage context clear without needing to name 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?

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: hybrid metadata filters, auto-inference with explicit params winning, water-hazard expansion logic, soft filtering for partial data coverage, name_contains exact substring behavior, and specific data-coverage caveats (Tokyo-only toilets, Greater Tokyo ridership). It also explicitly states MLIT hazard categories are relayed 'as-is, NOT a safety judgment.' 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 long but dense and well-structured, front-loaded with the core purpose and then organized by filter behavior, coverage notes, and role split. Every sentence contributes useful information, though a few concepts (soft filters, water-hazard expansion) could be simplified without losing meaning. For a tool with 10 parameters and complex semantics, this length 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?

Given the tool's complexity, an output schema exists, and the description still adds necessary context: data coverage limitations, relationship to sibling tools, auto-inference behaviors, and edge cases like name_contains. It doesn't need to explain return values because the output schema covers that. The description leaves no obvious gaps for an agent deciding to use this 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?

Although the schema already documents all 10 parameters (100% schema coverage), the description adds substantial meaning: it explains how auto-inference works, that explicit params override inferred ones, the special limit rule with name_contains, soft_filters for partial coverage parameters, and the semantics of flood_rank_max and accessible_toilet_min. This is far beyond baseline schema descriptions.

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 ('Discover') and resource ('Japanese train stations') and explains the method ('by describing what you want around them'). It also explicitly distinguishes the tool from siblings via the role split: 'station_search finds candidate stations — then get_toilet_by_station / search_ramen / get_station_hazard / get_station_context for detail on one station.'

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 explicit usage guidance and alternatives: it names sibling tools for follow-up detail, explains when to use name_contains ('Use for "stations whose name contains X" requests that semantic search cannot guarantee'), and clarifies what the tool does not do (e.g., taste/quality words not evaluated, coverage limitations). This goes far beyond implied context.

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