MCP tools reference

Use this when the user explicitly asks, in any language, to book or reserve a specific service, place, date, time, or previously selected slot. The direct request itself is sufficient booking intent; do not ask for a second confirmation when the place, service, and slot are unambiguous. Preserve the user's language and exact service, place, city, brand, and employee names; fill structured fields when they are known. Query is required for unresolved natural-language requests, but omit it when providerId and serviceId were already returned by another tool. If no date or time is supplied, set firstAvailable=true instead of asking for a date. For a date range, use inclusive fromDate and toDate. Use date only for one exact day; for the earliest slot use slotPreference=earliest and for the latest use slotPreference=latest. Prefer book_first_available_appointment for explicit first, soonest, earliest, or ASAP intent. When a prior tool returned providerId, serviceId, optional employeeId, and startAt, pass those identifiers and finalize without another confirmation. If no place was supplied and the host provides location, prefer nearest results and return the place and slot for confirmation. Use search_providers for browsing or comparison.

Use this when the user explicitly asks, in any language, to book the first, soonest, earliest, fastest, ASAP, or as-soon-as-possible appointment, and also when a direct booking request has no date or time. The direct request itself is sufficient booking intent; do not ask for a second confirmation when the place and service are unambiguous. Preserve the user's language and exact service, place, city, brand, and employee names; fill structured fields when they are known. Query is required for unresolved natural-language requests, but omit it when providerId and serviceId were already returned by another tool. For a date range, use inclusive fromDate and toDate. Use date only for one exact day; for the earliest slot use slotPreference=earliest and for the latest use slotPreference=latest. This flow always sends firstAvailable=true, searches from now or from fromDate, checks availability, and finalizes when a specific place is supplied or resolved. If no place was supplied and the host provides location, prefer nearest results and return a selected place and slot for confirmation instead of booking a random place. Do not ask for a date only because none was supplied.

Use this when the user explicitly confirms they want to cancel an existing Umovi booking. Accepts either the internal bookingId or the short bookingRef shown to the client in Umovi booking details and emails.

Use this when the user wants open booking slots for a service at a place on one specific calendar day or time window, especially after search_providers returns NEEDS_DATE. Use date for the requested day and optional after/before for a time window on that day. If the user asks for all slots that day, set limit high, up to 50. If the user asks to book the first/earliest or last/latest slot on that day, prefer find_next_available_slot or book_appointment with date and slotPreference instead of listing slots first. If bookingFlow.status is HAS_SLOTS, ask the user to choose a slot or continue to book_appointment when the slot is already clear.

Use this when a booking tool returned a draftId for an explicit backend confirmation step. If the status is NEEDS_DATA_DISCLOSURE_ACKNOWLEDGEMENT, first present the data-sharing notice and set providerDataDisclosureAcknowledged=true only after the user actively acknowledges it. This acknowledgement is not marketing consent.

Use this when the user asks for the first, soonest, earliest, last, latest, or next available booking slot for a selected Umovi place and service. If no date range or horizon is supplied, search the next 7 days without asking for a date. With rescheduleBookingId, the result includes up to 10 times on the nearest available day so the user can choose before reschedule_booking is called. Use inclusive fromDate for requests like "po 7 czerwca" / "after June 7" after converting strict-after wording to the first allowed ISO date; use inclusive toDate for "przed 11 lipca" / "before July 11" after converting strict-before wording to the last allowed ISO date; use fromDate and toDate for "miedzy 5 a 10 lipca" / "between July 5 and July 10". Use date for one exact day. For the first or earliest slot on that exact day, send date with slotPreference=earliest or direction=forward; for the last/latest slot on that day, send date with slotPreference=latest or direction=backward. Requires providerId and serviceId from search_providers or get_provider_profile results.

Use this when the connected client asks for details of one Umovi booking, including when they provide the short booking identifier/code shown in Umovi or an email. Provide exactly one bookingId or bookingRef; put the short identifier in bookingRef and preserve its letters, digits, and separators. Use the returned providerId, serviceId and reschedule metadata before checking reschedule availability.

Use this when the connected client wants to read or check for replies in the conversation attached to one already-created booking. This is not a generic inbox or a way to contact a place without a booking. Accept exactly one bookingId or bookingRef; use bookingRef for the short code shown in Umovi or email. The place is resolved from that booking. This is read-only and must not mark messages as read. The result already contains the booking status and the complete compact conversation needed to answer whether the place replied, so answer directly and do not call get_booking_details. The default compact conversation returns message text only; set includeEvents=true only when the user explicitly asks for booking status history. Call render_booking_messages only when the user explicitly asks to open, show, or display the conversation widget; do not render it for a simple reply/status check.

Use this when the connected Umovi client wants to list or search their upcoming, past, cancelled, or recent bookings. Put a short booking identifier/code in search when the user wants to find it within their booking list; use get_booking_details with bookingRef when they ask for that booking directly.

Use this when the connected client asks for saved Umovi places, frequently visited suggestions, or personalized rebooking recommendations.

Use this when the user selected a specific Umovi place and needs public details, services, address, booking constraints, or its defaultLanguage for client communication.

Use this when the connected client explicitly confirms removing a saved place. This also withdraws the persistent client-place relationship and unlinks its connected booking history as required by Umovi privacy semantics.

Use this when get_booking_messages has succeeded and the user explicitly asked to open, show, or display the booking conversation in the Umovi widget. Copy booking and timeline from get_booking_messages structuredContent. Do not call it for a simple question such as whether the place replied. This tool only renders existing data and does not send or modify anything.

Use this when search_providers has returned booking option data and the user should see those options in the Umovi widget. Copy providers, labels, bookingFlow, and total from search_providers structuredContent into this tool; do not call the backend from this render step.

Use this when the user explicitly asks to show or open a visual preview of one place. First call get_provider_profile, then copy its public result into provider. This compact preview shows one image, the place name, location, short description, and a conversational availability action; it does not render the full staff or price catalogue.

Use this when the user clearly asks to repeat one existing booking at the same place for the same service, using the first available eligible time unless they supplied a date or horizon. The request itself is sufficient booking intent. This tool resolves the prior booking and performs one booking flow.

Use this when the user explicitly confirms they want to move an existing Umovi booking to a new exact slot. This updates the existing booking atomically; do not call cancel_booking before this tool. Accepts either bookingId or bookingRef from get_my_bookings, booking details, or email. If the user has not chosen a new exact startAt yet, use check_availability or find_next_available_slot first.

Use this when the user clearly asks to move one existing booking to its first, earliest, or next available time. The request itself is sufficient intent, so do not split this into get_booking_details, find_next_available_slot, and reschedule_booking model calls. This tool resolves the existing booking, finds the first eligible slot within the requested horizon, and atomically reschedules it. Do not use it when the user wants to compare or choose among several times.

Use this when the connected client asks to save or refresh one Umovi place in saved places.

Use this when the user wants to find, compare, or explore Umovi booking options by service type, service name, place name, city, area, neighbourhood, employee, date, or time window. Preserve the user's language and exact service, place, city, brand, and employee names; fill structured fields when they are known. When the user asks for free, open, or available appointments without a date, set firstAvailable=true and search immediately; when they also omit a horizon, omit inDays to use the default next 7 days. Do not ask for a date before this default search. A supplied date or inDays horizon overrides the default. Do not use this for explicit direct booking intent; use book_first_available_appointment for first/soonest/as-soon-as-possible booking requests, and book_appointment for other exact booking requests. Returns places with matched services, eligible employees, localized labels, provider timezones, provider defaultLanguage for client communication, and bookingFlow. Use this to answer questions about the price of a service at a place: each matched service includes priceCents (regular price), effectivePriceCents (current price after any active promotion), onPromotion, promotionName, discountPercent or discountAmountCents, and omnibusMinPriceCents (the EU Omnibus lowest price in the 30 days before the promotion). When a service is on promotion, present the current price together with the regular price and the Omnibus lowest-30-day reference price.

Use this when the user wants to send a message in one existing booking conversation. This does not send a generic message to a place. Clear intent is enough; do not ask for a second confirmation. Resolve the place from bookingId or bookingRef and always set bodyLanguage to the language actually used in body. If the user gives semantic intent such as 'tell them I will be late', compose only the provider-facing sentence in providerCommunicationLanguage and use COMPOSED_IN_TARGET_LANGUAGE; do not copy the user's instruction into originalBody. If the user supplies exact final wording and it differs from the provider language, preserve it exactly in originalBody, put an automatic translation in body, set both language tags, and use AI_TRANSLATED_WITH_ORIGINAL. Use ORIGINAL_ONLY when the exact text already matches the target language. Set translationDeclinedByUser=true only when the user explicitly requests sending foreign-language wording without translation. Do not invent material facts or sensitive details.