Skip to main content
Glama
Sign In

Roomza Hotel Intelligence

by io.github.roomza-inc
OverviewDiscussionsAdmin

Search hotels

search_hotels
Read-onlyIdempotent

DISCOVERY ONLY: search Roomza's hotel database by city, keyword, or natural language query when the user has NOT named a specific hotel. Understands hotel types (boutique, resort, luxury), vibes (romantic, trendy, quiet), traveler types (couples, families, solo), neighborhoods, and nearby landmarks. Example queries: 'boutique hotels in SoHo', 'romantic resort near the Eiffel Tower', 'pet-friendly hotel in Seattle'. Renders for the user as a full map with a multi-hotel list (so do not repeat the list in prose). NEVER use this when the user names one specific hotel (e.g. 'Wynn Las Vegas'): the map of many hotels is wrong for that. Call get_hotel with the hotel name instead, then get_hotel_rooms and show_rooms.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_hotels"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityNoNarrow results to a specific city
limitNoMax results (default 10)
queryYesHotel name, city, or keyword
check_inNoCheck-in date YYYY-MM-DD, when the user gave dates
check_outNoCheck-out date YYYY-MM-DD

Output Schema

NameRequiredDescriptionDefault
noteYesSearch note, e.g. a nearby-city fallback explanation
stayNoThe dates passed to the search, echoed for the widget
countYesNumber of hotels returned
roomsNoSingle-hotel results only: that hotel's room cards, already shown to the user under the hotel
hotelsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / check_in
      Added value: +{
+  "description": "Check-in date YYYY-MM-DD, when the user gave dates",
+  "type": "string"
+}
    • addedInput schema / properties / check_out
      Added value: +{
+  "description": "Check-out date YYYY-MM-DD",
+  "type": "string"
+}
    • addedOutput schema / properties / hotels / items / properties / guestRating
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Guest score out of 10 from stays booked through the Nuitee network; not part of the Roomza score"
+}
    • addedOutput schema / properties / hotels / items / properties / guestReviews
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Number of guest reviews behind guestRating"
+}
    • addedOutput schema / properties / hotels / items / properties / photos
      Added value: +{
+  "description": "Single-hotel results only: header photos",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / hotels / items / properties / stars
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Supplier-declared star rating"
+}
    • changedOutput schema / properties / hotels / items / required
      Previous value: -[
-  "id",
-  "name",
-  "city",
-  "state",
-  "country",
-  "url",
-  "score",
-  "reviewCount",
-  "hotelType",
-  "vibes",
-  "neighborhood",
-  "lat",
-  "lng",
-  "photoUrl",
-  "roomCount",
-  "roomsWithRecords",
-  "fromNightly"
-]New value: +[
+  "id",
+  "name",
+  "city",
+  "state",
+  "country",
+  "url",
+  "score",
+  "reviewCount",
+  "hotelType",
+  "vibes",
+  "neighborhood",
+  "lat",
+  "lng",
+  "photoUrl",
+  "roomCount",
+  "roomsWithRecords",
+  "fromNightly",
+  "stars",
+  "guestRating",
+  "guestReviews"
+]
    • addedOutput schema / properties / rooms
      Added value: +{
+  "description": "Single-hotel results only: that hotel's room cards, already shown to the user under the hotel",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "bedType": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "blurb": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "bookUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Type cards only: Roomza stay flow with this room type preselected"
+      },
+      "currency": {
+        "type": "string"
+      },
+      "floor": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "hotelId": {
+        "type": "string"
+      },
+      "hotelName": {
+        "type": "string"
+      },
+      "id": {
+        "type": "string"
+      },
+      "kind": {
+        "description": "room = a numbered room with a Roomza record; type = a bookable room type at a hotel with no room records yet",
+        "enum": [
+          "room",
+          "type"
+        ],
+        "type": "string"
+      },
+      "location": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "photoSource": {
+        "anyOf": [
+          {
+            "enum": [
+              "room",
+              "hotel"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Whether photoUrl shows the actual room or is a hotel-level fallback"
+      },
+      "photoUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "priceNote": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Shown in the price slot when pricePerNight is null, e.g. a prompt to provide dates"
+      },
+      "pricePerNight": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Nightly price for the requested dates; null when no dates were given or no live rate exists"
+      },
+      "reviewCount": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "roomLabel": {
+        "type": "string"
+      },
+      "roomNumber": {
+        "type": "string"
+      },
+      "score": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "sqFt": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "url": {
+        "type": "string"
+      },
+      "view": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "id",
+      "hotelId",
+      "hotelName",
+      "location",
+      "roomLabel",
+      "roomNumber",
+      "floor",
+      "score",
+      "reviewCount",
+      "pricePerNight",
+      "priceNote",
+      "currency",
+      "photoUrl",
+      "photoSource",
+      "view",
+      "bedType",
+      "sqFt",
+      "blurb",
+      "url",
+      "kind",
+      "bookUrl"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / stay
      Added value: +{
+  "additionalProperties": false,
+  "description": "The dates passed to the search, echoed for the widget",
+  "properties": {
+    "check_in": {
+      "type": "string"
+    },
+    "check_out": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "check_in",
+    "check_out"
+  ],
+  "type": "object"
+}
  2. Changed7 schema fields changed
    • addedOutput schema / properties / hotels / items / properties / fromNightly
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Cached nightly from-price in USD; null when uncovered"
+}
    • addedOutput schema / properties / hotels / items / properties / lat
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / hotels / items / properties / lng
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / hotels / items / properties / photoUrl
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / hotels / items / properties / roomCount
      Added value: +{
+  "description": "Rooms tracked on Roomza for this hotel",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedOutput schema / properties / hotels / items / properties / roomsWithRecords
      Added value: +{
+  "description": "Tracked rooms with at least one verified review",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • changedOutput schema / properties / hotels / items / required
      Previous value: -[
-  "id",
-  "name",
-  "city",
-  "state",
-  "country",
-  "url",
-  "score",
-  "reviewCount",
-  "hotelType",
-  "vibes",
-  "neighborhood"
-]New value: +[
+  "id",
+  "name",
+  "city",
+  "state",
+  "country",
+  "url",
+  "score",
+  "reviewCount",
+  "hotelType",
+  "vibes",
+  "neighborhood",
+  "lat",
+  "lng",
+  "photoUrl",
+  "roomCount",
+  "roomsWithRecords",
+  "fromNightly"
+]
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "description": "Number of hotels returned",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "hotels": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "city": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "country": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "hotelType": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "id": {
+            "description": "Hotel UUID — pass to get_hotel_rooms, get_hotel_pricing, get_nearby, ask_about_hotel",
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "neighborhood": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "reviewCount": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "score": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Roomza score 0-100; null when unreviewed"
+          },
+          "state": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "url": {
+            "description": "Canonical Roomza hotel page",
+            "type": "string"
+          },
+          "vibes": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "city",
+          "state",
+          "country",
+          "url",
+          "score",
+          "reviewCount",
+          "hotelType",
+          "vibes",
+          "neighborhood"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "note": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Search note, e.g. a nearby-city fallback explanation"
+    }
+  },
+  "required": [
+    "count",
+    "note",
+    "hotels"
+  ],
+  "type": "object"
+}
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, closed-world, and non-destructive behavior. The description adds important behavioral context beyond annotations: it renders as a full map with a multi-hotel list, instructs the agent not to repeat that list in prose, and explains the natural-language query scope.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with 'DISCOVERY ONLY,' then gives examples, rendering behavior, and the critical exclusion. Every sentence contributes to correct tool selection or invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and complete parameter schema coverage, the description supplies the remaining needed context: discovery scope, natural-language capabilities, rendering behavior, and the exact alternative workflow for named hotels.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameter definitions are already well documented. The description adds meaningful semantic guidance for the required query parameter by explaining that it understands hotel types, vibes, traveler types, neighborhoods, and landmarks, though it does not add detail for limit or date parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('search Roomza's hotel database') and clearly scopes it as discovery-only for users who have not named a specific hotel. It explicitly distinguishes this tool from get_hotel, get_hotel_rooms, and show_rooms, so an agent can route correctly without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly when to use the tool (city, keyword, natural language discovery) and when never to use it (when the user names one specific hotel). It names the alternative workflow explicitly: get_hotel, then get_hotel_rooms, then show_rooms.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Roomza Hotel Intelligence toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources