Appointments
These tools cover the full lifecycle of planned work: reading the current planning, creating appointmentsAppointmentA task scheduled to a resource for a specific period - the scheduled instance you see on the planning board., changing them, and deleting them.
Get resource planning
Tool: get_resource_planning
Returns the scheduled appointments (subjects, times, assigned resourcesResourceAn entity that can carry out work - a person, vehicle, tool, or room - that you schedule on the planning board.) 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 taskTaskA unit of work that belongs to a job. It appears in the open task list until it is scheduled to a resource..
| 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."
Get next appointment
Tool: get_next_appointment
Returns the next upcoming appointment for one resource, counted from the current server time. Use it to answer "what's next for John?" without composing a date range. The resource display name is required - the tool does not map the calling user to a resource, so discover the name with search_resources or the dimescheduler://resources data source first. The returned item is null when nothing is planned within the look-ahead window. For a full schedule view use get_resource_planning.
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayName | string | Yes | Display name of the resource (e.g. John Doe) |
timeZone | string | No | IANA timezone identifier. Falls back to the user's profile timezone, then the organization default. |
lookAheadDays | number | No | How many days ahead to scan (default: 30, max: 90) |
Example prompt
"What is John Doe's next job?"
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."
Change appointment time
Tool: change_appointment_time
A narrower alternative to reschedule_appointment for the single case of moving an appointment to a new start time, optionally with a new duration. It identifies the appointment by appointmentNo only, so call search_appointments or get_appointment_details first when you do not have it. Under the hood it runs the same pipeline as reschedule_appointment, including conflict detection, and returns the updated appointment.
| Parameter | Type | Required | Description |
|---|---|---|---|
appointmentNo | string | Yes | Appointment number (hashed ID) returned by search_appointments / get_appointment_details |
newStartDateTime | string | Yes | New start date and time (ISO 8601 with explicit year, e.g. 2026-05-22T14:00:00Z) |
timeZone | string | No | IANA timezone identifier. Falls back to the user's profile timezone, then the organization default. |
newDuration | string | No | New duration, e.g. 2 hours, 90 minutes, 1h30m, 02:30:00. The existing duration is kept when omitted. |
idempotencyKey | string | No | Letters, digits, - and _, max 64 characters. Retrying with the same key within about 10 minutes returns the original response instead of applying the change again. |
For reassigning the appointment to other resources use change_appointment_resources; for renaming, recategorizing, or other metadata changes use update_appointment.
Example prompt
"Move appointment ABC123 to Friday at 9 AM and make it 90 minutes."
Change appointment resources
Tool: change_appointment_resources
A narrower alternative to reschedule_appointment for the single case of reassigning an appointment to a different set of resources. The new set replaces all existing assignments. Like change_appointment_time, it identifies the appointment by appointmentNo only and returns the updated appointment.
| Parameter | Type | Required | Description |
|---|---|---|---|
appointmentNo | string | Yes | Appointment number (hashed ID) returned by search_appointments / get_appointment_details |
resources | string[] | No | Preferred: array of resource display names, e.g. ["John Doe", "Jane Smith"]. Required when resourceDisplayNames is omitted. |
resourceDisplayNames | string | No | Deprecated comma-separated form (e.g. John Doe, Jane Smith). Used only when resources is omitted. |
timeZone | string | No | IANA timezone identifier. Falls back to the user's profile timezone, then the organization default. |
idempotencyKey | string | No | Letters, digits, - and _, max 64 characters. Retrying with the same key within about 10 minutes returns the original response instead of applying the change again. |
For time or duration changes use change_appointment_time; for subject, category, or other metadata use update_appointment.
Example prompt
"Reassign appointment ABC123 from John to Jane and Mark."
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."