realtycalendar-web-mcp

List bookings

list_bookings

Read-onlyIdempotent

Find hotel bookings and guests for a date range, filtered by room, source, guest, holds, unpaid or unassigned status, with totals for matched stays.

Instructions

Bookings and guests of the user's hotel in RealtyCalendar in a period: match=staying (guests in the house, who is in which room), arriving (check-ins, заезды) or departing (check-outs, выезды; rooms to clean). Filters: room, category, source (booking site: Островок, Яндекс…), guest name or phone, holds (заявки), unassigned (неразобранные: no room yet), unpaid (balance left to pay). Totals (sum, paid, left) cover all matches and their whole stays: a stay crossing the period's edge counts in full; say so with the totals. The period defaults to today; to find a guest's booking with no dates given ("найди бронь Петровой") use today to today + 180 days, and say which period you searched. No filter by the date a booking was made: for a recent booking from a site, filter by source and read "Дата бронирования" in get_booking. Not for "is room X free": use check_availability. Not for the user's own calendar, free time or meetings, staff schedules, other hotels or travel plans. Dates: today is in every result; stays are nights (check_out = departure day); a week is Monday to Sunday; "на выходные" = Friday and Saturday nights; a date without a year is the next one, or the last one when the user asks about the past. Say which dates you used.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_bookings"
  }
}

Input Schema

Name	Required	Description
`to`	No	End of the period (exclusive); default from + 1 day; at most 180 days after from
`from`	No	Start of the period, YYYY-MM-DD; default today
`room`	No	Room title like "22" or its id
`limit`	No	Max bookings returned (default 50); totals cover all
`match`	No	staying: the stay overlaps [from, to) (default); arriving: check_in in [from, to); departing: check_out in [from, to)
`query`	No	Guest name words, Cyrillic or Latin (matched in both scripts), or phone digits (at least 5, any format). Use a stem if unsure: "Петров" also finds Петрова
`source`	No	Channel name in Latin or Cyrillic: "островок", "ostrovok", "яндекс"; all matches
`status`	No	Default ["booked", "request"]; request = hold (заявка). ["request"] = holds only; add "canceled" for отменённые
`category`	No	Category: id, number ("02") or title words; all matches are used. Words or a stem are enough: "улучшен", "двухмест", "коттедж".
`unpaid_only`	No	Only bookings with left > 0
`unassigned_only`	No	Only bookings without a room in categories that have rooms

Output Schema

Name	Required	Description
`to`	Yes
`from`	Yes
`hint`	No	Present when a guest query found nothing
`match`	Yes
`today`	Yes
`totals`	Yes
`matched`	Yes
`bookings`	Yes
`currency`	Yes
`returned`	Yes
`today_weekday`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 11, 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, idempotentHint, and openWorldHint, but the description adds substantial behavioral context beyond them: totals cover all matches and whole stays even when a stay crosses the period edge, the period defaults to today, and no filter exists for booking creation date. It also discloses date interpretation rules (nights, week boundaries, weekend definition, year inference) that affect results.

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 description is long and dense, but every sentence carries operational information relevant to an 11-parameter tool with complex date and filtering semantics. It is front-loaded with purpose and match modes before moving to filters and date rules. Minor redundancy exists where match modes and some filter semantics are repeated from the schema, and the single-paragraph format could be easier to scan, but there is little wasted wording.

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?

Given the tool's complexity, 11 optional parameters, 100% schema coverage, an output schema, and read-only annotations, the description is complete. It covers purpose, match modes, filter behavior, totals semantics, date interpretation, default periods, and explicit exclusions against siblings. An agent has everything needed to select and invoke the tool correctly.

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?

With 100% schema description coverage, the schema already documents each parameter thoroughly. The description adds meaning beyond the schema by explaining that totals cover all matches and whole stays regardless of limit, and by clarifying date semantics like 'stays are nights' and 'a week is Monday to Sunday' that affect from/to interpretation. It reinforces but does not substantially extend the match, source, query, and status semantics already present 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?

The description states a specific verb and resource ('Bookings and guests of the user's hotel in RealtyCalendar in a period') and enumerates the three match modes (staying, arriving, departing), so an agent can distinguish it from siblings. It explicitly names check_availability and get_booking as alternatives for other tasks, reinforcing scope.

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?

It provides explicit when-to-use guidance for each match mode, default behavior, and special cases like finding a guest's booking without dates ('use today to today + 180 days'). It also states clear exclusions: 'Not for "is room X free": use check_availability' and 'Not for the user's own calendar, free time or meetings, staff schedules, other hotels or travel plans.'

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

Deploy Server