Tool reference
Every MCP tool is read-only and available only if its permission requirement is met and the admin has not disabled it. The tool descriptions below match what you see when calling tools/list.
Handshake
ping
Description: Connectivity check. Returns the Gurita server version and the current server time.
Parameters: (none)
Always available — cannot be disabled.
Assets
list_assets
Description: List resorts, vessels, and dive centers this token may query, with their IDs. Call this first if you need asset IDs for report tools.
Parameters: (none)
Permissions: Requires a staff read permission (Bookings, Dive Log, or Product).
Always available — cannot be disabled.
Bookings & Folios
find_bookings
Description: Search bookings by guest name, booking/reservation number, or free text; or list the bookings on one trip. Returns summary rows.
Parameters:
| Parameter | Type | Description |
|---|---|---|
search | string (optional) | Guest name, booking number, reservation number, or free text. |
trip | string (optional) | Trip (schedule) ID from find_trips. |
state | string (optional) | Booking state filter (e.g. "confirmed"). |
from | date (optional) | Only bookings overlapping this start date (YYYY-MM-DD). |
to | date (optional) | Only bookings overlapping up to this end date (YYYY-MM-DD). |
limit | number (1–25, default 10) | How many results to return. |
Requires: Either search or trip must be provided.
Permissions: Bookings (Read).
Disabled by: toolsBookings group toggle.
get_booking
Description: Fetch one booking by booking number or ID: stay dates, lifecycle dates, state, pax, rooms, and key references.
Parameters:
| Parameter | Type | Description |
|---|---|---|
booking | string | Booking number (e.g. "2026-167") or booking ID. |
Permissions: Bookings (Read).
Disabled by: toolsBookings group toggle.
get_folio_balance
Description: Folios (invoices) of one booking with totals, paid amounts, and open balance.
Parameters:
| Parameter | Type | Description |
|---|---|---|
booking | string | Booking number or booking ID. |
Permissions: Folio (Read).
Disabled by: toolsFinance group toggle.
Trips & Guest Lists
find_trips
Description: Find liveaboard trips (scheduled departures) by name, vessel, tour, port, or date. Call this first to turn a trip name into the ID for the other trip tools.
Parameters:
| Parameter | Type | Description |
|---|---|---|
search | string (optional) | Trip name, internal ID, tag, vessel name, tour name, or port. |
vessel | string (optional) | Vessel ID from list_assets. |
from | date (optional) | Only trips departing on or after this date (YYYY-MM-DD). |
to | date (optional) | Only trips departing on or before this date (YYYY-MM-DD). |
upcoming | boolean (default false) | Only trips departing from today on, soonest first. |
status | array (optional) | Trip statuses to include, e.g. ["confirmed"]. Empty = all. |
limit | number (1–50, default 10) | How many results to return. |
Permissions: Schedules (Read).
Disabled by: toolsTrips group toggle.
get_trip
Description: Fetch up to 10 trips by ID. Returns occupancy counts, revenue, and booking summaries (optional).
Parameters:
| Parameter | Type | Description |
|---|---|---|
trips | array of strings | Trip IDs from find_trips (1–10). |
include_bookings | boolean (default true) | Include booking rows for each trip. |
Permissions: Schedules (Read).
Disabled by: toolsTrips group toggle.
get_trip_guests
Description: Guest roster for one trip: who is on board, their cabin, booking, and nationality. Optionally nationalities only (no personal data).
Parameters:
| Parameter | Type | Description |
|---|---|---|
trip | string | Trip ID from find_trips. |
states | array (default ["confirmed"]) | Booking states to include, e.g. ["confirmed", "planned"]. |
include_guests | boolean (default true) | Include guest names. Set to false to return only per-country counts. |
Permissions: Schedules (Read) + Customers (Read) — both required.
Disabled by: toolsTrips group toggle.
Customers & Agencies
find_customers
Description: Search customers by name, customer number, email, or city. Returns profile summaries.
Parameters:
| Parameter | Type | Description |
|---|---|---|
search | string | Name, customer number, email, or city (minimum 2 characters). |
limit | number (1–25, default 10) | How many results to return. |
Permissions: Customers (Read). Restricted tokens are rejected — customer lookups require an unrestricted account (no asset assignment).
Disabled by: toolsCustomers group toggle.
get_customer
Description: Fetch one customer profile by ID: master data, contact, address, tags, and created date.
Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Customer ID from find_customers. |
Permissions: Customers (Read). Restricted tokens are rejected.
Disabled by: toolsCustomers group toggle.
find_duplicate_customers
Description: Scan all customers for potential duplicates: groups sharing an email, phone, or first + last name. Use get_customer on members to compare.
Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number (1–50, default 20) | Max duplicate groups per match type (email, phone, name). |
Permissions: Customers (Read). Restricted tokens are rejected.
Disabled by: toolsCustomers group toggle.
find_agents
Description: Search agents (travel agencies) by name, agency number, email, phone, or city. Returns profile summaries.
Parameters:
| Parameter | Type | Description |
|---|---|---|
search | string | Name, agency number, email, phone, or city (minimum 2 characters). |
limit | number (1–25, default 10) | How many results to return. |
Permissions: Agencies (Read). Restricted tokens are rejected.
Disabled by: toolsAgents group toggle.
get_agent
Description: Fetch one agent (travel agency) profile by ID: master data, contact, and address. No commission or credit figures.
Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Agent ID from find_agents. |
Permissions: Agencies (Read). Restricted tokens are rejected.
Disabled by: toolsAgents group toggle.
find_duplicate_agents
Description: Scan all agents for potential duplicates: groups sharing a name, email, or phone. Use get_agent on members to compare.
Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number (1–50, default 20) | Max duplicate groups per match type. |
Permissions: Agencies (Read). Restricted tokens are rejected.
Disabled by: toolsAgents group toggle.
Finance & Revenue
get_dashboard_statistics
Description: Booking trend snapshot: confirmed and planned bookings in the last N days vs. the prior period, plus a 12-month chart.
Parameters:
| Parameter | Type | Description |
|---|---|---|
days | number (1–365, default 30) | Look-back window in days. |
Permissions: Bookings (Read).
Disabled by: toolsFinance group toggle.
get_income_by_month
Description: Income/revenue per period: expected income, paid, onsite revenue, cash and bank amounts per currency. The core revenue report.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD), interpreted in instance timezone. |
to | date | End date (YYYY-MM-DD), inclusive. |
group_by | enum (default "month") | Time period: day, week, month, or year. |
asset | string (optional) | Asset ID from list_assets. Omit to use the token's default scope. |
include_reservations | boolean (default false) | Also count non-confirmed reservations. |
Permissions: Bookings (Read).
Disabled by: toolsFinance group toggle.
get_profit_loss
Description: Profit & loss by category (rooms, products, supplements, commissions, etc.) for one asset and period, in a single currency.
Parameters:
| Parameter | Type | Description |
|---|---|---|
asset | string | Asset ID from list_assets. |
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
currency | string (optional) | ISO currency code; defaults to instance base currency. |
prepayment_mode | enum (default "payment") | Which date allocates prepayments: payment, checkIn, or checkOut. |
Permissions: Bookings (Read).
Disabled by: toolsFinance group toggle.
get_payment_report
Description: Payments received per period, split by payment type, for one asset. Covers booking payments, onsite payments, or POS transactions.
Parameters:
| Parameter | Type | Description |
|---|---|---|
asset | string | Asset ID from list_assets. |
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
group_by | enum (default "month") | Time period: day, week, month, or year. |
date_field | enum (default "payment") | Which date buckets a payment: payment, checkin, or checkout. |
mode | enum (default "booking") | Revenue stream: booking, onsite, or pos. |
Permissions: Bookings (Read).
Disabled by: toolsFinance group toggle.
get_outstanding_payments
Description: Bookings with open or overdue balances: aggregate payment status plus affected booking details.
Parameters:
| Parameter | Type | Description |
|---|---|---|
days | number (1–365, default 30) | Look-back window in days. |
asset | string (optional) | Asset ID from list_assets. Omit to use the token's default scope. |
Permissions: Bookings (Read).
Disabled by: toolsFinance group toggle.
get_bank_cashflow
Description: Cash flow from bank entries: revenue vs. expenditure grouped by period, per currency.
Parameters:
| Parameter | Type | Description |
|---|---|---|
group_by | enum (default "month") | Time period: day, week, month, or year. |
currency | string (optional) | ISO currency code; defaults to instance base currency. |
Permissions: Bank (Read).
Disabled by: toolsFinance group toggle.
Occupancy
get_daily_occupancy
Description: Day-by-day occupancy: bed-nights, pax, and occupancy rates per date. Use for detailed short-range occupancy questions.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD); span capped at 400 days. |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
states | array (optional) | Booking states to include, e.g. ["confirmed"]. Empty = default set. |
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
get_occupancy_per_year
Description: Occupancy roll-up per year and month: pax and room occupancy percentages. Use for seasonal or year-over-year comparisons.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
states | array (optional) | Booking states to include. |
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
Analytics & Advanced Reports
get_utilization
Description: Capacity utilization over time: free rooms and free beds per period for a resort or vessel. Use for availability and overbooking questions.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
resort | string (optional) | Resort ID from list_assets. Required if token is asset-restricted and no vessel given. |
vessel | string (optional) | Vessel ID from list_assets. |
group_by | enum (default "day") | Time period: day, week, month, or year. |
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
get_vessel_targets
Description: Per-vessel revenue targets vs. actuals for a year, with per-cabin-type occupancy. Ideal for liveaboard performance reviews.
Parameters:
| Parameter | Type | Description |
|---|---|---|
year | number | Calendar year (2000–2100). |
assets | array (optional) | Vessel IDs from list_assets; empty = all accessible vessels. |
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
get_trip_occupancy
Description: Per-trip occupancy for one vessel over a year or date range: occupancy and revenue per scheduled departure. For a single named trip, use find_trips then get_trip.
Parameters:
| Parameter | Type | Description |
|---|---|---|
vessel | string | Vessel ID from list_assets. |
year | number (optional) | Calendar year (2000–2100). |
from | date (optional) | Start date (YYYY-MM-DD). |
to | date (optional) | End date (YYYY-MM-DD). |
Requires: At least one of year, from, or to.
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
get_conversion_rates
Description: Booking conversion funnel over time: how reservations/offers convert to confirmed bookings per period.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
group_by | enum (default "month") | Time period: day, week, month, or year. |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
Permissions: Bookings (Read).
Disabled by: toolsOccupancy group toggle.
Sales & Products
get_top_performers
Description: Rank top products, product categories, supplements, guests, customer tags, countries, agencies, sales agents, or rooms by revenue for a period. For "top customers" meaning individual people, use dimension "guests" — "customers" ranks customer tags/segments.
Parameters:
| Parameter | Type | Description |
|---|---|---|
dimension | enum | What to rank: products, product_categories, supplements, guests, customers, countries, agencies, sales_agents, or rooms. |
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
limit | number (1–50, default 10) | How many entries to return. |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
type | enum (default "prepayment") | Revenue stream (products/categories only): prepayment, onsite, or pos. |
Permissions: Bookings (Read).
Disabled by: toolsSales group toggle.
get_product_sales
Description: Product/service sales report: per-product quantities, revenue, cost, estimated profit, discounts, and taxes for a period.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
categories | array (optional) | Product category IDs to filter. |
types | array (optional) | Sale types to include, e.g. ["prepayment", "onsite"]. Empty = all. |
Permissions: Bookings (Read).
Disabled by: toolsSales group toggle.
get_pos_sales
Description: POS (bar/shop/restaurant) sales line items for a period. Large ranges are truncated — prefer short ranges or use get_top_performers with type "pos" for rankings.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
assets | array (optional) | Asset IDs from list_assets; empty = all accessible assets. |
Permissions: POS (Read).
Disabled by: toolsSales group toggle.
Dive Operations
get_dive_statistics
Description: Dive operation statistics over time: dives and dive-log activity grouped by period.
Parameters:
| Parameter | Type | Description |
|---|---|---|
from | date | Start date (YYYY-MM-DD). |
to | date | End date (YYYY-MM-DD). |
group_by | enum (default "month") | Time period: day, week, month, or year. |
Permissions: Dive Log (Read).
Disabled by: toolsDive group toggle.
ChatGPT Connector
The ChatGPT connector uses two built-in tools to search and fetch records. These are Gurita-specific implementations for ChatGPT's deep research features.
search
Description: Search this Gurita instance for bookings and customers matching a query. Returns result stubs (ID, title, URL) for use with the fetch tool.
Parameters:
| Parameter | Type | Description |
|---|---|---|
query | string | Free-text search: guest name, booking/reservation number, email, etc. |
Permissions: Bookings (Read) for bookings; Customers (Read) for customers. Restricted tokens are rejected for customer search.
Disabled by: toolsConnector, toolsBookings, or toolsCustomers group toggles.
fetch
Description: Fetch one booking or customer by ID (namespaced as booking:<id> or customer:<id>).
Permissions: Bookings (Read) or Customers (Read), depending on the record type. Restricted tokens are rejected for customers.
Disabled by: toolsConnector, toolsBookings, or toolsCustomers group toggles.
Disabled tool groups
The admin can disable entire groups of tools via Settings → AI Assistant (MCP). When a group is off, all its tools vanish from tools/list and are rejected on tools/call:
| Group | Tools affected |
|---|---|
toolsBookings | find_bookings, get_booking |
toolsCustomers | find_customers, get_customer, find_duplicate_customers |
toolsAgents | find_agents, get_agent, find_duplicate_agents |
toolsTrips | find_trips, get_trip, get_trip_guests |
toolsFinance | get_folio_balance, get_dashboard_statistics, get_income_by_month, get_profit_loss, get_payment_report, get_outstanding_payments, get_bank_cashflow |
toolsSales | get_top_performers, get_product_sales, get_pos_sales |
toolsOccupancy | get_daily_occupancy, get_occupancy_per_year, get_utilization, get_vessel_targets, get_trip_occupancy, get_conversion_rates |
toolsDive | get_dive_statistics |
toolsConnector | search, fetch (ChatGPT connector) |
The admin can also disable individual tools by name (e.g. get_bank_cashflow) even when their group is on. ping and list_assets cannot be disabled.