Appointments
The appointment tools cover the full lifecycle of planned work: reading the existing planning, creating new appointments, modifying them, and deleting them.
Get resource planning
Tool: get_resource_planning
Returns the scheduled appointments (subjects, times, assigned resources) for one or more known resources over a time range.
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayNames | string | Yes | Display names of the resources, comma-separated |
startDateTime | string | Yes | Start of the period (ISO 8601) |
endDateTime | string | Yes | End of the period (ISO 8601) |
timeZone | string | Yes | IANA timezone identifier |
Example prompt
"Give me the planning for resource Johnny Marr for this week."
Search appointments
Tool: search_appointments
Searches appointments by subject, date range, resource, or task.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier |
searchTerm | string | No | Search term to match against subject or description |
startDate | string | No | Start of the date-range filter (ISO 8601) |
endDate | string | No | End of the date-range filter (ISO 8601) |
resourceDisplayName | string | No | Resource display name to filter by |
taskNo | string | No | Task number to filter by |
categoryName | string | No | Category name to filter by |
limit | number | No | Maximum number of results to return (default: 500) |
Example prompt
"Show John's appointments this week."
Get appointment details
Tool: get_appointment_details
Returns full details for one appointment. The appointment can be identified by appointmentNo (preferred), task number, subject, resource, and/or day.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier |
appointmentNo | string | No | Appointment number (hashed ID) - the most precise way to identify an appointment |
taskNo | string | No | Task number to identify the appointment |
subject | string | No | Subject/title of the appointment |
resourceDisplayName | string | No | Resource display name (highly recommended when a task has multiple appointments) |
day | string | No | Day to find the appointment - ISO date with explicit year, or relative (today, tomorrow, Monday) |
startDateTime | string | No | Start date and time (alternative to day) - ISO 8601 with explicit year |
Example prompt
"Get details for the appointment on task 123 tomorrow."
Create appointment
Tool: create_appointment
Creates a new appointment for one or more resources at a specific time.
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Subject/title of the appointment |
startDateTime | string | Yes | Start (ISO 8601) |
endDateTime | string | Yes | End (ISO 8601) |
resourceDisplayNames | string | Yes | Display names of the resources to assign, comma-separated (e.g. John Doe, Jane Smith) |
timeZone | string | Yes | IANA timezone identifier |
description | string | No | Description / body text |
taskNo | string | No | Task number to link the appointment to (e.g. 24 or TASK-001) |
categoryName | string | No | Category name (e.g. Installation, Repair) |
timeMarkerName | string | No | Time marker name (e.g. Travel, Break) |
importance | number | No | Priority: 0 = Medium, 1 = High, 2 = Low |
Example prompt
"Schedule task 24 for John Smith tomorrow at 2 PM for 2 hours."
Update appointment
Tool: update_appointment
Updates an existing appointment with new details. Only the fields you want to change need to be provided. The appointment is identified by appointmentNo, or by subject + currentStartDateTime (with resourceDisplayName to disambiguate when needed).
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier |
appointmentNo | string | No | Appointment number to identify the appointment directly |
subject | string | No | Subject/title of the appointment to update (use with currentStartDateTime) |
currentStartDateTime | string | No | Current start date and time of the appointment (ISO 8601) |
resourceDisplayName | string | No | Resource display name to disambiguate when multiple appointments share a subject and date |
newSubject | string | No | New subject/title |
startDateTime | string | No | New start (ISO 8601) |
endDateTime | string | No | New end (ISO 8601) |
description | string | No | New description / body text |
resourceDisplayNames | string | No | New resource display names (comma-separated) - reassigns the appointment |
taskNo | string | No | Task number to link the appointment to |
categoryName | string | No | Category name |
timeMarkerName | string | No | Time marker name |
importance | number | No | Priority: 0 = Medium, 1 = High, 2 = Low |
Example prompt
"Update the appointment with subject 'Meeting' to start at 3 PM instead of 2 PM."
Reschedule appointment
Tool: reschedule_appointment
A higher-level alternative to update_appointment for the common case of moving and/or reassigning work. It accepts natural-language style parameters (relativeTimeShift: "2 hours later", newDuration: "90 minutes") and only requires the parameters that are explicitly being changed.
Identification
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier |
appointmentNo | string | No | Appointment number to identify the appointment directly |
taskNo | string | No | Task number to identify the appointment |
subject | string | No | Subject/title of the appointment |
resourceDisplayName | string | No | Current resource display name to identify the appointment |
currentDay | string | No | Current day - ISO date with explicit year, or relative (today, tomorrow) |
currentStartDateTime | string | No | Current start date and time (alternative to currentDay) - ISO 8601 with explicit year |
Move (change start time)
| Parameter | Type | Required | Description |
|---|---|---|---|
newDay | string | No | New day - ISO date with explicit year, or relative |
newTime | string | No | New time of day, e.g. 13:14, 14:00 - used when only a time is specified |
relativeTimeShift | string | No | Relative shift, e.g. 2 hours later, 30 minutes earlier |
newStartDateTime | string | No | Exact new start (ISO 8601 with explicit year) |
Duration (change end time)
| Parameter | Type | Required | Description |
|---|---|---|---|
newDuration | string | No | New duration, e.g. 2 hours, 90 minutes |
newEndDateTime | string | No | Exact new end (ISO 8601 with explicit year) |
Reassignment
| Parameter | Type | Required | Description |
|---|---|---|---|
newResourceDisplayNames | string | No | New resource display names, comma-separated |
Example prompt
"Move tomorrow's appointment for Jack Brugerling to next Monday at 2 PM."
Delete appointment
Tool: delete_appointment
Deletes an existing appointment. Identify it with appointmentNo, or with subject + startDateTime (and resourceDisplayName if needed).
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier |
appointmentNo | string | No | Appointment number to identify the appointment directly |
subject | string | No | Subject of the appointment to delete (use with startDateTime) |
startDateTime | string | No | Start of the appointment (ISO 8601) |
resourceDisplayName | string | No | Resource display name to disambiguate when multiple appointments share subject and date |
Example prompt
"Delete the appointment 'Meeting' scheduled for tomorrow at 2 PM."
Bulk reschedule appointments
Tool: bulk_reschedule_appointments
Reschedules many appointments in one call. Each item is processed independently - one item failing does not stop the others. Returns a per-item outcome with success/failure and the new appointment (or error message). Max 50 items per call.
Use this for "move all of John's Friday appointments to Monday" or "reassign these 12 jobs to Sarah" style requests.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier - applied to every item in the batch |
items | BulkRescheduleItem[] | Yes | Array of reschedule operations (max 50). Each item identifies an appointment and the changes |
Per-item identification follows the same rules as reschedule_appointment: use one of appointmentNo, taskNo, subject, or resourceDisplayName + currentDay / currentStartDateTime.
Per-item modifications follow the same rules as reschedule_appointment: provide at least one of newDay / newTime / newStartDateTime, newDuration / newEndDateTime, or newResourceDisplayNames.
Example prompt
"Move all of John's Friday appointments to Monday at the same times."
Bulk delete appointments
Tool: bulk_delete_appointments
Deletes many appointments in one call. Each item is processed independently - one item failing does not stop the others. Returns a per-item outcome with success/failure. Max 50 items per call.
Use this for "cancel all appointments for tomorrow" or "delete the 8 appointments I just made" style requests. The cancel-and-notify prompt wraps this tool together with send_message for the common case of cancelling a resource's day and informing them.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier - applied to every item in the batch |
items | BulkDeleteItem[] | Yes | Array of delete operations (max 50). Each item identifies an appointment |
Each item must identify an appointment using one of: appointmentNo, or subject + startDateTime (with optional resourceDisplayName to disambiguate).
Example prompt
"Cancel all of Jane's appointments for tomorrow."