Search 650,000 hotels, get each hotel's direct price with full offer lists, match rooms, book.
Scored across 2 tools
search_hotels (catalogue discovery) and get_hotel_details (single-hotel profile) target clearly different actions and the descriptions explain the intended flow between them. However, both descriptions reference tools that are absent from this set (get_hotel, search_hotels_v2), which muddies the agent's picture of what it should call.
Both names follow a clean snake_case verb_noun pattern (search_hotels, get_hotel_details) and are immediately readable. No mixing of conventions or casing styles.
Only two tools exist for a hotel discovery domain covering 650,000 properties. Search plus detail is the minimum viable pair, but the surface feels thin, especially with API-key variants alluded to but not exposed.
The search-and-refer flow is coherent (search, view details, then book via parley_url), so the core path closes. But availability/date-specific lookup, multi-city search, and the advertised api-key tools (get_hotel, search_hotels_v2) are missing, leaving dead references and gaps.
Full profile of one hotel by its hotel_id from search_hotels: description, amenities, images, rooms, guest reviews and guest insights. A price is included only when both check_in and check_out are given, as the all-inclusive total for that stay. parley_url is the hotel's page on Parley with the stay's dates, where the user can view live prices and book. Everything needed to describe the hotel is here; no web search needed. Works without an API key.
With an API key, prefer get_hotel.
| Name | Required | Description | Default |
|---|---|---|---|
| rooms | No | Number of rooms (0 = 1). Prices are only quoted for one room. | |
| guests | No | Number of adult guests (0 = default of 2). | |
| check_in | No | Check-in date, YYYY-MM-DD (today or later). Prices need check_in and check_out. | |
| currency | No | ISO 4217 currency code for prices, e.g. 'EUR', 'USD', 'GBP'. | EUR |
| hotel_id | Yes | The hotel's id (a UUID), as returned in hotel_id by search_hotels. | |
| check_out | No | Check-out date, YYYY-MM-DD, after check_in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior: the tool works without an API key, prices appear only when both dates are supplied and represent the all-inclusive stay total, and parley_url carries the dates for live booking. It stops short of stating failure behavior for an invalid hotel_id.
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 core purpose and what is returned, then conditions and routing. Slightly over-written — 'Everything needed to describe the hotel is here; no web search needed' is reassurance rather than instruction — but no sentence is wasted enough to hurt.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so by enumerating the profile sections. For a read-only lookup tool with full schema coverage and complete annotations, the only real omission is error/edge behavior for a bad hotel_id or out-of-range dates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are already documented (rooms, guests, dates, currency, hotel_id). The description only restates the check_in/check_out pairing required for a price, which the schema also says. Baseline 3 is appropriate 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 and resource ('Full profile of one hotel by its hotel_id') and enumerates exactly what comes back: description, amenities, images, rooms, reviews, guest insights. It also names the sibling that supplies the id (search_hotels), so an agent can distinguish it from search_hotels without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: use this without an API key, but 'With an API key, prefer get_hotel' — a named alternative with a selecting condition. It also states the precondition for pricing (both check_in and check_out required) and asserts 'no web search needed', removing a plausible wrong-path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the VistaLink hotel catalogue (650,000 hotels) in one city, a neighbourhood or landmark within it (area, e.g. city='Milan', area='Brera'), or around a point. Needs city, latitude+longitude, or hotel_name; describe the stay in vibe. Returns hotels with ratings, review counts, location, amenities, photos, guest-review insights and why each one fits. A price appears only when both check_in and check_out are given (the all-inclusive total for that stay). Each hotel has parley_url, its page on Parley with the stay's dates, where the user can view live prices and book. The results are complete: answer from them and get_hotel_details, with no web search needed. Call once per request. Works without an API key (at most 20 results).
With an API key, prefer search_hotels_v2.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Neighbourhood or landmark within city to search around, e.g. 'Brera' or 'Colosseum' (with city='Milan' / 'Rome'). Results are limited to hotels near it. | |
| city | No | City to search in, e.g. 'Lisbon'. A search needs city, latitude+longitude, or hotel_name. | |
| vibe | No | What the traveller is looking for, as free text or comma-separated tags, e.g. 'boutique design hotel' or 'romantic,quiet'. | |
| limit | No | Maximum number of results, 1-20 without an API key (1-50 with one). Larger values are reduced to the maximum. | |
| rooms | No | Number of rooms (0 = 1). Prices are only quoted for one room. | |
| guests | No | Number of adult guests (0 = default of 2). | |
| country | No | ISO 3166-1 alpha-2 country code of the city, e.g. 'PT'. Use it for city names that exist in several countries (Paris FR vs Paris US). | |
| check_in | No | Check-in date, YYYY-MM-DD (today or later). Prices need check_in and check_out. | |
| currency | No | ISO 4217 currency code for prices, e.g. 'EUR', 'USD', 'GBP'. | EUR |
| latitude | No | Search centre latitude in decimal degrees, used with longitude (0 = not set). | |
| amenities | No | Comma-separated amenities the hotel must have, e.g. 'wifi,pool'. | |
| check_out | No | Check-out date, YYYY-MM-DD, after check_in. | |
| longitude | No | Search centre longitude in decimal degrees, used with latitude (0 = not set). | |
| budget_max | No | Maximum price per night, in currency (0 = no maximum). | |
| budget_min | No | Minimum price per night, in currency (0 = no minimum). | |
| hotel_name | No | Hotel name or part of it, e.g. 'Four Seasons'. | |
| include_rates | No | Fetch live rates for check_in/check_out (adds about 30-45s). Needs an API key and both dates; ignored otherwise. | |
| radius_meters | No | Radius around latitude/longitude in metres (0 = default). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the read-only/idempotent safety profile, yet the description discloses real behavior: prices appear only when both dates are supplied (all-inclusive stay total), each hotel carries a parley_url for live prices and booking, results are capped at 20 without a key, include_rates costs 30-45s, and the tool should be called once. This is substantial context beyond the structured metadata.
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 resource and scope, and nearly every sentence carries information. However, the price rule is restated twice, the line breaks are oddly fragmented, and the parley_url/book-in-app sentence is long, so it is slightly padded rather than maximally tight.
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 18-parameter tool with no output schema, the description still tells the agent what comes back (ratings, review counts, location, amenities, photos, guest-review insights, fit rationale) and how to act on it. 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 coverage is 100%, so the baseline is 3, and the description adds cross-parameter meaning the schema states only per-field: the city/lat-long/hotel_name alternatives as a search-mode choice, the pairing rule for dates, and the all-inclusive nature of the quoted price. Marginal but real added value on top of an already thorough 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 (search the 650,000-hotel VistaLink catalogue) plus the three legitimate search modes: one city, an area/landmark within a city, or a point. It also distinguishes itself from the sibling by telling the agent to pair results with get_hotel_details and names search_hotels_v2 as the keyed alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: call once per request, works without an API key (max 20 results), prefer search_hotels_v2 when an API key exists. It also states when NOT to reach for the web ('answer from them and get_hotel_details, with no web search needed'), which is exactly the kind of when/when-not guidance agents need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
chat_about_hotelssearch_hotels1 field changedInput schema / properties / areaAdded value: +{
+ "default": "",
+ "description": "Neighbourhood or landmark within city to search around, e.g. 'Brera' or 'Colosseum' (with city='Milan' / 'Rome'). Results are limited to hotels near it.",
+ "examples": [
+ "Brera",
+ "Le Marais"
+ ],
+ "title": "Area",
+ "type": "string"
+}chat_about_hotelsget_hotel_detailssearch_hotelsSearch hotels worldwide, compare live room rates, and create booking payment links.
Search hotels, compare room offers and public or masked wholesale rates, then continue on Brek.
Find exact, directly bookable hotel rooms and apartments with live availability and prices.
AI hotel search and booking: millions of properties, 85,000+ cities, live rates.
Add one secure layer between your agents and this server.