# 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](/mcp/tools/distribution/oversell-rules/list_oversell_rules/) - List oversell rules for a unit type, optionally filtered by channel or
  enabled state
- [get_oversell_rule](/mcp/tools/distribution/oversell-rules/get_oversell_rule/) - Fetch a single oversell rule by ID
- [preview_oversell](/mcp/tools/distribution/oversell-rules/preview_oversell/) - Preview the per-night oversell a unit type would apply over a date range

### Write (batch / fan-out)

- [create_oversell_rules](/mcp/tools/distribution/oversell-rules/create_oversell_rules/) - Create one or more oversell rules
- [update_oversell_rules](/mcp/tools/distribution/oversell-rules/update_oversell_rules/) - Update one or more oversell rules by id
- [disable_oversell_rules](/mcp/tools/distribution/oversell-rules/disable_oversell_rules/) - Disable (soft-delete) one or more oversell rules by id
- [reorder_oversell_rules](/mcp/tools/distribution/oversell-rules/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.