Cliniko Tools — Health Practice Management
Langoedge Team5 min read
What are the Cliniko Tools?
For health and medical practices using Cliniko, Langoedge offers a complete suite of native tools. Attached to a Text Graph, they let an agent act as a virtual clinic receptionist — checking practitioner availability, searching patient records, scheduling appointments, and managing cancellations. A phone agent reaches them by mounting that Text Graph as a tool on a voice node.
Cliniko is one of a handful of integrations deliberately kept as hand-written tools rather than going through an MCP Connector, because clinic scheduling needs domain-specific aggregation across businesses, practitioners, appointment types, and availability that a generic tool call can't provide.
Prerequisite — an active account connection. Before your agents can check availability, query patients, or manage bookings, connect your Cliniko API key on the Connect page in your dashboard. Without it, any step using a cliniko_* tool will fail at runtime.
Every Cliniko tool is wrapped so it never raises an unhandled exception — a failure comes back to the agent as a readable message it can act on or relay, rather than crashing the graph mid-call. This matters on a live phone call, where a hard failure means dead air.
Available Cliniko Actions
Attach these tools to your graph nodes to automate front-desk clinic tasks. Twelve tools are available.
1. Clinic Configuration
| Tool | Parameters | Description |
|---|---|---|
cliniko_get_clinic_metadata |
resource (default all) |
Retrieves your clinic's structural configuration — businesses (locations), practitioners, and appointment types — in a single call. Pass all to fetch everything, or narrow it to one resource. |
This one tool replaces the three separate lookups (`cliniko_list_businesses`, `cliniko_list_practitioners`, `cliniko_list_appointment_types`) described in earlier documentation. Those names no longer exist. Fetching all three together in one call is both faster and what an agent almost always needs before it can book anything.
2. Patient Management
| Tool | Parameters | Description |
|---|---|---|
cliniko_search_patients |
query |
Searches patients by first name, last name, email, or phone number. |
cliniko_get_patient |
patient_id |
Retrieves the full profile of a single patient by ID. |
cliniko_create_patient |
first_name, last_name, plus optional email, mobile_phone, home_phone, patient_phone, date_of_birth, gender_identity, sex, time_zone, accepted_privacy_policy |
Creates a new patient record — for a first-time caller. |
cliniko_update_patient |
patient_id, plus any of the fields above |
Updates an existing patient record, e.g. correcting a phone number captured on a call. |
3. Availability Lookup
| Tool | Parameters | Description |
|---|---|---|
cliniko_get_available_times |
business_id, appointment_type_id, optional practitioner_id, from_date, to_date |
Retrieves real-time open slots. Omit practitioner_id to search all active practitioners at once and surface the earliest option; supply it to check one specific practitioner. |
There is no separate `cliniko_get_available_times_all_practitioners` tool. Leaving `practitioner_id` empty on `cliniko_get_available_times` is how you search across the whole clinic.
4. Appointment Booking & Management
| Tool | Parameters | Description |
|---|---|---|
cliniko_book_appointment |
business_id, practitioner_id, appointment_type_id, patient_id, starts_at, optional notes |
Books a new individual appointment directly into the Cliniko calendar. |
cliniko_list_appointments |
optional appointment_id, business_id, practitioner_id, patient_id, from_date, to_date, include_cancelled |
Lists or searches appointments, or fetches one by ID. Filter by patient_id to answer "when is my next appointment?". |
cliniko_reschedule_appointment |
appointment_id, new_starts_at |
Moves an appointment to a new date and time. |
cliniko_cancel_appointment |
appointment_id, optional cancellation_reason_code, cancellation_note |
Cancels an appointment through Cliniko's official cancellation endpoint, so it is recorded properly rather than silently deleted. |
cliniko_update_appointment_notes |
appointment_id, note_to_add |
Appends a timestamped note without overwriting what's already there — ideal for attaching a call summary. |
cliniko_mass_reschedule_practitioner_day |
practitioner_id, date, notify_via_sms (default true) |
Reschedules every active appointment for one practitioner on one day — the "practitioner called in sick" workflow — optionally texting each affected patient. |
`cliniko_list_appointments` covers what earlier documentation split into `cliniko_get_appointment` and `cliniko_list_patient_appointments`. Neither of those names exists any more: pass `appointment_id` to fetch one, or `patient_id` to list a patient's bookings.
A Typical Booking Flow
An agent booking a new patient generally moves through the tools in this order:
flowchart LR
A[cliniko_get_clinic_metadata] --> B[cliniko_search_patients]
B -- found --> D[cliniko_get_available_times]
B -- not found --> C[cliniko_create_patient] --> D
D --> E[cliniko_book_appointment]
E --> F[cliniko_update_appointment_notes]
Fetch the clinic's configuration first, because booking needs real business_id, practitioner_id, and appointment_type_id values — an agent cannot invent them.
Frequently Asked Questions
How does the receptionist agent handle practitioner preferences?
Call `cliniko_get_available_times` with the requested `practitioner_id`. If nothing suitable comes back, call it again **without** `practitioner_id` to search every active practitioner and offer the caller an alternative.
How are Cliniko credentials managed?
Connect your Cliniko API key on the **Connect** page. Langoedge establishes a secure bridge to your Cliniko shard domain (`https://your-shard.cliniko.com`) automatically. The key is never exposed to the LLM.
Can a Voice Graph use these tools directly?
No. A voice node's own tools are limited to agent transitions, ending the call, and calling a Text Graph. To let a phone agent book into Cliniko, put the `cliniko_*` tools on a **Text Graph** and mount that graph as a tool on your voice node. This is the recommended shape anyway — the Text Graph can run asynchronously so the agent keeps talking while the lookup happens, instead of leaving the caller in silence.
What happens if Cliniko is down or returns an error?
Each tool is wrapped so failures return a readable message to the agent rather than raising. The agent can then apologise and offer a callback instead of the call going silent.
Does cancelling really cancel, or just delete?
`cliniko_cancel_appointment` uses Cliniko's official cancellation endpoint and records a reason code, so the cancellation shows up properly in your practice records and reporting.