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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavioral context: seat counts may be cached and should be confirmed with a search, and classes_listed is the API's raw count rather than bookable classes. It does not mention rate limits, result caps beyond 'up to 7', or freshness of prices beyond the caching note.

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, then organized by output section (with_one_change, nearby_*). It is dense and slightly run-on in the middle, but every sentence carries information; 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 an output schema present, the description need not enumerate return fields, yet it usefully explains what each section means and how to act on the ids. Coverage of caveats (cached seats, raw class counts) is good; a note on result freshness or pagination would make it 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% for all three parameters, so origin/destination/date semantics are fully documented in the schema. The description adds no input-parameter detail of its own (its content is about output sections), 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?

The opening sentence states a specific purpose: finding alternative journeys (one-change trips, nearby train/bus/flight routes) when direct trains are full or expensive. The named result sections (with_one_change, nearby_*) make it easy to distinguish from mb_search_trains and mb_search_buses, which it explicitly points to as follow-ups.

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 clearly states the trigger condition ('when direct trains are full or dear') and routes the agent onward ('pass their ids to mb_search_trains, mb_search_buses or mb_search_flights'), plus a comparative hint that a direct bus may be cheaper/faster. There is no explicit statement of when *not* to use it (e.g., when a direct train exists and is available), so it falls just 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: days with no buses or not yet on sale are omitted rather than returned as errors, which prevents the agent from misreading a sparse calendar. It does not mention rate limits or pagination, keeping it short of 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?

Two short sentences, front-loaded with what the tool returns, followed by the routing advice. No filler; every clause carries information.

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

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

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. The description supplies the one thing neither structured field carries: the omission semantics of missing days and the sales-window 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 description coverage is 100% and all five parameters carry inline descriptions (origin/destination ids from mb_find_place, days default 30, seats, start_date default today). 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 and resource: 'Cheapest bus seat per day for a route.' An agent can immediately distinguish this calendar-style price lookup from mb_search_buses (actual itineraries) and from the flight/train 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 gives the workflow ('Use to find the cheapest day, then mb_search_buses for that day') and names the alternative tool with the condition that selects it. It also warns that sales typically open about a month ahead, which tells the agent when this tool will return thin results.

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, but the description adds substantial behavioral detail beyond them: exact layout symbol semantics (none, w, m, x, |, --, DR), the fact that price_toman is null for most buses, the location of seating rules, and the expiration of bus_id. This is unusually thorough output and precondition 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?

Front-loads the purpose in the first clause, then uses compact legend-style formatting. Every sentence carries necessary interpretation detail for a complex seat-map output, with no wasted wording.

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

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

For a single-parameter read tool with an output schema and safety annotations, the description supplies everything needed to interpret and use the result correctly: layout marks, rule pointer, price caveat, and bus_id expiration. Nothing material 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 the schema already explains bus_id comes from a fresh mb_search_buses result. The description adds the important nuance that bus_id expires and must be taken from a fresh search, giving an operational reason to re-fetch beyond the schema 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?

States a specific verb and resource ("Seat map of one bus") and enumerates exactly what the output contains: free seat numbers, seats sold to women and men, and a row-by-row layout. This clearly distinguishes it from sibling search tools like 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?

Provides clear operational context: bus_id comes from a fresh mb_search_buses result because it expires, and rule text is found in seat_rules. It does not name when-not-to-use cases or explicit alternative tools, but the context for correct invocation is well established.

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, openWorld). The description adds real behavior beyond them: sold-out hotels are included, no price data is returned, and filters apply to one 90-hotel page at a time so callers must check `pages`.

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 scope sentence, then a single tight usage paragraph with a clear alternative-routing clause. Zero 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 an output schema present, return values need no explanation; the description still notes the returned fields and the pagination cap. Nothing needed to call this 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 coverage is 100%, so field meanings (city slug, name substring, page, limit, stars, hotel_type) are already documented in the schema. The description only echoes stars/type filtering and page behavior, adding little syntax or format detail beyond it.

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') with scope details (sold-out included, stars/rating/address, no prices). This clearly separates it from sibling mb_search_hotels, which is date-bound.

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 ('browse or find a hotel by stars or type regardless of dates') and routes price-related needs to mb_search_hotels and mb_hotel_calendar by name. No inference required.

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 non-obvious data quirks beyond the annotations: rail operators repeat across several ids with each row listing all of them, and bus ids 276/278/280 are the VIP/Economy/Formal taxi classes. Pagination behavior is left to the schema's limit field.

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 resource list, then the two usage cases, then the data caveats. Three tight sentences with no filler; every clause carries information an agent needs.

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-format explanation is unnecessary. Between the mode enum, the code/id semantics, the rail-duplication caveat, and the taxi-class mapping, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the 3 baseline is met by the schema alone. The description adds meaning the schema does not: concrete id/code examples ('W5', bus id 4) and the bus-id-to-taxi-class mapping, which clarifies what the `mode: bus` results actually contain.

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 ('List airlines ... rail operators or bus companies') and enumerates the identifier each entity carries (IATA code for airlines, id for rail/bus). The agent immediately knows this is a reference/lookup table rather than a search tool, distinguishing it from mb_search_flights 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?

Explicitly names two use cases: 'to name a code seen in results (airline 'W5', bus company 4)' and 'to find an airline code for the `airlines` filter of mb_search_flights'. This routes the agent from a raw code back to this tool and from this tool forward to a sibling, with concrete examples.

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, open-world, idempotent, non-destructive behavior, so the description is not burdened with safety disclosure. It adds substantial domain-specific behavior: output ID shapes per mode, IATA versus city codes, railroad station IDs, 8-digit bus/taxi city IDs, and hotel slug conventions. These details go well beyond the annotations.

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

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

The description is front-loaded with the core purpose, then organized by mode with specific examples. Despite its density, every sentence provides useful information for invoking the tool correctly. There is no filler or repetition.

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

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

Given the complexity of five modes and differing ID formats, the description is complete enough for correct invocation. Annotations, full schema descriptions, and an output schema are present, so the description need not explain return structure or safety. It covers mode-specific semantics and next steps well.

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 meaningful semantics for the mode parameter by explaining what each mode returns and giving examples, though it does not add much for limit and query beyond the schema examples. This justifies a score above baseline but not perfect.

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 verb and resource: turning a place name into the code a search takes. It clearly distinguishes this lookup/resolution tool from sibling search tools such as mb_search_flights and mb_search_hotels. The mode-specific breakdown further clarifies what the tool produces.

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 gives clear context and mode-specific routing, including Next tools to use after obtaining codes. It does not explicitly state when not to use this tool or what alternative exists if the code is already known. Still, the mapping from mode to downstream search tool is strong 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/destructive=false, so the safety profile is covered. The description adds genuinely useful behavior: that it re-runs the prior search, the meaning of baggage_checked_with_airline, and the refund formula (paid x (100 - penalty_pct) / 100) plus penalty_text fallback.

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 in the first sentence, followed by dense semantic detail. The second paragraph is information-rich rather than padded, though the inline field semantics make it slightly denser than ideal.

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 fare-detail lookup with 8 params, an output schema, and full annotation coverage, the description supplies enough context (search dependency, field semantics, refund math) to call it correctly. It would be stronger with an explicit note on when to use it versus sibling fare 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%, so every parameter is already documented, including the flight_id format and the ALL-suffix codes. The description only indirectly references the party (adults/children/infants) and round-trip context, adding little beyond the schema, 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 ('every fare of one flight') and enumerates what is returned (refund penalties, baggage, fare rules, notes, per-passenger prices). It also names the sibling mb_search_flights and explains the relationship, so an agent can distinguish it from the search tool.

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 clarifies this re-runs the mb_search_flights search with the same route/date/party and returns the chosen flight, which tells the agent when it applies. However, it does not explicitly state when to prefer this over other fare-related siblings (e.g. mb_flight_price_calendar) or any 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is added context — which it does well: it discloses that values are cached site minimums that can differ from live results, and that days with no known fare are omitted (no flights, sold out, or not cached). It does not mention rate limits or pagination, but for a calendar endpoint that is a minor gap.

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

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

Three short sentences, front-loaded with the core definition, then the workflow, then the caveat. No filler and nothing buried.

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?

Output schema exists, so return values need not be explained; annotations cover safety; the description supplies the provenance/staleness caveat that the structured fields cannot express. An agent has everything needed to call this correctly and interpret gaps in 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 description coverage is 100%, so the baseline is 3; the description adds only the fare basis ('one-adult') and per-day granularity, without format, default, or range guidance (those live in the schema). Not enough added meaning to exceed the baseline.

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: 'Cheapest one-adult fare per day for a route over a date range, in one call.' This cleanly separates it from sibling tools like mb_search_flights (live fare search) and mb_flight_fare_details (single-fare breakdown).

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 to find the cheapest day to fly, then call mb_search_flights for that day' gives an explicit use case plus the follow-up tool. The caveat that values are cached minimums that may differ from a live search effectively tells the agent when this tool is not the right source for an exact/live fare.

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 structurally. The description adds useful behavioral context beyond that: results are plain-text passages accompanied by their source section, and it notes the content domain it indexes. It does not discuss result limits or ranking behavior, but the output schema covers the return shape.

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 compact sentences, front-loaded with the purpose, then usage, then the exclusion. Each sentence carries distinct information, though the source-category phrasing mildly duplicates the enum documentation.

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 search tool, the description covers purpose, invocation contexts, exclusions, and result format, while annotations carry safety and an output schema exists for return values. Nothing an agent needs to select or call this 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% and the schema already documents query (with Persian examples), limit, and the source enum values in detail. The description only loosely echoes the source categories ('rules', 'FAQ', 'help-center guides') without adding syntax or format guidance, so the baseline of 3 applies.

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

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

States a specific verb (Search) and resource (official rules, FAQ, help-center guides) plus the return shape (best matching passages). It also names the sibling tools that own adjacent content (mb_flight_fare_details / mb_search_trains / mb_search_buses), so an agent can distinguish it 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?

Explicitly enumerates when to use it (refund and cancellation rules, ID and baggage rules, auto-reserve behavior, change requests) and gives a clear when-not with named alternatives for fare-specific rules. Nothing 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 the safety profile (readOnly, idempotent, non-destructive, openWorld). The description goes further by disclosing data conventions not in structured fields: ratings are shown x2 out of 10, landmarks are in km with drive minutes, and the id-vs-slug 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?

The core purpose is front-loaded in the first clause and the routing notes follow compactly. The dense parenthetical about numeric ids is slightly awkward to parse but every sentence carries useful information.

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

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

An output schema exists, so return values need no explanation. The description covers the resource, the returned field groups, format quirks, and sibling routing, leaving little an agent needs for a correct call.

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 by clarifying the `hotel` workflow: after a numeric id you must obtain the 'city/hotel' ref via mb_find_place(mode='hotel'). That is genuine param guidance 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 names the resource (a single hotel) and enumerates exactly what is returned: stars, guest rating, reviews, location, landmarks, check-in rules, amenities, FAQ. This clearly separates it from mb_search_hotels and mb_city_hotels, though it opens with a field list rather than an explicit verb.

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

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

It explicitly routes the agent to siblings with conditions: 'For room prices on dates call mb_hotel_rooms' and 'for the cheapest nights mb_hotel_calendar'. The primary use case for this tool itself is only implied, but the alternative-tool guidance is concrete and actionable.

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 the domain semantics an agent actually needs: missing nights mean no free room, and nights past the last entry mean 'not loaded yet' rather than sold out. That is exactly the kind of non-obvious behavior 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?

Three short sentences, front-loaded with what the tool returns and its range, followed by usage routing and the edge-case semantics. No filler or restatement of the name.

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 formatting needn't be explained, and the description covers the remaining gaps an agent would hit: the range limit, gaps meaning no availability, and truncation meaning unloaded rather than sold out. Nothing needed 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%, and the schema itself documents the 'city_slug/hotel_slug' format with an example and regex. The description adds nothing about the parameter, 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 ('cheapest one-night room price per night') plus an explicit scope ('from today, up to about 48 days'). The 'hotel' framing plus the sibling set (bus/flight/train calendars) makes the domain unambiguous.

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 ('find the cheapest or the next free nights') and routes the agent to the follow-up tool ('then mb_hotel_rooms for exact prices'). The distinction between the calendar (cheapest/availability overview) and the rooms tool (exact prices) is spelled out, not inferred.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real behavioral context: rooms_left 0 means full, cancellation reflects the hotel's refund rule, and an empty rooms list means no availability rather than an error. It does not discuss rate limits or data freshness, 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?

It is short and front-loads the core definition before the field explanations, with no filler sentences. The telegraphic fragment style ('rooms_left 0 = full') is efficient but slightly terse for an unfamiliar reader.

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-value documentation is not required, and the description still interprets the important output fields (price_toman, rooms_left, cancellation). Combined with the empty-result guidance, an agent has enough to call and interpret this correctly; only edge cases like multi-room pricing mechanics are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: prices are independent of guest count, guests acts as a 'sleeps at least' filter, and price_toman is the post-discount whole-stay total for one room. This clarifies interpretation of both guests and the returned price beyond the schema 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 opening sentence names the specific resource (every room of a hotel) and what it returns (exact price for the dates), with the key outputs enumerated (whole stay, per night, rooms left, meals). An agent can distinguish this from mb_hotel (hotel details) and mb_hotel_calendar (availability calendar) 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?

It routes the agent explicitly to mb_hotel_calendar when the rooms list comes back empty, and gives the group-booking procedure ('add up several rooms for a group'). It does not spell out the broader when-to-use vs mb_hotel or the prerequisite that the hotel slug comes from mb_search_hotels, though that is covered in the schema.

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 safety is covered. The description adds real behavioral context beyond that: how route codes build the site path that notice rules match against, and that site_wide_active counts every active notice rather than only the filtered set.

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 clause, followed by the route-path mechanics and usage note. Three sentences with concrete examples, only mildly dense; the trailing reference to non-schema parameters is the one piece that does not clearly earn 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description supplies the route-matching model an agent needs to form valid origin/destination values, but its mention of search_mode/site_wide_active parameters absent from the schema leaves a small unresolved ambiguity.

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/service are already documented with patterns and examples. The description contributes path-construction examples (/flights/THR-MHD, /trains/tehran-mashhad), but it also discusses search_mode and site_wide_active, which appear nowhere in the input schema, muddying rather than clarifying parameter meaning.

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 (MrBilit's site notices) and enumerates what they cover (disruptions, rule changes, payment options) plus the scoping axis (service or route). It is clearly a retrieval tool distinct from the search siblings, though it never states the retrieval verb explicitly.

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

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

'Use before recommending a trip, alongside the search tools' gives a concrete when-to-use and points to the sibling family. There is no when-not guidance or named alternative, 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 readOnly/idempotent/openWorld, so the description's job is added context — and it delivers: price_toman is charged once per seat, refund_penalties apply to every bus unless overridden, and the until_hours_before / free_cancel_minutes semantics are spelled out, including that null means up to departure. That is genuine behavior an agent could not infer from the annotations.

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

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

Front-loads the purpose, then the id semantics, then the pricing/refund rules, then next-step routing — a sensible order with no filler. The refund-penalty sentence is dense and reads as a spec dump, which costs it the top mark.

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

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

For a 10-parameter search tool with a full schema and an output schema, the description covers the id-type rule, the money and cancellation semantics, and the follow-up calls, so an agent has everything needed to call it and interpret results. Return-value explanation is not required since an output schema exists.

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 baseline is 3; the description adds real meaning on top by explaining that a city id covers all its terminals while a terminal id covers only that one — a non-obvious distinction for origin/destination. The per-seat pricing and refund-penalty notes describe output fields rather than input parameters, so it does not go further than a 4.

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 ('Intercity buses on a date') and enumerates the returned attributes (company, terminal, times, price, free seats, bus type, stops, refund penalties). The resource noun 'buses' cleanly separates it from mb_search_flights, mb_search_trains, and mb_search_taxis.

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 forward: 'Next: mb_bus_seats with a bus_id for seat numbers and women/men seats; other days: mb_bus_price_calendar.' That covers the two most likely adjacent needs, but it never says when NOT to use this tool (e.g. vs mb_alternative_routes) or that ids must come from mb_find_place.

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?

Goes well beyond the annotations (readOnly/idempotent/openWorld/non-destructive) by disclosing non-obvious behavior: fares without enough seats are dropped by the site, sold-out/auto-reserve flights land in not_on_sale, domestic round trips return two separate tickets while international ones return a combined package, and times are local despite the +03:30 suffix. It also warns that IKA can be substituted when THR is requested.

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 in the first sentence, then dense but informative semantics. Every sentence carries a distinct fact (pricing, party sizing, round-trip shapes, timezone quirk, sibling routing); the parentheticals are compact though somewhat packed.

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 14-parameter search tool with an output schema, the description supplies exactly the missing operational context: fare semantics, round-trip list shapes, timezone behavior, and airport substitution. Nothing an agent needs to call it correctly or interpret results 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%, so the schema already documents all 14 parameters, making 3 the baseline. The description adds only indirect meaning by explaining that total_toman covers the whole party (adult/child/infant fares) and that fares lacking enough seats for the party are dropped, which loosely informs the party-size parameters.

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 with scope: 'Search flights for a date: every bookable flight with price, seats left, baggage and times.' It also distinguishes itself from siblings by routing detail work to mb_flight_fare_details and cheapest-day work to mb_flight_price_calendar.

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 follow-up routing is given: use mb_flight_fare_details for refund penalties, exact baggage and fare rules, and mb_flight_price_calendar first for the cheapest day. It does not state explicit when-not-to-use-this-tool conditions for the same job, but the alternative-selection guidance is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description goes beyond them by disclosing that sold-out hotels are excluded, that guest count does not affect prices, and how the returned price fields relate to each other. It does not mention pagination behavior despite the limit parameter, so it stops short of 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?

Front-loaded with the core purpose, then dense but purposeful sentences that each add routing or semantics. The telegraphic style ('Next: mb_hotel (reviews, location)') is efficient but sacrifices some readability, keeping it just short of 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 9-parameter search tool with an output schema, annotations, and many siblings, the description covers exclusions, price interpretation, guest-count behavior, and next-step tools. 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 coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by clarifying price semantics (cheapest room for all nights vs. per-night, after discount) and that guest count is not a pricing input, which is non-obvious and affects how the agent should combine this with mb_hotel_rooms.

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 ('Hotels and stays with a free room in a city for the dates, with the cheapest room price for the whole stay'), including the scope constraint that only hotels with availability are returned. It explicitly contrasts itself with siblings (mb_city_hotels lists every hotel; mb_hotel_rooms gives exact prices), so an agent can distinguish it without opening another 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?

Explicitly routes the agent: use mb_hotel_rooms(guests=...) to pick a room that fits, mb_hotel for reviews/location, mb_hotel_calendar for cheapest nights, and mb_city_hotels when sold-out properties matter. It also states the condition under which this tool omits results, which is exactly the when-not guidance needed.

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 read-only/idempotent/non-destructive profile, and the description adds genuinely new behavior: whole-car capacity (up to 3 passengers), one offer per pick-up slot, price_toman is for the whole car not per person, and the shape of the `classes` summary. It does not cover pagination or auth requirements, so not 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?

Purpose and the pricing model are front-loaded in the first two lines, with the caveats about empty results and the city-id prerequisite following efficiently. Slightly fragmented layout 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?

For a 7-parameter search with a full output schema and complete annotations, the description supplies the extra context an agent needs: capacity, per-car pricing, empty-result behavior, and the companion tool for city ids. Output format details are 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% – every parameter (date, limit, origin, car_class, depart_after/before) is already documented in the schema. The description's price and classes notes relate to the response, not to parameter syntax or meaning, so baseline 3 applies.

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

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

The opening sentence states a specific verb+resource: private door-to-door intercity taxis for a date, whole car up to 3 passengers, one offer per pick-up slot. This distinguishes it from the bus, train and flight search siblings by mode and by capacity/pricing model.

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 prerequisite (city ids must come from mb_find_place(mode='taxi')) and warns that many city pairs return no taxis. It stops short of explicitly saying when to prefer this over mb_search_buses/trains for the same route, so it is clear context without full alternative 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?

Beyond the readOnly/idempotent/destructive annotations, it discloses that seat counts are fresh (not cached), that price_toman is per adult, and how refund_penalties apply across classes. These are non-obvious behavioral traits an agent cannot infer from the schema or annotations.

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

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

Front-loaded with what the tool returns, then dense but purposeful routing sentences; every clause points to a concrete alternative or behavioral fact. Slightly telegraphic in places but no dead weight.

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 search tool with an output schema and full coverage, the description covers selection guidance, output semantics, cross-tool routing, and round-trip composition. Nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to outbound_class_id (return leg only, limits to the same rail company) and clarifies the per-adult pricing dimension. It's meaningful added context, though most parameters are still schema-documented.

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 ('Trains between two stations on a date') and enumerates the returned payload ('every class (wagon), its price per adult and free seats'). It also distinguishes itself from siblings by explicitly routing stops/pricing/calendar lookups elsewhere.

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 names alternatives with the condition that selects them: children/infants/whole-compartment pricing -> mb_train_price, stops/times -> mb_train_stops, sold-out days -> mb_train_price_calendar or mb_alternative_routes. It even spells out the round-trip pattern (two calls, return leg via outbound_class_id).

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 that this is a safe, idempotent, read-only lookup, and the description adds genuinely non-obvious behavior: class_id expiry, prices returned even for sold-out classes, and the warning that breakdown components do not sum exactly to the price because the price is what is actually paid. These are exactly the surprises an agent needs surfaced before calling.

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

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

Three short sentences, front-loaded with what the tool returns before the prerequisites and caveats. Every sentence carries information: the price composition, the input provenance, and the sold-out/gap-in-breakdown warnings.

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 explanation, and the description still covers the two things an agent must know to call correctly: where class_id comes from and its expiry, and the sold-out caveat. Nothing material is missing for a six-parameter pricing 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 description coverage is 100%, so the per-parameter meanings (adult, child, infant, foreigner, empty berth) are already documented; the description adds aggregation semantics — that the returned figure is per party category plus a total — which the schema does not express. Modest but real value above the baseline.

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 — the exact price of one train class for a party — and enumerates what the price breaks down into (adult, child, infant, foreigner, empty berth, total). An agent can tell this apart from mb_search_trains, but nothing explicitly distinguishes it from the sibling mb_train_price_calendar, which is the nearest competing option.

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

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

Gives a concrete prerequisite (class_id must come from a fresh mb_search_trains result, since it expires with the search) and an important caveat (a sold-out class still returns a price, so check seats_left in the search first). It stops short of naming an explicit exclusion or alternative for calendar-style pricing.

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, so safety is covered. The description adds genuine behavioral context beyond them: rows are omitted on days without enough free seats, and the window is truncated because sales open only ~18 days ahead, so later days will be missing. The one gap is currency/price units and whether results are cached.

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, all front-loaded: what it returns, how to use it, and the availability caveat. Every sentence earns its place with no repetition of schema or annotation content.

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 structure need not be explained, and the description supplies the important domain caveats (free-seat filtering, ~18-day sales horizon). What is missing is minor: price currency/units and whether the calendar is cached or live.

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 days, quota, seats, start_date, origin and destination, including the mb_find_place(mode='train') id hint. The description only adds '(one adult)', which is marginal and slightly at odds with the seats parameter allowing up to 10. Baseline 3 is correct.

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 train ticket per day for a route, one adult, filtered to days with free seats. It is immediately distinguishable from mb_train_price (single price) and mb_search_trains (actual bookings) by the per-day calendar framing.

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 or the next bookable day, then mb_search_trains for that day.' That names the follow-up tool and the condition that triggers it. It stops short of stating when NOT to use it (e.g. versus mb_train_price for a single departure), so it is strong but not fully closed.

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 value beyond them: it states the return shape (ordered stops with date and local time), that sold-out classes still work, and warns that the first stop may precede the queried station. That is meaningful behavioral context, not restatement.

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 sentence, then parameter caveats follow. Three short sentences, none wasted, 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 an output schema present the description need not explain return values, and annotations carry the safety profile. For a single-parameter read tool, the description plus schema cover what an agent needs, including the non-obvious edge case that the first stop can precede the queried station.

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 schema already documents the class_id format. The description adds disambiguation the schema lacks - 'never a train number' - plus the sold-out tolerance, which genuinely improves correct invocation.

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 verb and resource - 'Every station a train stops at, in order, with the date and local time at each.' It positions itself relative to the sibling mb_search_trains as the producer of the class_id, so an agent can distinguish it from search and pricing tools 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?

It gives the workflow source ('a class_id from mb_search_trains') and a useful edge-case note ('sold-out classes work too'), but never states when to prefer this over siblings like mb_train_price_calendar or why an agent would request stops. Usage is implied by the purpose rather than explicitly routed.

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 behavior beyond that: editorial text may contain stale prices/rules and search tools should be used for live data, plus the per-service identifier format requirements.

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 paragraphs with no waste; the purpose leads, the two operating modes follow, and the freshness caveat is placed last. 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 an output schema present, return values need no explanation, and the description covers the two invocation modes, identifier formats, and the staleness caveat. It is essentially complete, though it does not state what happens with no parameters at all (all params are optional).

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% (baseline 3), but the description adds cross-parameter meaning the per-field schema does not: which combination of service/origin/destination constitutes a route guide versus a magazine lookup, and that hotel routes use destination-only slugs. That mode grouping is real added 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: it returns MrBilit's guide content (summary, FAQ, article) for a route or city plus matching magazine posts. That is concrete and distinguishable from the sibling search tools, though it never names a sibling directly to sharpen the boundary.

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

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

It splits usage into two explicit modes — 'Route guide: service + origin + destination' and 'Magazine: query' — and redirects to search tools for live prices. This gives clear context, but there are no explicit when-not conditions or named alternatives beyond the price caveat.

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