1stay

Search Hotels

search_hotels

Read-only

Search hotels by location and dates for exactly one room. Returns available properties with nightly rates across major brands, boutique, and independent hotels.

The first 1Stay release supports one room per search and reservation. Guest pays the hotel directly. Hotel's own confirmation number. Loyalty points apply.

Input Schema

TableJSON Schema

Name	Required	Description
`rooms`	No	Number of rooms. 1Stay currently supports exactly one room per search and reservation; omit this field or set it to 1.
`cursor`	No	Pagination cursor from previous search response
`radius`	No	Search radius in miles, 1-100 (default 25). Applies only when the search resolves to coordinates - explicit latitude/longitude, or a venue, landmark or address that is geocoded. It is ignored for city searches, which resolve to a city code; the response reports which happened in resolution_type.
`check_in`	Yes	Check-in date in YYYY-MM-DD format (e.g. 2026-05-06). Must be today through 340 days from today.
`currency`	No	Currency code (default USD)
`latitude`	No	Latitude — must be provided together with longitude
`location`	No	City, address, venue, or landmark (e.g. 'Nashville, TN' or 'Times Square, NYC'). Required unless latitude and longitude are both provided.
`check_out`	Yes	Check-out date in YYYY-MM-DD format (e.g. 2026-05-07). Must be after check_in.
`longitude`	No	Longitude — must be provided together with latitude
`search_id`	No	Search ID paired with a pagination cursor from previous results
`max_results`	No	Max hotels to return, max 6 (default 6). Results are a representative selection across different hotel brands, not a ranking. Use the returned cursor to load more pages.
`guests_per_room`	No	Guests per room, 1-10 (default 2)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`rooms`	No
`cursor`	Yes
`results`	Yes
`check_in`	Yes
`has_more`	Yes
`check_out`	Yes
`search_id`	No
`total_results`	Yes
`guests_per_room`	No
`resolution_type`	No
`resolved_location`	No
`conversion_applied`	No
`requested_currency`	No
`returned_currencies`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedSep 24, 2026

changedInput schema / properties / guests_per_room / description

Previous value: -"Guests per room (default 2)"New value: +"Guests per room, 1-10 (default 2)"

changedInput schema / properties / guests_per_room / maximum
```
Previous value: -9007199254740991New value: +10
```
changedInput schema / properties / guests_per_room / minimum
```
Previous value: --9007199254740991New value: +1
```

changedInput schema / properties / max_results / description

Previous value: -"Max hotels to return, max 4 (default 4). Use the returned cursor to load more pages."New value: +"Max hotels to return, max 6 (default 6). Results are a representative selection across different hotel brands, not a ranking. Use the returned cursor to load more pages."

changedInput schema / properties / max_results / maximum
```
Previous value: -4New value: +6
```

changedInput schema / properties / radius / description

Previous value: -"Search radius in miles (default 25, max 100)"New value: +"Search radius in miles, 1-100 (default 25). Applies only when the search resolves to coordinates - explicit latitude/longitude, or a venue, landmark or address that is geocoded. It is ignored for city searches, which resolve to a city code; the response reports which happened in resolution_type."

changedInput schema / properties / radius / maximum

Previous value: -9007199254740991New value: +100

changedInput schema / properties / radius / minimum

Previous value: --9007199254740991New value: +1

Changed35 schema fields changedSep 19, 2026
- changedInput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / guests_per_room / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / guests_per_room / minimum
```
Added value: +-9007199254740991
```
- changedInput schema / properties / max_results / description
```
Previous value: -"Max hotels to return, max 15 (default 4)"New value: +"Max hotels to return, max 4 (default 4). Use the returned cursor to load more pages."
```
- addedInput schema / properties / max_results / maximum
```
Added value: +4
```
- addedInput schema / properties / max_results / minimum
```
Added value: +1
```
- addedInput schema / properties / radius / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / radius / minimum
```
Added value: +-9007199254740991
```
- removedInput schema / properties / rooms / const
```
Removed value: -1
```
- addedInput schema / properties / rooms / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / rooms / minimum
```
Added value: +-9007199254740991
```
- changedInput schema / properties / rooms / type
```
Previous value: -"number"New value: +"integer"
```
- changedOutput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- addedOutput schema / properties / check_in
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / check_out
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / cursor / $ref
```
Removed value: -"#/properties/results/items/properties/photo"
```
- addedOutput schema / properties / cursor / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- addedOutput schema / properties / guests_per_room / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / guests_per_room / minimum
```
Added value: +-9007199254740991
```
- changedOutput schema / properties / results / items / properties / address / additionalProperties
```
Previous value: -trueNew value: +{}
```
- removedOutput schema / properties / results / items / properties / avg_nightly_rate / $ref
```
Removed value: -"#/properties/results/items/properties/total_stay"
```
- addedOutput schema / properties / results / items / properties / avg_nightly_rate / anyOf
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / results / items / properties / distance_miles
```
Removed value: -{
-  "type": "number"
-}
```
- addedOutput schema / properties / results / items / properties / nights / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / results / items / properties / nights / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / results / items / properties / photo / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / results / items / properties / photo / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
- addedOutput schema / properties / results / items / properties / total_stay / anyOf
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / results / items / properties / total_stay / type
```
Removed value: -[
-  "number",
-  "null"
-]
```
- addedOutput schema / properties / rooms / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / rooms / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / total_results / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / total_results / minimum
```
Added value: +-9007199254740991
```
- changedOutput schema / required
```
Previous value: -[
-  "results",
-  "total_results",
-  "cursor",
-  "has_more"
-]New value: +[
+  "results",
+  "total_results",
+  "check_in",
+  "check_out",
+  "cursor",
+  "has_more"
+]
```
Changed27 schema fields changedAug 25, 2026
- changedInput schema / $schema
```
Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"
```
- addedInput schema / additionalProperties
```
Added value: +false
```
- removedInput schema / properties / guests_per_room / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / guests_per_room / minimum
```
Removed value: --9007199254740991
```
- changedInput schema / properties / max_results / description
```
Previous value: -"Hotels per page, max 4 (default 4). Use the returned cursor for more."New value: +"Max hotels to return, max 15 (default 4)"
```
- removedInput schema / properties / max_results / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / max_results / minimum
```
Removed value: --9007199254740991
```
- removedInput schema / properties / radius / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / radius / minimum
```
Removed value: --9007199254740991
```
- changedOutput schema / $schema
```
Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"
```
- addedOutput schema / properties / cursor / $ref
```
Added value: +"#/properties/results/items/properties/photo"
```
- removedOutput schema / properties / cursor / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / properties / guests_per_room / maximum
```
Removed value: -9007199254740991
```
- removedOutput schema / properties / guests_per_room / minimum
```
Removed value: --9007199254740991
```
- changedOutput schema / properties / results / items / properties / address / additionalProperties
```
Previous value: -{}New value: +true
```
- addedOutput schema / properties / results / items / properties / avg_nightly_rate / $ref
```
Added value: +"#/properties/results/items/properties/total_stay"
```
- removedOutput schema / properties / results / items / properties / avg_nightly_rate / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / properties / results / items / properties / nights / maximum
```
Removed value: -9007199254740991
```
- removedOutput schema / properties / results / items / properties / nights / minimum
```
Removed value: --9007199254740991
```
- removedOutput schema / properties / results / items / properties / photo / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / photo / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / results / items / properties / total_stay / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / total_stay / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / rooms / maximum
```
Removed value: -9007199254740991
```
- removedOutput schema / properties / rooms / minimum
```
Removed value: --9007199254740991
```
- removedOutput schema / properties / total_results / maximum
```
Removed value: -9007199254740991
```
- removedOutput schema / properties / total_results / minimum
```
Removed value: --9007199254740991
```
Changed27 schema fields changedAug 24, 2026
- changedInput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / guests_per_room / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / guests_per_room / minimum
```
Added value: +-9007199254740991
```
- changedInput schema / properties / max_results / description
```
Previous value: -"Max hotels to return, max 15 (default 4)"New value: +"Hotels per page, max 4 (default 4). Use the returned cursor for more."
```
- addedInput schema / properties / max_results / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / max_results / minimum
```
Added value: +-9007199254740991
```
- addedInput schema / properties / radius / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / radius / minimum
```
Added value: +-9007199254740991
```
- changedOutput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- removedOutput schema / properties / cursor / $ref
```
Removed value: -"#/properties/results/items/properties/photo"
```
- addedOutput schema / properties / cursor / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- addedOutput schema / properties / guests_per_room / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / guests_per_room / minimum
```
Added value: +-9007199254740991
```
- changedOutput schema / properties / results / items / properties / address / additionalProperties
```
Previous value: -trueNew value: +{}
```
- removedOutput schema / properties / results / items / properties / avg_nightly_rate / $ref
```
Removed value: -"#/properties/results/items/properties/total_stay"
```
- addedOutput schema / properties / results / items / properties / avg_nightly_rate / anyOf
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
```
- addedOutput schema / properties / results / items / properties / nights / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / results / items / properties / nights / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / results / items / properties / photo / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / results / items / properties / photo / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
- addedOutput schema / properties / results / items / properties / total_stay / anyOf
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / results / items / properties / total_stay / type
```
Removed value: -[
-  "number",
-  "null"
-]
```
- addedOutput schema / properties / rooms / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / rooms / minimum
```
Added value: +-9007199254740991
```
- addedOutput schema / properties / total_results / maximum
```
Added value: +9007199254740991
```
- addedOutput schema / properties / total_results / minimum
```
Added value: +-9007199254740991
```

Changed1 schema field changedAug 19, 2026

changedInput schema / properties / check_in / description

Previous value: -"Check-in date in YYYY-MM-DD format (e.g. 2026-05-06). Must be today or later."New value: +"Check-in date in YYYY-MM-DD format (e.g. 2026-05-06). Must be today through 340 days from today."

Changed3 schema fields changedAug 18, 2026

addedInput schema / properties / rooms / const
```
Added value: +1
```

changedInput schema / properties / rooms / description

Previous value: -"Number of rooms to search for (default 1, maximum 5). MCP checkout creates one room per reservation."New value: +"Number of rooms. 1Stay currently supports exactly one room per search and reservation; omit this field or set it to 1."

changedInput schema / properties / rooms / type

Previous value: -"integer"New value: +"number"

Changed3 schema fields changedAug 17, 2026

changedInput schema / properties / rooms / description

Previous value: -"Number of rooms (default 1)"New value: +"Number of rooms to search for (default 1, maximum 5). MCP checkout creates one room per reservation."

changedInput schema / properties / search_id / description

Previous value: -"Search ID from previous results — pass with cursor for next page"New value: +"Search ID paired with a pagination cursor from previous results"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "conversion_applied": {
+      "type": "boolean"
+    },
+    "cursor": {
+      "$ref": "#/properties/results/items/properties/photo"
+    },
+    "guests_per_room": {
+      "type": "integer"
+    },
+    "has_more": {
+      "type": "boolean"
+    },
+    "requested_currency": {
+      "type": "string"
+    },
+    "resolution_type": {
+      "type": "string"
+    },
+    "resolved_location": {
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "address": {
+            "additionalProperties": true,
+            "properties": {
+              "city": {
+                "type": "string"
+              },
+              "country": {
+                "type": "string"
+              },
+              "line1": {
+                "type": "string"
+              },
+              "postal_code": {
+                "type": "string"
+              },
+              "state": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "amenities": {
+            "items": {},
+            "type": "array"
+          },
+          "avg_nightly_rate": {
+            "$ref": "#/properties/results/items/properties/total_stay"
+          },
+          "booking_fee": {
+            "type": "number"
+          },
+          "booking_fee_currency": {
+            "type": "string"
+          },
+          "booking_type": {
+            "type": "string"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "distance_miles": {
+            "type": "number"
+          },
+          "hotel_id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "nights": {
+            "type": "integer"
+          },
+          "photo": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "review": {},
+          "reward_points_eligible": {
+            "type": "boolean"
+          },
+          "star_rating": {
+            "type": "number"
+          },
+          "total_stay": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "hotel_id",
+          "name",
+          "photo",
+          "total_stay",
+          "avg_nightly_rate",
+          "nights",
+          "currency",
+          "amenities",
+          "reward_points_eligible",
+          "booking_type"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "returned_currencies": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "rooms": {
+      "type": "integer"
+    },
+    "search_id": {
+      "type": "string"
+    },
+    "total_results": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "results",
+    "total_results",
+    "cursor",
+    "has_more"
+  ],
+  "type": "object"
+}

Changed1 schema field changedAug 10, 2026

removedInput schema / properties / chain_code

Removed value: -{
-  "description": "Two-letter hotel chain filter. MC=Marriott, HH=Hilton, HI=IHG, YX=Hyatt, BW=Best Western, WY=Wyndham, EL=Choice. Omit for boutique, independent, or unbranded searches.",
-  "type": "string"
-}

Changed1 schema field changedAug 7, 2026

changedInput schema / properties / max_results / description

Previous value: -"Max hotels to return, max 4 (default 4)"New value: +"Max hotels to return, max 15 (default 4)"

Changed1 schema field changedAug 4, 2026

changedInput schema / properties / max_results / description

Previous value: -"Max hotels to return, max 15 (default 10)"New value: +"Max hotels to return, max 4 (default 4)"

Changed2 schema fields changedAug 3, 2026

changedInput schema / properties / location / description

Previous value: -"City, address, venue, or landmark (e.g. 'Nashville, TN' or 'Times Square, NYC'). Required for all searches."New value: +"City, address, venue, or landmark (e.g. 'Nashville, TN' or 'Times Square, NYC'). Required unless latitude and longitude are both provided."

changedInput schema / required

Previous value: -[
-  "location",
-  "check_in",
-  "check_out"
-]New value: +[
+  "check_in",
+  "check_out"
+]

Changed1 schema field changedMay 26, 2026

changedInput schema / properties / chain_code / description

Previous value: -"Filter by hotel chain code (e.g. 'MC' for Marriott, 'HH' for Hilton)"New value: +"Two-letter hotel chain filter. MC=Marriott, HH=Hilton, HI=IHG, YX=Hyatt, BW=Best Western, WY=Wyndham, EL=Choice. Omit for boutique, independent, or unbranded searches."

Changed1 schema field changedApr 6, 2026

changedInput schema / properties / chain_code / description

Previous value: -"Two-letter hotel chain filter. MC=Marriott, HH=Hilton, HI=IHG, YX=Hyatt, BW=Best Western, WY=Wyndham, EL=Choice. Omit for boutique, independent, or unbranded searches."New value: +"Filter by hotel chain code (e.g. 'MC' for Marriott, 'HH' for Hilton)"

Changed1 schema field changedApr 1, 2026

changedInput schema / properties / chain_code / description

Previous value: -"Filter by hotel chain code (e.g. 'MC' for Marriott, 'HH' for Hilton)"New value: +"Two-letter hotel chain filter. MC=Marriott, HH=Hilton, HI=IHG, YX=Hyatt, BW=Best Western, WY=Wyndham, EL=Choice. Omit for boutique, independent, or unbranded searches."

Changed6 schema fields changedMar 25, 2026

changedInput schema / properties / check_in / description

Previous value: -"Check-in date (YYYY-MM-DD)"New value: +"Check-in date in YYYY-MM-DD format (e.g. 2026-05-06). Must be today or later."

changedInput schema / properties / check_out / description

Previous value: -"Check-out date (YYYY-MM-DD)"New value: +"Check-out date in YYYY-MM-DD format (e.g. 2026-05-07). Must be after check_in."

changedInput schema / properties / latitude / description

Previous value: -"Latitude — skip geocoding if provided with longitude"New value: +"Latitude — must be provided together with longitude"

changedInput schema / properties / location / description

Previous value: -"City, address, venue, or landmark. Required unless latitude/longitude provided."New value: +"City, address, venue, or landmark (e.g. 'Nashville, TN' or 'Times Square, NYC'). Required for all searches."

changedInput schema / properties / longitude / description

Previous value: -"Longitude — skip geocoding if provided with latitude"New value: +"Longitude — must be provided together with latitude"

changedInput schema / required

Previous value: -[
-  "check_in",
-  "check_out"
-]New value: +[
+  "location",
+  "check_in",
+  "check_out"
+]

First observedMar 18, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds beyond that: the 1Stay release limits searches/reservations to one room, guests pay the hotel directly, the hotel issues its own confirmation number, and loyalty points apply. This provides useful service-context behavior not present in the annotations.

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?

Two short paragraphs, front-loaded with the core search action and outcome, followed by concise service constraints. Every sentence adds value and there is no fluff or redundancy.

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

Completeness4/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 are covered elsewhere. The description plus schema fully address the one-room constraint, payment model, and search scope. It could be slightly more complete by pointing to sibling tools, but that belongs more under usage guidance.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema carries the parameter details. The description only restates 'location and dates' and 'exactly one room,' which duplicates what the schema already specifies; it adds no new parameter meaning.

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 names the specific verb 'Search' and resource 'hotels', and adds meaningful scope: by location and dates, for exactly one room, returning nightly rates across major brands. This clearly differentiates it from booking/management siblings like book_hotel and get_booking, so an agent can identify the tool without opening schemas.

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

Usage Guidelines3/5

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

The description implies the primary use case (finding available hotels) but does not explicitly contrast with alternatives like get_hotel_details or book_hotel, nor state conditions for when not to use the tool. The one-room constraint is present but is more a service limitation than guidance on tool selection.

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

All 1stay tools Inspect

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.

Search Hotels

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources