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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: prices are Toman per adult, the departure terminal field matters because Tehran has several terminals, and the source site provides no arrival time. Those caveats are exactly what an agent would otherwise discover only from the results.

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 core capability and scope land in the first clause, and the following sentences are short and load-bearing rather than filler. Minor structural oddity: the `from_terminal` note concerns an output field but sits mid-description, slightly interrupting the input-oriented flow.

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 no output schema, the description carries the return-value burden and does so: it lists the result fields and flags the missing arrival time. Currency units are stated. It stops short of describing pagination or total-count behavior behind `limit`, which is a modest gap for a search 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?

Schema description coverage is 100%, so origin/destination formats, date patterns, sort enum, limit bounds and only_available are already fully documented. The description's only additional detail, `from_terminal` and per-adult Toman pricing, describes return values rather than inputs. Baseline 3 applies.

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 a specific verb and resource ("Search intercity bus tickets") and bounds the scope precisely: two Iranian cities, one day. It also enumerates the returned fields (company, bus type, times, price, seats). It does not distinguish itself from the sibling al_buses_cheapest, so an agent must infer the split.

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?

Usage is conveyed only through an example query ("buses from Tehran to Shiraz tomorrow"), which implies the when-to-use context. There is no statement about when not to use it, and no routing to al_buses_cheapest or al_bus_seats even though both are close 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 already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely non-structured behavior: each call fans out into one search per day (a latency/cost signal), prices are in Toman per adult, only buses with a free seat are counted, and days with no qualifying bus return no price rather than an error.

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 short sentences, front-loaded with the output shape and then the routing rule. The only blemish is the mid-sentence parenthetical '(the site has no bus calendar)', which interrupts the main clause and could be folded into the following sentence without loss.

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?

There is no output schema, so the description must carry the return contract, and it does: per-day lowest price, per-day bus count, currency and unit (Toman per adult), the free-seat filter, and the empty-day representation. Nothing an agent needs to interpret a result or size its request 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 coverage is 100%, so all four parameters are already documented, making 3 the floor. The description still adds value by framing `days` as a cost dial ('keep `days` small') and by situating `date` as the anchor for the per-day walk, which the schema's 'starting at `date`' only partly conveys.

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 concrete verb and result shape: 'List the lowest bus price and the number of buses for each day from a start date.' It also names the exact sibling it competes with (al_buses) and states the condition that selects this one, so an agent can route without opening either 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?

Explicit routing guidance: 'Use before al_buses when the date is flexible' tells the agent both the alternative and the deciding condition (date flexibility). It adds a practical constraint — 'It runs one search per day, so keep `days` small' — that governs how to invoke it, not just whether to.

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 the safety profile (read-only, idempotent, non-destructive, open-world), so the description's job is to add the rest — and it does: the tool does not book, statuses mean available/male-booked/female-booked/blocked, and blocked seats are not for sale. It stops short of describing response shape or edge cases like a bus with no seat data, but adds solid behavior 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?

Front-loaded with the return content, then usage, then the layout/status decoding — no filler sentences. The layout explanation is dense and could be slightly crisper, but every clause carries operational meaning.

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?

There is no output schema, yet the description explains what comes back (counts per status, free seat numbers, per-seat row/column layout), what the statuses mean, and how the aisle splits columns. For a single-object lookup tool with fully documented params, nothing essential to 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?

Schema coverage is 100%, so every parameter is already documented with format, patterns and examples. The description corroborates that departure_time and company disambiguate the bus, but repeats what the schema already states rather than adding new semantics; baseline 3 applies.

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: show free seats on one bus, returning counts per status and free seat numbers, and explicitly says no booking occurs. This clearly separates it from al_buses, which finds/list buses rather than inspecting a single bus's seat map.

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 an explicit trigger ('Use after al_buses when the user cares where they sit or asks how full a bus is') plus the sequencing prerequisite and how to pick the bus among several (departure time plus company). The agent knows both when to call it and what data it needs first.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is free; the description still adds real value by disclosing return-field semantics — `code`, `train`/`flight` booleans, and `whole_city` rows whose code ends in ALL. It stops short of describing result volume, ordering or empty-result behavior, which is the only remaining behavioral gap.

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 core action, then the sequencing rule, then return-field semantics — a sensible priority order with no filler. The parenthetical "a tiny train stop may have no buses" and the ALL-code note are dense but each carries non-obvious 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?

With no output schema and only three optional parameters, the description supplies what an agent actually needs: how to query, which field to propagate, how to interpret the flags, and the international branch. The only minor omission is that it never mentions whether codes also feed al_stays or al_hotels, which is peripheral to calling the tool correctly.

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, but the description goes beyond the schema by tying international=true to a concrete consumer (al_flights_international) and giving world-city examples, and by clarifying that bus codes reuse the train codes. It does not expand on `limit` or query matching rules, which the schema already handles.

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 — look up city codes and what is sold per city — with concrete examples (THR for Tehran, MHD for Mashhad). It is unmistakably the code-resolution tool, distinct from al_trains, al_buses and al_flights which consume its output.

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?

"Use first when the user names a city" gives an explicit trigger, and it names the downstream alternatives (al_trains, al_buses, al_flights) plus the international case that feeds al_flights_international. A branch condition (international=true) is spelled out rather than 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?

Annotations already declare this a read-only, idempotent, non-destructive open-world lookup, so the safety profile is covered. The description adds genuinely useful behavior beyond that: fares repeat per flight across fare classes, prices are quoted in Toman per adult, and return_date/refund_rules change the result shape by adding `returning` and `refund_penalties` lists. It stops short of describing pagination behavior for limit or any rate/quota constraints.

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 core action and scope come first, followed by pricing/duplication caveats and then sibling routing, which is the right ordering. The parenthetical about `child_price_toman` and `infant_price_toman` is slightly compressed and reads awkwardly, but nothing is wasteful enough to cut.

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 an 11-parameter search with no output schema, the description covers the essentials: what is searched, what comes back at a field level, how optional parameters alter the response, and where to go for other cases. The only real gap is that the exact response envelope and pagination behavior are left implicit.

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 baseline is 3; the description earns above that by explaining the *effect* of parameters on the response rather than just restating them — return_date adds a `returning` list, refund_rules adds `refund_penalties` per fare, and the passenger counts are for group pricing in Toman. It also hints that repeated rows represent distinct fare classes, which the schema does not say.

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: "Search domestic flights between two Iranian airports on one day", then enumerates returned fields (airline, flight number, times, fare, seats). It immediately distinguishes itself from the sibling tools by the word "domestic" and by naming al_flights_international for foreign routes.

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?

Provides a concrete usage example ("flights from Tehran to Shiraz on 2026-11-12") and explicit routing rules to alternatives: use al_flights_cheapest for other days and al_flights_international for flights abroad. It also states which optional parameters to set for round trips, refund tables, and groups.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: fares are in Toman per adult, pricing is one-way domestic, and days without a flight are omitted rather than returned as nulls — a data-shape detail an agent needs. No output schema exists, so the return format is only partially characterized.

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, zero filler: purpose and scope first, then the relationship to the sibling and the pricing/missing-day conventions. Every clause 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?

For a four-parameter read-only search tool with rich schema descriptions and a full annotation set, the description supplies what structured fields cannot: currency unit, one-way domestic scope, and the sparse-day convention. Minor gaps remain — whether round trips are supported and what the per-day record contains — but nothing blocks correct invocation.

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 origin, destination, date, and days are fully documented in the schema, including Persian/English/code formats, Jalali vs Gregorian dates, and the 1–15 range for days. The description adds only the 'per adult' currency framing and the per-day iteration semantics, which is baseline for a fully documented 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?

States a specific verb and resource ('List the lowest domestic fare for each day') with clear scope — domestic, per-day, from a start date — and the stated goal ('pick the cheapest day to fly'). This is plainly distinguishable from the sibling al_flights, which the description names.

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 'Use before al_flights when the date is flexible,' naming the alternative and the condition that selects it. It stops short of stating the inverse (use al_flights when the date is fixed) or that international routes belong to al_flights_international, but the routing signal is strong.

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?

Well beyond the annotations, it discloses latency (10-20 seconds), the underlying mechanism (airlines answer one by one, at most 12 polls per call), default ordering (cheapest first), the returned fields, the fact that total_toman is the whole-group price, and that charter fares collapse to a single fare class. It also clarifies the tool is search-only and buying happens off-platform, which is important given openWorldHint.

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 scope statement and an example immediately after, then packs return-trip, pricing, and latency notes into compact clauses. Density is high but slightly crowded by the parenthetical aside about cities Alibaba sells.

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 12-parameter tool with no output schema, the description covers the response shape (airline, flight numbers, times, stops, baggage, price per adult), price semantics, round-trip behavior, and latency expectations. What remains unaddressed is how results are truncated at the limit/poll cap or what an empty result looks like.

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 already 100%, so the baseline is 3; the description adds real meaning on top by explaining that return_date produces a `return` leg on each fare and that THRALL expands to all Tehran airports. It leaves behavioral params like sort, limit, and cabin entirely to the schema, which is acceptable given the 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?

States a specific verb and resource plus scope: "Search international flights between Iran and abroad ... on one day," and gives a concrete example query. The scope is clear enough to distinguish it from al_trains/al_buses/al_stays, but the parenthetical "(or any two cities Alibaba sells)" muddies the international qualifier, and the sibling al_flights is never named as the domestic counterpart.

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 an explicit use case ("Use for 'flights from Tehran to Istanbul on 2026-11-16'"), tells the agent to pass return_date for round trips, to source city codes from al_cities with international=true, and to hand off purchasing to alibaba.ir. It stops short of explicitly excluding al_flights and al_flights_cheapest, so the domestic/summary siblings must be inferred.

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 annotations already establish a read-only, idempotent, non-destructive open-world operation. Beyond that, the description discloses total-stay pricing in Toman, the meaning of price_per_night_toman, parity with the site's list and count, and possible multi-second latency while hotels respond.

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 front-loads the purpose and follows it with a compact example, pricing semantics, source consistency, and latency. Each sentence contributes actionable information without substantial repetition or unnecessary 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 an eight-parameter search with fully documented inputs, the definition supplies enough context to select and invoke the tool and interpret its core prices. Listing result attributes partly compensates for the absent output schema, though explicit sibling differentiation and any important availability or freshness limitations would make it more 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 description coverage is 100%, so the structured input documentation already does most of the work. The example usefully shows several parameters working together, but it adds little input syntax or constraint information beyond the schema; the pricing clarification primarily concerns output fields.

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 opening sentence gives a specific verb and resource—searching hotels in a city—and identifies key result attributes such as stars, rating, meal plan, and perks. Domestic and international scope is stated, but the description does not explicitly distinguish this tool from the potentially overlapping al_stays or al_stay_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?

The explicit 'Use for' example provides a concrete natural-language request involving a city, star preference, stay length, and Jalali date. This gives clear selection context, although there is no when-not guidance or routing to an alternative sibling.

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 read-only, idempotent, non-destructive, open-world semantics, and the description adds information they cannot: prices are in Toman per night with the specific fields (price_base weekday, price_weekend, price_holiday), the calendar exposes availability plus nightly price, and guest names are deliberately omitted. That redaction and unit disclosure is genuine behavioral context, though nothing is said about missing/invalid ids or result 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?

Front-loaded with the capability and its return facets, then a short usage-routing sentence, then unit/field clarifications. Dense but nearly every clause carries information; the parenthetical field names are slightly listy but earn their place by anchoring the pricing semantics.

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 no output schema, the description carries the return-value burden and does so by enumerating the facets and the price/calendar structure. Only edge behavior (invalid id, empty reviews, calendar_days=0) is unaddressed, which is a minor gap for a read-only detail 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that calendar entries carry both availability and that night's price, and that price fields are per-night in Toman, which makes the reviews and calendar_days parameters' output concrete.

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 ("Show one villa or holiday home in full") and enumerates the returned facets: capacity, beds, amenities, house rules, cancellation terms, calendar, reviews. This clearly separates it from the list-level al_stays and from al_hotels, which is a different property type.

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 sequencing: "Use after al_stays when the user wants to decide on a place" tells the agent both the prerequisite call and the intent that triggers this one. It does not state exclusions (e.g., that hotels belong to al_hotels), so it stops short of full when/when-not guidance.

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 the annotations (readOnly, idempotent, open-world, non-destructive), the description discloses genuinely useful behavior: prices are in Toman with VAT excluded, the sort applies only to the first 100 places the site returns, and `found` is the full count rather than the returned count. It also states data provenance (Jabama listings sold through alibaba.ir), which matters for an agent assessing result trustworthiness. That is real added context the structured fields do not carry.

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, then the example, then the pricing and pagination caveats, then the handoff to al_stay_detail — a logical order with little filler. It is somewhat dense in field names (`price_per_night_toman`, `price_total_toman`, `found`) that concern results rather than invocation, which costs a point on tightness.

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 an 11-parameter search tool with no output schema, the description covers what an agent most needs: what it searches, a usage example, currency and VAT semantics for the price fields, the sort truncation at 100 with `found` as the true count, and where to go for per-listing detail. The remaining unknowns (result object shape) are delegated sensibly to al_stay_detail.

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 baseline is 3, but the description adds meaning on top: it clarifies the currency of price filtering and explicitly limits what the `sort` parameter actually operates over (the first 100 site results). That sort-scoping detail materially changes how an agent should interpret ordering results and is not in 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 opens with a specific verb and resource set: "Search villas, suites, cottages and other holiday homes for rent in a city, with price, rating and capacity." That is far more than a restatement of the name and tells an agent exactly what corpus is being queried. It stops short of 5 because it never explicitly contrasts itself with the sibling al_hotels tool, which an agent could plausibly confuse it with.

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?

A concrete worked example ("a villa in Masuleh for 4 people next weekend") anchors the intended use case, and the description routes onward to al_stay_detail for calendar, rules and amenities. It gives no explicit when-not guidance, such as when to prefer al_hotels over this tool or what to do if no results are returned.

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, the description discloses return composition (hotel, stars, rating, room, meal plan, transport, per-person and group price), latency/polling behavior ('at most 15 polls per call'), and that purchase must happen on alibaba.ir. This adds substantial operational context not covered by readOnly/openWorld/idempotent hints.

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 front-loads the purpose and then packs useful example, result, latency, and purchase-path information into a compact block. A few phrases are dense, but there is no obvious filler.

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 9-parameter, open-world search tool with no output schema, it explains what comes back, how quickly, and that the tool does not complete a purchase. The main completeness gap is the lack of explicit comparison to al_tours_cheapest, which matters given 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 100%, so all nine parameters are already documented in the schema. The description reinforces that prices are per person and for the whole group and describes the package result, but adds little parameter-specific meaning 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 gives a clear verb and resource — searching tour packages that bundle round trip and hotel — and scopes it to city-to-destination searches with example destinations. It does not differentiate from the close sibling al_tours_cheapest, and the phrase 'cheapest package' per hotel may blur that boundary.

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 provides a concrete usage example ('a 3-night Kish tour for two from Tehran next week'), which gives clear context for selecting the tool. It offers no explicit when-not guidance or comparison to alternatives such as al_tours_cheapest.

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 the safety profile (readOnly, idempotent, non-destructive, open-world), but the description adds substantive behavior: prices are Toman per person, they are per-tour for `nights` nights, and days with no tours are omitted rather than zero-priced. That sparse-result disclosure is exactly the kind of trait an agent needs before interpreting the response.

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 short sentences, each carrying distinct information (scope, sequencing, price semantics), with the core behavior front-loaded. The only blemish is awkward mid-sentence line breaks that slightly hurt scannability.

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 no output schema, the description must convey the return shape, and it does: a per-day lowest price keyed to the 11-day window, in Toman per person, with missing days absent. It stops short of specifying ordering or whether a full day-by-day object is returned, which is a minor remaining gap for a tool with no output schema.

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 all four parameters are already documented in the schema, including the Gregorian/Jalali date rule and the `nights` counting convention. The description restates the nights basis and adds the per-person price framing but adds no new parameter syntax or constraints, so the baseline 3 applies.

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 (list the lowest tour price per person) plus the exact scope: 11 departure days, 5 before and 5 after a given date. It also names the sibling al_tours as the contrasting tool, so an agent can distinguish it without opening either 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 an explicit selection rule — 'Use before al_tours when the date is flexible' — and a follow-up rule — 'Then call al_tours for the chosen day.' Both the when-to-use condition and the alternative tool are named directly.

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 and idempotent, and the description adds substantive behavior on top: prices are in Toman per adult, seats_left 0 means sold out, return_date adds a separate `returning` list, and suppliers error out during a post-midnight maintenance window so a retry in a few minutes is expected. That error-window warning is exactly the operational context annotations cannot carry.

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-loads the purpose, then the trigger example, then behavioral caveats; almost every sentence carries new information. Slightly dense with parenthetical code lists, but nothing is padding.

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 10-parameter, output-schema-less tool, the description sufficiently covers return fields, currency units, sold-out semantics, and a known failure mode. It leaves sort/limit/passengers behavior to the schema, which handles them adequately.

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 every parameter including date formats, city codes, and enum values. The description adds only marginal semantics beyond that – the meaning of a zero seats_left and the `returning` output list – plus a restatement of the class codes. Baseline 3 fits.

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 ('Search train tickets between two Iranian cities on one day') and enumerates what comes back: company, class, times, price, seats left. The sibling al_trains_cheapest is named as a distinct tool, so an agent can route without opening either 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 a concrete trigger example ('trains from Tehran to Mashhad on 1405-08-20') and an explicit alternative with its condition ('Call al_trains_cheapest to compare prices over the following days'). It does not address the non-rail siblings (al_buses, al_flights) or say when a rail search is the wrong choice, leaving some routing 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?

Beyond the annotations' safe, read-only profile, the description clarifies that prices are in Toman per adult and that a missing day means no train operates. It does not discuss price freshness or availability, but the added output semantics are useful and prevent misinterpretation.

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 compact and front-loaded with the tool's purpose, followed by workflow guidance and two important result-interpretation details. Every sentence earns its place without repeating schema-level constraints.

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 four-parameter lookup with complete schema descriptions and clear safety annotations, this supplies the information needed to select and invoke it correctly. It also covers the conceptual result shape, units, and empty-day meaning despite the absence of an output schema.

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%, including date formats, day ranges, and accepted city identifiers. The description's reference to a start date reinforces the schema but adds little parameter guidance beyond it, so the high-coverage baseline of 3 applies.

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 gives a specific verb, resource, and scope: listing the lowest train price for each day from a start date. It also distinguishes the tool from al_trains by positioning it as the flexible-date, cheapest-day selection step.

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 says to use this tool before al_trains when the travel date is flexible. This provides both a clear usage condition and the appropriate sibling tool for the subsequent search.

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