AI（Claude やその他の MCP クライアント）が、固定のチェックイン/チェックアウト日ではなく、柔軟な日付範囲内の宿泊日数に基づいてホテルの部屋を検索できるようにする MCP（Model Context Protocol）サーバーです。
例：「テルアビブで3泊、9月1日から9月20日の間のどこかで」— サーバーは範囲内のすべての可能なチェックイン日をスキャンし、それぞれの実際の価格を取得して、価格順に並べた最もお得な取引を返します。
アフィリエイトモデル: これは価格比較ツールのみです — 支払い情報を収集したり、予約を実行したりすることはありません。各結果には、ユーザーが自分で購入を完了できるソース（現時点では Booking.com）へのリンク（bookingUrl）が含まれています。
データソース: Amadeus for Developers — 観光分野をリードする無料APIで、完全に無料のテスト環境（test）があり、クレジットカードは不要です。
AIに公開されている4つのツール:
ツール | 機能 |
| 自由形式の都市名（「テルアビブ」）をIATAコード（「TLV」）に変換する |
| 指定された都市のホテル（とID）のリストを返す |
| メインツール — 日付範囲内の宿泊日数による柔軟な検索。各結果に予約リンク付き |
| 特定の取引の完全な詳細と最新価格 + 予約リンク |
「柔軟な検索」ロジックはsrc/services/hotelSearch.tsに実装されています：Amadeus（および他のすべてのプロバイダー）は呼び出しごとに固定の日付範囲のみをサポートするため、サーバーは定義されたウィンドウ内のすべての可能なチェックイン日を自分でスキャンし、それに応じてAPIを呼び出し、結果を集約します。各結果へのリンクはsrc/services/affiliateLink.tsで構築されます。
Related MCP server: Amadeus Hotel API MCP Server
1. 無料のAPIキーを取得する（2分、クレジットカード不要）:
認証後、My Self-Service Workspace で「New App」を作成する
API Key と API Secret を受け取る — これらが AMADEUS_CLIENT_ID と AMADEUS_CLIENT_SECRET になります
これはtest（サンドボックス）環境です — 完全に無料で、寛大な月間クォータと毎秒約10リクエストのレート制限があります。世界中の数十万のホテルを実際のデータ（ただし不完全/キャッシュされた場合もあります）でカバーしています。将来、完全なライブデータに切り替えるには、Amadeusにproductionアクセスを申請（有料）し、AMADEUS_ENV=production に変更します。
2. ローカルインストール:
npm install
cp .env.example .env
# ערכו את .env והכניסו את המפתחות שקיבלתם
npm run build3. すべてが機能することを確認する（クォータを消費せず、Amadeusに実際のリクエストを送信しません）:
npm testnpm startデフォルトでは、サーバーはstdio経由で実行されます（Claude Desktopなどのクライアントへのローカル接続に適しています）。HTTP経由のリモートサーバーとして実行する場合（Claude.ai / Cowork への「カスタムコネクタ」として、または他のリモートMCPクライアントからの接続用）:
TRANSPORT=http PORT=3000 npm start設定ファイル claude_desktop_config.json に追加します:
{
"mcpServers": {
"flexible-hotels": {
"command": "node",
"args": ["/נתיב-מלא/ל/flexible-hotels-mcp-server/dist/index.js"],
"env": {
"AMADEUS_CLIENT_ID": "המפתח-שלכם",
"AMADEUS_CLIENT_SECRET": "הסוד-שלכם"
}
}
}
}Claude Desktopを再起動すると、AIは会話内でこれらのツールを直接呼び出せるようになります。
製品を複数のユーザーがローカルでコードを実行せずに「プラグイン」として利用できるようにするには、サーバーをTRANSPORT=httpモードでサーバー/ホストにデプロイし、クライアント設定で https://あなたのドメイン/mcp アドレスをカスタムMCPコネクタとして接続します。
Railway（すでにアカウント + CLIがインストールされている場合に推奨）:
cd flexible-hotels-mcp-server
railway login # רק אם עוד לא מחוברים — פותח דפדפן לאישור
railway up --new -y --detach --json # יוצר פרויקט חדש, מעלה את הקוד ומפעיל build מה-Dockerfile
railway variable set AMADEUS_CLIENT_ID=המפתח-שלכם --skip-deploys
railway variable set AMADEUS_CLIENT_SECRET=הסוד-שלכם --skip-deploys
railway variable set AMADEUS_ENV=test
railway domain # מפיק כתובת ציבורית כמו https://xxx.up.railway.appサーバーは、Amadeusキーを設定する前でも起動し（ヘルスチェックに合格します）— 実際のキーが設定されて自動再デプロイが行われるまで、検索ツールは明確なエラーを返すだけです。
Render: プロジェクトルートのrender.yamlファイルがBlueprintとして準備されています — repoをRenderに接続し、「New」→「Blueprint」で、インターフェースでAMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRETを入力します（ファイル内のコメントを参照）。
すべてのオプションで注意：AMADEUS_CLIENT_ID/AMADEUS_CLIENT_SECRETはホストサーバー上の環境変数として設定する必要があり、コードに記述してはいけません。
User: תמצא לי 3 לילות בתל אביב, איפשהו בין ה-1 ל-20 בספטמבר, לזוג.
AI calls: flexible_hotels_resolve_city_code(keyword="Tel Aviv")
-> TLV
AI calls: flexible_hotels_search_flexible_offers(
city_code="TLV", nights=3,
earliest_check_in="2026-09-01", latest_check_in="2026-09-20",
adults=2
)
-> רשימת עסקאות ממוינת מהזולה ביותר, עם תאריך צ'ק-אין/אאוט מדויק וקישור הזמנה לכל אחת
User: מעולה, תראה לי את הפרטים המלאים של האופציה הכי זולה.
AI calls: flexible_hotels_get_offer_details(offer_id="...")
-> מחיר מעודכן + קישור לחיצה שמעביר את המשתמש להשלים את ההזמנה באתר המקוריこのサーバーは予約を実行せず、いかなる段階でも支払い情報に触れません — これは意図的で、シンプルさ/安全性のためであり、また「外部チェックアウト」を要求し、ツール自体によるクレジットカード番号の収集を禁止するアプリストア（ChatGPT App Directoryなど）の仕組みに沿ったものです。
実際の仕組み:
サーバーはAmadeus（無料）を通じて実際の価格を検索します。
各結果について、ホテル名と日付が事前入力されたBooking.comの検索ページへのリンクが構築されます（src/services/affiliateLink.ts）。
Booking.com Affiliate Partner Program（無料、自己登録、特別な承認不要）に登録してaidを取得すると、環境変数BOOKING_AFFILIATE_IDとして設定できます — するとすべてのリンクにあなたのパートナーIDが含まれ、リンク経由で行われた予約に対してコミッションを受け取れます。
BOOKING_AFFILIATE_IDがなくてもリンクは完全に機能します — ただ報酬が発生しないだけです。
これはまさにあなたが求めた「登録するだけ」です：Booking.comのパートナープログラムへの一度きりの登録（AmadeusやRailwayではなく）だけで、リンクが収益を生み始めます。
無料クォータ: Amadeusのtest環境は月間クォータとリクエストレート（約10/秒）に制限があります。N日間のウィンドウでの柔軟な検索は最大N回のリクエストを送信します（間に軽い遅延あり）— ウィンドウが大きいほど検索が遅くなります。クォータを保護するため、ウィンドウは検索ごとに30日に制限されています。
ホテル数: デフォルトでは、各日付について都市内の最大15のホテルがチェックされます（max_hotelsで最大30まで増やせるか、特定のhotelIdsに絞り込めます）。
サンドボックスデータ: test環境では、カバレッジが最も信頼できるのは大都市（例：NYC、LON、PAR）です。小さな都市ではホテルが少ないかゼロの場合があります — これはproductionへの移行で解決されます。
予約リンクはホテル名と日付に基づいてBooking.comの検索を構築します — Amadeusが提供しないため、特定の部屋へのディープリンクではありません。ほとんどの場合、関連するホテルが結果の最初に表示されます。
src/
├── index.ts # נקודת כניסה, רישום השרת והכלים
├── constants.ts # קבועים (URLs, מגבלות)
├── types.ts # טיפוסי TypeScript משותפים
├── services/
│ ├── amadeusClient.ts # קליינט HTTP מאומת ל-Amadeus (OAuth2, endpoints)
│ ├── hotelSearch.ts # הלוגיקה של חיפוש גמיש (הליבה)
│ ├── affiliateLink.ts # בניית קישור ההזמנה (Booking.com + aid אופציונלי)
│ └── format.ts # פורמט markdown לתשובות
├── schemas/
│ └── schemas.ts # סכמות Zod לכל כלי
├── tools/ # רישום כל כלי MCP
└── test/
└── hotelSearch.test.ts # בדיקות יחידה ללוגיקת החיפוש (ללא צורך במפתח API)
scripts/
└── smoke-test-tools.mjs # בדיקת עשן שמפעילה את השרת האמיתי ומוודאת שכל הכלים נחשפים כראוי固定数ではなく柔軟な宿泊日数範囲（最小/最大泊数）。
クォータ節約のための検索結果のキャッシュ。
追加のアフィリエイトプログラム（Expedia、Agodaなど）への参加と、Booking.comだけでなく各結果に複数のソースへのリンクを表示。
製品が成長するにつれて、より広いプロバイダーカバレッジのための有料プロバイダー（StayAPI / RapidAPIなど）への移行。
ChatGPTアプリストア（Apps SDK）への登録 — 独自の要件（OpenAI開発者アカウント、プライバシーポリシー、テスト用デモアカウント）を持つ別プロジェクト。現在のアフィリエイトモデル（クレジットカード収集なし）は、すでに彼らの「外部チェックアウト」要件に準拠しています。
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)
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | The Amadeus offer id returned by search_flexible_hotel_offers, e.g. 'XYZ123' | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond these by disclosing that prices may shift, that it never collects payment details, that it returns a click-through link, and that expired offers produce a specific error message. This provides rich behavioral context that annotations alone do not offer, and it does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (main description, Args, Returns, Examples, Error Handling) and is front-loaded with the core purpose. It is somewhat repetitive of the input schema (the Args section duplicates schema descriptions), but each section carries useful information and there is no fluff. A slightly tighter version could omit the repetition, but overall it is appropriately concise for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the exact fields returned (hotel name, price, dates, room, board, cancellation deadline, booking link). It also covers error handling and usage context. For a single-offer detail tool with read-only semantics, nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already fully documents both offer_id and response_format, including their types, defaults, and descriptions. The description repeats the same info (e.g., 'offerId returned by search_flexible_hotel_offers') without adding new meaning beyond what the schema provides. The expiry note appears in error handling, not in parameter semantics, so the description adds marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('fetch'), a precise resource ('full, up-to-date details for a single hotel offer previously returned by search_flexible_hotel_offers'), and explicitly ties it to a sibling search tool. This clearly differentiates it from the siblings (resolve_city_code, list_hotels_in_city, search_flexible_offers), so an agent knows exactly what this tool does and when to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit 'Use when' and 'Don't use when' examples, including a concrete scenario (double-check price before booking) and a negative condition (no offer_id yet -> run search first). It also states the timing requirement ('call this before telling the user a final price or sending them to book'), leaving no ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| city_code | Yes | IATA city code, e.g. 'TLV' for Tel Aviv, 'PAR' for Paris (use resolve_city_code to find it) | |
| radius_km | No | Search radius around the city center, in kilometers | |
| max_results | No | Maximum hotels to return | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine value beyond annotations: it discloses that the tool does NOT return prices/availability, states 'This tool does not modify any data' (consistent with destructiveHint=false), and documents the exact error message for invalid city codes. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear section headers (Args, Returns, Examples, Error Handling) and is front-loaded with the core purpose. Every section earns its place — the examples, error handling, and return description all add operational value. Slightly longer than minimal, but the structure makes it scannable, and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (4 params, 1 required, all schema-documented, no nested objects, no output schema) with rich annotations. The description covers what's returned (hotel name, hotelId, chain code, coordinates), error handling, the chaining pattern with search_flexible_hotel_offers, and when not to use it. An agent has everything needed to call it correctly — including awareness that no output schema exists but the return content is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description largely mirrors the schema (e.g., radius range 1-300, default 20, response_format enum). It adds modest value by embedding usage context in the examples (e.g., 'narrow radius_km' for a beachfront search, 'use resolve_city_code to find it' — though that hint also exists in the schema). The description doesn't introduce meaning beyond what the schema provides, so 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb-resource-scope combination: 'List hotels (with their Amadeus hotelId) located in a given IATA city code, optionally within a radius.' It explicitly differentiates itself from search_flexible_hotel_offers by clarifying it returns only hotel identity/location, NOT prices or availability. An agent can distinguish this from all three siblings without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the exact alternative (search_flexible_hotel_offers), the chaining pattern (pass returned hotelIds into it), and provides concrete 'Use when' / 'Don't use when' examples. It even shows how to narrow radius_km for neighborhood-specific searches. Nothing about when to invoke this tool is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Free-text city name or the start of it, e.g. 'Tel Aviv', 'Par', 'New York' | |
| max_results | No | Maximum cities to return | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds beyond these by specifying the return format (name, iataCode, country code), the exact error message ('No cities found matching ...'), and clarifies it is a pure lookup with no side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with purpose and usage context. It includes a clear one-liner, a brief explanation of why it's used first, parameter descriptions (somewhat redundant with schema), returns, examples, and error handling. It is slightly lengthy due to repeating the Args section, but every section earns its place and the structure aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with three parameters, no output schema, and strong annotation coverage, this description covers all necessary aspects: purpose, when to use, examples, return format, and error handling. An agent can invoke it correctly without ambiguity, making it complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters fully documented. The tool description repeats parameter details (e.g., max_results range and default, response_format enum) but adds no new semantic meaning beyond what the schema already provides. It reinforces usage examples but does not introduce additional information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Look up the 3-letter IATA city code for a free-text city name,' with concrete examples (Tel Aviv -> TLV, Paris -> PAR). It clearly distinguishes itself from sibling tools by explaining that all other tools require an IATA city_code, making this the prerequisite lookup tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('normally the first tool to call when the user names a city') and when not to use it ('Don't use when: you already have a 3-letter IATA city code'). It names dependent tools (list_hotels_in_city, search_flexible_hotel_offers) and provides a concrete example of usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| adults | No | Number of adult guests per room | |
| nights | Yes | Exact number of consecutive nights the guest wants to stay, e.g. 3 | |
| currency | No | Optional 3-letter ISO currency code to request prices in, e.g. 'USD', 'EUR', 'ILS' | |
| city_code | Yes | IATA city code to search in, e.g. 'TLV' for Tel Aviv (use resolve_city_code to find it from a name) | |
| hotel_ids | No | Optional list of specific Amadeus hotelIds to restrict the search to (from list_hotels_in_city). If omitted, the tool automatically looks up hotels in city_code and checks up to max_hotels of them. | |
| max_hotels | No | When hotel_ids is not provided, how many hotels in the city to check (higher = more thorough but slower, capped at 30) | |
| max_results | No | Maximum number of offers to return, sorted cheapest first | |
| room_quantity | No | Number of rooms to book | |
| latest_check_in | Yes | Latest allowed check-in date, YYYY-MM-DD. Must be no more than 30 days after earliest_check_in. | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
| earliest_check_in | Yes | Earliest allowed check-in date, YYYY-MM-DD. The search scans every possible check-in date from this date through latest_check_in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint and destructiveHint=false, the description enriches the behavioral profile substantially. It discloses an affiliate-search model ('never collects payment details or creates a booking'), the external bookingUrl flow, the Amadeus sandbox data source, per-date error handling via datesSkipped, and the scanning of every check-in date. These details go well beyond the annotations and materially shape an agent's expectations for side effects and response quirks. No contradiction with annotations; readOnlyHint aligns with the stated no-booking behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but unusually well-organized. It front-loads the core concept and the key differentiator (flexible window vs fixed dates) in the opening sentences, then flows logically through an example, non-use cases, affiliate disclaimer, parameter list, return shape, usage examples, and error handling. Every section earns its place: the return JSON is especially valuable given the lack of an output schema, and the error-handling note covers edge cases an agent would otherwise discover only at runtime. No redundant filler; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema, the description is exceptionally complete. It specifies the exact JSON return structure, including datesSkipped with reason fields and the cheapest summary object, which an agent needs to parse results reliably. It covers error conditions (window >30 days, per-date failures), explains the scanning algorithm, and provides two representative use cases. Combined with full schema parameter descriptions and annotations, nothing required to correctly invoke and interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already documented. The description adds value by explaining the conceptual relationship between earliest_check_in and latest_check_in as a 'window' with a worked example ('3 nights in Tel Aviv... is expressed as nights=3, earliest_check_in="2026-09-01", latest_check_in="2026-09-20"'), and by clarifying default behaviors (max_hotels auto-check, response_format selection). These additions go beyond simple schema repetition, though the marginal gain is modest since the schema descriptions already cover the same facts. A solid 4, not a 5 because the added insight is illustrative rather than essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: 'Find the cheapest hotel offers for a fixed NUMBER OF NIGHTS across a WINDOW of possible check-in dates.' It specifies the resource (hotel offers), the action (find cheapest), and the distinctive scope (flexible dates rather than fixed). It also explicitly positions itself as 'the core tool of this server' and contrasts with sibling tools such as list_hotels_in_city and resolve_city_code, making its role unmistakable. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and actionable. It provides concrete when-to-use examples ('find me the cheapest 3-night stay in Paris sometime in the next month') and a clear don't-use case ('Don't use when: the user already has exact fixed dates in mind'), followed by the recommended alternative (set earliest_check_in = latest_check_in). It also points to companion tools (resolve_city_code, list_hotels_in_city) for prerequisites, making routing between siblings trivial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0flexible_hotels_get_offer_detailsflexible_hotels_list_hotels_in_cityflexible_hotels_resolve_city_codeflexible_hotels_search_flexible_offersScored across 4 tools
Each tool has a clearly distinct purpose: resolving city names to codes, listing hotels, searching flexible offers, and getting offer details. There is no overlap or ambiguity between them; the workflow is linear and obvious.
All tool names follow the same pattern: 'flexible_hotels_' prefix followed by a verb_noun combination (resolve_city_code, list_hotels_in_city, search_flexible_offers, get_offer_details). The verbs are consistent and descriptive, making the API predictable.
Four tools is on the lower end but well-scoped for a focused flexible hotel search server. Each tool is necessary and covers a distinct step in the workflow; there is no bloat or redundancy.
The server covers the complete user journey: resolve city → optionally list hotels → search offers → get details. For an affiliate-focused read-only service, the surface is complete with no obvious missing operations or dead ends.
Search and book 3M+ hotels in 200+ countries. Agents pay per reservation in USDC on Base over x402. Hosted, no auth.
Book real hotel and resort stays from any AI agent: all-in pricing, hosted Stripe checkout, no key.
Search hotel prices, get best overall and best direct price in structured response. Get your developer token at https://Infoseek.ai/mcp
Search MCP servers, agent skills and APIs for travel: hotel ID mapping, rates, rooms.
