Google Flights Search (Real-Time Fares)

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

The description discloses behavioral traits beyond annotations: it requires a RapidAPI key, notes that each date/destination combination is a billed request, and mentions that the API usage count and quota come back in the response. It also describes the output fields including price_insights, which helps the agent understand the tool's behavior. No contradictions with annotations (readOnlyHint, openWorldHint etc.) are present.

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 at four sentences, each earning its place. It is front-loaded with the purpose, then covers inputs/outputs, usage guidance, and billing. No redundant or extraneous 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?

Given the tool's complexity (20 parameters, output schema exists), the description covers the essential use case well. It explains the key inputs, outputs, and usage patterns. The existence of an output schema reduces the need to detail return values. However, a few commonly used parameters like 'limit', 'sort_by', and 'currency' are not mentioned, which could improve completeness.

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 adds meaning for key parameters (origin, destination, departure date, date range) and mentions outputs like price, airline, duration. However, with 20 parameters and 0% schema description coverage, many parameters (e.g., limit, sort_by, currency, max_price, max_stops, seat_type, etc.) are not described. The description covers the core use case but does not fully compensate for the low schema 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 the tool's purpose: 'Search real-time one-way flights on Google Flights.' It specifies the verb 'search' and the resource 'one-way flights', distinguishing it from the sibling tool 'search_roundtrip_flights'. The title also reinforces the one-way focus.

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 provides explicit guidance: 'Use it for any one-way fare question, including open-ended ones.' It instructs on how to make efficient calls: 'For a flexible search make ONE call with a date range and/or several destinations -- do NOT call it once per date.' An example ('Cheapest flight to Sri Lanka anywhere in October' is one call) further clarifies best practices.

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?

Beyond annotations (readOnlyHint=true, openWorldHint=true), the description adds that the tool returns real-time data, pairs legs, and provides total price, per-leg details, a buy_link, and api_usage. It also explains the billing model. No contradiction with annotations. This adds meaningful behavioral context, especially the pricing and output 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?

The description is efficient with three focused paragraphs: purpose/output, usage guidance, and billing/auth. It is front-loaded with the key verb and resource. No fluff or repetition. Could be slightly more structured but remains clear and concise.

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 complexity (19 parameters, no schema descriptions, but output schema present), the description covers the core use case well and mentions key return fields. However, it lacks details on many optional parameters, pagination, or sorting behavior. The presence of an output schema partially offsets the need to describe return values, but parameter usage guidance is insufficient for a complete understanding.

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 19 parameters and 0% schema description coverage, the description only explains a few core parameters (origin/destination, departure date/range, return date/nights). It does not cover many others like limit, sort_by, currency, max_price, seat_type, passengers, stops, airline filters, etc. Given the high parameter count and lack of schema descriptions, the description should provide more guidance on these optional 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?

The description clearly states it searches round-trip flights on Google Flights, distinguishes from one-way by noting 'priced as paired legs rather than two separate one-ways', and contrasts with the sibling tool search_oneway_flights by implication. The verb 'search' and resource 'round-trip flights' are specific, and the description adds context about data source and pricing model.

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 explicitly says 'Use it for any return-trip fare question' and provides guidance on flexible date searches using departure_date_from/to and nights. It also mentions billing implications per date/destination combination and the requirement for a RapidAPI key. However, it does not explicitly state when not to use it (e.g., for one-way trips), but the name and context imply the alternative.

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