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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered by structured data. The description adds real value beyond that with the 2-credit cost and the paid-tier feature gating for ICAO lookups and logo URLs. It does not cover rate limits, failure behavior for unknown codes, or whether multiple identifier params can be combined.

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 body is dense and front-loaded, moving from what it matches to what it returns to tier limits and cost. The opening is marred by the redundant 'Airline Lookup: Airline Lookup is an airline codes API', which restates the tool title twice before any new 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?

An output schema exists, so the enumerated return fields are a bonus rather than a necessity, and cost plus tier gating are disclosed. The notable remaining gap is that the schema marks zero required parameters, and the description never says whether one identifier must be supplied or how conflicting iata/icao/name values are resolved.

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 of iata, icao and name is already documented in structured fields; baseline is 3. The description adds only one thing beyond the schema — that ICAO lookup is tier-gated — and says nothing about precedence when several identifiers are supplied, or that no parameter is marked required.

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 names a concrete verb and resource: it matches IATA codes and airline names to carrier profiles and enumerates the returned attributes (official title, callsign, registration country, operating status, low-cost flag). That is enough to separate it from airport-oriented siblings like AirportsLookup and AirportCodeConverter, though it never names those siblings 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?

Usage is only implied by the verb 'matches' — there is no statement of when to prefer this over AirportsLookup or AirportCodeConverter, nor what to do when a lookup fails. The one genuinely useful usage signal is the tier note that three-letter ICAO lookups require a paid plan, which tells an agent the icao parameter may not be usable on the free tier.

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