FlightDB

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

With readOnlyHint, destructiveHint=false, and openWorldHint=false already provided, the description adds meaningful context by describing the return shape ([{ period, byCountry: {...} }]) and that results are sorted chronologically. It does not cover auth or rate limits, but for a read-only query this is solid additional detail.

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 front-loaded with purpose, then return structure, then a concrete example. Every sentence earns its place without waste, making it easy to parse quickly.

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 return value explanation is redundant but not harmful. For a tool with five parameters and zero schema descriptions, the description leaves important parameter details (granularity, date format, code patterns) unaddressed, making it only partially complete.

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 must compensate for all five parameters. It mentions the optional date range and country filter, and the example shows the country array format, but it omits any explanation of granularity (enum with default), date format, airport code pattern (4 uppercase letters), or country code pattern (2 uppercase letters). This leaves significant gaps.

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 — arrival counts to one airport broken down by departure country — and clarifies the grouping dimensions (day/month/year). It does not explicitly differentiate itself from siblings like Flight_airport_arrival_trend or Flight_flights_by_country, but the purpose is otherwise clear.

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 implies usage via the example (comparing India vs China arrivals to Bali) and notes optional date range and country filter. However, it offers no explicit when-to-use versus when-not-to-use guidance or named alternatives among sibling tools.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return shape ([{ period, count }]) and chronological sorting, which annotations do not provide. It says nothing about date bounds, timezone, or empty results.

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 compact sentences, front-loaded with the core purpose, followed by scoping and a concrete example. No 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 read-only aggregation tool with an output schema already defined, the description plus annotations cover the essentials, and even restating the return shape aids selection. Missing date-format and timezone conventions are the only notable omissions.

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 0%, so the description must carry the load. It confirms the date range is optional, hints at granularity via 'day/month/year', and the WADD example shows the airport code is ICAO-style. However, dateTo/dateFrom formats and the 'hour' granularity are not addressed, so there are real gaps.

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+resource: arrival counts to one airport grouped by day/month/year. An agent can tell it returns a time series rather than a snapshot or stats, which separates it from Flight_airport_stats and Flight_airport_visits. It does not name those siblings explicitly, so it stops short of a 5.

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 example ('arrivals to Bali (WADD) for the last 12 months with granularity=month') implies when to reach for the tool, and the 'Optional date range' note clarifies scoping. But there is no when-not guidance and no comparison to the many sibling airport tools, leaving the agent to infer selection.

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, destructiveHint=false and openWorldHint=false, so safety behavior is covered. The description adds nothing further about behavior — no note on freshness of aggregation, whether counts are complete, or how the aggregates are scoped — so it neither contradicts nor enriches the annotations much.

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, no filler. The resource and its aggregates are front-loaded, and the parameter note follows. Every clause carries information an agent needs.

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 one required parameter, full annotations and an output schema, the definition needs only to identify the resource and the input format, both of which it does. The main residual gap is the absence of any hint about how this differs from overlapping siblings such as top_routes.

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 0%, so the description must carry the parameter, and it does: it specifies ICAO code, 4 letters, and gives a concrete example (WADD for Bali). The '4 letters' part duplicates the schema's ^[A-Z]{4}$ pattern, but the ICAO-vs-IATA distinction and the example are genuinely additive.

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 the resource (one airport) and enumerates exactly what is aggregated: total departures, top destination airports, top aircraft, departures by year. That distinguishes it from siblings like Flight_airport_arrivals_by_country and Flight_airport_arrival_trend, though it never explicitly names an alternative.

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: 'Aggregated stats for one airport' suggests investigation/profiling of an airport, and the second sentence is a parameter instruction rather than a when-to-use rule. There is no guidance on when to prefer this over Flight_top_routes or Flight_airport_visits, which overlap on similar data.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds the aggregation shape (per-airport, per-year visit and stay buckets), which is genuine behavioral context, but says nothing about coverage period, pagination, or what happens for an aircraft with no visits.

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 is a single front-loaded sentence with no filler, which is good. However, it is terse to the point of under-specification — the brevity is not paired with the disambiguation an agent needs among 15 siblings.

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 return values need not be explained, but for a tool with 15 sibling tools the description leaves the agent unable to tell this apart from Flight_airport_stats or Flight_visit_history. The required id parameter is also left under-explained.

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 must carry parameter meaning. It only echoes the parameter name ('one aircraft id') without saying where to obtain a valid id (e.g. Flight_list_aircraft / Flight_get_aircraft_from_list) or what happens with an unknown id.

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 resource (per-airport visit and stay aggregates) with a clear grouping (by year) and filter (one aircraft id). It is understandable on its own, but it does nothing to distinguish it from near-neighbours like Flight_airport_stats or Flight_visit_history.

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?

There is no guidance on when to choose this tool over the many airport/visit siblings, and no prerequisites or exclusions are stated. The agent must infer usage purely from the noun phrase.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's only behavioral addition is the 'stacked-series style payload' hint about output shape, which is partly redundant with the existing output schema.

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 sentence, front-loaded with the resource and granularity, and nothing superfluous. It is arguably too sparse rather than verbose.

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 output schema absolves the description of explaining return values, and annotations cover safety. However, with a crowded sibling set and no differentiation or usage routing, an agent still lacks enough to confidently choose this tool over Flight_flights_by_year.

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 single parameter has 0% schema description coverage, but the description does clarify that the id refers to an aircraft and that results are scoped to it. That is minimal added meaning over the self-explanatory parameter name.

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 (arrival-country flight counts), a granularity (per-year), and a scope (one aircraft id), which is enough to distinguish it from Flight_flights_by_year and Flight_airport_arrivals_by_country in broad terms. The 'stacked-series style payload' phrasing is a shape hint rather than a purpose statement, but the core verb+resource is clear.

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?

No when-to-use guidance and no mention of alternatives, despite several closely related siblings (Flight_flights_by_year, Flight_airport_arrivals_by_country). The agent must infer the selection criteria from the data shape alone.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results are aggregated into per-year counts across four fixed distance bins, which is genuinely useful context beyond the annotations, but it omits any note on what the bins mean or how the aircraft scope affects results.

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 sentence, front-loaded with the output shape and then the grouping dimension and scope. Nothing is 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?

An output schema exists, so return values need not be documented, and the description supplies the aggregation semantics (bins plus per-year counts). For a one-parameter read-only tool this is nearly sufficient; only the provenance/format of aircraftId is left dangling.

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% for the single aircraftId parameter. The phrase 'for one aircraft id' usefully clarifies that the tool is scoped to a single aircraft rather than a fleet, but it gives no hint about the expected identifier format or where to obtain it (e.g., Flight_list_aircraft).

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 the computation (per-year counts), the grouping dimension (trip distance category with its four enumerated bins), and the scope (one aircraft id). That is specific enough to separate it from Flight_flights_by_year and Flight_flights_by_country, 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternative aggregation tools. The agent must infer from the name that this is the distance-binned variant rather than the yearly or country variant.

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, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds the return payload keys { years, counts }, but that is also covered by the output schema, so it adds limited behavioral context beyond structured data.

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 a single, front-loaded sentence with no filler. It communicates the metric, scope, and return shape compactly.

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 read-only aggregation tool with annotations and an output schema, the description is minimally adequate. It is missing parameter guidance and sibling differentiation, but structured fields cover safety and return details.

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 must compensate for the single aircraftId parameter. It only repeats 'one aircraft id' without format, source, or examples, adding little semantic meaning beyond the parameter name and schema 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?

The description states a specific metric and grouping: per-calendar-year flight counts for one aircraft id. It clearly identifies the resource and scope, but does not explicitly differentiate itself from siblings like Flight_flights_by_country or Flight_list_flights.

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 by the metric description: use this when yearly flight counts for a single aircraft are needed. However, there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance despite many sibling tools.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: flights are ordered newest first, and aggregates come back empty rather than erroring when no flights exist. It says nothing about pagination or result volume limits, which matters for an aircraft with thousands of flights.

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 with no filler, and the empty-aggregate edge case is stated up front. It does lead with return fields rather than purpose, but the whole thing is short enough that front-loading is not a real problem.

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 an output schema present, the description need not document return values, and it still names the aggregate keys and the empty-result behavior. Combined with read-only annotations, the definition is largely self-sufficient; the remaining gap is the undocumented aircraftId format.

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 single parameter aircraftId has 0% schema description coverage, so the description carries the full burden and only implies that it identifies the aircraft ('for an aircraft'). It never states the expected ID format (internal ID vs. registration/tail number) or where to obtain a valid value, which is the most likely source of a failed call.

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 all flights for a single aircraft plus derived aggregates (byYear, byDistance, byCountry, airportVisits, visitHistory), which is a specific verb-and-resource statement. It does not, however, distinguish itself from overlapping siblings such as Flight_flights_by_year, Flight_flights_by_distance, or Flight_visit_history, which deliver a subset of the same 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?

The only usage cue is the phrase 'used on the detail page'; there is no explicit guidance on when to call this versus Flight_get_aircraft_from_list, Flight_list_flights, or the individual aggregate siblings whose data it bundles. An agent must infer the choice from the return-field list alone.

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, non-destructive, closed-world, so the safety profile needs no restating. The description still adds real behavioral context beyond the annotations: a missing id yields null rather than an error, and the result is only the list row without derived stats or charts. It stops short of noting performance/auth characteristics or the size of the row, so not a 5.

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 short sentences, no filler: what it returns, the null edge case, and the sibling alternative. The most important qualification (fast header-only lookup) is 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?

For a single-parameter read-only lookup with an output schema present, the description covers the remaining gaps: the null-on-missing case, the shallow row shape, and where to go for richer data. Nothing needed to call it correctly 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?

One parameter (aircraftId) with 0% schema description coverage, so the description must compensate. 'By id' clarifies that the id is the AircraftList row identifier, but it adds no format, source, or example, and the parameter name is largely self-explanatory. Adequate but thin.

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 (get) and precise resource (a single AircraftList row) keyed by id, and explicitly scopes it as a 'fast header lookup'. It also names the sibling get_aircraft_detail and what that sibling is for, so the agent can distinguish the two without opening either 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?

Explicitly routes the agent: use this for lightweight header lookups, use get_aircraft_detail for charts and full derived stats. That names the alternative and the condition that selects it, which is exactly the when/when-not guidance expected.

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 the safety profile (readOnlyHint, destructiveHint=false, closed-world), so the description only needs to add behavior — and it does, disclosing that a miss returns null rather than raising an error. That is exactly the kind of context annotations cannot convey; it omits only cache/consistency or output-shape detail, which the output schema covers.

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 identifies the resource and key, a second sentence delivers the only surprising behavior (null on miss). Zero filler for a single-parameter lookup.

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 return-shape explanation is unnecessary and the null-on-miss note is a sufficient bonus. The only meaningful omission for a tool in this crowded sibling set is a pointer to Flight_search_airports for code-unknown cases.

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 0%, so the description must carry the parameter meaning, and it does: the single 'code' argument accepts either IATA or ICAO format and is referred to as 'id' elsewhere. Combined with the schema's ^[A-Z0-9]{3,4}$ pattern, an agent can construct a valid call without guessing.

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 — retrieve an airport row by IATA/ICAO code — which is precise enough to distinguish it from aggregate siblings like Flight_airport_stats or Flight_flights_by_country. It does not explicitly contrast with Flight_search_airports, the closest lookup sibling, so it stops short of a 5.

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 agent can infer this is an exact-key lookup rather than a search, but the description never says when to prefer it over Flight_search_airports or what to do when the exact code is unknown. No exclusions or prerequisites 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 already cover the safety profile (readOnly, non-destructive, closed-world), so the description's contribution is the added detail: pagination behavior, the { data, total } envelope, and the non-obvious normalization that hyphens are stripped from reg. It stops short of stating page-size caps or what total counts, but it does add real context beyond 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?

Front-loaded and dense: the resource and its filters come first, return shape last. A couple of terse internal references ("AircraftList scalar") add jargon without adding meaning, but nothing is padded.

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 9-parameter, filter-only read tool with an output schema and read-only annotations, the description covers the discriminating behavior (substring matching, hyphen stripping, sorting, paging envelope). The unmentioned ownopSearch and the absent default page/limit values are the only material omissions, and those are visible in the 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?

With 0% schema description coverage, the description carries the full burden and largely succeeds: it maps regSearch, country (2-letter constraint), icaoSearch/ownop as substring matching, usedBySearch, sortBy, and sortOrder with semantics the bare schema does not convey. Gaps remain — page/limit are only implied by "Paginated", and ownopSearch is never mentioned.

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 and operation: "Paginated aircraft directory (AircraftList)" with an enumerated filter set. It is clear what the tool returns, but it never contrasts itself with siblings like Flight_get_aircraft_from_list or Flight_get_aircraft_detail, so the agent must infer the boundary.

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 filters (reg, country, ICAO substring, usedBy) suggest this is the browse/search entry point before fetching a detail record. There is no explicit "use this when…" or "use X instead for…" statement, and no mention of the relationship to Flight_get_aircraft_detail.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: that filters are substring matches rather than exact equality, that results are paginated, and that the response is shaped as { data, total } with nested airport objects — details an agent cannot get from 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?

Two sentences, front-loaded with the core action and filter inventory, then the return shape. Efficient, with only the return-format sentence being arguably redundant given an output schema exists. No filler or repetition of the tool name as prose.

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 14 optional parameters and an output schema, the description covers the main filter families and the response envelope well. Gaps remain around pagination bounds (limit max 100, page starts at 1) and routing versus the aggregate siblings, but these are secondary for a filter-driven list tool whose annotations and schema carry safety and structure.

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 only 43% across 14 parameters, so the description must compensate and it does so partially: it clarifies substring semantics for aircraft id, airport/city, and country filters, and explains sortBy is a 'Flight scalar field' paired with sortOrder. It omits page/limit (despite calling the tool 'paginated'), flightId, and icaoType, leaving several of the undocumented parameters unexplained.

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) and resource (flight rows) plus its paginated nature and the filter dimensions available, so an agent understands what it returns. It does not differentiate itself from aggregate siblings such as Flight_flights_by_country, Flight_flights_by_year, or Flight_top_routes, which also expose flight data, so the agent must infer that this is the raw row-level listing.

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 phrase 'optional filters' implies this is the general-purpose query tool for flight rows, which hints at usage. However, there is no explicit guidance on when to prefer this over the many aggregation siblings (by_country, by_distance, by_year, top_routes), nor any stated prerequisites or 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?

With readOnlyHint, openWorldHint=false, and destructiveHint=false already present, the description adds useful behavioral context by stating that only large and medium airports are returned. It does not need to repeat the safety annotations, and it introduces no contradiction.

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 three short, front-loaded sentences with no wasted text. Search fields, scope, and intended workflow are each stated efficiently.

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 an output schema and safety annotations, so the description need not explain return values or read-only behavior. It covers the core search behavior and airport scope, though the limit parameter remains undocumented in prose.

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 should compensate. It explains the required q parameter well by listing searchable fields, but it does not mention the limit parameter or its constraints.

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 and resource: search airports by name, city, IATA or ICAO code. It also scopes the result set to large and medium airports, which distinguishes it from broader airport 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?

It gives clear usage context: use this to find an airport's ICAO code before calling other airport tools. It does not explicitly name alternatives or when not to use it, but the intended workflow is clear.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the sort order ('sorted by flight count descending') and the returned fields (city and country info), which is useful context beyond the annotations. It does not disclose the default limit of 20, the 100 cap, or how the date window affects the ranking, which are relevant behavioral facts.

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 short sentences ordered sensibly: purpose, filter dimensions, the bidirectional switch, return shape, then an example. The example partially restates what the second sentence already says, but nothing is egregiously padded.

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 return-shape sentence is a bonus rather than a requirement, and the read-only nature is covered by annotations. However, for a tool with 8 parameters where two are date bounds, omitting any description of the time window leaves a real gap in what an agent needs 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 only 13%, so the description must carry most of the load. It explains the country/airport filters and re-explains bidirectional (already documented in the schema), but dateFrom and dateTo — likely the most consequential parameters for a frequency ranking — and limit are never mentioned in either place.

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 and metric — 'Top flight routes ranked by frequency' — with the filtering dimensions named immediately after. It is distinguishable from siblings like Flight_flights_by_country or Flight_flights_by_distance by being route-centric, though it never explicitly contrasts itself with them.

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 a concrete worked example ('departureCountry=AU, arrivalCountry=ID, bidirectional=true') that shows exactly how to compose the filters for the intended use case. It stops short of naming alternatives or stating when another tool is preferable, so no exclusions are provided.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the shape matches UI visit history, which is a weak format cue and does not discuss pagination, auth, or other operational behavior; with an output schema present, this is modest added value.

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?

A single sentence with no repetition, front-loaded with the resource and scope. The parenthetical '(same shape as UI visit history)' is somewhat imprecise but not excessive.

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 read-only one-parameter tool with annotations and an output schema, the description states the resource and scope. Still, it leaves the parameter format and sibling selection implied, so it is adequate but not fully complete.

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 must compensate for the lone aircraftId parameter. It identifies aircraftId as an aircraft identifier but gives no format, source, or example; this is partial compensation only.

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 identifies a specific resource—visit timeline/history—and scopes it to one aircraft id, so an agent can infer it returns that aircraft's visit history. However, the noun-phrase wording ('structure') is less direct than a verb like 'Get', and it does not explicitly distinguish this from sibling tools such as Flight_get_aircraft_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?

No when-to-use guidance, no exclusions, and no alternative tool is named. The only usage cue is the 'one aircraft id' scope, leaving the agent to infer when this is preferable to get_aircraft_detail or airport_visits.

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