Pro Flight Search Airport Delays

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about input flexibility (IATA, city, name) and the alias relationship, which is useful but does not contradict annotations. No additional behavioral details like error handling or ambiguous input handling are needed given 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: the first delivers the core purpose, the second adds input flexibility and alias info. No unnecessary words; front-loaded and efficient.

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 and rich annotations, the description adequately covers input flexibility and alias. It does not need to explain return values. Minor gaps like error handling are acceptable for a read-only tool with good structured metadata.

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 baseline is 3. The tool's free-text description reiterates that it accepts IATA code, city, or airport name, which adds little beyond the schema's parameter descriptions. The schema already provides sufficient meaning for both parameters.

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 clearly states the verb 'Get' and the resource: 'airport-level delay, cancellation, weather flight-rules, and 24-hour forecast context for one airport'. It also lists accepted input types (IATA code, city, name) and distinguishes from siblings by specifying 'for one airport' and noting the alias relationship.

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?

Description implies usage for retrieving delay status for a single airport with flexible input. However, it does not explicitly state when to use this tool versus its alias (get_airport_delay_status) or sibling search tools, nor does it provide exclusions or prerequisites.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds context about searching 'tracked airports' and returning IATA codes, which clarifies the scope and output beyond annotations. No contradictions.

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, consisting of two sentences that effectively communicate the tool's purpose, usage context, and relationship to an alias. No unnecessary words.

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 (single parameter, good annotations, output schema exists), the description is complete. It covers when to use, what it returns, and its relation to sibling tools, leaving no critical gaps.

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 provides a detailed description of the 'query' parameter with examples. The description mentions 'airport reference' but does not significantly add new information beyond what the schema already covers. Baseline 3 due to high schema description coverage.

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 that the tool searches tracked airports when a reference is ambiguous and returns IATA codes. It distinguishes itself from sibling tools like airport.get_delay_status and the alias search_supported_airports, making the purpose 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?

The description specifies when to use the tool ('when a user's airport reference is ambiguous') and mentions its output can be used with airport.get_delay_status, implying a chaining use case. However, it does not explicitly state when not to use it or compare with other search alternatives.

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 indicate read-only; description adds live data, 24-hour forecast, and input flexibility 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?

Two efficient sentences front-load key action and scope; zero unnecessary words.

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?

Covers input flexibility, data scope, and example queries; output schema covers result format, so description is sufficiently 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 has 100% parameter descriptions; description adds minor extra context (e.g., format usage note) but does not significantly add beyond 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?

Clear verb+resource: get live airport delay/weather data. Distinguishes from flight-number tracking but not from sibling 'airport.get_delay_status' which appears identical.

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?

Explicit calls to use for specific questions (e.g., 'are there delays at JFK'), but no when-not-to-use or alternatives for 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 provide safety profile (readOnly, idempotent, non-destructive). Description adds that it returns IATA codes but doesn't disclose additional behavior beyond what annotations and schema cover.

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 efficient sentences: first states purpose and trigger, second states output and next step. No wasted words.

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 with full schema coverage, output schema exists. Description covers trigger, output, and usage with sibling tool. Nothing 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 covers 100% of parameter 'query' with description and examples. Description only recontextualizes the trigger, not adding new parameter meaning. Baseline of 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?

Clearly states it searches airports when user's reference is ambiguous, returns IATA codes, and directs to use with get_airport_delay_status. Distinguishes from siblings by being a preliminary lookup.

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 says when to use: when airport reference is ambiguous and before calling get_airport_delay_status. Provides concrete examples (London, Chicago).

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