> ## Documentation Index
> Fetch the complete documentation index at: https://build.practicehub.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools reference
> The tools an AI client finds on the PracticeHub MCP server
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](/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
`list_entity_types` once per session — the agent learns the resources, attributes and accepted input.
`patient-lookup-tool` with a name, phone or email; `patient-info-tool` for the full record.
`query_entities` on `locations`, `appointment_types` and `practitioners?active=eq:1`.
`check_availability` with the location and appointment type (and optionally a practitioner and date range) — the agent offers only slots that are actually free.
`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
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.
Read-only. Lists a resource with the API's [filter syntax](/guides/querying#filters).
| 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.
Read-only. One record by id.
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------- |
| `entity` | string | Yes | Resource name |
| `id` | integer | Yes | Record id |
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.
Read-only. Free, bookable slots for a location and appointment type — the MCP form of [`GET /availability`](/guides/booking). 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
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) |
Read-only. Detailed information about one patient.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ----------- |
| `patient_id` | integer | Yes | Patient id |
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) |
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 |
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](/guides/writing).