Look up the 3-letter IATA city code for a free-text city name (e.g. "Tel Aviv" -> "TLV", "Paris" -> "PAR").

Every other tool in this server (list_hotels_in_city, search_flexible_hotel_offers) requires an IATA city_code, so this is normally the first tool to call when the user names a city.

Args:

• keyword (string): city name or the start of it, e.g. "Tel Aviv", "New York", "Par"

• max_results (number): max cities to return, 1-20 (default 10)

• response_format ('markdown' | 'json'): output format (default markdown)

Returns: matching cities with their name, iataCode, and country code.

Examples:

• Use when: "find flexible hotel deals in Tel Aviv" -> call with keyword="Tel Aviv" first to get city_code="TLV"

• Don't use when: you already have a 3-letter IATA city code

Error Handling:

• Returns "No cities found matching ..." if the keyword doesn't match anything

List hotels (with their Amadeus hotelId) located in a given IATA city code, optionally within a radius.

Use this to discover hotelIds you can pass into search_flexible_hotel_offers via hotel_ids, e.g. to restrict a search to a specific neighborhood or a shortlist of hotels the user already mentioned by name. It does NOT return prices or availability — only hotel identity/location. This tool does not modify any data.

Args:

• city_code (string): 3-letter IATA city code, e.g. "TLV", "PAR" (use resolve_city_code to find it)

• radius_km (number): search radius around the city center in km, 1-300 (default 20)

• max_results (number): max hotels to return, 1-30 (default 20)

• response_format ('markdown' | 'json'): output format (default markdown)

Returns: hotel name, hotelId, chain code, and coordinates for each matching hotel.

Examples:

• Use when: "only search hotels near the Tel Aviv beachfront" -> narrow radius_km, then pass returned hotelIds to search_flexible_hotel_offers

• Don't use when: you just want priced offers — use search_flexible_hotel_offers directly, it looks up hotels automatically

Error Handling:

• Returns "No hotels found for city code ..." if the city_code is invalid or has no coverage in this environment

Find the cheapest hotel offers for a fixed NUMBER OF NIGHTS across a WINDOW of possible check-in dates, instead of a single fixed check-in/check-out date pair. This is the core tool of this server.

For example: "3 nights in Tel Aviv, sometime between Sep 1 and Sep 20" is expressed as nights=3, earliest_check_in="2026-09-01", latest_check_in="2026-09-20". The tool scans every possible check-in date in that window (each implying checkout = check-in + nights), fetches real priced offers for each, and returns the cheapest options found, sorted by price — so the caller can see which exact dates are the best deal.

This does NOT search by a single fixed date — for that, just set earliest_check_in = latest_check_in. This is an AFFILIATE search tool: it never collects payment details or creates a booking. Each returned offer includes a bookingUrl — a link to the real hotel/OTA listing where the guest can complete the purchase themselves, if they choose to. Data comes from the Amadeus for Developers hotel API (free test/sandbox environment by default).

Args:

• city_code (string): 3-letter IATA city code, e.g. "TLV" (use resolve_city_code to find it from a name)

• nights (number): exact stay length in nights, 1-28

• earliest_check_in / latest_check_in (YYYY-MM-DD): the flexible window of possible check-in dates, at most 30 days apart

• hotel_ids (string[], optional): restrict to specific Amadeus hotelIds (from list_hotels_in_city)

• max_hotels (number): if hotel_ids is omitted, how many hotels in the city to auto-check (default 15)

• adults (number): guests per room (default 2)

• room_quantity (number): rooms to book (default 1)

• currency (string, optional): 3-letter ISO currency code, e.g. "USD"

• max_results (number): how many offers to return, cheapest first (default 10)

• response_format ('markdown' | 'json'): output format (default markdown)

Returns: For JSON format: { "cityCode": string, "nights": number, "earliestCheckIn": string, "latestCheckIn": string, "datesScanned": number, "datesWithOffers": number, "datesSkipped": [{ "date": string, "reason": string }], "hotelsConsidered": number, "offers": [{ "offerId", "hotelId", "hotelName", "checkInDate", "checkOutDate", "nights", "currency", "totalPrice", "boardType", "roomDescription", "bookingUrl" }, ...], "cheapest": <same shape as one offer, or null>, "truncated": boolean }

Examples:

• Use when: "find me the cheapest 3-night stay in Paris sometime in the next month"

• Use when: "is it cheaper to go for a long weekend early or late September?"

• Don't use when: the user already has exact fixed dates in mind — a single-date search is faster (set earliest_check_in = latest_check_in), though this tool still works for that case.

Error Handling:

• Returns an error if the date window exceeds 30 days — narrow it and retry

• Individual dates that error out (e.g. sandbox has no data) are listed in datesSkipped rather than failing the whole search

Fetch full, up-to-date details for a single hotel offer previously returned by search_flexible_hotel_offers, including its cancellation policy.

Offer prices can shift between search and booking, so call this before telling the user a final price or sending them to book. Like the rest of this server, it never collects payment details — it only reads offer details and returns a click-through link to the real site.

Args:

• offer_id (string): the offerId returned by search_flexible_hotel_offers

• response_format ('markdown' | 'json'): output format (default markdown)

Returns: hotel name, confirmed price, check-in/check-out dates, room description, board type, cancellation deadline, and a booking link to the real site.

Examples:

• Use when: the user picked one result from search_flexible_hotel_offers and wants to double-check the price before going to book

• Don't use when: you don't have an offer_id yet — run search_flexible_hotel_offers first

Error Handling:

• Returns "No details found for this offer id" if the offer expired (Amadeus test-environment offers are short-lived)