Checklist Tools

These tools cover a Checklist as a whole: finding one, reading it with its history and the tasks attached to it, starting one from a template, renaming, completing, archiving or deleting it, tagging it and managing its public link. The work inside a checklist — completing tasks, answering fields, assigning people — is on Checklist Task Tools.

Each tool is the MCP counterpart of a route on the Checklists REST page and calls the same handler, so a tool and its route give the same answer, apply the same permission checks and refuse in the same words. Every call acts as the member the API key acts as, and the permission checks listed at the top of the Checklists REST page apply in the same way.

How These Tools Behave

• Keys are strings holding a GUID. A malformed key is refused with VALIDATION_ERROR, naming the argument you sent (for example checklistKey) rather than the REST route's parameter name.
• Dates are ISO 8601 instants in UTC, for example 2026-10-30T17:00:00Z.
• Results carry the same JSON as the REST response — camelCase, properties with no value omitted, a Z on every timestamp — in structuredContent and again as text. A tool whose route answers 204 No Content returns {"result":null}.
• Refusals come back as an ordinary tool result with isError set, carrying the v3 error body in structuredContent. The text block starts with the error code and message and ends with the requestId. See Errors for the codes and How It Works for the result format.
• idempotencyKey is accepted by the write tools that list it. Sending the same key with the same arguments within 24 hours returns the first call's answer instead of repeating the work, marked with checkflow.io/idempotentReplay in the result's _meta. The same key with different arguments, or while the first call is still running, is refused with CONFLICT. Keys are at most 255 characters. See Idempotency.
• Annotations are the hints each tool publishes to the client. A hint a tool does not declare is left out, and the client falls back to the MCP defaults: a tool with no readOnlyHint is assumed to write, one with no destructiveHint is assumed to be potentially destructive and one with no idempotentHint is assumed not to be safe to repeat.

Tools

Tool	What it does	Read/Write
list_checklists	Lists checklists, optionally for one template or status	Read
search_checklists	Finds a template's checklists by the values filled in on them	Read
get_checklist	Reads one checklist in full	Read
get_checklist_activity	Reads a checklist's activity feed	Read
list_attached_tasks	Lists the standalone tasks attached to a checklist	Read
create_checklist	Starts a checklist from a template	Write
update_checklist	Changes a checklist's name, status or due date	Write
delete_checklist	Deletes a checklist permanently	Write
set_checklist_archived	Archives or unarchives a checklist	Write
set_checklist_complete	Marks a checklist complete or reopens it	Write
add_checklist_tags	Adds tags to a checklist	Write
remove_checklist_tag	Removes one tag from a checklist	Write
get_checklist_share	Reads a checklist's public link settings	Read
set_checklist_share	Creates or replaces a checklist's public link settings	Write
stop_sharing_checklist	Takes a checklist's public link down	Write

list_checklists

Lists the workspace's checklists, most recently started first. Archived checklists are left out unless includeArchived is true, and checklists run from an archived template are never listed.

The list is read as the acting member and shows only what their template permissions allow. A template they have no permission on does not appear at all, so an empty list can mean either that nothing matched or that nothing is visible to them. To page, send the nextCursor from the previous reply with every other argument unchanged.

Name	Type	Required	Description
templateKey	string (GUID)	No	Only checklists made from this template.
status	string	No	One of All (default), Scheduled, InProgress, RecentlyComplete, Complete. Case is ignored. The first three are the values a checklist's own status reads back as; All and RecentlyComplete are ways of asking rather than states.
sort	string	No	field, field:asc or field:desc, where the field is one of name, scheduledDate, startDate, endDate. Default startDate:desc.
after	string	No	The nextCursor from the previous reply. A cursor used with different filters or a different sort is refused.
pageSize	integer	No	Results per page, 1–100. Default 50. A value outside the range is not refused; the default of 50 is used instead.
includeArchived	boolean	No	Include archived checklists. Default false.

• Returns: a page of Checklist objects — items, nextCursor, hasMore and total. See Pagination.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/checklists.
• Example prompt: "Which Invoice Review checklists are still in progress?"

search_checklists

Finds the checklists of one template by what has been filled in on them — "the checklist where Customer is Acme". A template key and at least one field condition are required, and every condition must hold.

Name a field by its key or its label. A label that names more than one field is refused, and the refusal lists the keys to choose between. Values match as text, case-insensitively. Only field types that appear in reporting can be searched — Short Text, Long Text, E-Mail, Website, Date & Time, File Upload, Dropdown, Multi-Choice, Sub-Tasks and Members — and a condition on any other type is refused rather than matching nothing.

Field values are projected for searching by a background job, so a value written seconds ago may not be findable yet. To confirm a write you just made, read the checklist back with get_checklist.

Name	Type	Required	Description
templateKey	string (GUID)	Yes	The template whose checklists to search.
fields	array of objects	Yes	The conditions, all of which must hold. Each is { field, value, match }: field is a field's key or label, value is the text to match, and match is equals (the default) or contains.
status	string	No	As on list_checklists: All, Scheduled, InProgress, RecentlyComplete or Complete.
sort	string	No	As on list_checklists: name, scheduledDate, startDate or endDate, optionally with :asc or :desc.
after	string	No	The nextCursor from the previous reply. Repeat every other argument unchanged alongside it.
pageSize	integer	No	Results per page, 1–100. Default 50.
includeArchived	boolean	No	Include archived checklists. Default false. Checklists of an archived template are never returned.

• Returns: a page of Checklist objects, as list_checklists does.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: POST /v3/checklists/search.
• Example prompt: "Find the Supplier Onboarding checklist where Supplier Name is Northwind Components."

get_checklist

Reads one checklist in full: its tasks with their field values, its parameters and its tags.

status is Scheduled, InProgress or Complete, read off the checklist's dates. Complete means somebody marked the checklist finished, which is allowed while work is still outstanding. Whether the work is actually finished is allTasksComplete, which only this tool reports. Tasks attached to the checklist by hand are not included — use list_attached_tasks for those.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.

• Returns: the Checklist Detail object — the Checklist object plus dueDate, allTasksComplete, tags, parameters and tasks.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/checklists/{key}.
• Example prompt: "Show me everything on Invoice Review — INV-2041 and tell me what's still outstanding."

get_checklist_activity

Reads what has happened on a checklist, most recent first — who did what, and when. Each entry carries a readable description with the task and field names already filled in, plus taskKey and fieldKey for entries about a particular task or field. There is no event type: activity is recorded as prose, so those two keys are the structured part. Names are resolved when the feed is read, so a renamed task appears under its current name throughout its history.

Most entries are written a second or two after the event, so this is not the way to confirm a write you have just made — the reply to the write is.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
sort	string	No	occurredAt, occurredAt:asc or occurredAt:desc. Default occurredAt:desc.
after	string	No	The nextCursor from the previous reply.
pageSize	integer	No	Entries per page, 1–100. Default 50. Changing it while paging is safe, because the cursor resumes from an entry rather than a row number.

• Returns: a page of Activity Entry objects, each with occurredAt, actor (name, email), description and, where they apply, taskKey, taskName, fieldKey, fieldName and dateTimeValue.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/checklists/{key}/activity.
• Example prompt: "Who changed the approval amount on Invoice Review — INV-2041, and when?"

list_attached_tasks

Lists the tasks attached to a checklist — the ones somebody raised against it, rather than the steps its template defines — oldest first. This is the one part of a checklist that get_checklist does not report.

The list takes no filters and no paging: it belongs to the checklist, does not depend on who asks, and is bounded by how many tasks were attached. isAssignedExclusively is reported, not applied — when it is true, only the people in assignees may open or complete the task. Each attached task is a standalone task and is read and changed with the Standalone Task Tools, under the same key.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.

• Returns: { "tasks": [...] }, where each task is an Attached Task object with key, name, status, dueDateTime, completedDateTime, completedBy, notApplicableDateTime, notApplicableBy, createdDateTime, createdBy, assignees, isAssignedExclusively and url (properties with no value are omitted).
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/checklists/{key}/attached-tasks.
• Example prompt: "Has anyone raised extra tasks against Invoice Review — INV-2041?"

create_checklist

Starts a checklist from a template. The template's tasks and fields are copied onto it from the template's current version, and the checklist stays on that version for its whole life. You can set template parameters here; any you do not name keep the template's default.

The reply is the full checklist, including the key of every task — which is what the task tools need next.

Name	Type	Required	Description
templateKey	string (GUID)	Yes	The template to run, from list_templates.
name	string	Yes	The checklist's name.
referenceId	string	No	Your own identifier for this checklist, carried on it and reported back. Free text; it is not interpreted and need not be unique.
parameters	array of objects	No	Parameter values to start with, as { key, value }, where key is the parameter's key or its name. A parameter you do not name keeps the template's default, and a name matching no parameter is ignored rather than refused.
idempotencyKey	string	No	Send the same key again to retry this call safely. Use a new key for each new checklist.

• Returns: the full checklist, as get_checklist returns it.
• Annotations: destructiveHint: false.
• REST equivalent: POST /v3/checklists.
• Example prompt: "Start an Invoice Review checklist for INV-2041 and set the Approver parameter to Sarah Chen."

update_checklist

Changes a checklist's name, status or due date. Send only what you mean to change: an argument you leave out is left alone, and naming none of the three is refused.

status accepts Complete or InProgress. Scheduled (a start date that has not arrived) and RecentlyComplete (a window of time) are not states you can set. A checklist has no due date of its own, so a due date is written onto the work still outstanding on it; tasks whose due date the template calculates from a rule are left to the rule. Asking for the state the checklist is already in changes nothing and notifies nobody.

On the REST route, a property sent as null is cleared and an omitted one is left alone. A tool call cannot tell an omitted argument from a null one, so this tool uses clearDueDate to remove the due date instead.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
name	string	No	A new name. Blank is refused.
status	string	No	Complete or InProgress.
dueDate	string (date-time)	No	A new due date, as an ISO 8601 instant in UTC.
clearDueDate	boolean	No	Remove the due date. Default false; ignored unless true. Sending it together with dueDate is refused.

• Returns: the full checklist, as get_checklist returns it.
• Annotations: idempotentHint: true.
• REST equivalent: PATCH /v3/checklists/{key}.
• Example prompt: "Rename INV-2041's checklist to Invoice Review — INV-2041 (Disputed) and make it due on 30 October."

delete_checklist

Deletes a checklist with its tasks and the comments, field values, files and tags they hold. Any Linked Checklist control pointing at this checklist is unlinked first, and tasks attached to it survive as unattached standalone tasks.

danger

Deleting a checklist cannot be undone. To hide a checklist while keeping it, archive it with set_checklist_archived instead — the tool's description tells the model this is almost always what was meant.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.

• Returns: nothing — {"result":null}.
• Annotations: destructiveHint: true, idempotentHint: true.
• REST equivalent: DELETE /v3/checklists/{key}.
• Example prompt: "Delete the duplicate Invoice Review — INV-2041 checklist I created by mistake this morning."

set_checklist_archived

Archives a checklist or takes it back out of the archive. An archived checklist is left out of list_checklists unless includeArchived is true, and out of the Tasks grid, analytics and its template's listings. Its tasks, comments and field values stay exactly as they are.

Only workspace Administrators can do this. Archiving hides a checklist from everyone, so unlike renaming or completing it is not governed by the per-checklist run permission, and a connection whose key acts as the workspace rather than a member is refused. Asking for the state the checklist is already in succeeds and changes nothing.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
isArchived	boolean	Yes	True to archive it, false to bring it back.

• Returns: the Checklist object, with isArchived as requested.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/checklists/{key}/archive to archive, DELETE /v3/checklists/{key}/archive to unarchive.
• Example prompt: "Archive the Employee Onboarding — Priya Patel checklist."

set_checklist_complete

Marks a checklist finished or reopens it, notifying everyone assigned to it either way. This does not complete or reopen the checklist's tasks: a checklist can be closed with work still outstanding, and a reopened one can come back with every task still done. That is why the reply reports isComplete and allTasksComplete separately — read both rather than inferring one from the other. Asking for the state the checklist is already in succeeds, writes nothing and notifies nobody.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
isComplete	boolean	Yes	True to mark it finished, false to put it back in progress.

• Returns: the Completion object — key, name, url, isComplete, endDateTime and allTasksComplete.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/checklists/{key}/complete to complete, DELETE /v3/checklists/{key}/complete to reopen.
• Example prompt: "Mark Invoice Review — INV-2041 as complete even though the filing task is still open."

add_checklist_tags

Adds one or more tags to a checklist, by name. A name the workspace has not used before creates the tag — there is no separate step for creating one — so a misspelling does not fail; it adds a new tag. The reply's created array is the only way to tell that happened, which is why the tool's description tells the model to read list_tags first and reuse an existing name.

Matching is case-insensitive, so Urgent and urgent are one tag. Naming a tag the checklist already carries succeeds and writes nothing.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
tags	array of strings	Yes	The names to add. At least 1, at most 25, each at most 100 characters.

• Returns: tags (every tag now on the checklist, ordered by name) and created (the names this call added to the workspace for the first time; empty when every name already existed).
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/checklists/{key}/tags.
• Example prompt: "Tag Invoice Review — INV-2041 as urgent and q3-audit."

remove_checklist_tag

Removes one tag from a checklist, by name, matched case-insensitively. Removing a tag the checklist does not carry succeeds and writes nothing. If that was the tag's last use anywhere in the workspace, the tag itself is deleted and the reply says so in tagDeleted — tags are created by being used and removed when they stop being used.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
tagName	string	Yes	The tag to remove.

• Returns: tags (every tag now on the checklist) and tagDeleted.
• Annotations: destructiveHint: true, idempotentHint: true.
• REST equivalent: DELETE /v3/checklists/{key}/tags?name=….
• Example prompt: "Take the urgent tag off Invoice Review — INV-2041."

get_checklist_share

Reads whether a checklist has a public link and the conditions on it: the link and its key, whether a password is required, when it expires and whether it already has, whether it closes once the checklist is complete and whether visitors may only read it. The password itself is never returned — it is stored as a hash, and setting a new one is the only way to recover from losing it.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.

• Returns: the Share object — isShared, sharedKey, sharedUrl, isPasswordProtected, expiresAt, isExpired, expireOnceComplete and isReadOnly.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/checklists/{key}/share.
• Example prompt: "Is Invoice Review — INV-2041 shared publicly, and when does the link expire?"

set_checklist_share

Gives a checklist a public link, or changes the conditions on one it already has. Anyone holding the returned URL can open the checklist without signing in, subject only to the password and expiry set here — the tool's description tells the model to check with you before calling it.

The arguments describe the whole shared state, not a change to it: any argument you leave out is set to its default, so calling this with only the key shares the checklist with no password, no expiry and no restrictions. It works this way because the password is stored as a hash, so there is no value that could mean "keep the current password". The link's key survives every change made here; stopping sharing and then sharing again is the only way to invalidate a link already handed out.

Refused when the checklist's template has sharing and embedding turned off.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.
password	string	No	A password visitors must enter. Omit for no password.
expiresAt	string (date-time)	No	When the link stops working, as an ISO 8601 instant in UTC. Omit for no expiry.
expireOnceComplete	boolean	No	Close the link once the checklist is complete. Default false.
isReadOnly	boolean	No	Visitors may read the checklist but not fill it in. Default false.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: the checklist's shared state, as get_checklist_share returns it, including the sharedUrl to hand out.
• Annotations: none declared.
• REST equivalent: PUT /v3/checklists/{key}/share.
• Example prompt: "Share Invoice Review — INV-2041 with our auditor as read-only, with a password, until 31 October."

stop_sharing_checklist

Takes a checklist's public link down. The link stops working immediately, and the password, the expiry and both flags go with it — sharing the checklist again starts from the defaults with a new key. A checklist that is not shared succeeds and writes nothing.

This works even when the template has sharing and embedding turned off, so that turning that setting off can never leave a live link with no way to remove it.

Name	Type	Required	Description
checklistKey	string (GUID)	Yes	The checklist's key.

• Returns: the checklist's shared state after the change, as get_checklist_share returns it.
• Annotations: destructiveHint: true, idempotentHint: true.
• REST equivalent: DELETE /v3/checklists/{key}/share.
• Example prompt: "Take down the public link on Invoice Review — INV-2041."

Related Pages

• Checklists API — the REST routes behind these tools, with full object definitions and example responses.
• Checklist Task Tools — completing, assigning and filling in the tasks inside a checklist once you have its task keys.
• Workspace, People and Tasks Grid Tools — reading tag names before tagging, and finding outstanding work across every checklist.
• Share a Checklist — what a visitor sees when they open a checklist's public link.