Schedule Tools

These tools let an AI client work with your workspace's schedules: standing rules that start a checklist from a template at set times. Each schedule has a series of runs — one per occurrence, written out ahead of time to a horizon of 400 days for a daily schedule and ten years for a yearly one. A run is pending until it is due, created once it has a checklist, and missed if it fell due and produced none. The tools mirror the Schedules REST routes.

A schedule is named by an integer scheduleId and a run by an integer runId, not by a key. A schedule's startDateTime is a wall-clock time in the schedule's own time zone, with no Z and no offset; every other timestamp is UTC.

The descriptions spend most of their words on failures that store without complaint and then behave wrongly — a schedule whose template has been archived goes on listing a next run and produces nothing — so they tell the model to read templateIsArchived before believing nextRun, and to ask list_schedule_runs for missed runs when something looks wrong.

How to Read This Page

Every tool acts on the workspace your API key belongs to, as the member (or the workspace) the key acts as. There is no workspace argument. See Connecting.

• The Read/Write column in the summary table says whether a tool can change anything.
• Annotations are the hints a tool publishes to your client: readOnlyHint, destructiveHint and idempotentHint. A hint a tool does not declare is left out of its definition, and the MCP specification tells a client to assume the cautious default in that case — that the tool may write, may be destructive and is not idempotent. See Tool Annotations.
• idempotencyKey appears on the write tools that accept it. It is optional and at most 255 characters. If a call times out or its answer is lost, send it again with the same key and the same arguments: the first call's answer comes back, marked checkflow.io/idempotentReplay in the result's _meta, instead of the work happening twice. The same key with different arguments is refused with CONFLICT, and so is a retry while the first call is still running. See Idempotency.
• Refusals come back as an ordinary tool result with isError set. structuredContent carries the v3 error body — code, message, requestId and field — and the text block summarises it. See Errors and How It Works.
• A tool that returns nothing, such as a delete, answers with a result that is not flagged isError and carries no data.

Tool Summary

Tool	What it does	Read/Write
list_schedules	Lists the workspace's schedules	Read
get_schedule	Returns one schedule with its parameter values	Read
create_schedule	Creates a schedule and its series of runs	Write
update_schedule	Changes a schedule	Write
delete_schedule	Deletes a schedule and its pending runs	Write
list_schedule_runs	Lists one schedule's runs	Read
get_schedule_run	Returns one run	Read
delete_schedule_run	Skips one pending run	Write
create_schedule_run_checklist	Starts a run's checklist now	Write

list_schedules

Lists the workspace's schedules, by name from A to Z. The description tells the model to read templateIsArchived on every row before believing nextRun: the job that turns a run into a checklist skips an archived template without saying so, so such a schedule keeps listing a next run and producing nothing. Parameter values are not on these rows; get_schedule has them.

Name	Type	Required	Description
templateKey	string	No	Only the schedules of this template, from list_templates.
isActive	boolean	No	true for schedules generating runs, false for those switched off. Omit for both.
sort	string	No	field, field:asc or field:desc, where field is name, templateName, startDateTime, nextRun or createdDateTime. Default name:asc.
after	string	No	The nextCursor from the previous page. Send the same filters with it.
pageSize	integer	No	Results per page, 1 to 100. Default 50. A value outside the range is not refused; the default of 50 is used instead.

• Returns: the standard list envelope (see Pagination) holding Schedule objects without parameters.
• Annotations: readOnlyHint true, idempotentHint true.
• REST equivalent: GET /v3/schedules.
• Example prompt: "Which schedules are running in CheckFlow, and when does each fire next?"

get_schedule

Returns one schedule in full, with the parameter values its checklists start with and who created it. The description points the model at two fields: templateIsArchived, which says whether the schedule produces anything at all, and startDateTime, which is a wall-clock time in timeZone — startDateTimeUtc beside it is the instant, and the two drift apart at each clock change. A parameter listed without a name is a value stored against a parameter the template has since removed; it is ignored when runs are generated.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule's id, from list_schedules.

• Returns: a Schedule object.
• Annotations: readOnlyHint true, idempotentHint true.
• REST equivalent: GET /v3/schedules/{id}.
• Example prompt: "Show me the details of the monthly Invoice Review schedule."

create_schedule

Creates a schedule and, with it, the whole series of runs it will produce. Everything that decides when a run happens is checked before anything is stored. There is no duplicate check — two schedules on the same template at the same time are two schedules and make two checklists, which is reasonable with different parameters on each. The template cannot be changed afterwards.

Name	Type	Required	Description
name	string	Yes	The schedule's name, at most 100 characters. This is not what its checklists are called.
templateKey	string	Yes	The template each run starts from, from list_templates. An archived template is refused.
timeZone	string	Yes	The zone the schedule's clock runs in — an IANA name such as Europe/London or a Windows name such as GMT Standard Time. The one sent is the one stored.
startDateTime	string	Yes	When the first run is due, as a wall-clock time in timeZone: 2026-03-01T09:00:00. A value with a Z or an offset is refused rather than converted. A time in a spring-forward gap is refused. A start in the past is allowed for a repeating schedule and refused for a one-off.
recurrence	object	Yes	How often it repeats: repeats, every and daysOfWeek. See Recurrence.
checklistNameFormat	string	No	What the checklists are called. Defaults to the template's name. May contain placeholders expanded when each run is generated, such as {{ template.name }}, {{ schedule.name }}, {{ checklist.date.yyyy-MM-dd }}, {{ checklist.week }} and {{ checklist.quarter }}. An unknown placeholder is refused.
isActive	boolean	No	Whether to start generating runs straight away. Default true.
parameters	array of objects	No	Values every checklist starts with, each key and value, where key is the parameter's key or name. A name matching no parameter of the template is refused. get_template lists a template's parameters.
idempotencyKey	string	No	Retries this call safely. See How to Read This Page.

• Returns: the new Schedule object.
• Annotations: destructiveHint false.
• REST equivalent: POST /v3/schedules.
• Example prompt: "Schedule an Invoice Review checklist at 9am London time on the last weekday of every month, starting in March 2026."

Recurrence

recurrence is a nested object, and refusals about it name recurrence.every or recurrence.daysOfWeek.

Field	Description
repeats	never, daily, weekly, monthly, yearly, last_day_of_month, last_weekday_of_month, first_weekday_of_month, last_day_of_quarter or last_weekday_of_quarter. never is a one-off, not a way of switching the schedule off.
every	How many units between runs. Read only by daily, weekly, monthly and yearly; sending it with any other repeats is refused.
daysOfWeek	monday to sunday. Read only by daily and weekly; sending it with any other repeats is refused.

For how the app presents these choices, see Create a Schedule. The placeholders in checklistNameFormat are covered in Auto Generated Values.

update_schedule

Changes a schedule. Send only what should change; sending nothing is refused. The template cannot be changed.

recurrence is replaced whole rather than merged: {"repeats": "weekly"} on a schedule that ran every two days on Mondays and Fridays leaves it weekly, with every back to 1 and no days of the week. The description tells the model to read the schedule first and send the recurrence it wants in full. parameters are merged instead. A change to the start, the time zone, the recurrence, the name pattern or the active flag regenerates the pending runs, and the answer's runsRegenerated says whether that happened; the history of runs already produced is kept.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule's id, from list_schedules.
name	string	No	The new name. Cannot be cleared.
checklistNameFormat	string	No	The name pattern for future checklists, with the same placeholders as create_schedule. Send an empty string to go back to the template's name. Checklists already made keep their names.
timeZone	string	No	The new zone. On its own it keeps the wall-clock time and moves the instant: a 09:00 schedule moved from Europe/London to America/New_York still runs at 09:00. Send startDateTime too to change both.
startDateTime	string	No	A new first-run time, as a wall-clock time with no Z and no offset. The same rules as create_schedule.
recurrence	object	No	A new recurrence, replacing the old one entirely.
isActive	boolean	No	Whether to generate runs. Turning it off deletes the runs that have not happened; turning it back on generates a fresh series from now. Occurrences inside the off period are not made up.
parameters	array of objects	No	Parameter values to change, merged onto the stored ones. A parameter with a null value is removed and the template's default applies again. An empty list changes nothing.

• Returns: the Schedule object, with runsRegenerated.
• Annotations: idempotentHint true.
• REST equivalent: PATCH /v3/schedules/{id}.
• Example prompt: "Pause the monthly Invoice Review schedule."

delete_schedule

Deletes a schedule and the runs it has not produced yet. Checklists it has already made stay, including one created minutes ago for a run that was just due. To stop a schedule without losing it, update_schedule with isActive false is the reversible alternative.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule's id, from list_schedules.

• Returns: nothing.
• Annotations: destructiveHint true, idempotentHint true.
• REST equivalent: DELETE /v3/schedules/{id}.
• Example prompt: "Delete the weekly Supplier Onboarding schedule — we don't need it any more."

list_schedule_runs

Lists one schedule's runs, oldest first, because a run series is a calendar. status is derived: created has a checklist, pending is due in the future and has none, and missed is due in the past and has none. A run is missed when the template was archived, when the workspace's subscription had lapsed when it was due, or when the job failed — and nothing else in the product reports those, so status missed is the way to ask. A run a few minutes overdue also reads as missed while the job is on its way to it.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule, from list_schedules.
status	string	No	pending, created or missed. Omit for all three.
from	string	No	Only runs due at or after this wall-clock time in the schedule's zone, such as 2026-03-01T00:00:00.
to	string	No	Only runs due at or before this time, in the same form as from.
sort	string	No	field, field:asc or field:desc, where field is scheduledDateTime, checklistName, startedDateTime or completedDateTime. Default scheduledDateTime:asc. There is no status sort.
after	string	No	The nextCursor from the previous page. Send the same filters with it.
pageSize	integer	No	Results per page, 1 to 100. Default 50.

• Returns: the standard list envelope holding Run objects, each with id, scheduleId, status, checklistName, scheduledDateTime, scheduledDateTimeUtc, timeZone and, once it exists, checklist, startedDateTime and completedDateTime.
• Annotations: readOnlyHint true, idempotentHint true.
• REST equivalent: GET /v3/schedules/{id}/runs.
• Example prompt: "Has the Invoice Review schedule missed any runs this year?"

get_schedule_run

Returns one run: when it is due, what its checklist will be called, and the checklist once there is one. checklistName is settled when the series is written, not when the checklist is made. If somebody renamed the checklist, checklistName and checklist.name disagree — and that difference is the only record of the rename.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule the run belongs to.
runId	integer	Yes	The run's id, from list_schedule_runs. Not the checklist's key.

• Returns: a Run object.
• Annotations: readOnlyHint true, idempotentHint true.
• REST equivalent: GET /v3/schedules/{id}/runs/{runId}.
• Example prompt: "What will next Monday's scheduled checklist be called?"

delete_schedule_run

Skips one occurrence of a schedule — the only way to do so. The skip lasts until somebody changes the schedule's timing, which rebuilds the pending series and brings the occurrence back. A run that has already produced a checklist is refused: deleting the row would not delete the checklist, only the record of where it came from. Deleting the checklist removes the run with it.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule the run belongs to.
runId	integer	Yes	The run to skip, from list_schedule_runs.

• Returns: nothing.
• Annotations: destructiveHint true, idempotentHint true.
• REST equivalent: DELETE /v3/schedules/{id}/runs/{runId}.
• Example prompt: "Skip the Invoice Review run due on 25 December 2026."

create_schedule_run_checklist

Starts a run's checklist now, ahead of its time. The checklist starts with the schedule's parameter values, the same ones the scheduling job would have used, and starts now, while the run keeps the time it was originally due. The tool names a state rather than an act: a run that already has a checklist answers with that checklist and changes nothing, and checklistCreated says which happened. Nobody is notified.

Name	Type	Required	Description
scheduleId	integer	Yes	The schedule the run belongs to.
runId	integer	Yes	The run to start, from list_schedule_runs.

• Returns: the Run object with its checklist and checklistCreated.
• Annotations: destructiveHint false, idempotentHint true.
• REST equivalent: POST /v3/schedules/{id}/runs/{runId}/checklist.
• Example prompt: "Start next month's Invoice Review checklist now — we're closing the books early."

Related Pages

• Schedules — the REST routes behind these tools, with the full Schedule and Schedule Run objects.
• Managing Schedules — how schedules look and behave in the app.
• Template Authoring Tools — list_templates and get_template, where a schedule's template key and parameters come from.
• Checklist Tools — working with the checklists a schedule starts.