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

No annotations are supplied, so the description carries the burden, and it does disclose the key behavioral fact: this is a derived summary and per-flight detail is unavailable due to a server-side breakage. It also describes the aggregate return shape. It does not mention auth requirements, rate limits, or expected latency, which is why it falls short of 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?

Front-loaded with purpose, then parameter semantics, then the critical limitation note — a sensible ordering with little waste. The long enumeration of returned fields is somewhat redundant given an output schema exists, which keeps it from a top score.

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 3-required-param aggregate tool with an output schema and no annotations, the description covers purpose, inputs, and the major v1 limitation. The one remaining gap an agent might hit is how to obtain valid location ids, which is only implied by "bus location ids".

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% (bare titles only), so the description must compensate, and it does: origin_id/destination_id are identified as bus location ids covering the same city pair, and date is pinned to YYYY-MM-DD. That resolves the main ambiguity an agent would face — that despite being a flight tool, the ids are bus-domain identifiers.

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 scope up front: "Flight summary for a route + date" with the exact fields returned (counts, min/max price, durations, departures, direct flag, airlines). The parenthetical that it comes from the bus-journeys response distinguishes it from obilet_search_bus_journeys and obilet_journey_detail, so an agent can tell what it is without opening the 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?

Gives clear usage context by naming the city-pair scope and warning that individual flight listings are NOT available in v1 because the async endpoint is broken — that prevents a whole class of wrong attempts. It stops short of naming an explicit alternative (e.g. "use obilet_search_bus_journeys for the raw data") or saying the location ids must first come from obilet_search_locations, so it is not a full when/when-not map.

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 carries the full burden; it implies a read-only lookup and discloses that prices are quoted in TRY with a separate service fee and original price, which is genuinely useful. It never states whether availability/prices are live, whether results are cached, or any auth or rate-limit behavior, so an agent cannot fully predict the call's side effects.

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 with the one-line purpose, then a dense field inventory, with the id provenance moved to the end where it belongs. The field enumeration borders on redundant since an output schema exists, and the run-on list is slightly hard to scan, but there is little wasted wording.

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 lookup with an output schema present, this is largely sufficient: it explains the input's origin and signals the breadth of the return payload. The remaining gap is failure behavior for an invalid or expired journey_id, which the description does not address.

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 compensate; it does the most important thing by telling the agent where the opaque journey_id originates (obilet_search_bus_journeys). It does not add the integer type or say whether the id is stable across dates, but provenance is the key semantic gap and it is covered.

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: 'Full detail of one bus journey', then enumerates exactly what comes back (partner, stations, times, prices in TRY, stops). This clearly separates it from the list-oriented obilet_search_bus_journeys, though it never names that sibling as the 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?

The clause 'journey_id: from obilet_search_bus_journeys' does convey the required prerequisite (search first, then fetch detail), which is real usage guidance. However, there is no explicit when-to-use vs when-not, and no statement about what to do if the journey is no longer bookable.

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 supplied, so the description carries the full burden. It does disclose the aggregation semantics ('across all journeys'), the currency (TRY), and the computed statistics, which is real behavioral value; however it says nothing about whether it is a read-only query, how it behaves when no journeys exist, or whether results are cached or limited to certain carriers.

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 dense sentences with the returned metrics front-loaded and parameter notes second; no filler and no 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 simple three-required-parameter aggregate query with an output schema, the description covers purpose, returned metrics, and parameter formats adequately. The remaining gap is id provenance — how to resolve origin_id and destination_id — which an agent must guess from the sibling list.

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% — the schema gives only bare titles — so the description must compensate. It supplies the date format (YYYY-MM-DD) and characterizes origin_id/destination_id as bus location ids, which is useful, but it does not say where those ids come from (presumably obilet_search_locations) or whether they denote cities versus terminals.

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 (price statistics for a bus route + date) and enumerates exactly which statistics are returned (journey count, min/median/mean/max price in TRY). This clearly distinguishes it from obilet_search_bus_journeys, which lists individual journeys rather than aggregates, though no sibling is named 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 alternatives such as obilet_search_bus_journeys or obilet_journey_detail. The aggregate purpose implies a cheap overview use case, but the agent must infer that entirely.

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 supplied, the description carries the full burden and does disclose meaningful behavior: the default sort (

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 structure is good: the resource/scope line comes first, then a compact per-parameter block, then the return payload. It is dense but every clause carries information; only the trailing return-field enumeration is slightly verbose given an output schema exists.

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 5-parameter search tool with a declared output schema, nothing an agent needs in order to call it correctly is missing: id provenance, date format, sort options, and limit bounds are all stated. Return values are described even though the output schema already covers them, which is surplus rather than a gap.

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 and it does: origin_id/destination_id are explained as bus location ids with a worked example, date is pinned to YYYY-MM-DD with a sample, sort is given all three enum values with their ordering semantics and the default, and limit is bounded to 1..24. That covers all five parameters with meaning the bare schema does not convey.

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 statement ('Bus journeys for one route + date'), so the agent immediately knows this is a route/date search over bus inventory. It explicitly points at obilet_search_locations for the id source, but it never distinguishes itself from siblings like obilet_journey_detail or obilet_price_stats, which keeps it from 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?

It gives one real prerequisite: origin_id/destination_id must come from obilet_search_locations, illustrated with a concrete İstanbul Avrupa 349 -> Ankara 356 example. Beyond that there is no when-to-use versus when-not guidance, no mention of when to prefer obilet_journey_detail (for a specific journey) or obilet_price_stats (for price trends), so the selection logic across siblings is only implied.

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 supplied, so the description carries the behavioral burden. It does disclose a real quirk — bus ids are ints while flight ids are strings like "250_0" — and names the returned fields, but it says nothing about matching behavior (partial vs exact, Turkish character handling), result limits, or authentication needs.

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 purpose is front-loaded in the first sentence, followed by compact per-parameter notes and a closing routing hint. There is no filler; every clause, including the example ids, conveys usable 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?

An output schema exists, so the brief return-field mention is a bonus rather than a requirement, and both parameters are addressed despite zero schema coverage against a 2-parameter tool. The only shortfall for a search tool is the absence of guidance on match quality and ambiguity handling.

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, and it largely does: query is illustrated with concrete city examples, and kind is documented with both allowed values, the default, and the associated id type per mode. It still omits match semantics and whether an empty or ambiguous query is an error.

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 plus scope: search obilet.com locations (cities, towns, airports) by name. That is far more than the tool name alone and tells an agent exactly what kind of entity is resolved here versus the journey/detail 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 explicitly routes the agent forward: use the returned id in obilet_search_bus_journeys for bus or obilet_flight_summary for flight, and the kind parameter selects which. There is no explicit when-not-to-use or note about calling this without a downstream lookup, but the workflow context is clear.

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