MCP Tools Reference

Full catalog of MCP tools exposed by Hostex. This page is auto-generated
from the x-mcp extension in resources/openapi/v3.json — to add or
modify a tool, edit the spec, not this page.

How to read this page

• Each tool is one H3 section. Use the right-side table of contents (or
  browser Ctrl+F) to jump straight to a tool by name.
• The line under the tool name shows the underlying HTTP endpoint, the
  side-effect class, and the v3 version that first exposed it.
• Read-only tools work with any access token. Write tools need
  a writable token. Write · requires confirmation tools are
  destructive or irreversible — MCP clients are expected to prompt
  the user before running them.
• For full parameter and response schemas, click through to the
  matching reference/<endpoint> page in the sidebar (the spec-driven
  API Reference) or look up path + method in the spec.

---

Quick counts

---

automation

3 tools — 1 read-only, 2 writable

delete_automation_action

DELETE /automation/actions/{plan_id} · Write · requires confirmation · since v3.4.0

Delete a pending automation plan (a waiting-status send_message or review automation) so it will not be sent. ⚠️ Irreversible — but only this single occurrence is cancelled; the underlying automation rule is untouched and will continue generating new plans on its next trigger. Only supports send_message and review plans.

Example phrases

• "Cancel this pending welcome message"
• "Don't post this review — delete it"

execute_automation_action

POST /automation/actions/{plan_id}/execute · Write · requires confirmation · since v3.4.0

Immediately trigger a pending automation plan (a waiting-status send_message or review automation). Equivalent to tapping 'Run now' on a pending item in the app. ⚠️ Irreversible: the message will be sent immediately / the review will be posted to the channel immediately. Only supports send_message and review plans; review additionally requires the reservation to have reached its check-out date.

Example phrases

• "Send this pending welcome message now"
• "Post this queued positive review immediately"

search_automation_actions

GET /automation/actions · Read-only · since v3.4.0

List pending (waiting-to-run) automation plans. Two kinds are covered: (1) automated messages (type=message, equivalent to the in-app 'upcoming messages' list within the next 30 days); (2) automated reviews (type=review). Filter by keyword, property ids, time range, channel, rule event. Common use cases: review which messages will be auto-sent to guests on a given day, find a specific pending plan to trigger or cancel manually.

Example phrases

• "Which automated messages will go out tomorrow"
• "Upcoming pending messages for Coastal Villa"
• "Queued automated reviews"

calendar

10 tools — 4 read-only, 6 writable

create_calendar_share_link

POST /calendar_share_links · Write · since v3.5.0

Create a new public calendar share link. Pick scope=entire to expose all properties (idempotent: returns the existing link if any), or scope=partial plus property_ids to expose only specific properties. The returned url is a public, read-only calendar that the operator can hand off to cleaners, owners, or external collaborators.

Example phrases

• "Create a shared calendar link for all my properties"
• "Generate a share link for properties 101 and 102"
• "Give me a public calendar link I can send to my cleaner"

delete_calendar_share_link

DELETE /calendar_share_links/{id} · Write · since v3.5.0

Permanently invalidate a public calendar share link. Anyone holding the previous URL will get a share link invalid error. Look up the link id via search_calendar_share_links first.

Example phrases

• "Revoke calendar share link 42"
• "Delete the calendar share link I sent to my cleaner"

get_pricing_ratios

GET /pricing_ratios · Read-only · since v3.4.0

Get the per-channel listing price ratios (in %) for a given property or room type. Use the ratios client-side to compute each listing's target price (target = round(base * ratio / 100)), then loop update_listing_prices to push the new prices. Listings with readonly=true cannot be updated via update_listing_prices and must be skipped. Exactly one of property_id / room_type_id is required.

Example phrases

• "What are the price ratios on each OTA for Coastal Villa #1"
• "I want to reprice this room type — show me the ratio per channel"

search_availabilities

GET /availabilities · Read-only · since v3.4.0

Query the property-level availability calendar. Returns each property's daily availability status (available=true/false) within the requested date range. Note the distinction: this is the property master calendar (which decides whether bookings are open) — it differs from per-channel listing inventory / prices (use search_listing_calendars for those). Common use cases: check which days a property is free, find which days are booked or blocked.

Example phrases

• "Which days is Coastal Villa #1 open next month"
• "Which properties are still bookable this weekend"

search_calendar_share_links

GET /calendar_share_links · Read-only · since v3.5.0

Search / paginate the operator's public calendar share links. Returns each link's id, scope (entire / partial), the property_ids it exposes (empty for entire-scope links) and the share URL. Use this to enumerate existing links before creating or deleting one.

Example phrases

• "List my calendar share links"
• "What calendar share links have I created"
• "Show the share link for property 123"

search_listing_calendars

POST /listings/calendar · Read-only · since v3.4.0

Query the per-channel listing calendar (daily price, inventory, minimum-stay and other restrictions per channel_type + listing_id within a date range). Note: a listing is the OTA-side entry (Airbnb, Booking, etc.) for one property and carries channel-specific price / inventory. To query the property master calendar use search_availabilities.

Example phrases

• "Prices on Airbnb for Coastal Villa May 20-30"
• "Booking inventory and minimum-stay for this property next week"

update_availabilities

POST /availabilities · Write · requires confirmation · since v3.4.0

Open / block a property's availability over a date range (available=true opens, false blocks). Asynchronous: a successful response only means the task was submitted; the change takes a short while to propagate to channels. Will cascade to all connected channels' inventory for that property. Note: this controls the property master calendar — distinct from per-channel listing inventory (update_listing_inventories). Blocking the wrong dates can make the property unbookable or impact existing reservations, so double-check the date range.

Example phrases

• "Block Coastal Villa #1 next Monday through Wednesday"
• "Reopen Coastal Villa for May 20-25"

update_listing_inventories

POST /listings/inventories · Write · requires confirmation · since v3.4.0

Update the inventory of a channel listing for specific dates. Asynchronous — channel-side propagation takes a short while. Note: this only updates per-channel inventory and does NOT touch the property master calendar (property availability); subsequent master-calendar changes can overwrite this. To open / block the property master calendar use update_availabilities. Wrong values can cause oversells or sellouts.

Example phrases

• "Set Airbnb inventory to 0 for this property next week"
• "Set Booking inventory to 1 for May 20-25"

update_listing_prices

POST /listings/prices · Write · requires confirmation · since v3.4.0

Update the selling price of a channel listing for specific dates. Asynchronous — channel-side propagation takes a short while. Pricing changes directly affect what guests see and pay, so double-check channel / listing / dates / currency / amount. For long-term dynamic pricing, prefer integrating a service such as PriceLabs rather than calling this endpoint manually.

Example phrases

• "Raise Airbnb price to 800 for this property on May 20-25"
• "Add a 20% markup on Booking for next weekend"

update_listing_restrictions

POST /listings/restrictions · Write · requires confirmation · since v3.4.0

Update the booking restrictions of a channel listing for specific dates (minimum nights, maximum nights, whether check-in / check-out is allowed on the date, etc.). Asynchronous. Common use cases: require at least 3 nights during peak season, close check-in on a specific date.

Example phrases

• "Require a 2-night minimum on Airbnb for next weekend"
• "Close check-in on Booking for May 1"

finance

8 tools — 5 read-only, 3 writable

create_transaction

POST /transactions · Write · requires confirmation · since v3.4.0

Record an income or expense entry (bookkeeping). Required: direction (income / expense) + amount (positive number) + item_id + payment_method_id. Can be linked to a reservation (stay_code) or to a property (property_id), but not both; omit both to record an operator-level entry (master account only). When stay_code is supplied, currency is inherited from the reservation; otherwise currency is required. Look up item_id / payment_method_id via GET /income_items, /expense_items, /income_methods, /expense_methods.

Example phrases

• "Record a $200 cleaning expense for reservation ABC123"
• "Log that we received a $500 deposit from the guest"
• "Coastal Villa spent $1500 on maintenance this month"

delete_transaction

DELETE /transactions/{id} · Write · requires confirmation · since v3.4.0

Permanently delete a transaction entry. ⚠️ Irreversible — deleting will affect the cumulative income / expense totals for the linked property / reservation / operator. If only the amount is wrong, use update_transaction instead of deleting.

Example phrases

• "Delete this expense entry — it was recorded incorrectly"

search_expense_items

GET /expense_items · Read-only · since v3.4.0

List all available expense item categories (cleaning, maintenance, linen, platform commission, etc.). Returns each item's id and name. Required: call this before create_transaction with direction=expense to obtain a valid item_id.

Example phrases

• "What expense categories are available"
• "Which item_id should I use for maintenance fees"

search_expense_methods

GET /expense_methods · Read-only · since v3.4.0

List all available expense payment methods (cash, bank transfer, credit card, etc.). Returns each method's id and name. Required: call this before create_transaction with direction=expense to obtain a valid payment_method_id.

Example phrases

• "What expense payment methods are available"
• "Which payment_method_id should I use to log a cash expense"

search_income_items

GET /income_items · Read-only · since v3.4.0

List all available income item categories (room fee, deposit, cleaning fee, etc.). Returns each item's id and name. Required: call this before create_transaction with direction=income to obtain a valid item_id.

Example phrases

• "What income categories are available"
• "Which item_id should I use to log a deposit"

search_income_methods

GET /income_methods · Read-only · since v3.4.0

List all available income payment methods (cash, bank transfer, Stripe, PayPal, etc.). Returns each method's id and name. Required: call this before create_transaction with direction=income to obtain a valid payment_method_id.

Example phrases

• "What income payment methods are available"
• "Which payment_method_id should I use to log a cash receipt"

search_transactions

GET /transactions · Read-only · since v3.4.0

Query transaction entries (income / expense ledger). Filter by direction (income / expense), linked reservation (stay_code), linked property (property_id), date range, etc.; or pass id directly to fetch a single entry. Returns each entry's amount, currency, item (item_id / item_name), payment method, and linked object. start_date / end_date are optional when filtering by id.

Example phrases

• "All income this month"
• "Expenses for Coastal Villa #1 this month"
• "All transactions related to reservation ABC123"
• "Show me the details of transaction 12345"

update_transaction

PATCH /transactions/{id} · Write · requires confirmation · since v3.4.0

Update an existing transaction entry. Only amount / item_id / payment_method_id / action_at / note and similar fields can be changed; direction (income / expense), the linked object (reservation / property / operator-level), and currency are immutable — to change those, delete_transaction and re-create with create_transaction.

Example phrases

• "Change this expense amount to 320"
• "Update the note on this transaction"

knowledge_base

5 tools — 2 read-only, 3 writable

create_knowledge_base

POST /knowledge_bases · Write · requires confirmation · since v3.5.0

Create a new knowledge base entry with AI reply content and scope (properties/channels).

Example phrases

• "Create a new knowledge base entry"
• "Add an automated reply content"

delete_knowledge_base

DELETE /knowledge_bases/{id} · Write · requires confirmation · since v3.5.0

Delete a knowledge base entry.

Example phrases

• "Delete this knowledge base"
• "Remove this knowledge base entry"

get_knowledge_base

GET /knowledge_bases/{id} · Read-only · since v3.5.0

Get full details of a single knowledge base entry by ID, including content, scope, and enable status.

Example phrases

• "View knowledge base entry details"
• "Get the content of this knowledge base"

search_knowledge_bases

GET /knowledge_bases · Read-only · since v3.5.0

Search/paginate knowledge base entries. Filter by property IDs or channel types. Returns id, title, enable status, scope and processing status.

Example phrases

• "List all my knowledge base entries"
• "Find knowledge bases for a specific property"
• "Search knowledge bases for Airbnb channel"

update_knowledge_base

PATCH /knowledge_bases/{id} · Write · requires confirmation · since v3.5.0

Update all fields of a knowledge base entry, including content, scope, and enable status.

Example phrases

• "Update the content of this knowledge base"
• "Modify the scope of a knowledge base"
• "Enable or disable this knowledge base"

messaging

4 tools — 2 read-only, 2 writable

get_conversation

GET /conversations/{conversation_id} · Read-only · since v3.4.0

Get a single conversation's details and message list. Call search_conversations first to obtain a conversation_id. Returns each message's sender, content, timestamp, and attachments.

Example phrases

• "Show me what we've discussed with this guest"
• "Full chat history for this thread"

search_conversations

GET /conversations · Read-only · since v3.4.0

List conversation threads. A thread carries all messages with a given guest and may be linked to one or more reservations. Returns each thread's id, latest message preview, unread count, linked channel, etc. Common use cases: find a guest's thread to reply to, list recently active threads.

Example phrases

• "Any unread messages recently"
• "Where is the thread with John"
• "All conversations on Airbnb"

send_message

POST /conversations/{conversation_id} · Write · requires confirmation · since v3.4.0

Send a text or image message to the guest in a specific conversation. Messages cannot be recalled once sent. Double-check that conversation_id is correct and that the content complies with channel policy (Airbnb / Booking, etc.) — do not include external contact info or third-party links, otherwise the channel may block the message or suspend the account.

Example phrases

• "Reply to this guest and tell them the lock code is 6688"
• "Send a welcome message in this thread"

update_conversation_note

PATCH /conversations/{conversation_id}/note · Write · since v3.7.0

Set or clear the host-side private note attached to a conversation thread. Notes are stored only in Hostex and are NEVER sent to the guest or any channel; they are shared across operators in the account so the team can leave context for each other. Call search_conversations first to obtain a conversation_id. Pass an empty string or null in note to clear the existing note. Returns the updated note and updated_at.

Example phrases

• "Add a note on this thread: VIP guest, always confirm late check-in"
• "Update the note on this conversation"
• "Clear the note on this conversation"

meta

3 tools — 3 read-only, 0 writable

search_custom_channels

GET /custom_channels · Read-only · since v3.4.0

List the operator's custom channels (channels the operator defines themselves — e.g. WhatsApp, Facebook Messenger, returning-customer direct — on top of the built-in Airbnb / Booking / etc.). Returns each channel's id and name. Call this first when you need a custom_channel_id for create_reservation / update_reservation_basic.

Example phrases

• "What custom channels do I have"
• "What is the id of the WhatsApp channel"

search_reservation_tags

GET /reservation_tags · Read-only · since v3.5.0

Search / paginate the operator's reservation tag dictionary. Returns each tag's id, tag_name, color and whether it is a system default tag. Use this to discover existing tag names (and their ids) before calling add_reservation_tag, or to enumerate tags for management UIs.

Example phrases

• "List all my reservation tags"
• "Do I already have a 'VIP' reservation tag"
• "Search reservation tags containing 'cleaning'"

search_tags

GET /tags · Read-only · since v3.4.0

List the operator's property tags (the tags attached to properties / room types, not reservation tags). Each entry returns id, name, color and the property_ids / room_type_ids the tag is applied to. Use search_reservation_tags for the reservation tag dictionary.

Example phrases

• "What property tags are available"
• "Which properties carry the 'Beachfront' tag"

property

13 tools — 5 read-only, 8 writable

create_property

POST /properties · Write · requires confirmation · since v3.4.0

Create a new property. Only accepts title; all other details (address, channels, photos, pricing, etc.) are configured later in the admin portal. ⚠️ Consumes one slot from the subscription's property quota; will fail when the quota is exhausted.

Example phrases

• "Create a new property named 'Coastal Villa #5'"
• "Add another room called Studio A"

create_property_group

POST /groups · Write · since v3.6.0

Create a new property group (an operator-defined collection of properties such as 'Sea-view suites', 'Downtown apartments'). Optionally pass property_ids to pre-assign properties. Returns the new group's id, name and the property_ids it now contains. Use search_properties first to look up property ids.

Example phrases

• "Create a property group called 'Sea-view suites'"
• "Create a group 'Downtown apartments' with properties 101, 102, 103"

create_property_tag

POST /tags · Write · since v3.6.0

Create a new property tag (the tag dictionary used to label properties / room types, e.g. 'Beachfront', 'Pet-friendly'). Optionally attach properties (property_ids) and / or room types (room_type_ids) at creation time. For tagging existing properties / room types under a tag that already exists, use update_property_tag instead. Returns the new tag's id, name, color, property_ids and room_type_ids.

Example phrases

• "Create a property tag called 'Beachfront'"
• "Add a 'Pet-friendly' tag and attach properties 101, 102"

create_room_type

POST /room_types · Write · requires confirmation · since v3.4.0

Create a new room type. Optionally pass property_ids to attach several properties at once (each property must not already belong to another room type). ⚠️ Not supported on the Basic subscription; the room type count cannot exceed the property quota.

Example phrases

• "Create a room type called 'City-view King Room'"
• "Create a new room type and attach rooms 101, 102, 103"

delete_property_group

DELETE /groups/{id} · Write · since v3.6.0

Permanently delete a property group. Properties previously attached to the group are NOT deleted, only detached. Look up the group id via search_property_groups first.

Example phrases

• "Delete the 'Old downtown apartments' group"
• "Remove property group 7"

delete_property_tag

DELETE /tags/{id} · Write · since v3.6.0

Permanently delete a property tag. The properties and room types previously labelled with the tag are NOT deleted, only detached. Look up the tag id via search_tags first.

Example phrases

• "Delete the 'Old discount' property tag"
• "Remove property tag 12"

search_channel_accounts

GET /channel_accounts · Read-only · since v3.4.0

List the third-party channel accounts (Airbnb, Booking.com, etc.) connected by the current operator. Returns each account's internal id, channel_type, username (login / identifier), channel-side account id (origin_account_id), and current authorization status (auth_status: active / connecting / disconnected / exception / unknown). Common use cases: inventory the connected OTAs, check whether a given channel account is still online, filter by channel_type to obtain channel_account_id for subsequent listing queries.

Example phrases

• "Which OTAs am I connected to"
• "Is my Airbnb account still online"
• "What is the channel account id of my Booking account"

search_listings

GET /listings · Read-only · since v3.4.0

List the listings synced from connected channel accounts (the OTA-side property entries). A listing represents one property's posting on one channel and is uniquely identified by listing_id (channel-side id) + channel_type. Can be filtered by channel_account_id (from search_channel_accounts), listing_id, or channel_type. Returns each listing's title, cover image, deep link URL, inventory, shelf status (shelf_status), and a pass-through metadata object (geo / images / rate plans and other channel-side metadata; structure varies by channel). Common use cases: inventory the listings on each OTA, look up specific listings under a channel account, fetch listing_id before pricing / restriction workflows.

Example phrases

• "What listings do I have on Airbnb"
• "How many listings are under this Booking account"
• "Where is Coastal Villa posted across OTAs"

search_properties

GET /properties · Read-only · since v3.4.0

Search / paginate the operator's properties. Returns each property's id, name, address, status, and connected channels. Common use cases: list all properties to pick from, look up a property name by id, browse the asset list during onboarding.

Example phrases

• "List all my properties"
• "How many properties do I have"
• "What is the id of Coastal Villa #1"

search_property_groups

GET /groups · Read-only · since v3.4.0

List property groups. A group is an operator-defined collection of properties (e.g. 'Sea-view suites', 'Downtown apartments', 'Handled by cleaner A'). Returns each group's id, name, and associated property ids. Common use cases: batch-operate or filter by group.

Example phrases

• "What property groups do I have"
• "Which properties are in the Sea-view Suites group"

search_room_types

GET /room_types · Read-only · since v3.4.0

List room types. A room type groups interchangeable properties of the same kind and is used to sell by room-type inventory (vs. selling a specific property). Returns each room type's id, name, and associated properties.

Example phrases

• "List my room types"
• "What room types do I have"

update_property_group

PATCH /groups/{id} · Write · since v3.6.0

Rename a property group and/or replace its property assignment. property_ids REPLACES the full list (not additive): to add a property, fetch the current ids via search_property_groups(id=...) first, then PATCH with the combined list. Pass an empty array to detach all properties from the group.

Example phrases

• "Rename group 5 to 'Coastline villas'"
• "Add property 110 to the 'Sea-view suites' group"
• "Remove all properties from group 7"

update_property_tag

PATCH /tags/{id} · Write · since v3.6.0

Rename a property tag, change its color, or replace the properties / room types it is attached to. Both property_ids and room_type_ids REPLACE the full list (not additive): to add a property to a tag without dropping the existing ones, fetch the current ids via search_tags(id=...) first, then PATCH with the combined list. Pass an empty array to detach all properties / room types from the tag.

Example phrases

• "Rename property tag 3 to 'Oceanfront'"
• "Attach properties 110, 111 to the 'Pet-friendly' tag"
• "Detach all room types from the 'Family suite' tag"

reservation

18 tools — 3 read-only, 15 writable

add_reservation_tag

POST /reservations/{stay_code}/tags · Write · since v3.4.0

Add a tag to a reservation. If the tag does not exist it will be created automatically. Common use cases: flag VIP guests, problem reservations, reservations requiring special attention.

Example phrases

• "Tag this reservation as VIP"
• "Mark this reservation as 'pickup confirmed'"

allocate_reservation

POST /reservations/{stay_code}/allocate · Write · requires confirmation · since v3.4.0

Allocate / re-allocate a reservation's stay to a specific property. Typical scenarios: (1) a room-type reservation (sold by room type) needs to be assigned to a concrete property after booking; (2) reassign a conflicting reservation to another vacant property of the same room type. ⚠️ If the target property already has a stay in the same date range, that stay will be marked as conflicting and moved to the reservation box.

Example phrases

• "Assign reservation ABC123 to Coastal Villa #1"
• "Move this reservation to Villa #2"

approve_reservation

POST /reservations/{reservation_code}/approve · Write · requires confirmation · since v3.4.0

Approve a reservation that is pending host confirmation (status=wait_accept). The system will call the channel to confirm the reservation and the guest will be notified that the host accepted. ⚠️ Irreversible. Only works on reservations in wait_accept status (i.e. channel reservations where the guest sent a booking request waiting for host approval — mainly Airbnb 'Request to Book' and similar). Calls against already-confirmed or cancelled reservations will fail.

Example phrases

• "Approve reservation ABC123"
• "Accept this guest's booking request"

cancel_reservation

DELETE /reservations/{reservation_code} · Write · requires confirmation · since v3.4.0

Cancel a Direct Booking reservation. ⚠️ Irreversible and will immediately release the property's occupancy. This endpoint only supports cancelling direct bookings — channel reservations (Airbnb / Booking / Agoda, etc.) must be cancelled on the channel side. A wrong cancellation may leave the guest without a room and trigger refund disputes.

Example phrases

• "Cancel reservation ABC123"
• "The guest isn't coming — cancel this direct booking"

create_reservation

POST /reservations · Write · requires confirmation · since v3.4.0

Create a Direct Booking reservation, bypassing any OTA channel. Requires property id, check-in / check-out dates, guest name & contact, pricing, etc. A direct booking is treated as a full reservation in the system and supports the complete payment / receipt flow. Note: this endpoint cannot be used to record Airbnb / Booking / etc. channel reservations (those are synced in from each channel).

Example phrases

• "Create a direct booking at Coastal Villa #1, May 20-22, guest John, 3 pax, $600"
• "Record a direct booking for a returning customer"

create_reservation_tag

POST /reservation_tags · Write · since v3.5.0

Create a reservation tag in the operator's dictionary so it can later be attached to reservations via add_reservation_tag. Use this when the user wants to define a brand new tag (e.g. 'Pickup confirmed'). Note that add_reservation_tag will already auto-create a tag if it does not exist; prefer this endpoint only when the user explicitly wants to manage the dictionary itself.

Example phrases

• "Create a reservation tag called 'Repeat guest'"
• "Add 'Late check-in' to my reservation tag list"

create_review

POST /reviews/{reservation_code} · Write · requires confirmation · since v3.4.0

Write a host review of a guest, or a host reply to the guest's review. ⚠️ Irreversible and will be publicly shown on the channel (Airbnb / Booking, etc.), affecting both the host's and the guest's reputation scores. When drafting on behalf of the host, ensure the content is objective and contains no contact info or external links (otherwise the channel may block it or penalize the listing).

Example phrases

• "Write a positive review for guest ABC123: punctual, respected the property"
• "Reply to the guest's review on reservation XYZ"

decline_reservation

POST /reservations/{reservation_code}/decline · Write · requires confirmation · since v3.4.0

Decline a reservation that is pending host confirmation (status=wait_accept). ⚠️ Irreversible; the guest will be notified that the host declined. Frequent declines can hurt the host's Acceptance Rate on Airbnb and similar channels. Only works on reservations in wait_accept status.

Example phrases

• "Decline reservation ABC123"
• "Reject this guest's booking request"

delete_reservation_tag

DELETE /reservation_tags/{id} · Write · since v3.5.0

Permanently remove a reservation tag from the operator's dictionary. Only custom tags can be deleted (is_default = false from search_reservation_tags). Deletion also detaches the tag from every reservation it was applied to. Lookup the tag id via search_reservation_tags first.

Example phrases

• "Delete the reservation tag 'Repeat guest'"
• "Remove the 'Late check-in' tag from my tag list"

move_reservation_to_box

POST /reservations/{stay_code}/move_to_box · Write · requires confirmation · since v3.4.0

Move a reservation's stay into the reservation box. Once in the box, the stay disappears from the master calendar view, but the reservation itself is NOT cancelled and the guest is NOT notified. Common use cases: temporarily set aside conflicting or anomalous reservations until they can be handled; later use allocate_reservation to reassign the stay to a specific property.

Example phrases

• "Move reservation ABC123 to the reservation box for now"
• "Tuck this conflicting reservation away"

remove_reservation_tag

DELETE /reservations/{stay_code}/tags · Write · since v3.4.0

Remove a tag from a reservation.

Example phrases

• "Remove the VIP tag from this reservation"

search_reservation_custom_fields

GET /reservations/{stay_code}/custom_fields · Read-only · since v3.4.0

Get the current definitions and values of a reservation's custom fields. Custom fields are defined by the operator in system settings to hold extra business-specific info (license plate, allergies, special requests, etc.). Call this first to obtain field ids and current values before invoking update_reservation_custom_fields.

Example phrases

• "Show me all custom fields on reservation ABC123"
• "What is the license-plate field on this reservation"

search_reservations

GET /reservations · Read-only · since v3.4.0

Search reservations. Filter by reservation code, channel reservation id, property, status, check-in / check-out date range, etc. Returns a list of reservations including guest info, stay status, pricing, and channel. Common use cases: find reservations by date / property / status, or check whether a given reservation exists. By default returns reservations with check_out within the next 180 days.

Example phrases

• "Reservations checking in next week"
• "Which guests are checking out tomorrow"
• "Unconfirmed reservations on Airbnb"
• "All reservations for Coastal Villa this month"

search_reviews

GET /reviews · Read-only · since v3.4.0

List reviews. Filter by channel, property, rating, replied status, etc. Returns each review's channel, reservation, guest, rating, content, and host reply (if any). Common use cases: surface recent low-rating reviews, find unreplied reviews to handle.

Example phrases

• "Show recent low-rating reviews"
• "All reviews for Coastal Villa #1 this month"
• "Which reviews haven't been replied to yet"

update_reservation_basic

PATCH /reservations/{stay_code} · Write · requires confirmation · since v3.4.0

Update a reservation's basic info: guest name / phone / email, check-in / check-out dates, party size, pricing, remarks (remarks / channel_remarks), etc. Common use cases: edit remarks, update the guest's contact info, change dates. Note: changing dates can create conflicts with other reservations — verify before calling.

Example phrases

• "Change the remarks on reservation ABC123 to 'Deposit collected'"
• "Change this reservation to check in May 20 through 22"
• "Update the guest's phone number"

update_reservation_checkin_details

PATCH /reservations/{stay_code}/check_in_details · Write · requires confirmation · since v3.4.0

Update a reservation's check-in details: lock code, expected arrival / departure time, deposit info, etc. Common use cases: set the door-lock code in the admin before the guest arrives, record the expected arrival time so cleaning can be scheduled. This endpoint does NOT notify the guest — pair with send_message if the guest needs to be informed.

Example phrases

• "Set the lock code for reservation ABC123 to 6688"
• "Note that the guest will arrive at 14:00"

update_reservation_custom_fields

PATCH /reservations/{stay_code}/custom_fields · Write · requires confirmation · since v3.4.0

Update the values of a reservation's custom fields. Custom fields are defined by the operator in system settings to hold extra business-specific info (license plate, allergies, special requests, etc.). Recommended to call search_reservation_custom_fields first to fetch the field definitions and current values, then call this endpoint to update.

Example phrases

• "Set the license-plate field on reservation ABC123 to CA-7XYZ123"
• "Record that this guest is allergic to peanuts"

update_reservation_stay_status

PUT /reservations/{stay_code}/stay_status · Write · since v3.4.0

Update a reservation's stay status (stay_status), e.g. checkin_pending (awaiting check-in) → in_house (checked in) → stay_completed (checked out). Common use case: manually process check-in / check-out.

Example phrases

• "Mark this reservation as checked in"
• "The guest has checked out — mark it"
• "Check in ABC123"

task

8 tools — 2 read-only, 6 writable

create_staff

POST /staffs · Write · requires confirmation · since v3.4.0

Create a staff member / contractor (cleaner, maintenance technician, receptionist, housekeeper, etc.). Defaults to active. Use property_ids to restrict the staff to specific properties (omit to authorize all properties). For international operators, mobile must use the +<country code> <number> format, e.g. +1 4155550100.

Example phrases

• "Add a new cleaner named Mary, phone +1 4155550100"
• "Add a maintenance technician who only services Coastal Villa #1"

create_task

POST /tasks · Write · requires confirmation · since v3.4.0

Create a task (cleaning / maintenance / reception / room service / other). Can optionally be linked to a property (property_id), a reservation (stay_code), or assigned to a staff member (staff_id). When stay_code is supplied the task is bound to that reservation and property_id defaults to the reservation's property if omitted. type selects the task category; level is only meaningful for cleaning tasks.

Example phrases

• "Create a cleaning task for Coastal Villa #1 tomorrow morning"
• "Create a cleaning task for reservation ABC123"
• "Assign a maintenance task to John"

delete_staff

DELETE /staffs/{id} · Write · requires confirmation · since v3.4.0

Permanently delete a staff member / contractor along with all their property authorizations. ⚠️ Irreversible. If you only want to temporarily disable the staff, use update_staff to set is_active=false instead.

Example phrases

• "Delete John from staff"
• "Remove Lily — she has left the company"

delete_task

DELETE /tasks/{id} · Write · requires confirmation · since v3.4.0

Permanently delete a task. ⚠️ Irreversible — the task history and associated staff assignment records are wiped. If you only want to mark it done or cancelled, use update_task to change status instead.

Example phrases

• "Delete task 123"
• "Remove this cleaning task — I created it by mistake"

search_staffs

GET /staffs · Read-only · since v3.4.0

List the staff / contractors (cleaners, maintenance technicians, receptionists, housekeepers, etc.). Returns each staff member's id, name, type, and contact details. Common use case: look up staff_id by name before calling create_task / update_task.

Example phrases

• "Which cleaners do I have"
• "What is the maintenance technician's phone number"
• "What is John's staff id"

search_tasks

GET /tasks · Read-only · since v3.4.0

Search tasks (cleaning / maintenance / reception / room service / other). Filter by id (to fetch one task), status, type, property, staff, date range, etc. Returns each task's id, type, property, assigned staff, status, expected execution time, and more. Pass id to fetch a single task's details.

Example phrases

• "What cleaning tasks do I have today"
• "All tasks for Coastal Villa #1 next week"
• "Open maintenance tasks"
• "Show me the details of task 123"

update_staff

PATCH /staffs/{id} · Write · requires confirmation · since v3.4.0

Update a staff member's info. All fields are optional; only the supplied fields are changed. ⚠️ Note: passing property_ids fully replaces the staff's authorized property list (it is not appended); passing an empty array clears all authorizations. Use is_active to enable / disable the staff.

Example phrases

• "Change Mary's phone number to +1 4155550199"
• "Deactivate John"
• "Let Lily service both Villa #1 and Villa #2"

update_task

PATCH /tasks/{id} · Write · requires confirmation · since v3.4.0

Update an existing task. All fields are optional; only the supplied fields are changed. Pass property_id=0 or staff_id=0 to detach the task from its property / staff. Common use cases: change task status (e.g. mark as completed), reassign staff, change the expected time, add a note.

Example phrases

• "Mark this task as completed"
• "Reassign this task to Lily"
• "Reschedule this cleaning task to 3 PM"