Skip to main content
Glama

Search hotels

mb_search_hotels
Read-onlyIdempotent

Search hotels with free rooms in an Iranian city for your dates and compare the cheapest room prices for the whole stay, filtering by stars, amenities, type, breakfast, and refundability.

Instructions

Hotels and stays with a free room in a city for the dates, with the cheapest room price for the whole stay.

price_toman is the cheapest room for all nights (one room, after discount); cheapest_room_sleeps is how many that room sleeps (often 1). Guest count does not change prices: pick a fitting room with mb_hotel_rooms(guests=...). Next: mb_hotel, mb_hotel_rooms, mb_hotel_calendar.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "city": "<city>",
      "check_in": "<check_in>",
      "check_out": "<check_out>"
    },
    "name": "mb_search_hotels"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityYesCity slug from mb_find_place(mode='hotel'), e.g. 'mashhad' or 'kish'.
sortNoOrder; rating is the site's default.rating
limitNoMax hotels.
check_inYesCheck-in date YYYY-MM-DD.
amenitiesNoPersian words, each matching an amenity title, e.g. ['استخر'] (pool), ['پارکینگ'].
check_outYesCheck-out date YYYY-MM-DD (1 to 30 nights).
min_starsNoOnly hotels with at least this many stars, e.g. 4.
hotel_typeNoKind of stay.any
breakfast_onlyNoOnly stays whose cheapest room includes breakfast.
refundable_onlyNoOnly refundable stays.
max_price_per_night_tomanNoHighest price per night for one room in Toman, e.g. 3000000.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changedv0.5.0
    • removedInput schema / properties / amenities / anyOf
      Removed value: -[
      -  {
      -    "items": {
      -      "maxLength": 30,
      -      "minLength": 2,
      -      "type": "string"
      -    },
      -    "maxItems": 5,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / amenities / description
      Previous value: -"Only hotels with an amenity whose Persian title contains each word, e.g. ['استخر'] (pool, jacuzzi or sauna), ['پارکینگ']."New value: +"Persian words, each matching an amenity title, e.g. ['استخر'] (pool), ['پارکینگ']."
    • addedInput schema / properties / amenities / items
      Added value: +{
      +  "maxLength": 30,
      +  "minLength": 2,
      +  "type": "string"
      +}
    • addedInput schema / properties / amenities / maxItems
      Added value: +5
    • addedInput schema / properties / amenities / type
      Added value: +[
      +  "array",
      +  "null"
      +]
    • changedInput schema / properties / check_in / description
      Previous value: -"Check-in date YYYY-MM-DD, e.g. '2026-10-20'."New value: +"Check-in date YYYY-MM-DD."
    • changedInput schema / properties / check_out / description
      Previous value: -"Check-out date YYYY-MM-DD, e.g. '2026-10-23' (1 to 30 nights)."New value: +"Check-out date YYYY-MM-DD (1 to 30 nights)."
    • removedInput schema / properties / max_price_per_night_toman / anyOf
      Removed value: -[
      -  {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / max_price_per_night_toman / minimum
      Added value: +0
    • addedInput schema / properties / max_price_per_night_toman / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
    • removedInput schema / properties / min_stars / anyOf
      Removed value: -[
      -  {
      -    "maximum": 5,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / min_stars / maximum
      Added value: +5
    • addedInput schema / properties / min_stars / minimum
      Added value: +1
    • addedInput schema / properties / min_stars / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
    • removedInput schema / title
      Removed value: -"mb_search_hotelsArguments"
  2. Changed12 schema fields changedv0.3.0
    • removedInput schema / properties / amenities / title
      Removed value: -"Amenities"
    • removedInput schema / properties / breakfast_only / title
      Removed value: -"Breakfast Only"
    • removedInput schema / properties / check_in / title
      Removed value: -"Check In"
    • removedInput schema / properties / check_out / title
      Removed value: -"Check Out"
    • removedInput schema / properties / city / title
      Removed value: -"City"
    • removedInput schema / properties / hotel_type / title
      Removed value: -"Hotel Type"
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / max_price_per_night_toman / title
      Removed value: -"Max Price Per Night Toman"
    • removedInput schema / properties / min_stars / title
      Removed value: -"Min Stars"
    • removedInput schema / properties / refundable_only / title
      Removed value: -"Refundable Only"
    • removedInput schema / properties / sort / title
      Removed value: -"Sort"
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "title": "mb_search_hotelsDictOutput",
      -  "type": "object"
      -}New value: +null
  3. Changed2 schema fields changedv0.2.1
    • addedInput schema / properties / amenities
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "maxLength": 30,
      +        "minLength": 2,
      +        "type": "string"
      +      },
      +      "maxItems": 5,
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Only hotels with an amenity whose Persian title contains each word, e.g. ['استخر'] (pool, jacuzzi or sauna), ['پارکینگ'].",
      +  "title": "Amenities"
      +}
    • addedInput schema / properties / breakfast_only
      Added value: +{
      +  "default": false,
      +  "description": "Only stays whose cheapest room includes breakfast.",
      +  "title": "Breakfast Only",
      +  "type": "boolean"
      +}
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare this a safe, idempotent, open-world read, so the description doesn't need to restate safety. It instead adds genuinely non-obvious behavior: only hotels with actual availability are returned, price_toman is a whole-stay total for one room after discount, and cheapest_room_sleeps caps occupancy for that priced room. Rate limits, pagination behavior and the full result shape are not mentioned.

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

Conciseness4/5

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

The core capability is front-loaded in the first sentence, followed by tightly packed clarifications and a next-step pointer. The parenthetical detail about one room after discount is worth the words. The guest-count sentence is slightly indirect but carries real information, so nothing is clearly wasted.

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?

With eleven parameters and no output schema, the definition supplies the one thing the schema cannot: what the returned price and occupancy figures mean. Combined with the workflow pointers to mb_hotel_rooms and mb_hotel_calendar, an agent has enough to call this correctly and interpret results without guessing.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented with format, defaults and examples, which sets the baseline at 3. The description's added meaning ('Guest count does not change prices') clarifies the intent of the price/occupancy filters but mostly explains returned fields rather than the eleven input parameters. It neither harms nor substantially extends the schema.

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

Purpose4/5

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

The opening sentence names the resource (hotels/stays), the required scope (a city, specific dates) and the key constraint (only properties with a free room), plus what the reported price represents. It is clearly a date-scoped availability+price search rather than a plain listing. It does not, however, distinguish itself from the sibling mb_city_hotels or mb_hotel, so the sibling separation is only partially achieved.

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?

It gives an explicit next-step chain ('Next: mb_hotel, mb_hotel_rooms, mb_hotel_calendar') and a concrete rule for when to switch tools ('Guest count does not change prices: pick a fitting room with mb_hotel_rooms(guests=...)'). The city parameter's schema description also routes the agent to mb_find_place first. There are no explicit exclusions or a stated case for choosing mb_city_hotels instead.

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