Skip to main content
Glama

Plan hotel stays for an itinerary

plan_stays
Read-onlyIdempotent

Plan hotel stays for each stop of an India trip: set check-in/check-out dates, search hotels near arrival and departure points, and rank options by nightly price plus drive time. Does not book.

Instructions

Plans where to stay for each stop of a trip in India. Each stay is an arrival (place + time) and the next departure (place + time); places are lat+lng, station code, IATA code or place name, so train and flight times from any source can be passed in. For every stay it works out check-in/check-out dates (early-morning arrivals book the previous night), searches hotels near the arrival point and, if elsewhere, the departure point, and ranks them by nightly price plus drive time from arrival and to departure (valued at value_of_time_inr_per_hour). Returns candidates with leave-by times that include a check-in buffer for trains or flights, IRCTC retiring-room options for 3–48 h stays at stations, and warnings for late arrivals, early departures and same-day stays. Does not book.

Input Schema

NameRequiredDescriptionDefault
staysYesOne entry per stop, in trip order.
adultsNoAdults (18+) sharing the one room searched for.
min_starsNoMinimum hotel class (official stars).
radius_kmNoHotel search radius around each point.
candidatesNoHotels to return per stay.
children_agesNoAges (0–17) of children sharing that room, one entry per child, e.g. [6, 9]; empty for adults only.
max_price_inrNoMaximum nightly price in INR.
min_rating_pctNoMinimum guest rating in percent, e.g. 60 = 6.0/10 = 3.0/5. Default 0 (server setting); 0 turns the filter off. While on, hotels with no guest rating are left out.
value_of_time_inr_per_hourNoHow much an hour of transfer time is worth, to trade travel time against price (0 = price only).

Output Schema

NameRequiredDescriptionDefault
notesYesBuffers used, price and routing caveats, and attribution.
staysYesOne plan per requested stay, in trip order.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed49 schema fields changedv0.3.0
    • changedInput schema / properties / adults / description
      Previous value: -"Guests in the room; searches are for one room."New value: +"Adults (18+) sharing the one room searched for."
    • addedInput schema / properties / children_ages
      Added value: +{
      +  "default": [],
      +  "description": "Ages (0–17) of children sharing that room, one entry per child, e.g. [6, 9]; empty for adults only.",
      +  "items": {
      +    "maximum": 17,
      +    "minimum": 0,
      +    "type": "integer"
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
    • addedInput schema / properties / min_rating_pct
      Added value: +{
      +  "default": 0,
      +  "description": "Minimum guest rating in percent, e.g. 60 = 6.0/10 = 3.0/5. Default 0 (server setting); 0 turns the filter off. While on, hotels with no guest rating are left out.",
      +  "maximum": 100,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / min_stars / description
      Added value: +"Minimum hotel class (official stars)."
    • addedOutput schema / properties / notes / description
      Added value: +"Buffers used, price and routing caveats, and attribution."
    • addedOutput schema / properties / stays / description
      Added value: +"One plan per requested stay, in trip order."
    • addedOutput schema / properties / stays / items / properties / arrive / description
      Added value: +"Where and when the traveller arrives."
    • addedOutput schema / properties / stays / items / properties / arrive / properties / at / description
      Added value: +"Arrival or departure time in IST, ISO-8601 with +05:30."
    • addedOutput schema / properties / stays / items / properties / arrive / properties / code / description
      Added value: +"Railway station code or airport IATA code (null when the place has none)."
    • addedOutput schema / properties / stays / items / properties / arrive / properties / kind / description
      Added value: +"Kind of place: station, airport, bus_station, landmark, locality or point (raw coordinates)."
    • addedOutput schema / properties / stays / items / properties / arrive / properties / label / description
      Added value: +"Label of the point: as given, else its code or name."
    • addedOutput schema / properties / stays / items / properties / arrive / properties / name / description
      Added value: +"Resolved place name."
    • addedOutput schema / properties / stays / items / properties / candidates / description
      Added value: +"Hotels for this stay, lowest score_inr first, then cheapest."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / hotel_id / description
      Added value: +"Hotel id as source:source_id of the first source that listed it."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / lat / description
      Added value: +"Hotel latitude."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / leave_by / description
      Added value: +"Latest time to leave the hotel, IST ISO-8601: departure minus drive time and the train or flight buffer."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / lng / description
      Added value: +"Hotel longitude."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / minutes_from_arrival / description
      Added value: +"Traffic-adjusted drive from the arrival point, minutes (null when not routed)."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / minutes_to_departure / description
      Added value: +"Traffic-adjusted drive to the departure point, minutes (null when not routed)."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / name / description
      Added value: +"Hotel name."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / per_night_inr / description
      Added value: +"Lowest per-night INR price across sources."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / rating_10 / description
      Added value: +"Guest review score on a 0–10 scale (null if unrated)."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / score_inr / description
      Added value: +"per_night_inr × nights plus both drives valued at value_of_time_inr_per_hour, INR; lower is better."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / seller / description
      Added value: +"Booking site of per_night_inr; the source id when the source names no seller."
    • addedOutput schema / properties / stays / items / properties / candidates / items / properties / stars / description
      Added value: +"Official hotel class, 1–5 stars (null if unknown)."
    • addedOutput schema / properties / stays / items / properties / check_in / description
      Added value: +"Hotel check-in date, YYYY-MM-DD; the previous day for arrivals before 06:00 IST."
    • addedOutput schema / properties / stays / items / properties / check_out / description
      Added value: +"Hotel check-out date, YYYY-MM-DD."
    • addedOutput schema / properties / stays / items / properties / depart / description
      Added value: +"Where and when the traveller leaves."
    • addedOutput schema / properties / stays / items / properties / depart / properties / at / description
      Added value: +"Arrival or departure time in IST, ISO-8601 with +05:30."
    • addedOutput schema / properties / stays / items / properties / depart / properties / code / description
      Added value: +"Railway station code or airport IATA code (null when the place has none)."
    • addedOutput schema / properties / stays / items / properties / depart / properties / kind / description
      Added value: +"Kind of place: station, airport, bus_station, landmark, locality or point (raw coordinates)."
    • addedOutput schema / properties / stays / items / properties / depart / properties / label / description
      Added value: +"Label of the point: as given, else its code or name."
    • addedOutput schema / properties / stays / items / properties / depart / properties / name / description
      Added value: +"Resolved place name."
    • addedOutput schema / properties / stays / items / properties / nights / description
      Added value: +"Nights between check_in and check_out."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / description
      Added value: +"Arrival or departure stations with IRCTC retiring rooms, listed only for 3–48 h stays."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / distance_km / description
      Added value: +"Straight-line distance from the search place, km; 0 for the station itself."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / lat / description
      Added value: +"Station latitude (null if unknown)."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / lng / description
      Added value: +"Station longitude (null if unknown)."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / managed_by / description
      Added value: +"Who runs the retiring rooms, as IRCTC lists it."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / station_code / description
      Added value: +"Station code."
    • addedOutput schema / properties / stays / items / properties / retiring_rooms / items / properties / station_name / description
      Added value: +"Station name."
    • addedOutput schema / properties / stays / items / properties / searched_around / description
      Added value: +"Labels of the points hotels were searched around: the arrival, and the departure when elsewhere."
    • addedOutput schema / properties / stays / items / properties / sources_failed / description
      Added value: +"Sources that did not answer for this stay, and why."
    • addedOutput schema / properties / stays / items / properties / sources_failed / items / properties / code / description
      Added value: +"Error code, e.g. UPSTREAM_UNAVAILABLE or RATE_LIMITED."
    • addedOutput schema / properties / stays / items / properties / sources_failed / items / properties / message / description
      Added value: +"What went wrong."
    • addedOutput schema / properties / stays / items / properties / sources_failed / items / properties / source / description
      Added value: +"Id of the source that failed."
    • addedOutput schema / properties / stays / items / properties / stay / description
      Added value: +"Stay number, from 1, in trip order."
    • addedOutput schema / properties / stays / items / properties / stay_hours / description
      Added value: +"Hours from arrival to departure, 1 decimal."
    • addedOutput schema / properties / stays / items / properties / warnings / description
      Added value: +"Late arrivals, early departures, short or same-day stays and empty results."
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description still adds substantial non-obvious behavior: early-morning arrivals book the previous night, hotels are searched near arrival and if elsewhere also the departure point, ranking blends nightly price with drive time valued at value_of_time_inr_per_hour, leave-by times include a check-in buffer, retiring rooms are offered for 3–48 h stays, and late/early/same-day cases emit warnings.

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?

Purpose is front-loaded in the first sentence and every sentence carries information about distinct behavior; nothing is redundant filler. The third sentence is a long multi-clause run-on bundling check-in logic, search scope, ranking and outputs, which makes it harder to scan.

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

Completeness4/5

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

For a 9-parameter orchestration tool with an output schema, the description covers scope, computation logic, ranking, warnings and the non-booking boundary, so an agent can invoke it correctly. The only real omission is routing guidance against the six sibling tools that overlap it partially (search_hotels, find_retiring_rooms, travel_times).

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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents the point formats, adults/children, radius, candidates and filters. The description adds value by explaining how value_of_time_inr_per_hour is actually applied (drive time from arrival and to departure traded against nightly price), which the schema only states abstractly.

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?

States a specific verb and resource ('Plans where to stay for each stop of a trip in India') and immediately defines the unit of work: one stay = arrival point/time + next departure point/time. The itinerary-level, multi-stop scope makes it distinguishable from the single-search siblings like search_hotels.

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?

Clear context for when the tool applies (planning lodging across all stops of a trip, with train/flight times passed in from any source) and an explicit exclusion ('Does not book'). It never names an alternative, though — nothing tells the agent to fall back to search_hotels for a single stay or find_retiring_rooms for a lone retiring-room query.

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