search-hotels
Find available hotels by location coordinates and booking details. Retrieve key hotel information, including name, address, star rating, price range, and room types. Use session_id for additional results beyond the initial 50.
Instructions
Search for available hotels based on location coordinates and booking requirements. This tool returns a paginated list of hotels with their key details including name, address, star rating, price range, and available room types. Each hotel includes summary information about amenities and available rates.
The results are limited to 50 hotels per request. If more results are available, you can retrieve them using the load-more-hotels tool with the returned session_id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adults | No | Number of adults | |
| check_in_date | No | Check-in date (YYYY-MM-DD) | 2025-06-25 |
| check_out_date | No | Check-out date (YYYY-MM-DD) | 2025-06-26 |
| children | No | Number of children | |
| facilities | No | Facility IDs to filter hotels by, the IDs can be inferred with facilities resource. | |
| latitude | Yes | Latitude of the location | |
| longitude | Yes | Longitude of the location | |
| name | No | Optional location name or hotel name. | |
| search_context | No | A summary of the search context which will be used by the server to better make the recommendation |
Implementation Reference
- The main handler function for the 'search-hotels' tool. It constructs the API request for hotel availability, handles responses, stores hotels in session state, formats summaries, records telemetry metrics, and returns YAML-formatted results with pagination info.export async function searchHotels(params: { latitude: number; longitude: number; name?: string; check_in_date: string; check_out_date: string; adults: number; children: number; facilities?: number[]; }) { const requestBody = { check_in_date: params.check_in_date, check_out_date: params.check_out_date, guests: [ { adults: params.adults, children: Array(params.children).fill(8), infant: 0, }, ], location: { latitude: params.latitude.toString(), longitude: params.longitude.toString(), }, facility_ids: params.facilities ? params.facilities : [], max_results: 50, }; // Calculate metrics data const nights = calculateNights(params.check_in_date, params.check_out_date); const totalTravelers = params.adults + params.children; const metrics = getMetrics(); // Make API request to search for hotels const availabilityResult = await makeApiRequest<any>( "/api/v1/hotels/availability", "POST", requestBody ); if (!availabilityResult) { // Record failed search call metrics.recordHotelSearchCall({ location_name: params.name, check_in_date: params.check_in_date, nights: nights, total_travelers: totalTravelers, status: 'error' }); return createYamlResponse({ status: "error", message: "Failed to retrieve hotel availability data. Please try again later." }); } const { session_id=null, has_more=false, hotels = [], total = 0 } = availabilityResult; // Record hotel search metrics metrics.recordHotelSearchResults(hotels.length); metrics.recordHotelSearchCall({ location_name: params.name, check_in_date: params.check_in_date, nights: nights, total_travelers: totalTravelers, status: hotels.length === 0 ? 'empty' : 'success' }); if (hotels.length === 0) { return createYamlResponse({ status: "empty", message: "No hotels found matching your criteria. Please try different search parameters." }); } // Store hotels in session for later retrieval hotels.forEach((hotel: Hotel) => { session.hotels[hotel.id.toString()] = hotel; }); // Format results for response const hotelSummaries = hotels.map((hotel: Hotel) => formatHotelToSummaryObject(hotel)); var message = `Found ${hotels.length} available hotels matching the search criteria.`; if (has_more) { message = message + " Additional hotels are available. If the user needs more options or if the current results don't meet their preferences, use the load-more-hotels tool with the provided session_id to retrieve more options." } else { message = message + " These are all available hotels matching the search criteria. If the user isn't satisfied with these options, consider suggesting modifications to their search parameters (dates, location, facilities, etc.)." } return createYamlResponse({ status: "success", total_hotels: total, hotels: hotelSummaries, session_id: session_id, message: message, }); }
- src/hotel-mcp/server/standard.ts:65-90 (registration)Registers the 'search-hotels' tool with the MCP server, including detailed description, Zod input schema for validation, and the instrumented searchHotels handler function.server.tool( "search-hotels", `Search for available hotels based on location coordinates and booking requirements. This tool returns a paginated list of hotels with their key details including name, address, star rating, price range, and available room types. Each hotel includes summary information about amenities and available rates. The results are limited to 50 hotels per request. If more results are available, you can retrieve them using the load-more-hotels tool with the returned session_id. `, { latitude: z.number().describe("Latitude of the location"), longitude: z.number().describe("Longitude of the location"), name: z.string().optional().describe("Optional location name or hotel name."), check_in_date: z.string().default("2025-06-25").describe("Check-in date (YYYY-MM-DD)"), check_out_date: z.string().default("2025-06-26").describe("Check-out date (YYYY-MM-DD)"), adults: z.number().min(1).default(2).describe("Number of adults"), children: z.number().min(0).default(0).describe("Number of children"), search_context: z.string().optional().describe( "A summary of the search context which will be used by the server to better make the recommendation"), facilities: z.array(z.number()).optional().describe( "Facility IDs to filter hotels by, the IDs can be inferred with facilities resource." ), }, getTelemetry().telemetryMiddleware.instrumentTool("search-hotels", searchHotels) );
- Zod schema object defining the input parameters and validation rules for the 'search-hotels' tool, including defaults and descriptions.{ latitude: z.number().describe("Latitude of the location"), longitude: z.number().describe("Longitude of the location"), name: z.string().optional().describe("Optional location name or hotel name."), check_in_date: z.string().default("2025-06-25").describe("Check-in date (YYYY-MM-DD)"), check_out_date: z.string().default("2025-06-26").describe("Check-out date (YYYY-MM-DD)"), adults: z.number().min(1).default(2).describe("Number of adults"), children: z.number().min(0).default(0).describe("Number of children"), search_context: z.string().optional().describe( "A summary of the search context which will be used by the server to better make the recommendation"), facilities: z.array(z.number()).optional().describe( "Facility IDs to filter hotels by, the IDs can be inferred with facilities resource." ), },
- Helper function used by searchHotels to calculate the number of nights between check-in and check-out dates for metrics recording.function calculateNights(checkInDate: string, checkOutDate: string): number { const checkIn = new Date(checkInDate); const checkOut = new Date(checkOutDate); const timeDiff = checkOut.getTime() - checkIn.getTime(); return Math.ceil(timeDiff / (1000 * 3600 * 24)); }