Tools reference - PracticeHub API

Clients discover these automatically with tools/list; this page is the human-readable version. There are two kinds:

Generic tools are driven by the API’s resource registry, so they cover every resource on the API Reference — including ones added after this page was written.
Curated tools wrap the common clinical flows with friendlier parameters. They use the same services as the generic tools and the REST API.

A typical booking

Discover

list_entity_types once per session — the agent learns the resources, attributes and accepted input.

Find the patient

patient-lookup-tool with a name, phone or email; patient-info-tool for the full record.

Find the reference ids

query_entities on locations, appointment_types and practitioners?active=eq:1.

Check availability

check_availability with the location and appointment type (and optionally a practitioner and date range) — the agent offers only slots that are actually free.

Book

appointment-book-tool with the ids and one of the returned slots; the end defaults to the appointment type’s duration. A time that is no longer free is refused (slot_unavailable) — check again and offer the next.

Agents should confirm the details with the person before calling any write tool. Write tools are marked destructive in their annotations so clients that ask for confirmation will do so.

Generic tools

list_entity_types

Read-only. Returns every resource with its attributes (filterable / sortable flags), the write operations it supports and the input accepted per operation — the MCP form of GET /schema. No parameters.

query_entities

Read-only. Lists a resource with the API’s filter syntax.

Parameter	Type	Required	Description
`entity`	string	Yes	Resource name, e.g. `patients`, `appointments`
`filters`	string	No	Query-string filters: `last_name=like:%smith%&created=gte:2026-01-01`; metadata as `metadata[key]=op:value`
`sort`	string	No	`attr:asc` or `attr1,attr2:desc`
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Rows per page (default 25, max 100)

Returns the same data / meta / links envelope as the REST list endpoint.

get_entity

Read-only. One record by id.

Parameter	Type	Required	Description
`entity`	string	Yes	Resource name
`id`	integer	Yes	Record id

write_entity

Create, update or delete any writable resource through the same path as POST / PATCH / DELETE on the REST API — validation, business rules and audit trail included.

Parameter	Type	Required	Description
`entity`	string	Yes	Resource name
`operation`	string	Yes	`create`, `update` or `delete`
`id`	integer	For update / delete	Record id
`attributes`	string	For create / update	A JSON object of attributes, e.g. `{"name": "Google"}`; may include `"metadata": {…}`. On delete, carries any delete options (e.g. `{"void_payments": true}` for invoices)

Unsupported operations (a read-only resource, or update on payment_allocations) and rule refusals come back as tool errors with the API’s message.

check_availability

Read-only. Free, bookable slots for a location and appointment type — the MCP form of GET /availability. Slots are in the clinic timezone with the practitioner_id, start and end to pass to appointment-book-tool (or group_master_id for a group slot); unavailable_dates lists days with nothing free.

Parameter	Type	Required	Description
`location_id`	integer	Yes	Location id
`appointment_type_id`	integer	Yes	Appointment type id
`practitioner_id`	integer	No	Limit to one practitioner
`from`	string	No	`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`; default today
`to`	string	No	Default 7 days from `from`; at most 31 days
`visibility`	string	No	`online` (patient view, default) or `all` (staff view)
`max_per_day`	integer	No	Cap on slots per day (1–50)
`rescheduled_appointment_id`	integer	No	When moving an existing appointment: its id, so its current time isn’t counted as busy

Curated tools

patient-lookup-tool

Read-only. Searches patients by name, phone number or email.

Parameter	Type	Required	Description
`query`	string	Yes	Name, phone number or email
`limit`	integer	No	Max results (default 10)

patient-info-tool

Read-only. Detailed information about one patient.

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient id

appointment-lookup-tool

Read-only. A patient’s appointments — upcoming only by default.

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient id
`upcoming_only`	boolean	No	Only future appointments (default true)

appointment-book-tool

Books a new appointment. Same validation as write_entity on appointments (active patient, location, practitioner; resource at that location; the time free in the diary — call check_availability first) and triggers confirmation messaging as a staff booking would.

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient id
`appointment_type_id`	integer	Yes	Appointment type id
`location_id`	integer	Yes	Location id
`practitioner_id`	integer	Yes	Practitioner id
`start`	string	Yes	Start in the clinic timezone, `YYYY-MM-DD HH:MM:SS`
`end`	string	No	End; defaults to start + the appointment type’s duration
`note`	string	No	Booking note

appointment-reschedule-tool

Moves an existing appointment, keeping its duration unless a new end is given; can also change practitioner or location. Cascades to grouped appointments and records the reschedule in the audit trail.

Parameter	Type	Required	Description
`appointment_id`	integer	Yes	Appointment id
`start`	string	Yes	New start, `YYYY-MM-DD HH:MM:SS`
`end`	string	No	New end (defaults to keeping the current duration)
`practitioner_id`	integer	No	Move to this practitioner
`location_id`	integer	No	Move to this location

Cancelling, marking missed, arriving or reinstating an appointment is done with write_entity — operation: update with attributes: {"status": "cancelled", "cancel_note": "…"} — see Writing.

​A typical booking

​Generic tools

​Curated tools

A typical booking

Generic tools

Curated tools