FlightFinder Aviation Safety Data

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context by specifying the output metrics and time range concept, but does not disclose additional behavioral details such as data freshness, coverage caveats, or response size.

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 dense sentence that front-loads the action and resource, then lists the specific statistics returned. Every word earns its place, with no fluff 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?

With one well-documented parameter, rich annotations, and an output schema present, the description provides all essential context for an agent to call this tool correctly. Nothing critical 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?

Schema description coverage is 100% and the single parameter 'family' is already documented with a type and example slug. The description reinforces the 'aircraft family' concept but does not add meaningful semantics 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 states a specific verb ('Aggregate') and resource ('safety statistics for an aircraft family'), and enumerates the exact metrics returned: occurrences, hull losses, fatal accidents, fatalities, and first/latest year. This clearly distinguishes it from sibling tools like get_accident or search_accidents, which target individual accidents rather than family-level aggregates.

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 intended use is implied: call this when you need aggregated family-level safety statistics rather than detailed individual accident records. However, it does not explicitly state when not to use it or name alternatives, leaving some inference to the agent.

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 description discloses the return fields (name, city, country, coordinates) which goes beyond the annotations. It also mentions the data source and license (CC0), providing additional transparency about the tool's 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?

The description is concise, one sentence, with the main action upfront and additional details following. It avoids unnecessary words and is well-structured.

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 lookup tool, the description is complete: it specifies the input, the output fields, and the data source. Combined with the annotations indicating read-only and idempotent behavior, an agent has sufficient context to use the tool effectively.

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 description repeats the parameter description from the schema ('ICAO ident or IATA code') without adding further detail about formats or examples. Since the schema already covers the parameter, the description adds no new semantic meaning.

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 purpose: resolving an airport by ICAO or IATA code. It uses a specific verb 'resolve' and identifies the resource (airport) and the data source (OurAirports). This distinguishes it from siblings like accident search 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 description does not provide any guidance on when to use this tool compared to alternatives. It only describes what it does, but does not explain scenarios or criteria for selection, such as needing airport details vs accident records.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds genuinely useful behavioral context beyond those hints: the data is public-domain, submitted by pilots/controllers, the default no-arg behavior returns multiple aggregate views, and state values must be lowercase hyphenated slugs. It does not discuss volume or edge cases, but the output schema likely 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?

Two sentences carry all the essential information with no filler. The resource and source are front-loaded, and the conditional behavior is stated compactly with the slug-format constraint included.

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 tool with one optional parameter, full schema description coverage, safety annotations, and an output schema, the description covers everything needed for correct invocation: no-arg behavior, per-state behavior, and the expected state format. There is no apparent missing operational information.

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 already documents the single state parameter at 100% coverage as a 'US state slug for a per-state breakdown.' The description adds the specific lowercase-hyphenated format requirement and clarifies that the parameter is optional and switches the response into state-level mode, which is more than the schema alone provides. 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 identifies a specific resource (FAA UAS/drone sighting reports), names the data source, and explains both invocation modes: no-arg gives national totals/yearly series/leading states and cities, while a state argument gives a per-state breakdown. This is unambiguous and naturally distinguishes the tool from the accident/laser/wildlife-strike siblings, even without explicit contrast.

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 usage context: call with no arguments for national aggregate data, or pass a state slug for a state-level breakdown. It does not explicitly list exclusions or alternatives, but the modes are concrete enough that an agent knows how to choose between them.

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 safety (readOnly, idempotent, non-destructive), and the description adds behavioral value by disclosing that the response includes source-attribution links and narrative references. This helps the agent know what kind of data to expect beyond a simple occurrence object. 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 a single, well-constructed sentence that leads with the core action and object, then appends the valuable response details. Every phrase earns its place, with no fluff 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 single-parameter read-only tool with a full input schema, rich annotations, and an available output schema, this description is sufficiently complete. It conveys the essential purpose and the notable extra content (source links, narrative references) without over-explaining. Missing explicit fallback guidance is minor given the tool's simplicity.

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 required parameter 'id' is fully described in the input schema as 'FlightFinder occurrence id', and the description repeats only that same notion. Since schema coverage is 100%, the description does not need to add much, but it also adds no extra format, validation, or usage details 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 states a specific verb ('Fetch'), a resource ('one occurrence'), and the key identifier (FlightFinder id), while also noting it returns source-attribution links and narrative references. This clearly distinguishes it from search_accidents (which searches multiple occurrences) and get_narrative (which likely fetches a narrative directly).

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 when the agent already has a specific FlightFinder id, but it does not explicitly state when to prefer this tool over search_accidents or get_narrative. No exclusions or alternative tool references are given, leaving the routing decision to inference.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond that: open-licensed sources return full text while others return a limited excerpt plus a source_url deep link, and id URL-encoding is handled automatically. This gives the agent important expectations about varying outputs.

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 tight sentences with no filler. The core action is front-loaded, followed by the two most useful operational caveats: licensing-dependent output and automatic URL-encoding. Every sentence earns its place.

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 description is sufficient for a read-only, two-parameter tool with a full input schema and an output schema. It covers the important licensing behavior and encoding detail. Minor gaps such as explicit error or not-found behavior are not necessary given the output schema and simple invocation model.

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. The description adds valuable parameter guidance by explicitly stating that 'id URL-encoding is handled for you — pass the raw case id,' which prevents a common mistake. It also reinforces that source is a source code, though the schema already covers that.

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: 'Fetch an investigation narrative by (source, case id).' It clearly distinguishes this tool from siblings like search_accidents or get_accident by identifying the required lookup key and mentioning the licensing-dependent return behavior.

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 the tool should be used when you already know a source and case id, and the schema points to list_sources for valid source codes. However, it does not explicitly contrast with alternatives such as search_accidents or explain when not to use it, leaving the routing largely to inference.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: what the no-argument call returns (national totals, injuries, yearly series), that state/airport arguments alter the breakdown, and that data is US-government public domain. Minor gaps such as invalid-slug handling are not disclosed, but the core behavior is clear.

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, front-loaded with the topic and then a compact explanation of argument-dependent behavior. Every clause earns its place, with no repetition of the tool name or schema field names.

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, the presence of an output schema, and annotations covering read-only/idempotent safety, the description is complete for correct invocation. It covers the no-argument return contents, the optional breakdown behavior, the slug format requirement, and the data provenance. Nothing essential for calling this tool 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?

The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds extra meaning by specifying the slug format (lowercase hyphenated) and the 'state OR airport' exclusivity, which goes beyond the schema's generic phrasing. This is genuinely useful guidance for constructing valid calls.

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 identifies the tool as providing FAA-reported laser incidents aimed at aircraft, with a specific verb implied by 'Reported' and a distinct resource (laser incidents). It distinguishes from sibling tools like wildlife_strikes and drone_sightings by naming the exact incident type, and it differentiates behavior by arguments: no args for national totals/injuries/yearly series; state or airport for breakdowns.

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 context: no arguments for national data, or pass a state/airport slug for a breakdown. It also states the required slug format and that state OR airport are alternatives, implying mutual exclusivity. It does not explicitly name sibling alternatives or when not to use the tool, but the domain clarity makes the choice straightforward.

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 mark the tool read-only, idempotent, and non-destructive; the description adds concrete behavioral context by stating the unfiltered scope ('every data source') and the exact fields returned. This exceeds what annotations alone convey, though it omits richer details such as pagination or data freshness, which are partly covered by 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?

A single well-structured sentence front-loads the action and scope, then packs the response fields into a compact clause. There is no redundant or filler content.

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 list tool with an output schema, the description provides all essential context: scope, returned attributes, and the full-vs-excerpt nuance. Nothing needed for correct invocation 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?

With zero parameters, there is no parameter burden for the description to carry; the baseline of 4 applies. The schema coverage is complete, and the description's field list compensates for any ambiguity about what the empty-schema listing returns.

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?

Description names a concrete action ('List every data source in the corpus') and enumerates the output attributes (license, homepage, narrative count, republication policy), making the tool's purpose unmistakable. It is naturally distinguished from the sibling accident/lookup tools, which are specific records rather than corpus metadata.

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 clearly implies this is the go-to for a corpus-level inventory, but it does not explicitly state when to use it versus alternatives or mention any exclusions. Usage context is inferable from the zero-parameter design and sibling names, not 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 signal read-only, idempotent, and non-destructive behavior, and the description adds value by explaining the merged and deduplicated corpus, source-attribution links, and pagination cursor. No contradiction exists between description and 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?

Three tight sentences front-load the purpose, then list filters, then state the return shape. There is no filler and no unnecessary repetition of schema details.

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 conveys corpus provenance, filtering capability, result shape, and pagination mechanism. An agent has enough to decide to call it and understand paging without opening any sibling 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?

The input schema already describes every parameter with formats, defaults, bounds, and examples, giving 100% coverage. The description's filter list summarizes the schema but adds no new meaning or syntax beyond it, so the 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 opens with a specific verb and resource: 'Search the merged aviation-accident corpus...' It adds distinguishing scope ('80+ official agencies, occurrence-level dedup') and names concrete filters, clearly separating it from sibling get_accident/get_narrative style 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 description establishes clear context: it is the list/search entry point across the merged corpus, with filters and pagination. It does not explicitly state when to prefer get_accident for a single record or get_narrative for narrative text, so it stops short of a 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 read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: default no-argument behavior, the yearly series since 1990, the breakdown options, and slug format expectations. It does not contradict 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?

Three sentences, each earning its place: source/licensing, default mode, and filtered mode with slug format. The most important usage distinction (no args vs one arg) is front-loaded before parameter details.

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 tool with two optional, fully documented parameters and an output schema, the description is complete. It explains what happens with no arguments, what happens with each filter, and how to format slugs; nothing needed for a correct call 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?

The schema already covers both parameters at 100%, but the description adds meaningful semantics: airport and species are alternatives ('OR'), they request 'that breakdown', and slugs are lowercase and hyphenated with concrete examples. This gives an agent everything needed to construct a valid 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 identifies the FAA National Wildlife Strike Database as the resource and enumerates what it provides: global totals, yearly series, leading airports/species/flight phases, or per-airport/per-species breakdowns. It lacks an explicit verb like 'retrieves' or 'returns', but the resource and scope make its purpose unambiguous and distinct from accident-focused siblings.

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 modes: call with no arguments for global aggregates, or pass airport/species for a breakdown. However, it does not explicitly state when to prefer wildlife_strikes over sibling tools or provide exclusions, so an agent must infer tool selection from the resource name and content.

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