Vio.com

List of hotel IDs to fetch data for. Use hotel IDs from previous search results. This fetches detailed information for these specific hotels without performing a search.

Check-in date (YYYY-MM-DD). Must be today or a future date. IMPORTANT: When user specifies month/day without year (e.g., "January 25"), use the NEXT occurrence of that date. If that date has already passed this year, use next year.

Check-out date in 'YYYY-MM-DD' format. Must be after checkIn. Defaults to 3 nights after check-in.

3-char uppercase ISO currency code (e.g., 'USD', 'EUR', 'GBP'). ONLY provide this when the user EXPLICITLY mentions a currency (e.g., "show prices in EUR", "I want to pay in dollars"). Do NOT provide this field otherwise - leave it empty and it will be automatically derived from the user's country.

Days from today to check-in. Use for relative dates like "next week" (7), "tomorrow" (1), "in 2 weeks" (14). Overrides checkIn if provided. Use with nights parameter for stay duration.

When true, run input parsing/normalization/validation but skip the upstream call. Returns the same output shape with empty results and the normalized stay metadata. Validation errors throw the same way as a real call.

Hotel data categories to include in results. This parameter controls WHICH INFORMATION to return, NOT which hotels to filter. To FILTER hotels by specific amenities or features, use the filters parameter. Each type adds specific fields: - location: Hotel location details, area description, attractions description, and nearby attractions - rating: Guest ratings and review statistics - classification: Star rating, property type, themes, and national ratings description - facility: Hotel facilities list, amenities description, business amenities description, and dining description (INFO only, does NOT filter) - media: Hotel images and image count - policy: Hotel policies including check-in, fees description, policies description, know before you go, and special instructions (INFO only, does NOT filter) - offer: Available room offers with pricing (configure via offers options) - room: Room types with descriptions, amenities, and offers (configure via rooms options) - faq: Frequently asked questions about the hotel. Use when user asks about common guest questions, what guests typically ask, hotel policies/rules, or general information inquiries - review: Guest reviews with ratings and text (configure via reviews options) - insight: AI-generated review summaries with overall summary and category breakdowns (Facilities, Cleanliness, Rooms, Service, Location, Food) - analytics: Historical price analytics — average price over a time range, comparison vs similar hotels, and historical price data IMPORTANT: Include "analytics" when the user asks about a hotel's price *quality* — value comparisons (cheaper/expensive vs similar hotels, good deal, worth it, fair price, overpriced) or historical price trends (going up/down lately). For "WHEN should I go?" / "cheapest dates" / "price calendar" / flexible-date questions, use the search_hotels_availability tool instead — analytics gives historical context for fixed-date searches, not future date discovery. Note: propertyDescription, roomsDescription, and phone are always included at the hotel level when hotel data is available. Both singular and plural forms are accepted (e.g., "policy" or "policies").

Options for including media data (hotel images).

Number of nights for the stay duration. If provided with day_distance, calculates check-out. If provided with check_in, calculates check-out. Defaults to 3 nights.

Options for including offers data. Only applies when include contains "offers".

The user prompt that triggered this tool call IN ENGLISH. If the user prompt is in another language, translate it to English first. IMPORTANT: Remove ALL personally identifiable information (PII) before sending. Strip out: names, emails, phone numbers, addresses, credit card numbers, passport/ID numbers, and any other personal data. Keep only the intent and travel-related details (destination, dates, preferences).

Options for including reviews data. Only applies when include contains "reviews".

Options for including rooms data. Only applies when include contains "rooms".

Room configuration specifying occupancy for each room. CRITICAL: When the user mentions number of adults or children (e.g., "3 adults", "family of 4", "2 people"), you MUST extract this as the roomsConfiguration parameter. Each room requires an adults count and optional children ages (0-17). Examples: "3 adults" → [{adults: 3}], "2 adults and 1 child age 5" → [{adults: 2, children: [5]}], "2 rooms for 4 people" → [{adults: 2}, {adults: 2}]. Only use the default [{adults: 2}] if occupancy is NOT mentioned at all in the user query. AMBIGUITY HANDLING: When a multi-room request is ambiguous (guest count could be per-room or total), ask the user to clarify BEFORE calling any tool. Ambiguous: "2 rooms for 2 adults" (1 per room, or 2 per room?). Unambiguous: "2 rooms with 2 adults each" → [{adults: 2}, {adults: 2}].

Offers polling mode. Use 'fast' (default) for essentially all queries — price lookups, hotel discovery, recommendations, single-hotel fetches, comparisons within the returned offer set. Fast returns offers in under ~3 seconds with high coverage of available providers and is the right choice when the user just wants to see hotels and prices. Use 'deep' ONLY when the user explicitly asks for exhaustive price comparison across *every* provider (phrases like "check every OTA", "compare all providers", "exhaustive search"). Deep takes up to 10 seconds and is rarely warranted — prefer fast unless completeness is explicitly required.

Search for hotels near a specific ADDRESS or LANDMARK (NOT for hotel names). Use ONLY when user wants hotels NEAR a place: "near the Eiffel Tower", "near 123 Main Street", "close to Central Park". Do NOT use for hotel names - use queries instead (e.g., queries: ["Hilton Amsterdam"]). Do NOT use for destinations - use queries instead (e.g., queries: ["Paris, France"]). Mutually exclusive with queries/latitude/longitude/near_me.

Check-in date (YYYY-MM-DD). Must be today or a future date. IMPORTANT: When user specifies month/day without year (e.g., "January 25"), use the NEXT occurrence of that date. If that date has already passed this year, use next year.

Check-out date in 'YYYY-MM-DD' format. Must be after checkIn. Defaults to 3 nights after check-in.

3-char uppercase ISO currency code (e.g., 'USD', 'EUR', 'GBP'). ONLY provide this when the user EXPLICITLY mentions a currency (e.g., "show prices in EUR", "I want to pay in dollars"). Do NOT provide this field otherwise - leave it empty and it will be automatically derived from the user's country.

Days from today to check-in. Use for relative dates like "next week" (7), "tomorrow" (1), "in 2 weeks" (14). Overrides checkIn if provided. Use with nights parameter for stay duration.

When true, run input parsing/normalization/validation but skip the upstream call. Returns the same output shape with empty results and the normalized stay metadata. Validation errors throw the same way as a real call.

Hotel-level search filters. All LOV-based filters (propertyTypes, facilities, themes) accept natural language terms in ENGLISH. FILTER COMBINATION LOGIC: - Multiple filter types combined = AND logic (e.g., starRatings:[4,5] + facilities:["gym","pool"] returns 4-5 star hotels WITH gym AND pool) - propertyTypes/excludePropertyTypes: OR logic (any match), mutually exclusive - facilities: AND logic (must have ALL) - themes: OR logic (any match) - starRatings/guestRating: OR logic (any match) NOTE: Offer-level filters (mealIncluded, freeCancellation, payLater) are in the offers options object.

Hotel data categories to include in results. This parameter controls WHICH INFORMATION to return, NOT which hotels to filter. To FILTER hotels by specific amenities or features, use the filters parameter. Each type adds specific fields: - location: Hotel location details, area description, attractions description, and nearby attractions - rating: Guest ratings and review statistics - classification: Star rating, property type, themes, and national ratings description - facility: Hotel facilities list, amenities description, business amenities description, and dining description (INFO only, does NOT filter) - media: Hotel images and image count - policy: Hotel policies including check-in, fees description, policies description, know before you go, and special instructions (INFO only, does NOT filter) - offer: Available room offers with pricing (configure via offers options) - room: Room types with descriptions, amenities, and offers (configure via rooms options) - faq: Frequently asked questions about the hotel. Use when user asks about common guest questions, what guests typically ask, hotel policies/rules, or general information inquiries - review: Guest reviews with ratings and text (configure via reviews options) - insight: AI-generated review summaries with overall summary and category breakdowns (Facilities, Cleanliness, Rooms, Service, Location, Food) - analytics: Historical price analytics — average price over a time range, comparison vs similar hotels, and historical price data IMPORTANT: Include "analytics" when the user asks about a hotel's price *quality* — value comparisons (cheaper/expensive vs similar hotels, good deal, worth it, fair price, overpriced) or historical price trends (going up/down lately). For "WHEN should I go?" / "cheapest dates" / "price calendar" / flexible-date questions, use the search_hotels_availability tool instead — analytics gives historical context for fixed-date searches, not future date discovery. Note: propertyDescription, roomsDescription, and phone are always included at the hotel level when hotel data is available. Both singular and plural forms are accepted (e.g., "policy" or "policies").

Latitude for geographic search (-90 to 90). Must be used with longitude. Use for coordinate-based searches like "hotels at 52.3676, 4.9041". Mutually exclusive with query/near_me.

Longitude for geographic search (-180 to 180). Must be used with latitude. Use for coordinate-based searches. Mutually exclusive with query/near_me.

Options for including media data (hotel images).

Search near user's current GPS location. Mutually exclusive with query/latitude/longitude.

Number of nights for the stay duration. If provided with day_distance, calculates check-out. If provided with check_in, calculates check-out. Defaults to 3 nights.

Options for including offers data. Only applies when include contains "offers".

Starting positions in search results (one offset per location in "queries" array, 0-based). The system scans from these positions and returns the requested number of hotels with available offers. Use the "nextOffsets" array from the response to fetch the next page of results. Example: queries=["Manhattan", "Brooklyn"] with offsets=[0, 10] starts Manhattan at 0 and Brooklyn at 10. If not provided, defaults to [0, 0, ...] for all locations.

Enable rooms optimization to find the best offer across different room configurations for the same total occupancy. When true, SAPI searches for best offers across equivalent room combinations. For example, if 6 adults are requested, it will compare offers for "6 adults in 1 room", "3|3 (two 3-person rooms)", and "2|2|2 (three 2-person rooms)" configurations. The optimization works at the hotel level - each hotel will show offers for only one room configuration (the one with the best deal). Use this when users want the best price regardless of specific room split, or when searching for large groups where room configuration flexibility could yield better rates.

Number of hotels to return (default 10). Only specify if user explicitly requests a different number. Returns this many hotels with available offers (system automatically filters out hotels without offers and fetches additional pages if needed to reach the target count).

Price display mode. 'total' returns prices for the entire stay (default). 'nightly' returns prices divided by number of nights for per-night rates.

The user prompt that triggered this tool call IN ENGLISH. If the user prompt is in another language, translate it to English first. IMPORTANT: Remove ALL personally identifiable information (PII) before sending. Strip out: names, emails, phone numbers, addresses, credit card numbers, passport/ID numbers, and any other personal data. Keep only the intent and travel-related details (destination, dates, preferences).

Search queries for finding hotels. Use this for ALL hotel searches including: (1) Destinations: "Paris, France", "Manhattan, New York", "Bahia, Brazil". (2) Specific hotels by name: "Hilton Amsterdam", "Marriott Times Square". (3) Similar hotels: To find hotels similar to a specific hotel, use the hotel name directly (e.g., queries: ["Leonardo Hotel Amsterdam"]). This returns the searched hotel plus similar alternatives nearby. Do NOT use the location - use the hotel name. (4) Multiple locations or hotels: ["Paris", "London"] or ["Hilton Paris", "Marriott Paris"] for comparison. IMPORTANT: Always provide complete context (e.g., "Lisbon, Portugal" not just "Lisbon", "Hilton Amsterdam" not just "Hilton"). Supports 1-3 queries. Results are merged using relevance ranking. Mutually exclusive with address/latitude/longitude/near_me.

Search radius in meters for coordinate-based searches. Only applies when using latitude+longitude or near_me (not with query). Examples: 1000 (1km), 5000 (5km), 10000 (10km). Use when user specifies distance like "within 5km", "walking distance" (~1000m), "nearby" (~5000m). Omit for default radius.

Options for including reviews data. Only applies when include contains "reviews".

Options for including rooms data. Only applies when include contains "rooms".

Room configuration specifying occupancy for each room. CRITICAL: When the user mentions number of adults or children (e.g., "3 adults", "family of 4", "2 people"), you MUST extract this as the roomsConfiguration parameter. Each room requires an adults count and optional children ages (0-17). Examples: "3 adults" → [{adults: 3}], "2 adults and 1 child age 5" → [{adults: 2, children: [5]}], "2 rooms for 4 people" → [{adults: 2}, {adults: 2}]. Only use the default [{adults: 2}] if occupancy is NOT mentioned at all in the user query. AMBIGUITY HANDLING: When a multi-room request is ambiguous (guest count could be per-room or total), ask the user to clarify BEFORE calling any tool. Ambiguous: "2 rooms for 2 adults" (1 per room, or 2 per room?). Unambiguous: "2 rooms with 2 adults each" → [{adults: 2}, {adults: 2}].

Offers polling mode. Use 'fast' (default) for essentially all queries — price lookups, hotel discovery, recommendations, single-hotel fetches, comparisons within the returned offer set. Fast returns offers in under ~3 seconds with high coverage of available providers and is the right choice when the user just wants to see hotels and prices. Use 'deep' ONLY when the user explicitly asks for exhaustive price comparison across *every* provider (phrases like "check every OTA", "compare all providers", "exhaustive search"). Deep takes up to 10 seconds and is rarely warranted — prefer fast unless completeness is explicitly required.

Sort hotels by this criteria. ONLY use when user explicitly asks to sort/order results (e.g., "sort by price", "cheapest first", "highest rated"). Options: popularity (default), price, guestRating, starRating, distance.

Sort order direction. ONLY use with sortField when explicitly sorting. ascending (low to high) or descending (high to low).

Search for hotels near a specific ADDRESS or LANDMARK (NOT for hotel names). Use ONLY when user wants hotels NEAR a place: "near the Eiffel Tower", "near 123 Main Street", "close to Central Park". Do NOT use for hotel names - use queries instead (e.g., queries: ["Hilton Amsterdam"]). Do NOT use for destinations - use queries instead (e.g., queries: ["Paris, France"]). Mutually exclusive with queries/latitude/longitude/near_me.

3-char uppercase ISO currency code (e.g., 'USD', 'EUR', 'GBP'). ONLY provide this when the user EXPLICITLY mentions a currency (e.g., "show prices in EUR", "I want to pay in dollars"). Do NOT provide this field otherwise - leave it empty and it will be automatically derived from the user's country.

When true, run input parsing/normalization/validation but skip the upstream call. Returns the same output shape with empty results and the normalized stay metadata. Validation errors throw the same way as a real call.

Calendar end date (YYYY-MM-DD). Last check-in date to show availability for. Defaults to 14 days after startDate. Maximum range is 61 days from startDate.

Hotel-level search filters. All LOV-based filters (propertyTypes, facilities, themes) accept natural language terms in ENGLISH. FILTER COMBINATION LOGIC: - Multiple filter types combined = AND logic (e.g., starRatings:[4,5] + facilities:["gym","pool"] returns 4-5 star hotels WITH gym AND pool) - propertyTypes/excludePropertyTypes: OR logic (any match), mutually exclusive - facilities: AND logic (must have ALL) - themes: OR logic (any match) - starRatings/guestRating: OR logic (any match) NOTE: Offer-level filters (mealIncluded, freeCancellation, payLater) are in the offers options object.

List of hotel IDs to fetch data for. Use hotel IDs from previous search results. This fetches detailed information for these specific hotels without performing a search.

Latitude for geographic search (-90 to 90). Must be used with longitude. Use for coordinate-based searches like "hotels at 52.3676, 4.9041". Mutually exclusive with query/near_me.

Longitude for geographic search (-180 to 180). Must be used with latitude. Use for coordinate-based searches. Mutually exclusive with query/near_me.

Maximum number of hotels to check availability for (default 10, max 10). SAPI's /availability endpoint hard-caps at 5 per request, so values above 5 are split into parallel batches and merged. Wall-clock is similar across values (parallel calls), but each batch is an additional SAPI request — pass a lower number when SAPI load matters more than calendar diversity.

Search near user's current GPS location. Mutually exclusive with query/latitude/longitude.

Number of nights per stay when calculating rates (default 3). The availability calendar shows the cheapest rate for this stay duration at each check-in date.

Price display mode. 'total' returns prices for the entire stay (default). 'nightly' returns prices divided by number of nights for per-night rates.

The user prompt that triggered this tool call IN ENGLISH. If the user prompt is in another language, translate it to English first. IMPORTANT: Remove ALL personally identifiable information (PII) before sending. Strip out: names, emails, phone numbers, addresses, credit card numbers, passport/ID numbers, and any other personal data. Keep only the intent and travel-related details (destination, dates, preferences).

Search queries for finding hotels. Use this for ALL hotel searches including: (1) Destinations: "Paris, France", "Manhattan, New York", "Bahia, Brazil". (2) Specific hotels by name: "Hilton Amsterdam", "Marriott Times Square". (3) Similar hotels: To find hotels similar to a specific hotel, use the hotel name directly (e.g., queries: ["Leonardo Hotel Amsterdam"]). This returns the searched hotel plus similar alternatives nearby. Do NOT use the location - use the hotel name. (4) Multiple locations or hotels: ["Paris", "London"] or ["Hilton Paris", "Marriott Paris"] for comparison. IMPORTANT: Always provide complete context (e.g., "Lisbon, Portugal" not just "Lisbon", "Hilton Amsterdam" not just "Hilton"). Supports 1-3 queries. Results are merged using relevance ranking. Mutually exclusive with address/latitude/longitude/near_me.

Room configuration specifying occupancy for each room. CRITICAL: When the user mentions number of adults or children (e.g., "3 adults", "family of 4", "2 people"), you MUST extract this as the roomsConfiguration parameter. Each room requires an adults count and optional children ages (0-17). Examples: "3 adults" → [{adults: 3}], "2 adults and 1 child age 5" → [{adults: 2, children: [5]}], "2 rooms for 4 people" → [{adults: 2}, {adults: 2}]. Only use the default [{adults: 2}] if occupancy is NOT mentioned at all in the user query. AMBIGUITY HANDLING: When a multi-room request is ambiguous (guest count could be per-room or total), ask the user to clarify BEFORE calling any tool. Ambiguous: "2 rooms for 2 adults" (1 per room, or 2 per room?). Unambiguous: "2 rooms with 2 adults each" → [{adults: 2}, {adults: 2}].

Offers polling mode. Use 'fast' (default) for essentially all queries — price lookups, hotel discovery, recommendations, single-hotel fetches, comparisons within the returned offer set. Fast returns offers in under ~3 seconds with high coverage of available providers and is the right choice when the user just wants to see hotels and prices. Use 'deep' ONLY when the user explicitly asks for exhaustive price comparison across *every* provider (phrases like "check every OTA", "compare all providers", "exhaustive search"). Deep takes up to 10 seconds and is rarely warranted — prefer fast unless completeness is explicitly required.

Sort hotels by this criteria. ONLY use when user explicitly asks to sort/order results (e.g., "sort by price", "cheapest first", "highest rated"). Options: popularity (default), price, guestRating, starRating, distance.

Sort order direction. ONLY use with sortField when explicitly sorting. ascending (low to high) or descending (high to low).

Calendar start date (YYYY-MM-DD). First check-in date to show availability for. Defaults to 15 days from today. Must be today or a future date. IMPORTANT: When user specifies month/day without year (e.g., "January 25"), use the NEXT occurrence of that date. If that date has already passed this year, use next year.