Skip to main content
Glama
Sign In

Roomza Hotel Intelligence

by io.github.roomza-inc
OverviewDiscussionsAdmin

Show rooms

show_rooms
Read-onlyIdempotent

REQUIRED whenever you present rooms. Whenever you are about to mention, recommend, or describe one or more specific rooms to the user, you MUST call this tool with those room UUIDs INSTEAD of writing the rooms in text. This is mandatory even when there is only ONE matching room — show it as a single hero card, never describe a lone room in prose. Call this BEFORE writing any prose about the rooms; the cards must appear first, then a brief summary. Pass room UUIDs (from get_hotel_rooms or search results) in ranked order, best first, 1 to 8 rooms. ALWAYS pass check_in and check_out when you know the user's dates: card prices are then for those exact dates. Without dates, cards show a typical from-price that can differ a lot from any specific dates. Each card shows photo, Roomza score, view, bed, and price. NEVER ask the user whether they want to see cards or images — just call this tool. When get_hotel_rooms returns no tracked rooms (a roomTypes list instead), call this with hotel_id and no room_ids: it renders the hotel's bookable room types as cards with photos and prices, each linking straight to booking.

Input Schema

NameRequiredDescriptionDefault
check_inNoCheck-in date YYYY-MM-DD. Pass whenever the user's dates are known so card prices match those dates.
hotel_idNoHotel UUID or slug. Pass INSTEAD of room_ids when get_hotel_rooms found no tracked rooms: shows the hotel's bookable room types as cards. With tracked rooms and no room_ids, shows its top-scored rooms.
room_idsNoRoom UUIDs to display, in ranked order (best first). 1-8 rooms. Omit when passing hotel_id for a hotel with no tracked rooms.
check_outNoCheck-out date YYYY-MM-DD.

Output Schema

NameRequiredDescriptionDefault
stayNoThe dates the card prices are for, echoed for the widget
roomsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / hotel_id
      Added value: +{
+  "description": "Hotel UUID or slug. Pass INSTEAD of room_ids when get_hotel_rooms found no tracked rooms: shows the hotel's bookable room types as cards. With tracked rooms and no room_ids, shows its top-scored rooms.",
+  "type": "string"
+}
    • changedInput schema / properties / room_ids / description
      Previous value: -"Room UUIDs to display, in ranked order (best first). 1-8 rooms."New value: +"Room UUIDs to display, in ranked order (best first). 1-8 rooms. Omit when passing hotel_id for a hotel with no tracked rooms."
    • removedInput schema / properties / room_ids / minItems
      Removed value: -1
    • removedInput schema / required
      Removed value: -[
-  "room_ids"
-]
    • addedOutput schema / properties / rooms / items / properties / bookUrl
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Type cards only: Roomza stay flow with this room type preselected"
+}
    • addedOutput schema / properties / rooms / items / properties / kind
      Added value: +{
+  "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"
+}
    • changedOutput schema / properties / rooms / items / required
      Previous value: -[
-  "id",
-  "hotelId",
-  "hotelName",
-  "location",
-  "roomLabel",
-  "roomNumber",
-  "floor",
-  "score",
-  "reviewCount",
-  "pricePerNight",
-  "priceNote",
-  "currency",
-  "photoUrl",
-  "photoSource",
-  "view",
-  "bedType",
-  "sqFt",
-  "blurb",
-  "url"
-]New value: +[
+  "id",
+  "hotelId",
+  "hotelName",
+  "location",
+  "roomLabel",
+  "roomNumber",
+  "floor",
+  "score",
+  "reviewCount",
+  "pricePerNight",
+  "priceNote",
+  "currency",
+  "photoUrl",
+  "photoSource",
+  "view",
+  "bedType",
+  "sqFt",
+  "blurb",
+  "url",
+  "kind",
+  "bookUrl"
+]
    • addedOutput schema / properties / stay
      Added value: +{
+  "additionalProperties": false,
+  "description": "The dates the card prices are for, echoed for the widget",
+  "properties": {
+    "check_in": {
+      "type": "string"
+    },
+    "check_out": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "check_in",
+    "check_out"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changed
    • addedOutput schema / properties / rooms / items / properties / photoSource
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "room",
+        "hotel"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Whether photoUrl shows the actual room or is a hotel-level fallback"
+}
    • changedOutput schema / properties / rooms / items / required
      Previous value: -[
-  "id",
-  "hotelId",
-  "hotelName",
-  "location",
-  "roomLabel",
-  "roomNumber",
-  "floor",
-  "score",
-  "reviewCount",
-  "pricePerNight",
-  "priceNote",
-  "currency",
-  "photoUrl",
-  "view",
-  "bedType",
-  "sqFt",
-  "blurb",
-  "url"
-]New value: +[
+  "id",
+  "hotelId",
+  "hotelName",
+  "location",
+  "roomLabel",
+  "roomNumber",
+  "floor",
+  "score",
+  "reviewCount",
+  "pricePerNight",
+  "priceNote",
+  "currency",
+  "photoUrl",
+  "photoSource",
+  "view",
+  "bedType",
+  "sqFt",
+  "blurb",
+  "url"
+]
  3. Changed5 schema fields changed
    • addedInput schema / properties / check_in
      Added value: +{
+  "description": "Check-in date YYYY-MM-DD. Pass whenever the user's dates are known so card prices match those dates.",
+  "type": "string"
+}
    • addedInput schema / properties / check_out
      Added value: +{
+  "description": "Check-out date YYYY-MM-DD.",
+  "type": "string"
+}
    • addedOutput schema / properties / rooms / items / properties / priceNote
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Shown in the price slot when pricePerNight is null, e.g. a prompt to provide dates"
+}
    • addedOutput schema / properties / rooms / items / properties / pricePerNight / description
      Added value: +"Nightly price for the requested dates; null when no dates were given or no live rate exists"
    • changedOutput schema / properties / rooms / items / required
      Previous value: -[
-  "id",
-  "hotelId",
-  "hotelName",
-  "location",
-  "roomLabel",
-  "roomNumber",
-  "floor",
-  "score",
-  "reviewCount",
-  "pricePerNight",
-  "currency",
-  "photoUrl",
-  "view",
-  "bedType",
-  "sqFt",
-  "blurb",
-  "url"
-]New value: +[
+  "id",
+  "hotelId",
+  "hotelName",
+  "location",
+  "roomLabel",
+  "roomNumber",
+  "floor",
+  "score",
+  "reviewCount",
+  "pricePerNight",
+  "priceNote",
+  "currency",
+  "photoUrl",
+  "view",
+  "bedType",
+  "sqFt",
+  "blurb",
+  "url"
+]
  4. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "rooms": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "bedType": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "blurb": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "currency": {
+            "type": "string"
+          },
+          "floor": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "hotelId": {
+            "type": "string"
+          },
+          "hotelName": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "location": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "photoUrl": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "pricePerNight": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "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",
+          "currency",
+          "photoUrl",
+          "view",
+          "bedType",
+          "sqFt",
+          "blurb",
+          "url"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "rooms"
+  ],
+  "type": "object"
+}
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds substantial behavior: what each card renders (photo, score, view, bed, price), how prices change based on whether dates are passed, the 1-8 cap, and the fallback rendering mode. This is exactly the context annotations cannot express.

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

Conciseness4/5

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

The mandatory call instruction and the cards-first ordering are front-loaded, which is the right priority. It is long and uses heavy capitalization for emphasis, and a couple of sentences (the 'mandatory even when there is only ONE room' clause) restate the same rule, but every section carries operational information.

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?

An output schema exists, so return values need no explanation, and the description covers the remaining decisions an agent must make: when to call, source of UUIDs, ordering, date handling, and the no-tracked-rooms fallback. Complete for this tool's complexity.

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 the baseline is 3, but the description adds real meaning: room_ids must be in ranked order best-first and capped at 8, hotel_id is the substitute when no tracked rooms exist, and check_in/check_out materially change displayed prices. Only slight duplication of the schema text keeps it from a 5.

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?

States a specific verb and resource ('show rooms' as rendered cards) and explicitly separates itself from siblings get_hotel_rooms and search results by naming them as the source of UUIDs. An agent can tell immediately that this is the presentation tool, not a retrieval tool.

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?

Gives explicit when-to-use triggers ('whenever you are about to mention, recommend, or describe one or more specific rooms'), explicit exclusions ('NEVER ask the user whether they want to see cards'), the ordering rule (cards first, then prose), and the alternative path (hotel_id fallback when get_hotel_rooms returns no tracked rooms). Nothing 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.

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