Travel Search

Search tours, hotels, flights, trains, and activities through a single MCP-backed CLI.

CLI

python scripts/travel_search.py <command> --input '<JSON object>'
python scripts/travel_search.py describe <command>
python scripts/travel_search.py list-tools

Commands: search-tours, cheapest-tours, search-hotels, get-tour-details, search-flights, flight-calendar, search-trains, search-activities, list-destinations.

Parameters below and in references/usage.md are current. Run describe <command> once per command when you need a field not documented here; never invent fields from memory.

Examples

python scripts/travel_search.py search-tours --input '{"departure_city":"Москва","country":"Турция","date_from":"YYYY-MM-DD","date_to":"YYYY-MM-DD","nights_min":7,"nights_max":10,"adults":2,"meal":"AI"}'
python scripts/travel_search.py search-flights --input '{"origin":"MOW","destination":"AYT","depart_date":"YYYY-MM-DD","adults":1}'
python scripts/travel_search.py search-trains --input '{"origin":"Москва","destination":"Сочи","depart_date":"YYYY-MM-DD","sort":"price","limit":5}'
python scripts/travel_search.py search-activities --input '{"city":"Анталья","date_from":"YYYY-MM-DD","date_to":"YYYY-MM-DD","persons":2,"children_allowed":true,"sort":"recommended","limit":5}'

Даты

YYYY-MM-DD в примерах — заполнитель. Сначала определите сегодняшнюю дату; если она неизвестна, выполните date +%F. Все даты передавайте в формате YYYY-MM-DD и не раньше сегодняшней, месяц для flight-calendar — в формате YYYY-MM. Если год не назван («15 сентября», «в мае»), имеется в виду ближайший такой день или месяц в будущем.

Scope

• Use this skill as the search layer of travel planning. Build itineraries with general reasoning; use the skill to find package tours, hotel-only stays, flights, trains, activities, destination directories, prices, and booking links.
• Does not make bookings, store personal travel data, access email/calendar, or keep a long-term travel workspace.
• Exact geography stays fixed unless the user explicitly agrees to broaden it.

Hard constraints

Treat these as non-negotiable filters — do not silently relax them:

• Geography (country, resort, city, hotel when named)
• Dates and night range
• Traveler composition (adults, children, infants)
• Budget when stated

If children are in the party and ages are unknown, ask for ages before presenting bookable family prices. Do not invent ages for pricing.

Budget: never auto-show offers that break a hard budget. Alternatives outside any hard constraint may appear only after explicit user consent, and only in a separate labeled section. Alternatives that satisfy every hard constraint (e.g. other hotels when the named ones do not fit) need no consent.

When to use which command

Activities

Если город экскурсий не найден, попробуйте ближайший крупный город или туристический центр. search-activities ищет по теме через query («сафари», «острова») и принимает необязательные date_from и date_to в формате YYYY-MM-DD (date_from ≤ date_to), persons от 1 до 100 и булево children_allowed. Сортировка: recommended (по умолчанию), price, rating или reviews. В каждой записи указан источник provider, единица цены price_unit (per_person, per_group, per_ticket или unknown) и понятный текст price_text. Сравнивайте цены только при одинаковом price_unit; сортировка price не смешивает разные единицы.

Туры и отели

• date_from…date_to — окно дат вылета (для search-hotels — заезда) не длиннее 31 дня, то есть до календарного месяца.
• list-destinations с {"country": "…"} даёт точные названия для resort; resorts_level_travel_only — места, которые есть только у Level.Travel (по ним ищет только он).
• Всегда передавайте nights_min и nights_max явно (по умолчанию 7–10) и держите диапазон не шире 5 значений: Level.Travel ищет только nights_min…nights_min+4 (сервер сузит диапазон и добавит примечание), Travelata — весь диапазон. Для более широкого диапазона сделайте несколько поисков по очереди.
• Питание meal (в cheapest-tours — список meals) передавайте кодом: RO — без питания, BB — завтраки, HB — полупансион, FB — полный пансион, AI — всё включено, UAI — ультра всё включено.
• search-hotels тоже требует departure_city: передайте домашний город пользователя, а если он неизвестен — «Москва». Город влияет только на доступность предложений.
• В предложениях есть beach_distance_m и beach_line — данные источника; null значит «неизвестно», а не «близко». Рейтинг — по шкале 0–10.
• Выдача — по одному варианту на отель (самый дешёвый); more_offers — сколько ещё дат и вариантов у отеля.
• cheapest-tours — быстрый обзор самых дешёвых туров только из Travelata; для выбранного предложения вызовите get-tour-details с его offer_id.

Авиабилеты

• search-flights: return_date (YYYY-MM-DD) необязателен. Поездку туда-обратно длиннее 30 дней сервер ищет как два перелёта в одну сторону: у элементов есть leg (outbound или return), итоговая цена — их сумма. Поиск в одну сторону возвращает самый дешёвый вариант на каждую дату — часто это один результат. Цены всегда для эконом-класса, даже если trip_class ≠ 0.
• Цены авиабилетов — за одного взрослого; price_total_adults — сумма за взрослых. Детские тарифы источник не даёт — так и скажите. one_way_combo — два билета в одну сторону, когда они дешевле туда-обратно. Время в departure_at местное: вылет в 00:55 — это ночь накануне.
• Пустой ответ авиапоиска значит «нет в кэше цен», а не «нет рейсов»: проверьте соседние даты в flight-calendar и дайте ссылку.
• flight-calendar: month в формате YYYY-MM; цены — за билет в одну сторону.

Ошибки

При ошибке CLI завершается с кодом 1 и печатает {"error":true,"category":…,"message":…}; для tool_error в message — текст сервера.

• Сообщение о неверных данных — исправьте ввод и не повторяйте запрос без изменений.
• «Источник отклонил параметры запроса…» — измените параметры.
• «Источник временно недоступен…» (ошибка всего вызова) — повторите один раз чуть позже, затем сообщите пользователю.
• «Сервис поиска сейчас перегружен…», «Слишком много запросов…» или rate_limited — подождите около минуты.
• Не запускайте второй search-tours, пока не завершился первый, и не повторяйте его с теми же аргументами. Если результатов мало, расширяйте поиск в рамках жёстких ограничений или с согласия пользователя.

Workflow

1. Clarify hard constraints: place, dates/nights, travelers, budget, and every must-have condition (meal, stars, distance to the beach).
2. Translate each constraint into a parameter literally — never leave a must-have only in your head:
   • Fixed stay («с 5 по 11») → date_from = date_to = check-in date, nights_min = nights_max = number of nights. Flexible dates → a date_from…date_to window.
   • Budget → price_max for the whole party and the whole stay; convert per-person or per-night budgets first.
   • Place → the exact resort name from list-destinations (a district inside a region looks like «Регион: Район»; a resort includes its districts).
   • Party → adults and kids_ages (each child's age).
   • Conditions → their own parameters (meal, stars_min/stars_max, beach_distance_max, beach_line_max, center_distance_max). «Первая линия» → beach_line_max 1; «не дальше N м» → beach_distance_max N; «у моря» without a number → beach_distance_max 500 (say so); «в центре» → center_distance_max ≈ 1500; «ровно 4★» → stars_min = stars_max = 4.
   • No parameter for a condition (sea view, aquapark) → say it cannot be filtered and check names or get-tour-details room names.
   • «A или B» (two meals, two resorts) → one search per value: meal and resort take one value, and meal matches exactly.
   • A star range («4–5★») → stars_min = lower bound; if only the lower bound shows up, search the upper bound too.
3. Build --input as one JSON object (use describe only for a field not documented here).
4. User named specific properties → pass them in hotels and search the resort where they are (if their resorts are unknown or many, as on atolls, search the country). Properties in different resorts need separate searches. Check that each named_hotels[].hotel really is the property the user meant; a brand may return several (other_matches). If none fit, run the same search without hotels for alternatives.
5. Call the command; preserve partial multi-provider results as success.
6. For a specific offer, refresh with get-tour-details before booking guidance. The confirmed price may differ from the search price — re-check the budget and say if it changed.
7. Present a short shortlist with prices, key facts, and links the server returned. When asked to compare named properties, cover each one from named_hotels: fits / does not fit (reason and price) / not found. When nothing fits, say which constraint removed the options and ask before relaxing it.

Rules

• Russian catalog values/examples are intentional: the upstream directory uses Russian names. Preserve the user's answer language where possible; do not force Russian conversation. Use Russian catalog values for MCP calls when required.
• Fresh details for a chosen tour use get-tour-details; do not reuse stale offer payloads as live quotes.
• Prefer short booking URLs from the response. If a short URL is missing, never fall back to a raw/long provider URL.
• Cached flight prices (including calendar data) are not live quotes — say they may be outdated.
• Tutu.ru train data is not real-time. The requested date only shapes the result link. Verify the train, seats, and final price on Tutu.ru; never present min_price_rub as confirmed availability.
• Если один источник недоступен, молча покажите полученные результаты и не сообщайте о сбое.
• Keep the requested geography; show actual sub-area names without switching regions silently.
• Default presentation: 5–8 strong options, calm text layout, group tours by hotel when multiple offers share one property.
• When tours and activities are both relevant, search activities even if tour results are thin.

Presentation

• Flights: route, dates, price, transfers/baggage notes if present, then link.
• Trains: train number, departure/arrival time, travel time, indicative carriage prices, the non-real-time warning, then link.
• Tours/hotels: property, stars/rating, area, meal, check-in and nights, price, brief fit note, then link.
• Prefer short conclusions over long tables.