HemmaBo Host Booking Engine

Search Properties

hemmabo_search_properties

Read-only

Search available vacation rental properties by location and travel dates. Use when the user wants to find or browse places to stay. Discovery only, and price-free: call vrp_get_verified_stay_offer with the host domain and same dates before the final answer so the client can render the verified stay offer widget; the price and the signed booking link come only from that offer. Do NOT use when the user already has a propertyId or host domain. Returns propertyId, host domain, the host's booking_url, live availability and capacity. Parameters combine as one filter with guests and the checkIn/checkOut range (checkIn strictly before checkOut): region matches broadly against region, city, and country names, while country matches the country field alone — omit both and the search spans every published property. Capacity misses are excluded; date-unavailable matches return separately in unavailableMatches with up to three alternative windows. Booking and payment happen only on the host's own domain, at the signed direct_booking_url. The agent never books, pays, cancels or changes a booking.

Input Schema

TableJSON Schema

Name	Required	Description
`guests`	Yes	Total guest count as a positive integer (e.g. 2, 4, 6). Used for capacity filtering and staircase pricing tiers. Properties with maxGuests below this value are excluded from search results.
`region`	No	Region, area, or destination to search within (e.g. 'Skåne', 'Kävlinge', 'Toscana', 'Bavaria'). Partial case-insensitive match against region, city, and country. Optional — omit both region and country and the search spans every published property.
`checkIn`	Yes	Arrival date in ISO 8601 calendar format YYYY-MM-DD (e.g. '2026-07-15'). Must be today or later in the property's timezone. Must be strictly before checkOut; together they define the stay length used for pricing and availability.
`country`	No	Country name to filter by (e.g. 'Sweden', 'Italy', 'Morocco'). Partial case-insensitive match against the country field. Optional — omit both region and country and the search spans every published property.
`checkOut`	Yes	Departure date in ISO 8601 calendar format YYYY-MM-DD (e.g. '2026-07-22'). Must be strictly after checkIn on the same calendar. The guest does not stay the departure night.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present only when isError=true.
`guests`	No	Echoed guest count.
`checkIn`	No	Echoed check-in date (YYYY-MM-DD).
`checkOut`	No	Echoed check-out date (YYYY-MM-DD).
`properties`	No	Available properties matching the search criteria: each host domain and its own booking URL, without a price.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 12, 2026

changedOutput schema / properties / properties / description

Previous value: -"Available properties matching the search criteria, with live host-source pricing."New value: +"Available properties matching the search criteria: each host domain and its own booking URL, without a price."

removedOutput schema / properties / properties / items / properties / currency

Removed value: -{
-  "description": "ISO 4217 currency code (e.g. 'SEK', 'EUR').",
-  "type": "string"
-}

removedOutput schema / properties / properties / items / properties / directBookingTotal

Removed value: -{
-  "description": "Preferred field for user-facing copy: direct host-source total, in whole units of the property's currency (not minor units).",
-  "type": "integer"
-}

removedOutput schema / properties / properties / items / properties / federationTotal

Removed value: -{
-  "description": "Legacy field: the direct host-source total (the same value as directBookingTotal), in whole units of the property's currency (not minor units). Use directBookingTotal in user-facing copy.",
-  "type": "integer"
-}

removedOutput schema / properties / properties / items / properties / hostSourcePublicTotal

Removed value: -{
-  "description": "Preferred field for user-facing copy: public host-source total for the date range, in whole units of the property's currency (not minor units).",
-  "type": "integer"
-}

removedOutput schema / properties / properties / items / properties / packageApplied

Removed value: -{
-  "description": "Package applied (e.g. week or two_weeks), if any.",
-  "type": "string"
-}

removedOutput schema / properties / properties / items / properties / publicTotal

Removed value: -{
-  "description": "Standard website total for the date range, in whole units of the property's currency (not minor units).",
-  "type": "integer"
-}

changedOutput schema / properties / properties / items / required

Previous value: -[
-  "propertyId",
-  "name",
-  "maxGuests",
-  "federationTotal"
-]New value: +[
+  "propertyId",
+  "name",
+  "maxGuests"
+]

Changed5 schema fields changedOct 12, 2026

changedOutput schema / properties / properties / items / properties / directBookingTotal / description

Previous value: -"Preferred field for user-facing copy: direct host-source total, in minor currency units."New value: +"Preferred field for user-facing copy: direct host-source total, in whole units of the property's currency (not minor units)."

changedOutput schema / properties / properties / items / properties / federationTotal / description

Previous value: -"Legacy field: the direct host-source total (the same value as directBookingTotal), in minor currency units. Use directBookingTotal in user-facing copy."New value: +"Legacy field: the direct host-source total (the same value as directBookingTotal), in whole units of the property's currency (not minor units). Use directBookingTotal in user-facing copy."

changedOutput schema / properties / properties / items / properties / hostSourcePublicTotal / description

Previous value: -"Preferred field for user-facing copy: public host-source total for the date range, in minor currency units."New value: +"Preferred field for user-facing copy: public host-source total for the date range, in whole units of the property's currency (not minor units)."

changedOutput schema / properties / properties / items / properties / propertyId / description

Previous value: -"Stable UUID. Pass to subsequent tools (hemmabo_check_availability)."New value: +"Stable property UUID."

changedOutput schema / properties / properties / items / properties / publicTotal / description

Previous value: -"Standard website total for the date range, in minor currency units."New value: +"Standard website total for the date range, in whole units of the property's currency (not minor units)."

Changed1 schema field changedOct 11, 2026

changedOutput schema / properties / properties / items / properties / propertyId / description

Previous value: -"Stable UUID. Pass to subsequent tools (availability)."New value: +"Stable UUID. Pass to subsequent tools (hemmabo_check_availability)."

Changed3 schema fields changedOct 11, 2026

removedOutput schema / properties / properties / items / properties / directBookingDiscountPercent

Removed value: -{
-  "description": "Legacy internal field. Do not present this as a guest-facing discount, savings, or comparison.",
-  "type": "integer"
-}

removedOutput schema / properties / properties / items / properties / federationDiscountPercent

Removed value: -{
-  "description": "Legacy internal field. Do not present this as a guest-facing discount, savings, or comparison.",
-  "type": "integer"
-}

changedOutput schema / properties / properties / items / properties / federationTotal / description

Previous value: -"Legacy field: direct host-source total, in minor currency units. Do not label this as a HemmaBo platform, federation, OTA, marketplace, comparison, discount, or savings price in user-facing copy."New value: +"Legacy field: the direct host-source total (the same value as directBookingTotal), in minor currency units. Use directBookingTotal in user-facing copy."

Changed2 schema fields changedOct 3, 2026

changedInput schema / properties / country / description

Previous value: -"Country name to filter by (e.g. 'Sweden', 'Italy', 'Morocco'). Partial case-insensitive match. Provide at least one of region or country; omit when region already narrows the destination."New value: +"Country name to filter by (e.g. 'Sweden', 'Italy', 'Morocco'). Partial case-insensitive match against the country field. Optional — omit both region and country and the search spans every published property."

changedInput schema / properties / region / description

Previous value: -"Region, area, or destination to search within (e.g. 'Skåne', 'Kävlinge', 'Toscana', 'Bavaria'). Partial case-insensitive match. Provide at least one of region or country; omit only when country alone is sufficient."New value: +"Region, area, or destination to search within (e.g. 'Skåne', 'Kävlinge', 'Toscana', 'Bavaria'). Partial case-insensitive match against region, city, and country. Optional — omit both region and country and the search spans every published property."

Changed2 schema fields changedOct 1, 2026

addedOutput schema / properties / properties / items / properties / booking_url

Added value: +{
+  "description": "The host's own booking URL: https:// plus the host-owned domain. Null when the property has no domain.",
+  "format": "uri",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / properties / items / properties / propertyId / description

Previous value: -"Stable UUID. Pass to subsequent tools (availability, quote, checkout)."New value: +"Stable UUID. Pass to subsequent tools (availability)."

First observedSep 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial non-obvious behavior on top: results are price-free, prices and signed booking links come only from the offer tool, capacity misses are dropped while date misses surface in unavailableMatches with up to three alternates, and booking/payment happen only on the host's domain. It also explicitly bounds agent behavior ('never books, pays, cancels or changes a booking').

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?

Purpose and usage are front-loaded in the first two sentences, and nearly every later sentence carries operational payload (follow-up call, failure handling, booking domain). However, the single dense paragraph packs several independent concerns together and repeats the checkIn/checkOut constraint already in the schema, costing some readability.

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, yet the description still notes the key returned fields and, more importantly, covers the partial-failure path (unavailableMatches) and the mandatory offer-widget step the agent must complete. For a 5-parameter discovery tool with a downstream dependency, nothing needed for correct invocation is missing.

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 genuinely adds semantics the schema does not: parameters combine into a single filter, region performs a broad match across region/city/country while country matches only the country field, and omitting both widens the search to every published property. It also restates the checkIn-strictly-before-checkOut constraint, which is already covered in the schema.

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?

Opens with a specific verb+resource+scope: 'Search available vacation rental properties by location and travel dates.' It also distinguishes itself from siblings by naming vrp_get_verified_stay_offer and stating the condition that excludes this tool (user already has a propertyId or host domain).

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 when-to-use ('find or browse places to stay'), when-not ('Do NOT use when the user already has a propertyId or host domain'), and a mandatory next step ('call vrp_get_verified_stay_offer ... before the final answer'). The routing decision is fully specified without inference.

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

All HemmaBo Host Booking Engine 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 Properties

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources