MBD Travel

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds capability-boundary context the annotations cannot: that no continent/region/theme grouping exists and that only destinations (not tours) are returned. It stops short of any note on pagination or result limits.

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, zero filler, with the core capability and the default scope front-loaded ahead of the exclusion clause.

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 present, return shape need not be described, and the description covers scope semantics, defaults, and the key negative constraint. Nothing an agent needs before calling this read-only listing tool 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 description coverage is 100% and all four parameters are documented there, so the baseline is 3. The description only restates the scope enum and adds that 'cities' pertains to one country, which is useful but marginal over 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?

States a specific verb and resource ('Lists catalogue countries and cities') plus the payload ('their published tour counts'). The closing line 'Returns destinations only, not tours' explicitly separates it from the tour-oriented siblings (search_tours, get_tour, compare_tours).

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 the three valid scopes with the condition that selects each ('cities (of one country)', 'featured (default)'), and rules out unsupported groupings. It never names a sibling tool to use instead for tour data, so the routing guidance is implicit rather than explicit.

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, closed-world), so the bar is lower, and the description still adds real value: it discloses that every field of each tour is returned, that no winner/score/verdict is produced, and that nulls remain null. That last point is an important expectation-setter an agent could otherwise misread.

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, front-loaded sentences with no filler, and the negative disclosure ('no winner, score or verdict') is placed prominently. Minor redundancy between 'with the same fields' and 'returns every field of each tour' keeps it just under a 5.

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 read-only comparison tool with an output schema present and annotations covering safety, the description is nearly sufficient: return shape, scope, and the absence of a verdict are all addressed. Missing only usage/routing guidance and any note on invalid or duplicate slugs.

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 67%: currency and language carry their own descriptions and the slugs array documents minItems/maxItems/uniqueItems, so the schema does most of the work. The description's 'two to four tours' reinforces the slugs cardinality and adds the 'same fields' comparison semantics, but no new format or syntax detail.

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 ('compare') and resource ('tours'), and pins the scope at two to four tours, which the agent can immediately distinguish from single-tour tools like get_tour. It falls short of a 5 only because it never names a sibling to route against.

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 mechanics and output shape but gives no when-to-use context or alternative: no guidance on choosing this over get_tour for one tour or search_tours when merely browsing candidates. Nothing is misleading, but the agent gets no routing help.

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, closed-world behavior, so the bar is lower. The description adds real context beyond them: unpublished records return NOT_FOUND, currency is switched by editing the id rather than a parameter, and a tour record's shape (itinerary, inclusions, exclusions, hotels, departures) plus explicit disclosure of what it lacks.

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 value, then id format, then currency mechanics, then edge cases. Every sentence carries information; nothing is padding, even the compact 'names what it lacks' clause conveys missing-field disclosure.

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 one-parameter read tool with an output schema and full annotation coverage, this is nearly complete: id syntax, currency behavior, record shape and the NOT_FOUND case are all covered. The remaining hole is sibling disambiguation against get_tour and search.

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% and there is only one parameter, but the description is where the id grammar actually lives: the <type>:<lang>:<currency>:<key> format and the note that changing the currency segment switches currency. That is genuine meaning beyond the schema's circular 'format as in the tool description' text.

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 and resource: returns full text, price and site link for a record id. It is clear what the tool produces, but it never distinguishes itself from siblings like get_tour or search, so an agent must guess which fetch-style tool to reach for.

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 only implied: the required id parameter and the stated id format suggest 'call this when you already have a record id.' There is no explicit when-to-use guidance and no routing away from get_tour or search, which overlap heavily with this tool.

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, closed-world), so the bar is lower; the description still adds useful behavior beyond them: deterministic ordering (soonest first), the selection criterion (departure date, not price/discount), and the explicit absence of date/destination filters. Deduction: it references a 'windowDays' input that does not exist in the schema, which is stale/incorrect behavioral detail.

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 behavior (what it returns and ordering) before caveats, and no sentence is pure filler. The keyword enumeration ('last minute, near-term, urgent, right away...') is somewhat padded, but it plausibly serves query-intent matching.

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 present, return values need no explanation, and annotations carry the safety profile. The description supplies everything else an agent needs: scope, sort order, selection basis, and the lack of date/destination filters.

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 limit, currency, and language are already fully documented and the baseline is 3. The description adds nothing about those parameters, and its only parameter-related sentence refers to a nonexistent 'windowDays', which is mildly misleading rather than additive.

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 (returns tours) plus a precise scope: departures soon, sorted soonest first, selected by departure date only. It also disambiguates from a discount-style listing ('it is not a discount') and from filtered searches ('no date range or destination filter'), so an agent can distinguish it from search_tours/search without opening schemas.

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 intent list (last minute, near-term, urgent, right away, this week, airfare-price) tells the agent exactly which user phrasings should route here, and the 'not a discount' and 'no date range or destination filter' clauses set expectations for when NOT to use it. However, it never names a sibling tool as the alternative for filtered searches, leaving that 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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description still adds real value: past departures are excluded, prices are untrimmed so every occupancy slot is present, and the returned dates are guaranteed to be the catalogue's complete set. Missing only operational details such as auth or rate limits.

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 what is returned, then constraints, then paging — a sensible order. One mild redundancy: 'with the price of every occupancy slot' and 'every occupancy slot is listed' restate the same guarantee.

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 return shape needn't be explained, and the description covers the remaining gaps an agent would care about: exclusion of past departures, completeness of the date set, and the pagination contract. Only the date-range filter behavior is left entirely to the 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 86%, so the schema already documents from/to, limit, cursor, currency and language. The description reinforces the default page size and the cursor-based paging contract but adds no syntax or constraint detail beyond what the schema already provides.

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 ('Returns a tour's departures') and immediately scopes the payload to per-occupancy-slot pricing (adult, single, extra bed, children, infant). This clearly separates it from get_tour (catalogue detail) and search_tours (discovery) without needing any schema inspection.

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 implied by the content description and the 'past departures are excluded' constraint, but the description never says when to call this versus get_tour or search_tours, nor names any alternative. An agent can infer the intent but gets no explicit routing 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavior beyond that: unpublished tours fail with PRODUCT_NOT_FOUND, absent data is surfaced in a `missing` field rather than omitted silently, and pricing is deliberately limited to the first departure — all useful for interpreting 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?

Front-loaded with the core purpose and then a compact inventory of returned fields, with the edge cases (missing, PRODUCT_NOT_FOUND, first-departure-only pricing) at the end. It is dense but every clause carries information; a bulleted list of fields would read slightly better than the run-on sentence.

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 field inventory is somewhat redundant, but the description still covers the things the schema does not: the unpublished-tour error code, the `missing` fallback for empty fields, and the pricing scope. Nothing an agent needs to call it correctly appears to be absent.

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 clear descriptions for slug (product.slug), currency and language, and both enums are spelled out. The description adds essentially nothing about parameter meaning beyond the fact that currency drives the quoted price, 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?

Opens with a specific verb+resource ('Returns one tour') and enumerates exactly what the record contains: description, airline, nights, itinerary, inclusions, hotels, upcoming departures and first-departure pricing. The closing line 'Only the first departure is priced here' cleanly separates it from get_departures, so an agent can pick between the two 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?

Usage is only implied: the note that only the first departure is priced here hints that get_departures is the tool for full pricing, and PRODUCT_NOT_FOUND explains an unpublished-slug outcome. There is no explicit 'use this when…' statement or named alternative, so the agent must infer the routing.

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 readOnlyHint/idempotentHint/no destruction, and the description adds genuinely new behavior: no supplier call (consistent with openWorldHint=false), no price returned, results carry a hotelId, and the no-match branch returns nearby MBD hotels plus a contact link. Disclosing fallback behavior on empty results is exactly the kind of trait annotations cannot express.

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?

Four tight sentences, front-loaded with what the tool is before the matching rules and the no-match behavior. The parentheticals are dense but each earns its place; there is no filler or restatement of the title.

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 return values need not be enumerated, yet the description still flags the hotelId field and the empty-result fallback. Combined with pagination via cursor and the price-scope exclusion, an agent has everything needed to call this 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 only 50%, so the description has to carry weight, and it does for the two most ambiguous parameters: city matches area words (e.g. "Antalya", "Business Bay") while search matches name words. Cursor is documented in the schema, and currency/language are self-explanatory enums, so the remaining gap is small but not zero.

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 ("Lists the curated hotel pool") and immediately bounds the scope: by country, area, stars, with facility tags, no supplier call, no price. An agent can tell this apart from a pricing tool because the description says a price requires dates and guests, which points at the quote_hotel_stay sibling 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 clear selection condition in the negative: this tool returns the pool, and pricing is explicitly out of scope because "a price needs dates and guests." It also explains the two search axes so the agent picks the right argument. It stops short of naming the alternative tool explicitly, so routing is inferred rather than stated.

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 (readOnlyHint, destructiveHint=false), so the description correctly adds the traits they don't: a daily supplier-call limit, the 'unverified price is not returned' validation rule, and the PRICE_ON_REQUEST path that returns pageUrl and contact. These are concrete operational behaviors beyond structured fields, though the rate limit is left unquantified.

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 purpose and every sentence carries a distinct fact (scope, validation, PRICE_ON_REQUEST, rate limit, requirements, nationality default). It reads as a dense telegraphic cluster rather than flowing prose, which slightly hurts scanability.

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 present, return values needn't be explained, and the description covers the key edge cases (PRICE_ON_REQUEST, nationality default, call limits). It is nearly complete, missing only a quantified rate limit and any note on what the pricingSource distinction means for the caller.

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 75% and the schema already documents dates, guest caps, hotelIds and the nationality default. The description mostly restates requirements ('Needs check-in, check-out and guests') and the nationality default rather than adding syntax or format meaning, 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 ('Gets a live supplier offer or MBD contract price ... for hotels and dates') and immediately scopes it as non-transactional ('Books nothing and holds no room'). This lets an agent distinguish it from booking tools and from siblings like quote_transfer or list_hotels 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?

Usage is implied rather than explicit: 'Books nothing and holds no room' signals this is the pricing step, not a booking step, and 'Needs check-in, check-out and guests' gives prerequisites. However, no sibling is named and no when-not-to-use condition is stated, so routing among the quote_* tools is left 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?

With readOnly/idempotent/destructive/openWorld annotations already covering the safety profile, the description still adds real value: the no-side-effect guarantee against basket/hold/order, and the pricing rule that a 7th passenger requires a second vehicle. It stops short of describing how the cheapest option is chosen or what happens when no list price exists.

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 dense sentences, front-loaded with the core action and output contents, then constraints, then inputs. The parenthetical about the 7th passenger is slightly clunky but carries real business logic, so nothing is wasted; it is just packed tightly rather than elegantly.

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 return values need no prose, and annotations cover safety. The description still supplies the two things structured data cannot: the read-only/no-side-effect scope and the conditional district requirement. An agent has everything needed to invoke this 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 3 is the baseline, but the description adds genuinely new information by stating which inputs are needed and, crucially, the conditional 'Istanbul also needs district' — a requirement the schema presents only as an optional string. That conditional dependency is not derivable from the structured fields alone.

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 ('prices one transfer for a party from the stored list price') and even enumerates what the quote contains: vehicles needed, price per vehicle, total, cheapest option. The phrase 'Reads only: no basket, hold or order' separates it from booking/basket-oriented siblings, and the name parallels quote_hotel_stay without ambiguity.

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 an explicit exclusion — 'Reads only: no basket, hold or order' — which tells the agent this is a pricing check, not a purchase step, and it lists the minimum inputs needed to run it. It does not, however, name a sibling alternative (e.g. search_transfers) for the case where the agent only has a destination rather than a slug.

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 readOnly/idempotent/openWorld, so the description's added value is the currency resolution chain (argument, then query tokens like 'dollar'/'AED', else EUR) and the warning that a hotel result carries a price note rather than a price. Those are real behavioral traits beyond the structured fields, though pagination/ordering behavior is not disclosed.

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 scoping facts (what is searchable, currency fallback, hotel price note, exclusions) are front-loaded and mostly waste-free, but the dense single paragraph with stacked parenthetical examples is harder to scan than a short structured list would be.

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 read-only, single-query search with an output schema, the definition covers everything an agent needs to invoke it correctly: scope, currency resolution, default language, result granularity, and the explicit boundary of the index. Return-value detail is rightly delegated to the 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 the baseline is 3, but the description genuinely extends it: it explains that currency can be inferred from the query text and what the fallback is, plus that Turkish queries are accepted for the language dimension. It adds meaning the schema's terse 'Price currency.' does not.

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 ('Free-text search over published MBD Travel tours, experiences, hotels and the Dubai visa') and explicitly names what is out of scope (flights, transfers, booking, payment), which separates it from siblings like search_tours, search_transfers and quote_transfer without opening a 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 context and a de-facto routing rule via the exclusions ('Flights, transfers, booking and payment are not in the index'), which points an agent to the transfer/flight siblings. It stops short of naming a specific alternative tool or stating when to prefer get_tour/list_hotels over a broad search.

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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: prices are 'from' prices with a basis rather than fixed prices, and a no-match query returns an empty list plus an emptyReason instead of 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 tight sentences that front-load the core capability, then the price caveat, then the empty-result behavior and scope boundary. No filler or 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?

With an output schema present the return shape need not be described, yet the description still flags emptyReason, and it covers price semantics and catalogue scope. Only pagination/sort-default behavior is left entirely to the schema, which is a minor omission for an 11-parameter 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 coverage is 91%, so the schema documents nearly every parameter including enum values, defaults and the minor-units convention for maxPrice. The description mostly restates the filter fields; its only semantic addition is the 'from-price with basis' caveat that helps interpret maxPrice.

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 pair (lists/filters) plus an exact resource (published tours) and enumerates the filter dimensions. The closing clause 'Tours only: no hotels, experiences or visas' actively separates it from siblings like list_hotels and search_transfers.

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 'Tours only' line draws a useful scope boundary against some siblings, and the filter list implies the search use case. However, it never says when to prefer this over compare_tours, find_last_minute_tours or get_tour, and gives no prerequisites or exclusions for those 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description earns extra credit by adding domain behavior: fixed per-vehicle pricing, the rule that a 7th passenger requires a second vehicle, and the Istanbul side-pricing model, none of which the annotations convey.

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?

Information-dense and front-loaded: market coverage first, then pricing model, then filters, then the read-only guarantee. It is telegraphic and slightly list-like, but essentially no sentence is wasted.

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 present and rich annotations, the description only needs to carry domain semantics, and it does: markets, airports, pricing basis, and the side/district coupling. The one missing piece is an explicit hand-off to quote_transfer for price quoting or booking.

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 already 88%, so the baseline is 3. The description goes beyond it by explaining the side/district relationship ('priced by hotel side (pass district or side)') and the passenger capacity constraint, both of which clarify how parameters interact rather than merely restating enum values.

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 states a specific domain and resource (private transfers, fixed price per vehicle) and enumerates the two markets it covers, Dubai and Istanbul, with their airports. It does not, however, contrast itself with the sibling quote_transfer, which is the closest alternative for transfer pricing, so the 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?

It lists the filterable dimensions (airport, serviceType, direction, side, district, passengers) and notes the read-only nature, which gives implied usage context. But it never states when to reach for this tool versus quote_transfer or search, so the routing decision is left to inference.

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