stopover-planner

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

Discloses return values with status and payload, and polling recommendation. No annotations, so description carries full burden; it covers key behaviors but lacks error handling.

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 fluff. Every word contributes to understanding the tool's purpose and behavior.

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 response format and polling interval. No output schema, so description compensates well. Could mention what happens if job ID is invalid, but overall complete for simple polling.

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?

Only one parameter, jobId, which is implied as the background job ID but not explicitly stated. Schema has no description, so tool description adds context but could be more precise.

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 polls a search from a background-job tool and specifies the response format. It distinguishes from sibling search tools that initiate jobs.

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?

Describes when to use (polling a background job) and provides polling interval. Could explicitly mention not to use for synchronous results, but context 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?

With no annotations, the description fully carries the burden. It transparently states it runs as a background job, returns a jobId, and requires polling. No destructive actions mentioned, which is appropriate.

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 concise, front-loaded sentences with zero waste. Each sentence adds critical 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?

The tool has 5 parameters all documented. No output schema, but the description explains the return value (jobId) and how to retrieve results. Covers the main behavioral aspects despite no annotations.

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%, but the description adds value by explaining the aggregation purpose and providing additional context like 'must be real calendar dates' and 'country or continent'.

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 finds cheapest live fares from one origin to every destination city in a whole country, distinguishing it from sibling tools like search_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?

The description explains when to use this tool (scanning entire country) and mentions it replaces dozens of route searches. It also notes the asynchronous nature and need to poll get_job_result, providing clear context.

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?

No annotations provided, so description carries full burden. It clearly discloses the async behavior: 'runs as a background job: returns a jobId; poll get_job_result until done.' This is critical for correct usage. It does not mention rate limits or auth, but as a search tool, destructive concerns are minimal.

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 short sentences effectively convey purpose and usage pattern. No extraneous information; every word serves a purpose. Front-loaded with key functionality.

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 4 parameters with full schema and no output schema, the description explains the output nature (jobId, polling) and result contents (prices, links). It is sufficient for an agent to understand the workflow, though additional details on result format would be nice.

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 the schema already documents each parameter (dates, origin, oneway, nonstop). The description adds context like 'live GBP prices' and 'booking links' but does not enhance parameter understanding beyond the schema. Baseline score 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?

The description clearly states the tool finds cheapest destinations worldwide from an origin on given dates, with live GBP prices and booking links. It explicitly answers 'where can I fly cheaply' questions, distinguishing it from sibling tools like search_flights (specific flights) and search_country_sweep (likely country-level sweeps).

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 indicates this is for 'where can I fly cheaply' inquiries and notes it runs as a background job returning a jobId. While it implies the workflow (poll get_job_result), it does not explicitly state when not to use it or compare directly with alternatives beyond the sibling list.

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?

No annotations exist, so the description carries the burden. It discloses the synchronous nature, typical latency, and output fields (airline, price, duration, etc.). However, it does not mention error conditions, rate limits, or whether the tool is purely read-only (though 'Live' and 'booking link' imply no destructive actions).

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 concise sentences: first states purpose, second lists output fields, third gives performance context. No redundant information; front-loaded with the most critical purpose.

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?

Without an output schema, the description adequately covers returned fields (airline, GBP price, duration, stops, times, booking link) and performance. It could be more explicit about how multiple dates are handled (e.g., separate flights per date), but overall the description is complete for a search tool with 5 parameters.

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%, with detailed descriptions for each parameter (e.g., dates format and constraints). The tool description does not add significant meaning beyond what the schema already provides, though it reinforces that dates are one per array element and output includes GBP prices.

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 retrieves live Google Flights prices for one route across one or more dates, specifying the resource (prices), verb (search/live), and scope (one route, multiple dates). It distinguishes from siblings like search_country_sweep and search_explore_anywhere by focusing on specific route pricing.

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 explicit when-to-use or when-not-to-use guidance is provided. The description mentions synchronous timing (5-20 seconds), which implies it's suitable for real-time queries, but does not discuss alternatives or exclusions among the 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?

No annotations are provided, so the description bears the full burden. It comprehensively discloses the async job behavior, immediate jobId return, polling requirement, data source (Google Flights), currency (GBP), and booking links per leg. This is rich behavioral context.

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 focused and informative: first defines purpose, second clarifies scope, third explains async workflow. 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?

The description covers purpose, data source, currency, booking links, and async polling. It slightly lacks detail on the return value format (no output schema), but refers to get_job_result, which is adequate given the sibling tool context. For a moderate-complexity tool, it is mostly 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 coverage is 100%, so baseline is 3. The description does not add extra semantics beyond what the schema already provides for each parameter; it mainly describes overall behavior. Only minor context like 'live Google Flights data' adds value 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 clearly states the tool finds 'complete multi-day stopover itineraries between two cities' with specific details on legs, hub stay, pricing, and booking links. It distinguishes itself from siblings like search_flights by focusing on multi-day stopovers.

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 implicitly guides when to use the tool: for stopover itineraries with a hub city and multiple date splits. It mentions the async nature and polling requirement, providing usage context. However, it does not explicitly state when not to use it or compare directly with siblings by name.

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