MAQAMI Travel

Find alternative hotel rates

post_bookings_bookingid_alternative_prebooks

Search alternative rates at the same hotel for a confirmed booking and create prebook sessions to compare prices for changed dates or occupancy.

Instructions

Overview

Hard Amendment — Search for alternative rates at the same hotel and create prebook sessions for a confirmed booking. Used when the guest needs to change their check-in/check-out dates or room occupancy.

When to Use

Date changes — Guest needs different check-in or check-out dates
Occupancy changes — Guest needs a different number of adults or children
Hard amendments — Situations where the booking must be cancelled and re-booked with new parameters

How It Works

The system searches for live availability at the same hotel with the new parameters.
Up to maxPrebooks alternative rates are selected (sorted by price ascending). Defaults to 3 when omitted; capped at 10 (any larger value is silently clamped to 10).
A prebook session is created for each rate.
The caller receives a list of prebookId values with prices to show the guest.

What You Get

Up to maxPrebooks prebook sessions — Each with a prebookId, final pricing, cancellation policies, and room details
Price comparison — priceDifferencePercent shows how each alternative compares to the original booking's selling price (negative = cheaper than what the guest paid, positive = more expensive)
Policy change flags — cancellationChanged and boardChanged highlight any policy differences

Key Notes

The booking must be in CONFIRMED status.
If the original booking is non-refundable, only non-refundable alternatives are returned (unless overridden with refundableRatesOnly).
The nationality and currency of the original booking are used for the availability search.

Quick Start

Call this endpoint with the bookingId and new occupancies/dates — get back up to maxPrebooks prebookId values.

On this server: rebooking is not available, so use this only to show the guest alternative prices. To change a booking, cancel it if its policy allows and make a new booking, or contact MAQAMI support.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Input Schema

Name	Required	Description
`email`	Yes	The email address used to make the booking. The server checks it against the booking before returning or changing anything.
`checkin`	No	The new check-in date in YYYY-MM-DD format. Must be before `checkout`.
`checkout`	No	The new check-out date in YYYY-MM-DD format. Must be after `checkin`.
`lastName`	No	The booking holder's last name, if the customer gives it. Optional.
`boardType`	No	Filter results by board/meal-plan type (e.g. `RO` for Room Only, `BB` for Bed & Breakfast). Leave empty to return all board types.
`bookingId`	Yes	(Required) The unique identifier of the confirmed booking to amend.
`maxPrebooks`	No	Maximum number of alternative prebook sessions to create. Defaults to 3 when omitted. Values above 10 are silently capped at 10; values ≤ 0 fall back to the default. The response may contain fewer entries when the hotel does not have enough distinct alternative offers.
`occupancies`	Yes	The desired room occupancies for the amended stay. One entry per room.
`refundableRatesOnly`	No	When true, only fully refundable alternative rates are returned. Defaults to false (or true if the original booking was refundable).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.0.6Oct 7, 2026

addedInput schema / properties / email

Added value: +{
+  "description": "The email address used to make the booking. The server checks it against the booking before returning or changing anything.",
+  "type": "string"
+}

addedInput schema / properties / lastName

Added value: +{
+  "description": "The booking holder's last name, if the customer gives it. Optional.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "bookingId",
-  "occupancies"
-]New value: +[
+  "bookingId",
+  "email",
+  "occupancies"
+]

First observedv0.1.0Sep 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare non-read-only, non-idempotent, non-destructive, and the description adds substantial context beyond them: the CONFIRMED-status prerequisite, that non-refundable originals yield only non-refundable alternatives, that nationality and currency are inherited from the original booking, and that the email must match the booking. It also notes this server cannot actually rebook, a meaningful behavioral limit.

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 definition is long but front-loaded and clearly sectioned under headers, so an agent can scan to the relevant part. There is some redundancy — 'Quick Start' largely restates the final step of 'How It Works' — which keeps it out of the top band.

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?

With 100% schema coverage and no output schema, the description closes the remaining gaps by describing what comes back (prebookId, final pricing, cancellation policies, room details) and the policy-change flags cancellationChanged and boardChanged. Nothing an agent needs to invoke or interpret the call 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 baseline is 3, but the description adds real semantics the schema lacks: alternatives are sorted by price ascending, maxPrebooks defaults to 3 and clamps above 10, and priceDifferencePercent is defined relative to the original selling price (negative = cheaper). The refundableRatesOnly override behavior is also explained in prose.

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 a specific verb+resource (search alternative rates at the same hotel and create prebook sessions) and scopes it to a confirmed booking being 'hard amended'. It explicitly contrasts with the amend path ('rebooking is not available, so use this only to show the guest alternative prices'), which separates it from sibling put_bookings_bookingid_amend.

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?

A dedicated 'When to Use' section enumerates the three triggering scenarios (date changes, occupancy changes, hard amendments). It also states the precondition (booking must be CONFIRMED) and the server-specific fallback when a true rebooking is needed, which is exactly the when-to-use/when-not guidance an agent needs.

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

Deploy Server