WIA GIL: hotels, places, travel basics

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

Annotations already declare this a safe, idempotent, closed-world read, so the bar is lower; the description still adds genuinely useful behavior: a data_as_of date, a disclaimer, and an explicit warning that the data may be out of date. It also discloses the Korean-passport bias of the visa field, which annotations could never convey.

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?

Front-loads the resource and scope in one dense sentence, with the freshness caveat in the same breath. The trailing Korean translation is redundant for an English-reading agent but plausibly aids matching; no filler beyond that.

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 usefully enumerates the returned fields and flags the staleness caveat, which is what an agent needs to set expectations. Given the tool's simplicity, nothing material 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?

Only one parameter and schema description coverage is 100% ('2-letter country code, e.g. JP'), so the schema does the work. The description's '(ISO alpha-2)' is a marginal restatement rather than added syntax or validation meaning, matching 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?

Enumerates exactly what the tool returns for a country keyed by ISO alpha-2 code (currency, voltage/plug, time zone, emergency numbers, visa status, embassy), which cleanly separates it from the hotel/places/route/exchange siblings. The retrieval verb is only implicit in 'Basic travel info', but the resource and scope are 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?

Usage is implied rather than stated — an agent can infer it should call this when a user needs country-level travel basics. The important qualifier that visa/entry status is scoped to Republic of Korea passport holders is surfaced, which is real guidance, but there is no explicit when-to-use-vs-alternatives or 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is fully covered. The description adds meaningful provenance context ('cross rates computed from a USD table', 'not a transaction rate'), which is more than the annotations provide, but says nothing about caching, rate limits, or freshness of the rates.

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?

Short, front-loaded, and every clause adds information (provenance, caveat, defaults). The trailing bilingual '(참고용 환율)' slightly duplicates the English caveat but is negligible overhead.

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 two-param, zero-required read tool with rich annotations and no output schema, the description covers what it does, its precision caveat, and its default behavior. Only the return shape/freshness is unstated, which is minor at 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 coverage is 100%, so both params are already documented with their defaults in the schema. The description's 'Defaults to 10 major currencies' loosely reinforces the symbols parameter but adds no syntax or format detail beyond the schema.

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

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

States a specific resource (exchange rates) and clarifies the nature of the data (cross rates computed from a USD table). This cleanly separates it from the sibling travel/hotel/place tools, which cover entirely different domains, though it doesn't name any sibling explicitly.

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 caveat 'Not a transaction rate' implies reference-only usage, and 'Defaults to 10 major currencies' hints at default behavior. However, there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives for transaction-grade rates.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by bounding the result set — explicitly stating that overview text, review ratings, photos, prices and booking links are NOT returned — which prevents an agent from promising unavailable data to a user.

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?

One tightly packed sentence plus a short negative-scope clause; the returned fields are front-loaded after the verb. The bilingual Korean parenthetical is partly duplicative but is short and aids non-English agents, so it does not seriously dilute the definition.

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 compensates by enumerating the returned fields and the notable omissions, which is the key thing an agent needs. Combined with the 100%-covered input schema and full annotations, nothing material is missing for 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?

Schema coverage is 100%, so the baseline is 3, but the description adds an XOR constraint ('provide exactly one') that the schema does not encode — both properties are individually optional with no oneOf/anyOf structure. That missing constraint is exactly what the description supplies.

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?

Opens with a specific verb and resource ('Get details of one hotel') and then enumerates exactly which fields come back (address, star rating, check-in/out, rooms, year opened), so the agent knows the payload shape up front. It also names the sibling that supplies hotel_id (gil_hotels_nearby), which disambiguates it from the other gil_* 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 'provide exactly one' rule and the pointer to gil_hotels_nearby as the source of hotel_id imply a workflow, but there is no explicit statement of when to call this versus gil_hotels_nearby (e.g. 'use gil_hotels_nearby first to discover ids, then this to enrich'). No exclusions or preconditions beyond the identifier constraint are stated.

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 cover safety (readOnly, idempotent, non-destructive), so the description rightly spends its words elsewhere: it discloses hard caps (20 km, 20 results), result ordering (nearest first), the fields returned, explicit exclusions (no prices, review ratings, photos, booking links), and data provenance (partner/Agoda affiliate database). That last point is material because it tells the agent the data is third-party and may be incomplete.

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 definition is tightly front-loaded: scope, caps, output fields, exclusions, provenance, in that order. The trailing Korean parenthetical mostly repeats the English content, which is minor but unnecessary duplication.

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?

No output schema exists, so the description carries the burden of describing returns and does so by enumerating the fields (star rating, address, WIA Pin Code) and the empties/edge behavior implied by the hard result cap. For a read-only lookup tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, with ranges and defaults documented for lat, lng, limit and radius_km, so the baseline is 3. The description restates the caps ('max 20 km, max 20 results') but adds no syntax or semantic detail beyond what the schema already provides for each 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 opens with a specific verb and resource ('List hotels within a radius ... of a coordinate') and immediately fixes scope: max 20 km, max 20 results, nearest-first ordering. This distinguishes it from sibling tools by resource (hotels vs. gil_places_nearby) and operation (list vs. gil_hotel_detail).

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

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

The usage context is implied by the constraints (radius cap, result cap, coordinate input), so an agent knows this is a proximity lookup. However, it never explicitly routes the agent to alternatives, e.g. 'use gil_hotel_detail for full property info' or 'use gil_places_nearby for non-hotel POIs', nor does it state when not 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: names may appear in non-English languages and some places have no English name, which sets expectations about result quality. It still omits whether the data is live or cached and how results are ordered.

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 tight sentences, front-loaded with purpose and then the data caveat. The appended Korean gloss duplicates the English meaning and is dead weight for most agents, but it is brief and does no harm.

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 six-parameter read-only lookup with no output schema, the description covers purpose, coordinate/radius scoping, the 20 km cap and the language caveat, which is most of what an agent needs. The one real gap is the shape of the returned list (fields per place, ordering, pagination), which neither the description nor an output schema supplies.

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 lat/lng, lang, type, limit and radius_km are all documented in the schema itself. The description's 'radius (max 20 km)' merely restates the schema's 0.5-20 bound rather than adding syntax, defaults, or interaction rules (e.g. whether limit applies per type).

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?

States a specific verb (List), resource (landmarks or transport stops/stations), and scope (within a radius of a coordinate), which cleanly separates it from the similarly-shaped gil_hotels_nearby and the rest of the gil_* family. An agent can select it without opening the schema.

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 constraints (max 20 km) but never says when to choose this over gil_hotels_nearby or gil_search_city, nor any prerequisite such as needing a resolved coordinate first. Usage is only inferable from the resource name.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: it flags the result as 'approximate', discloses the 5,000 km straight-line limit, and explicitly bounds the payload to distance and segments with no travel time or geometry.

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?

One tightly front-loaded sentence plus a parenthetical Korean translation; every clause earns its place (scope, limit, output bounds). The bilingual parenthetical is mildly redundant for an English-only agent but not wasteful enough to penalize heavily.

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 usefully names the return content (distance and segments) and the approximation limit, which covers the return-value burden. However, for a 5-parameter tool at 20% schema coverage, the absence of any parameter-level guidance leaves the definition incomplete.

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 only 20% (only 'mode' is described), so the description must compensate — yet it says nothing about the four required lat/lng inputs, their expected format, or the meaning of the mode enum values. The gap is left entirely to 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 states a specific verb+resource ('approximate road/land route distance between two coordinates') with an explicit scope limit (5,000 km straight-line) and output boundary (distance and segments only). It is unambiguous against siblings like gil_places_nearby or gil_hotels_nearby, though it never names an alternative to sharpen the distinction.

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 only implied — the reader infers this is a point-to-point distance tool rather than a routing or travel-time service. The negative clause 'no travel time, no route geometry' gestures at when this tool is NOT sufficient, but no alternative tool or prerequisite is named.

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 closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious matching behavior ('prefix match', i.e. not substring or fuzzy) plus the shape of results, which an agent cannot infer from annotations alone.

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?

One front-loaded sentence covering purpose, match mode, outputs, and downstream use, with a compact bilingual gloss appended. No filler and nothing buried.

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 two-parameter read-only search with no output schema, the description supplies the essentials: what it matches on and what comes back. Minor gaps remain on result ordering and whether multiple city matches are possible, but nothing blocks 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 limit range and query length are already documented. The description still earns credit by specifying that matching is prefix-based, extra semantics about the query parameter that the schema's 'City name, 1-60 chars' does not convey.

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?

States a specific verb and resource ('Search cities by name') and enumerates the fields returned (coordinates, country, hotel count, main airport). It also positions the tool against siblings by noting the returned lat/lng feeds the nearby tools, so an agent can distinguish lookup from gil_hotels_nearby/gil_places_nearby without inspecting schemas.

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 sentence 'Returns lat/lng usable as input to the nearby tools' gives clear chaining context: use this first to resolve a city, then call the nearby tools. It stops short of explicit exclusions (e.g., what to do for ambiguous or partial names, or when to prefer country-level data), so no full when/when-not guidance.

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