search_hotels

Instructions

Implementation Reference

• src/server.ts:738-742 (handler)

  Handler for search_hotels: calls POST /v1/availability/search with the input args, trims the response via trimHotelResponse, and returns the result as formatted JSON text.

  case "search_hotels": {
    const result = await apiCall("POST", "/v1/availability/search", args);
    const trimmed = trimHotelResponse(result);
    return { content: [{ type: "text", text: JSON.stringify(trimmed, null, 2) }] };
  }

• src/server.ts:177-203 (schema)

  Schema/definition of search_hotels tool in ALL_TOOLS array, specifying input parameters (city, country, brand, check_in, check_out, room_type, max_rate_usd, amenities, min_star_rating) with check_in and check_out as required.

  {
    name: "search_hotels",
    description:
      "Search hotels, lodging, accommodations, resorts, and places to stay for a trip. Filter by city, country, check-in/check-out dates, room type, nightly price, star rating, and amenities (pool, gym, wifi, etc.). Returns matching properties with rates, photos, and availability across 2M+ properties (LiteAPI). Use this when the user wants to book a hotel, find a place to stay, compare lodging options, or pick a resort.",
    inputSchema: {
      type: "object" as const,
      properties: {
        city: { type: "string", description: "City name (e.g., 'New York', 'Tokyo')" },
        country: { type: "string", description: "ISO 3166-1 alpha-2 country code (e.g., 'US', 'JP')" },
        brand: { type: "string", description: "Hotel brand name to filter by" },
        check_in: { type: "string", description: "Check-in date (YYYY-MM-DD)" },
        check_out: { type: "string", description: "Check-out date (YYYY-MM-DD)" },
        room_type: {
          type: "string",
          enum: ["standard", "deluxe", "suite", "penthouse", "accessible"],
        },
        max_rate_usd: { type: "number", description: "Maximum nightly rate in USD" },
        amenities: {
          type: "array",
          items: { type: "string" },
          description: "Required amenities (wifi, gym, pool, spa, restaurant, etc.)",
        },
        min_star_rating: { type: "number", description: "Minimum star rating (1-5)" },
      },
      required: ["check_in", "check_out"],
    },
  },

• src/server.ts:525-532 (registration)

  Registration via ListToolsRequestSchema handler — search_hotels (and others) are exposed as available tools, filtered by AGENT_MODE (hotels is NOT in AGENT_MODE_ONLY_TOOLS so always visible).

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: ALL_TOOLS
      .filter((t) => AGENT_MODE || !AGENT_MODE_ONLY_TOOLS.has(t.name))
      .map((t) => {
        const a = TOOL_ANNOTATIONS[t.name];
        return a ? { ...t, annotations: a } : t;
      }),
  }));

• src/server.ts:543-631 (helper)

  Helper that trims/transforms the raw API hotel response: applies a quality-floor sort (3.5 star min → cheapest), deduplicates room rate variants, limits to 12 results, and strips unnecessary fields for LLM consumption.

  function trimHotelResponse(raw: any, limit = 12): any {
    const data = Array.isArray(raw?.data) ? raw.data : [];
    // "Best value" sort — quality floor then cheapest — so the top of the
    // list isn't a $40 budget motel with a 1-star rating just because it's
    // the cheapest. Approach:
    //   1. Apply a 3.5+ rating floor (using google_rating || star_rating).
    //      Hotels missing both ratings are tentatively kept (LiteAPI sometimes
    //      omits ratings for legitimate properties).
    //   2. If the floor leaves at least 5 results → sort those by cheapest.
    //      Otherwise relax to 3.0 floor; if STILL <5, drop the filter
    //      entirely so the LLM has something to show.
    //   3. Within the chosen pool, sort cheapest_rate ascending.
    const ratingOf = (h: any) => h.google_rating ?? h.star_rating ?? null;
    const rateOf = (h: any) => h.cheapest_rate ?? h.rate_usd ?? Infinity;
    const passesFloor = (h: any, min: number) => {
      const r = ratingOf(h);
      return r === null || r >= min;
    };
    let pool = data.filter((h: any) => passesFloor(h, 3.5));
    let appliedFloor: number | null = 3.5;
    if (pool.length < 5) {
      pool = data.filter((h: any) => passesFloor(h, 3.0));
      appliedFloor = pool.length >= 3 ? 3.0 : null;
      if (appliedFloor === null) pool = [...data];
    }
    const sorted = pool.sort((a: any, b: any) => rateOf(a) - rateOf(b));
    const trimmed = sorted.slice(0, limit).map((h: any) => {
      const rooms: any[] = h.available_rooms || h.rooms || h.rates || [];
      // Keep cheapest rate per distinct room name — booking-service already
      // dedupes some, but LiteAPI can still return 100+ rate variants per
      // property (Member Rate, Advance Purchase, etc.).
      const byRoom = new Map<string, any>();
      for (const r of rooms) {
        const key = (r.room_name || r.room_type || "Standard").trim();
        const prev = byRoom.get(key);
        if (!prev || (r.rate_usd ?? Infinity) < (prev.rate_usd ?? Infinity)) {
          byRoom.set(key, {
            room_name: r.room_name || r.room_type || "Standard",
            rate_id: r.rate_id || null,
            rate_usd: r.rate_usd,
            total_usd: r.total ?? null,
            board_type: r.board_type || "",
            refundable: !!r.refundable,
            cancel_policy: (r.cancel_policy || "").slice(0, 240),
            max_occupancy: r.max_occupancy || null,
          });
        }
      }
      const photos: any[] = (h.photos || h.images || []).slice(0, 1);
      return {
        property_id: h.property_id || h.property?.property_id || h.liteapi_hotel_id,
        offer_id: h.offer_id,
        name: h.name || h.property?.name,
        stars: h.star_rating || h.stars || h.property?.star_rating || null,
        city: h.city || h.property?.city,
        address: (h.address || h.property?.address || h.location_name || "").slice(0, 200),
        // Real field names from booking-service /v1/availability/search:
        //   cheapest_rate     → per-night USD
        //   total_cheapest    → total for the stay
        //   total_nights      → nights
        cheapest_rate_usd: h.cheapest_rate ?? h.price_per_night_usd ?? rooms[0]?.rate_usd ?? null,
        total_cheapest_usd: h.total_cheapest ?? null,
        total_nights: h.total_nights ?? null,
        currency: h.currency || "USD",
        google_rating: h.google_rating || h.rating || null,
        review_count: h.review_count || h.reviews_count || 0,
        description: (h.description || h.property?.description || "").replace(/<[^>]*>/g, "").slice(0, 360),
        thumbnail: typeof photos[0] === "string" ? photos[0] : photos[0]?.url || null,
        amenities: (h.amenities || []).slice(0, 8),
        rooms: Array.from(byRoom.values()).slice(0, 4),
        source: h.source || h.source_provider || "liteapi",
      };
    });
    return {
      data: trimmed,
      meta: {
        count: trimmed.length,
        total_returned: data.length,
        trimmed_for_llm: data.length > limit,
        // "Best value" = quality floor + cheapest. The LLM should treat
        // result[0] as the recommended cheapest-among-quality option, NOT
        // necessarily the absolute cheapest property in the city. If the
        // user explicitly asks for "cheapest no matter what" they can
        // re-call with cheapest_only or pick the lowest-rated result here.
        sorted_by: "best_value (quality_floor_then_cheapest)",
        quality_floor_applied: appliedFloor,
      },
    };
  }

• src/server.ts:505-518 (registration)

  Annotation registration: marks search_hotels as read-only, idempotent, and open-world for the MCP Connector Directory.

    search_hotels: { title: "Search Hotels", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    search_flights: { title: "Search Flights", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    search_transport: { title: "Search Ground Transport", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    search_dining: { title: "Search Restaurants & Dining", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    search_activities: { title: "Search Activities & Experiences", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    search_events: { title: "Search Live Events & Tickets", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    manage_trip: { title: "Manage Trip Lifecycle", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
    create_booking: { title: "Create Hotel Booking", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
    manage_booking: { title: "Manage Existing Booking", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
    submit_feedback: { title: "Submit Post-Stay Feedback", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
    check_rewards: { title: "Check $NOMD Rewards Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
    create_booking_intent: { title: "Create Booking Deep-Link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
    get_capabilities: { title: "Get Connector Capabilities", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
  };