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

Annotations already declare the safe read-only, idempotent, open-world profile, so the description is freed to add real behavioral context: seat counts may be cached and must be confirmed with a search, and classes_listed is the API's raw class count rather than bookable classes. These caveats materially change how an agent trusts and reports the data.

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?

Purpose is front-loaded in one clause, then structured field notes for with_one_change and nearby_* routes. Dense but every sentence carries information; slight density could be trimmed but nothing 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 no output schema, the description compensates by naming the returned sections (with_one_change, nearby_bus_routes, nearby_*), their contents (price, duration, wait at change), and the correct follow-up tools. An agent has everything needed to call it and interpret the result.

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?

All three parameters are fully documented in the schema (origin/destination as mb_find_place train station ids, date with the 18-day sales window), so the schema does the heavy lifting and the description adds no parameter-level detail. Baseline 3 is appropriate at 100% 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 purpose: alternatives when direct trains are full or expensive, covering one-change trips plus nearby train/bus/flight routes. It clearly distinguishes itself from direct-search siblings like mb_search_trains by scoping to the 'no good direct option' case.

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 when this is useful (direct trains full or dear), warns that a direct bus in nearby_bus_routes may be cheaper and faster, and tells the agent to pass the returned ids to mb_search_trains, mb_search_buses or mb_search_flights. That is a complete use/next-step 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely non-redundant behavior: absent days mean no buses or not-yet-on-sale, not an error, and the ~1 month booking window explains sparse results. It does not cover pricing units or pagination, but with annotations present this is solid added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler, front-loading what the tool returns before the follow-up action and the sales-window caveat. Every sentence 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?

With no output schema, the description carries the return-value burden and does so: per-day cheapest seat, listing omitted days, and the booking-window caveat. All five parameters are documented in the schema, so nothing an agent needs to call it correctly 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%, so origin/destination/day-range/seats semantics are already fully documented in the schema with examples. The description adds only the implicit notion that the result is per-day and per-seat; baseline 3 applies when the schema does the heavy lifting.

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+resource ('Cheapest bus seat per day for a route') and its cardinality, and distinguishes itself from mb_train_price_calendar/mb_flight_price_calendar by the bus domain. It also clarifies a non-obvious output property: days with no service are omitted rather than returned as empty.

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 when to use it ('Use to find the cheapest day') and what to do next ('then mb_search_buses for that day'), naming the sibling tool. It also warns that bus sales typically open about a month ahead, which tells the agent how to interpret a short or empty calendar.

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/destructiveHint=false, and the description adds substantial context beyond that: the full layout legend (w/m/x/|/--/DR), the note that rule text lives in seat_rules, that price_toman is null for most buses, and that bus_id expires. This is unusually rich behavioral disclosure.

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?

Purpose is front-loaded in the first sentence, and the layout legend, though lengthy, earns its place because there is no output schema to explain the marks. Slightly dense but no wasted sentences.

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 full burden of explaining the return format, and it does so thoroughly via the row-by-row legend and the price/rule pointers. An agent has everything needed to call and interpret the result.

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 a single parameter, so the schema already documents bus_id. The description adds genuine meaning beyond the schema by warning that bus_id expires and must come from a fresh search, which changes how the agent should source the value.

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+resource ('Seat map of one bus') and immediately enumerates the returned content: free seats, gender-sold seats, and row layout. It is clearly distinguishable from list/search siblings like mb_search_buses, which the description implicitly references for obtaining a fresh bus_id.

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 stated: it tells the agent to take bus_id from a fresh search and to use the search price when price_toman is null, which is useful operational guidance. However, there is no explicit when-to-use vs. when-not statement or named alternative, so it sits at the minimum-viable level.

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, openWorld), so the description's job is to add semantics beyond that, which it does: sold-out hotels are included, there are no prices, and results are paginated at 90 per page. It stops short of describing the ordering or the full return shape, but the added disclosure is substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler: the result set is front-loaded, then usage plus the alternative routing. The 'check `pages`' pointer is compact and actionable.

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 6-parameter, no-output-schema list tool, the description covers scope, pagination limits, absent fields and alternatives, which is enough to call it correctly. Minor gaps remain around result ordering and what a page object contains, but the essential call-time information is present.

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 city, name, page, limit, stars and hotel_type, making 3 the baseline. The description echoes the star/type filtering and the 90-per-page pagination unit but adds no syntax or edge-case detail 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?

States a specific verb and resource (every listed hotel of a city) plus the scope boundary that sold-out hotels are included and prices are absent. It distinguishes itself from mb_search_hotels and mb_hotel_calendar by naming them as the price-oriented alternatives.

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 when to use it ('to browse or find a hotel by stars or type regardless of dates') and when not to ('Prices: mb_search_hotels (dates) or mb_hotel_calendar (one hotel)'), naming the correct siblings. Nothing about partner-tool selection 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?

Annotations already cover readOnly, idempotent, openWorld, and non-destructive, so the safety profile is fully declared. The description adds domain-specific behavior beyond the annotations: rail operators repeat under several ids with each row listing all of them, and bus ids 276/278/280 are the taxi classes VIP/Economy/Formal. This is valuable interpretive context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short lines, front-loaded with the resource list, then usage, then the rail/taxi idiosyncrasies. Every sentence earns its place with no 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 3-param read-only lookup with no output schema, the description covers purpose, usage routing, and result-interpretation quirks. It could mention output ordering or pagination behavior for the limit parameter, but the essentials an agent needs to call and interpret it are present.

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 the enum for mode is documented. The description adds domain meaning to code fields ('W5' airline, 4 bus company) that helps the agent interpret results, but does not extend the parameter documentation itself. Baseline 3 fits when the schema does the heavy lifting.

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 specific resource (airlines, rail operators, bus companies) and the return shape (IATA code, id, Persian/English names). This is a reference-lookup tool clearly distinguished from the sibling search_* tools.

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 states when to use it: to name a code seen in results (airline 'W5', bus company 4) or to find an airline code for the `airlines` filter of mb_search_flights. Names a sibling tool and the routing condition, which is exactly the when-to-use signal an agent needs.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful domain behavior beyond that: Tehran domestic is THR not IKA, and these codes are preferred over XXXALL for domestic routes.

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 one-line purpose, then breaks down by mode with concrete examples. Dense and information-rich, though the multi-clause mode section could be tightened.

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 burden of explaining what is returned, and it does so by describing the code formats per mode. Covers the essential path from name to code and the handoff to search tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning the schema does not: the concrete per-mode id formats and example codes that let an agent interpret and choose `mode` correctly. It goes beyond the terse enum description without fully documenting limit behavior.

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 transformation ('Turn a city, airport, station or hotel name into the code a search takes'), naming both the input resource and the output artifact. This clearly distinguishes it from the mb_search_* siblings that consume those codes.

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 maps each mode to the id type it needs (flight→airports/cities, train→station ids, bus/taxi→8-digit city ids, hotel→slugs) and closes with a concrete 'Next:' routing to the five search tools. Both when-to-use and the downstream alternatives are named.

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/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the call re-executes a full search (implying latency/cost), and it explains how to interpret the returned baggage_checked_with_airline flag and the refund penalty formula. It omits any note on rate limits or result size/pagination.

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 tight blocks: the first sentence front-loads what the tool returns, the second covers the re-run behavior and the two non-obvious output fields. No filler or restated title text.

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 carry return-value meaning, and it does so for the two fields most likely to be misread (baggage_checked_with_airline, refund_penalties). Other returned data (fare rules, notes, per-passenger price structure) is named but not explained, which is a minor gap for a 9-parameter read tool with full schema coverage.

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 every parameter (including the 'ALL' city-code pattern and flight_id format) is already documented in the schema — the baseline is 3. The description only indirectly reinforces this by saying the search must be re-run with the same route, date and party; it adds no syntax or format detail of its own.

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: 'Every fare of one flight with refund penalties, confirmed baggage, fare rules, notes and per-passenger prices.' This clearly separates it from mb_search_flights (which finds flights) and mb_flight_price_calendar (which shows price trends) without needing to open any 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?

'Re-runs the mb_search_flights search (same route, date, party)' tells the agent the prerequisite (a prior search producing flight_id) and that the route/date/party inputs must match that search. It does not explicitly state when to prefer mb_flight_price_calendar or other siblings, so it stops short of full 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?

Beyond the readOnly/idempotent annotations, it discloses that values are the site's cached minimums and may diverge from a live search, and that days with no known fare are omitted for three distinct reasons (no flights, sold out, not cached). That is exactly the caveat an agent needs before trusting the numbers.

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. The purpose and the headline caveat (cached, not live) are front-loaded, with the omission rule last where it belongs.

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 carries the burden of explaining returns – and it does: one value per day, cheapest one-adult fare, days missing when unavailable. Nothing an agent needs to interpret or act on the result is 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 description coverage is 100% – origin, destination, days and start_date are all documented with patterns, defaults and formats in the schema. The description adds only that the fare basis is one adult, which is result semantics rather than parameter guidance, 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+resource+granularity: 'Cheapest one-adult fare per day for a route over a date range, in one call.' That immediately distinguishes it from the sibling mb_search_flights, which returns live itineraries rather than per-day minimums.

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 routes the agent: 'Use to find the cheapest day to fly, then call mb_search_flights for that day.' It names the follow-up tool and the condition that selects it, so the workflow is unambiguous.

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 safety is covered. The description adds genuine behavioral context beyond them: the response is plain-text passages tagged with their source section. It stops short of mentioning result quality, ranking, 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?

Three tight sentences, purpose front-loaded, usage examples second, sibling routing last. No filler and nothing repeated from the schema.

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 usefully explains the return shape (matching passages with source sections) and covers source routing, which is the main ambiguity for this tool. Only minor gaps remain around ranking or result volume, which the limit parameter already bounds.

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 the enum semantics for source and the Persian-language expectation for query, so the schema already does the heavy lifting. The description's mention of rules/FAQ/guides loosely mirrors the terms/faq/support enum but adds no new parameter-level detail. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search MrBilit's official rules, FAQ and help-center guides') plus the return type ('best matching passages'). It also distinguishes itself from fare-specific siblings by naming mb_flight_fare_details / mb_search_trains / mb_search_buses as the correct route for per-fare rules.

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 enumerates the question classes it is for (refunds/cancellation, ID and baggage, auto-reserve, change requests) and gives an explicit exclusion routing fare rules to three named siblings. Both the when and the when-not are covered.

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 readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description still adds genuinely useful behavioral context beyond the schema: the returned rating is on a 0-5 scale while the site displays it doubled out of 10, review text is clipped at 400 characters unless full_text is set, and landmark distances are in km with drive minutes in parentheses.

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?

Every sentence carries information — return contents first, then scale/truncation caveats, then routing to the three related tools. The only blemish is the awkward line breaking that splits sentences ('...unless full_text. For room prices...'), which slightly hurts front-loading and readability.

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 returned sections, flags the rating-scale conversion, and states the review truncation rule and the flag that lifts it. Combined with explicit routing to mb_hotel_rooms/mb_hotel_calendar/mb_find_place, 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 100%, so the baseline is 3, but the description goes further by explaining the two accepted identifier forms (numeric id vs 'city/hotel' slug) and how to obtain the slug form via mb_find_place, which is a workflow detail the schema pattern alone does not convey. It also implies the effects of reviews and full_text on the response.

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 single, concrete resource and enumerates exactly what is returned (stars, rating, reviews, location, landmarks, check-in rules, amenities, FAQ), and it clearly distinguishes itself from siblings by routing price/calendar queries elsewhere. The only shortfall is that the retrieval verb is implicit — it reads as a noun list ('One hotel: ...') rather than stating 'Returns details for one hotel'.

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 names alternatives and the conditions that select them: mb_hotel_rooms for room prices on dates, mb_hotel_calendar for cheapest nights, and mb_find_place(mode='hotel') to obtain the 'city/hotel' ref. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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, idempotent, non-destructive, open-world, so the safety profile is covered. The description nonetheless adds real behavioral context: the ~48-day horizon, that missing interior nights mean no availability, and that trailing gaps mean 'not loaded yet' rather than 'sold out' — a genuinely non-obvious distinction.

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, front-loaded with the return semantics, then usage, then the edge-case interpretation. Every sentence carries information an agent would otherwise have to guess.

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 correctly compensates by characterizing the result (per-night cheapest price), its range limit, and how to interpret gaps. That is exactly the missing structure an agent needs.

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 the single 'hotel' parameter is fully documented in the schema (format 'city_slug/hotel_slug', pattern, maxLength, example, and where to obtain it). The description adds no parameter-level detail, 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+resource+scope: the cheapest one-night room price per night, starting today and running up to ~48 days. It is immediately distinguishable from mb_hotel_rooms (exact prices) and from the train/bus/flight calendar 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?

Explicitly says when to use it ('to find the cheapest or the next free nights') and names the follow-up tool ('then mb_hotel_rooms for exact prices') for the precision case. Nothing is left to inference about tool selection.

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 this as a safe, idempotent, read-only lookup, so the description is free to add domain semantics instead: price is post-discount whole-stay, prices are independent of guest count, rooms_left 0 means full, and cancellation is the hotel's refund rule. It does not cover auth, rate limits, or pagination, so it stops short of a full 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?

Purpose and date scope are front-loaded in the first sentence, followed by field semantics in short, dense clauses. Every line carries information, though the parenthetical about guest count and multi-room groups is packed enough to need a second read.

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 correctly takes on return-value explanation (price_toman, rooms_left, cancellation, meals) and the empty-list edge case, which is what an agent needs to interpret results. It is nearly complete for a 4-parameter read tool; only structural details of the rooms list itself are 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%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying that guest count does not affect price and that guests instead selects rooms whose capacity fits ('choose rooms whose sleeps fits'). The date-range parameter semantics (1-30 nights) remain schema-only.

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 resource and scope: 'Every room of a hotel with its exact price for the dates', plus the fields returned (whole stay, per night, rooms left, meals). It partially differentiates from siblings by routing empty results to mb_hotel_calendar, but never states how it differs from mb_hotel or mb_search_hotels, which an agent must infer.

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 a clear use condition (fetch room-level availability and prices for a hotel/date range) and an explicit fallback with its trigger: 'Empty rooms list = nothing free for these dates (try mb_hotel_calendar)'. Prerequisites are only implied through the schema's reference to mb_search_hotels/mb_city_hotels for the hotel 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 declare readOnly/idempotent/openWorld/non-destructive, so the bar is lower. The description still adds real value by explaining how route codes map to site paths, but it also references `search_mode` and `site_wide_active`, which do not exist in the schema — useful-sounding context that an agent cannot act on.

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 in one clean sentence, then a second block on route codes and behavior. Slightly dense but every sentence is doing work; no 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 read-only, zero-required-parameter lookup with full schema coverage and no output schema, the definition covers when and how to call it. It omits any hint of the notice payload shape and references params the schema lacks, which are minor gaps.

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 format rules and the service enum are already documented, making 3 the baseline. The path-construction explanation adds some framing, but the mention of undeclared parameters (search_mode, site_wide_active) creates confusion rather than clarity.

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 resource (site notices for disruptions, rule changes, payment options) and its scope (per service or route). It is immediately distinguishable from every sibling, which are all search/price/lookup tools rather than notice retrieval.

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 before recommending a trip, alongside the search tools" gives a clear usage context and positions it relative to siblings. It does not state exclusions or when not to call it, so it stops short of a 5.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds real domain behavior beyond that: a city id spans all its terminals while a terminal id is exclusive, price_toman is per seat, and refund penalties apply per bus unless overridden. Auth requirements and result pagination are not addressed, keeping it below a 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?

Dense and front-loaded: the first sentence states exactly what comes back, then constraints, then next steps. The refund_penalties sentence is long and slightly run-on, but every clause carries distinct information, so there is no 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?

With 10 parameters, no output schema, and several domain-specific terms (price_toman, refund_penalties, city vs terminal ids), the description supplies exactly the missing context an agent needs: return field inventory, id semantics, and the refund-penalty field meanings. Nothing essential is left undocumented.

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 a 3 is the baseline, but the description genuinely clarifies parameter meaning beyond the schema: origin/destination take either a city id (all terminals) or a terminal id (that terminal only), which is the single most error-prone input decision. It also clarifies the price_toman unit semantics.

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 and scope ('Intercity buses on a date') and enumerates the returned fields (company, terminal, times, price per seat, free seats, bus type, stops, refund penalties). It also distinguishes itself from mb_bus_seats and mb_bus_price_calendar, so an agent can tell it apart from siblings without opening their 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?

Explicitly routes follow-on needs: 'Next: mb_bus_seats with a bus_id for seat numbers and women/men seats; other days: mb_bus_price_calendar.' That covers adjacent alternatives clearly, but it never states when NOT to use this tool (e.g. vs mb_search_taxis or mb_alternative_routes for the same route), so it falls 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 readOnly/idempotent/openWorld annotations, the description discloses real hidden behavior: international flights from Tehran may actually depart IKA when THR is requested (segments show real airports), off-sale flights are counted in not_on_sale, and domestic round trips return two separate ticket lists while international ones return a two-way package whose flight_id names both legs. These are non-obvious traits an agent could not infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose and no filler; each clause carries information. The middle sentence is dense with parenthetical asides (outbound/return, flight_id leg naming, IKA/THR), which costs some parseability but 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?

There is no output schema, so the description must explain return values, and it does: fare fields, the two-list vs. package round-trip shapes, and the not_on_sale bucket. Combined with the forward routing to fare details and the calendar, nothing essential for 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 description coverage is 100%, so the schema already carries parameter meaning and the baseline is 3. The description goes slightly further by explaining that price_toman is one adult's fare with taxes while total_toman covers the whole party, which clarifies how the adults/children/infants parameters affect pricing.

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 flights for a date') and immediately enumerates what the result set contains (price, seats left, baggage, times), which no sibling such as mb_search_trains or mb_search_buses provides. An agent can distinguish this from the train/bus/taxi/hotel searchers without opening any 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?

It routes the agent forward explicitly: use mb_flight_fare_details with the returned flight_id for refunds/baggage/rules, and mb_flight_price_calendar if the day must be chosen first. That is clear conditional guidance, but it never states when this tool is the wrong choice (e.g. vs. the calendar or fare-details tools as entry points) and gives no prerequisites.

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, open-world and non-destructive behavior, so the bar is lower. The description adds genuinely useful traits beyond them: that guest count does not alter prices, that sold-out properties are dropped from results, and what each returned price field means. Nothing is contradicted, though pagination/limit interplay and result ordering semantics are left to the schema.

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?

Purpose is front-loaded in the first sentence, followed by output-field definitions and then a compact routing block. Every section carries information, though the middle field-by-field paragraph reads as a run-on list and could be tightened.

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 11 parameters and no output schema, the description carries an unusual burden, and it does supply the meaning of the key returned price/occupancy fields plus the consumer chain. It still omits the overall result shape (e.g. hotel identity fields), limit/pagination behavior, and sort interaction, which an agent must infer.

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 all 11 parameters, which sets the baseline at 3. The description's extra detail (price_toman, per_night_toman, cheapest_room_sleeps, photo) describes returned fields rather than parameter meaning, and adds only the guest-count invariant that no parameter here controls.

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 (hotels/stays) with a clear scope: availability for the given dates plus the cheapest whole-stay price. It explicitly contrasts itself with the sibling mb_city_hotels by noting sold-out hotels are excluded here, so an agent can distinguish the two 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 routing conditions rather than just context: guest count doesn't affect price so room fitting belongs to mb_hotel_rooms(guests=...), and sold-out filtering is contrasted with mb_city_hotels. It also names the natural follow-up chain (mb_hotel, mb_hotel_rooms, mb_hotel_calendar) with the reason for each.

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, openWorld), the description discloses critical behavioral traits: capacity (up to 3 passengers), pricing scope (price_toman is for the whole car, not per person), empty-result behavior, and the summary structure of `classes` (cars, cheapest price, slots). This is rich domain-specific context that annotations cannot 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?

The description is front-loaded with the tool's purpose and packs useful details into four sentences without repetition. The pricing and classes notes are output-related and sit alongside parameter guidance, slightly blurring structure, but overall it is concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, no output schema, and full schema descriptions, the description covers purpose, usage, behavioral caveats, and return-format hints (empty results, `classes` summary). It omits any explanation of authentication or rate limits, but those may not be relevant; for the domain, it is largely 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 baseline is 3. The description adds a cross-reference to mb_find_place(mode='taxi') for origin/destination, but that is already in the schema; it also clarifies pricing (an output field, not a parameter) and output summarization. It does not add parameter-specific syntax or defaults 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 states a specific resource—private door-to-door intercity taxis—and specifies scope (whole car, up to 3 passengers) and granularity (one offer per pick-up slot). This clearly differentiates it from sibling transport-search tools like buses, trains, and flights.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a prerequisite (city IDs via mb_find_place(mode='taxi')) and a when-not (many city pairs have no taxis), but does not explicitly compare this tool to alternative sibling searches such as mb_search_buses or mb_search_trains. The context is still clear enough for an agent to know when to invoke it.

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 cover the safety profile, and the description adds real behavioral context beyond them: seat counts are fresh (not cached), price_toman is per adult, refund_penalties apply to every class unless overridden, and round-trip return legs are constrained to the same rail company.

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?

Dense but front-loaded: the core capability leads, followed by routing and round-trip mechanics. Nearly every sentence earns its place, though the compressed multi-clause routing block is slightly hard to parse.

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 8-parameter, no-output-schema search tool, the description covers the return shape (class, price per adult, free seats, refund penalties), data freshness, and cross-tool routing. Nothing needed to invoke it correctly 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?

With 100% schema description coverage, baseline is 3, but the description adds meaning beyond the schema — it explains the per-adult basis of pricing, the refund_penalty inheritance rule, and the company-locking behavior of outbound_class_id, which the schema only states mechanically.

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 precise verb+resource+scope: trains between two stations on a date, returning every class with price per adult and free seats. It is clearly distinguishable from siblings like mb_train_price, mb_train_stops, and mb_search_buses.

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: children/infants/whole compartments go to mb_train_price with class_id, stops and times to mb_train_stops, sold-out dates to mb_train_price_calendar or mb_alternative_routes, and round trips are described as two calls using outbound_class_id. When-to-use and alternatives are both spelled out.

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 safety (readOnly, idempotent, non-destructive), yet the description adds non-obvious session semantics (class_id expiry), a misleading-success case (sold-out classes still priced), and a data quirk (breakdown parts do not sum to the charged price). These are exactly the behaviours an agent cannot infer from structured fields.

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: what it returns first, then the prerequisite, then the sold-out caveat, with the breakdown note last. No filler, no restatement of the title or schema.

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 return-value disclosure and does so reasonably ('per adult, child, infant, foreigner and empty berth, and the total'), plus it warns about the breakdown's non-additivity. It omits error behaviour (e.g. expired class_id) and currency, minor gaps for a read-only price lookup.

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, and the description meaningfully exceeds it by explaining that the party composition (adult/child/infant/foreigner/empty berth) drives the returned breakdown. It adds interpretive value but no syntax or unit detail (e.g. currency) 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?

Names a specific verb+resource ('Exact price of one train class for a party') and enumerates the pricing dimensions returned, so an agent knows precisely what it computes. It also points at the source of class_id (mb_search_trains), which separates it from the search tool, though it never contrasts itself with the sibling mb_train_price_calendar or mb_flight_fare_details.

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 real precondition and a trap to avoid: class_id comes from mb_search_trains and expires with the search, and a sold-out class still returns a price so seats_left should be checked first. It does not state when to prefer the calendar variant or any explicit when-not case, so it stops short of a full 5.

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, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: only days with free seats are returned, and sales open only ~18 days ahead, so later days are absent. That explains partial results an agent would otherwise misread as 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 lines with zero waste; the core purpose and the free-seat constraint are front-loaded, and the sequencing hint plus sales-window caveat follow compactly.

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, but the description conveys the return shape (per-day cheapest fare for a route) and the data-coverage limit, which is the main thing an agent needs to interpret results. Only the relationship to mb_train_price is left unaddressed.

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 six parameters including the quota enum, seats, days and station-id hints are already fully documented. The description adds only the '(one adult)' framing and does not clarify how seats interacts with the free-seat filtering, 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 resource and scope: cheapest train ticket per day for a route, restricted to days with free seats. It clearly reads as a calendar-style tool distinct from mb_search_trains, but it never distinguishes itself from the sibling mb_train_price (single-day price), which an agent would need to choose between.

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 states when to use it ('find the cheapest or the next bookable day') and routes the agent to mb_search_trains for the chosen day. It stops short of naming the alternative price tool or any when-not condition, so it is strong but not fully closed-loop.

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/openWorld/non-destructive, so the bar is lower, and the description still adds genuinely non-obvious behavior: the first stop may precede the user's boarding station (Tehran-Mashhad train starting in Qom), and sold-out classes remain queryable. Return format is conveyed in one clause.

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, and the payload description is front-loaded before the parameter sourcing and the Qom caveat. Every sentence carries distinct 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 a single 100%-covered parameter, the description supplies exactly the missing pieces: what comes back, where the argument comes from, and a counterintuitive ordering caveat.

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 the schema already defines class_id, so baseline would be 3; the description goes beyond it by constraining the value's provenance (from a fresh mb_search_trains result) and warning against passing a train number instead.

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+resource ('every station a train stops at, in order') and even characterizes the return payload (date and local time per stop), which cleanly separates it from mb_search_trains and the other train 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 states the prerequisite explicitly (pass a class_id from mb_search_trains) plus two exclusions: sold-out classes are usable and a train number never is. It stops short of naming an alternative tool for any other case, so it is clear context rather than 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that — editorial text may quote out-of-date prices or rules, and live data must come from search tools — which is exactly the kind of caveat 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?

The purpose leads, followed by compact mode-specific clauses; every sentence carries information and nothing is repeated. The telegraphic 'service + origin + destination' fragments are efficient but slightly terse, keeping it just below 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?

With no output schema, the description does address what comes back (summary, FAQ, article, magazine posts) and flags content-staleness, so an agent can call it correctly. It could say more about how many results or clipped-vs-full-text behavior, but the essentials are present.

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. The description goes slightly beyond the per-parameter schema by tying parameters together — which combination (service+origin+destination vs. query) activates each mode and the special rule that hotel only needs the destination city slug — which is cross-parameter semantics the schema fields do not state.

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 concrete resource — MrBilit's guide content (summary, FAQ, article) plus travel-magazine posts — so an agent knows this returns editorial content rather than prices or availability. It implicitly separates itself from the search/booking siblings via the 'use the search tools for live prices' line, but it does not differentiate from other content-ish siblings such as mb_find_place, mb_notices, or mb_help.

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 clear selection rules: route-guide mode requires service + origin + destination, while magazine mode takes a query, and it redirects agents to search tools for live prices. There is no explicit 'do not use this for X' or contrast against the other non-search siblings, so it falls short of a 5.

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