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

Goes well beyond the readOnly/openWorld/destructive annotations: coverage is partial, a miss is not proof of invalidity, and results do not establish immigration entry or country presence. These caveats are exactly the kind of expectation-setting an agent needs to avoid false negatives on a lookup.

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?

Dense but front-loaded: purpose first, then return shape, then disambiguation, then caveats and the sibling handoff. Each sentence carries distinct guidance, though the disambiguation and handoff sentences could be tightened slightly without losing meaning.

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?

Single-parameter lookup with an output schema, so return shape needs no prose — yet the description still flags the extra matchedAirport fields that appear only on code matches. Combined with the coverage caveat, an agent has everything needed to call this and interpret a miss 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 0%, so the description carries the load, and it does: it defines the query's accepted forms (city name, country name, exact three-letter IATA code) and the exactness requirement on codes. Minor gap — it doesn't mention the 2–100 character bounds that the schema enforces.

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 reference cities) plus the accepted key forms (city/country name, exact three-letter IATA code), and the payload (ISO country, IANA timezone, and matchedAirport* fields). Nothing here could be confused with a journey/stay/loyalty sibling.

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?

Gives an explicit ordering rule ('use it before log_journey when location/timezone details are unknown'), a disambiguation policy for ambiguous codes (EWR → Newark vs New York), and a downstream handoff (retain matchedAirportCode in originIata/destinationIata). It even states what the tool does not do ('plain city searches do not infer airports').

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