Oversell Rules

MCP tools for reading and managing cancelation-driven oversell rules on a unit type’s OTA channels (e.g. Booking.com) and previewing the per-night oversell they produce.

Available Tools

Read

• list_oversell_rules - List oversell rules for a unit type, optionally filtered by channel or enabled state
• get_oversell_rule - Fetch a single oversell rule by ID
• preview_oversell - Preview the per-night oversell a unit type would apply over a date range

Write (batch / fan-out)

• create_oversell_rules - Create one or more oversell rules
• update_oversell_rules - Update one or more oversell rules by id
• disable_oversell_rules - Disable (soft-delete) one or more oversell rules by id
• reorder_oversell_rules - Reorder rules by precedence for one or more unit type + channel groups

Overview

An oversell rule sizes how many extra rooms a unit type sells on a night, based on the probability that existing bookings cancel. Each rule carries:

• channel - the OTA channel the rule applies to (v1: Booking.com).
• span - the effective date window (null = always in force).
• leadDays - the lead-time window (days to arrival) the rule applies within.
• pCancel - per-booking cancelation probability used to size the oversell.
• aversionZ - std-dev discount off the expected cancelations (higher = more conservative).
• maxOversell - hard cap on the computed per-night oversell (0 = blackout, force no oversell).
• priority - precedence among overlapping rules; the highest-priority rule in force on a night wins.
• enabled - whether the rule is currently active.

Typical flow

1. search_unit_types to find the unit types in scope.
2. list_oversell_rules for a unit type to read its current rules.
3. get_oversell_rule to inspect a single rule in detail.
4. preview_oversell over a date range to see, per night, the availability, booked count, computed oversell and resulting rooms-to-sell that the rules produce.

Managing rules

The write tools are batch / fan-out: each accepts an array and processes items in parallel, returning a { summary: { total, succeeded, failed }, results: [...] } payload so partial success is reported per item. As with every MCP tool, that payload is the JSON in the standard ToolResult envelope — serialized into content[0].text (see each tool’s Output section), with isError set only when all items fail.

• Create a portfolio of rules in one call with create_oversell_rules.
• Update (including enable/disable via the enabled field) with update_oversell_rules — only supplied fields change.
• Disable (soft-delete) with disable_oversell_rules.
• Reorder precedence with reorder_oversell_rules — orderedIds must list exactly the current rules for a unit type + channel; the first id wins on overlap.