HotelsCasa

Search hotels

search_hotels

Read-onlyIdempotent

Search hotels on HotelsCasa: hotels, apartments, guest houses and holiday homes that can actually be booked, in 77 countries — Europe, Turkey, Russia and Ukraine, the Caucasus, Central Asia, and the whole of Latin America including Mexico, Central America and the Caribbean. Search by city (English or local name; add country to disambiguate) or by lat/lng + radius_km. Country alone returns its main cities to choose from. Each item has stars, guest rating (out of 10), photo, price and the url of the hotel page. WITH DATES (check_in + check_out): availability is checked LIVE with the supplier before answering. Every item returned has a room actually free for those dates, and carries available:true, price_eur_per_night, price_total_eur, nights, board and refundable. Show price_total_eur for the stay together with the nightly rate, and say the price was checked for those dates. An empty list with availability_checked:true means there really is nothing free for those dates — say so and offer other dates or a wider radius. If availability_checked is false, the supplier did not answer: the prices are catalogue prices for OTHER dates — never present them as a confirmation. WITHOUT DATES: price_from_eur_per_night is an indicative starting price per night; show it as "from EUR X per night" and confirm on the page. Pass check_in/check_out/adults (and children_ages when children travel) to get real, bookable prices. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.

Input Schema

TableJSON Schema

Name	Required	Description
`lat`	No
`lng`	No
`city`	No	City name in English, e.g. Rome, Lisbon, Munich, Buenos Aires.
`lang`	No	Language of the answer and of the links: es, en, de, fr, it, pt, tr or ru. Default es.
`page`	No
`sort`	No
`type`	No	Accommodation type: apartments, aparthotels, guest houses, holiday homes, rural houses, villas.
`limit`	No	How many results to return (1-10, default 10).
`query`	No	Part of the hotel name (with city or lat/lng), or a city name.
`rooms`	No	How many rooms for the same stay (default 1).
`adults`	No
`country`	No	ISO-3166 alpha-2 country code, e.g. FR, IT, AR.
`check_in`	No	YYYY-MM-DD.
`children`	No
`check_out`	No	YYYY-MM-DD.
`price_max`	No	Max EUR per night. With dates it is applied to the live price for those dates; without dates, to the catalogue price.
`price_min`	No	Min EUR per night. Same rule as price_max.
`radius_km`	No	Radius for lat/lng search, default 10, max 50.
`stars_min`	No
`nationality`	No	Guest nationality, ISO-3166 alpha-2. Affects the rate; taken from the traveller IP when omitted.
`children_ages`	No	Ages of the children, comma separated, e.g. "4,9". The supplier prices a child by age; without this, 8 years is assumed.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`city`	No
`page`	No
`count`	No
`error`	No
`items`	No
`cities`	No
`message`	No
`next_page`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedSep 23, 2026

addedInput schema / properties / children_ages

Added value: +{
+  "description": "Ages of the children, comma separated, e.g. \"4,9\". The supplier prices a child by age; without this, 8 years is assumed.",
+  "type": "string"
+}

addedInput schema / properties / nationality

Added value: +{
+  "description": "Guest nationality, ISO-3166 alpha-2. Affects the rate; taken from the traveller IP when omitted.",
+  "type": "string"
+}

changedInput schema / properties / price_max / description

Previous value: -"Max EUR per night. Only hotels with a published rate are kept."New value: +"Max EUR per night. With dates it is applied to the live price for those dates; without dates, to the catalogue price."

addedInput schema / properties / price_min

Added value: +{
+  "description": "Min EUR per night. Same rule as price_max.",
+  "type": "number"
+}

addedInput schema / properties / rooms

Added value: +{
+  "description": "How many rooms for the same stay (default 1).",
+  "maximum": 4,
+  "minimum": 1,
+  "type": "integer"
+}

First observedSep 19, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description goes far beyond the annotations by explaining live supplier availability checks, the meaning of availability_checked true/false, how to present prices in both dated and dateless modes, and the requirement to return unchanged clickable URLs. It also warns against presenting catalogue prices as confirmations. This rich operational context is exactly what an agent needs and complements the readOnly/idempotent hints without contradiction.

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

Conciseness5/5

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

The description is long but every sentence earns its place: it front-loads the core purpose, then distinguishes dated vs dateless behavior, empty responses, supplier failure, and final booking requirements. The structure using WITH DATES/WITHOUT DATES is helpful for an agent scanning quickly. There is no filler or repetition that could be removed without losing important guidance.

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

Completeness5/5

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

Given the tool has 21 optional parameters and an output schema, the description covers the complete decision space needed to call it correctly: search modes, parameter combinations, live availability semantics, error conditions, price presentation rules, and the mandatory URL handling. The presence of an output schema means return-value documentation is not needed in the description. 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.

Parameters4/5

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

The description adds essential meaning beyond the schema for key parameters: city searches may use English or local names with country disambiguation, lat/lng requires radius_km, check_in/check_out trigger live availability, and children_ages affects pricing. Schema coverage is 67%, so the schema still documents several parameters, but the description provides the critical behavioral logic around dates, countries, and radius. A small deduction because some parameters like lang, page, sort, and rooms are only covered by the schema.

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

Purpose5/5

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

The description clearly states a specific verb and resource: searching bookable hotel properties on HotelsCasa, and enumerates accommodation types and geographic scope. It also differentiates from siblings by emphasizing live availability checking with dates and required hotel page URLs, which is not claimed by sibling tools like search_properties or get_hotel. The purpose is unambiguous and actionable.

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

Usage Guidelines4/5

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

The description provides strong context for when to use the tool: searching hotels by city or coordinates, with and without dates, and when country-only queries should be used. It does not explicitly name alternatives or state when not to use this tool versus siblings, but the context is clear enough that an agent would not confuse it with flight, vehicle, or activity search. A small deduction for missing explicit sibling routing.

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

All HotelsCasa tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.