Standalone Task Tools

These tools work on standalone tasks — tasks that belong to no template. A standalone task can hang off nothing at all, or be attached to a checklist, in which case the checklist cannot complete until the task is done or ruled out. raise_task is the way a model puts a new piece of work into a workspace when no checklist covers it.

Each tool is the MCP counterpart of a route on the Standalone Tasks REST page and calls the same handler, so a tool and its route give the same answer and refuse in the same words.

The tool names spell out standalone because a checklist task and a standalone task are different resources. A checklist task's key sent to one of these tools is reported as not found; read a checklist task with get_task instead. The tasks a list_my_work row marks with isStandalone: true, and the ones list_attached_tasks returns, are the ones these tools take.

How These Tools Behave

• Keys are strings holding a GUID. A malformed key is refused with VALIDATION_ERROR, naming the argument you sent (taskKey or itemKey).
• 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 and How It Works.
• idempotencyKey is accepted by the write tools that list it. The same key with the same arguments within 24 hours returns the first call's answer, 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: no readOnlyHint means the tool is assumed to write, no destructiveHint means it is assumed to be potentially destructive and no idempotentHint means it is assumed not to be safe to repeat.
• Assignee and mention arguments name a person or group either as { type, id } — type being TeamMember or Group — or as { name }, where the name is a member's full name, a member's email address or a group's name. Ids come from list_members and list_groups.

Tools

Tool	What it does	Read/Write
raise_task	Raises a new standalone task	Write
get_standalone_task	Reads one standalone task	Read
update_standalone_task	Changes a task's name, description, attachment, due date or assignees	Write
delete_standalone_task	Deletes a standalone task permanently	Write
complete_standalone_task	Completes a standalone task	Write
uncomplete_standalone_task	Returns a completed task to incomplete	Write
set_standalone_task_not_applicable	Rules a task out as not applicable	Write
clear_standalone_task_not_applicable	Brings a ruled-out task back	Write
get_standalone_task_activity	Reads a task's activity feed	Read
add_standalone_task_tags	Adds tags to a task	Write
remove_standalone_task_tag	Removes one tag from a task	Write
get_standalone_task_comments	Reads a task's comments	Read
add_standalone_task_comment	Adds a comment to a task	Write
remove_standalone_task_comment	Deletes a comment from a task	Write
get_standalone_task_files	Lists a task's files	Read
remove_standalone_task_file	Deletes a file from a task	Write
get_standalone_task_sub_tasks	Reads a task's sub-tasks	Read
add_standalone_task_sub_tasks	Appends sub-tasks to a task	Write
update_standalone_task_sub_task	Rewords or moves a sub-task	Write
remove_standalone_task_sub_task	Removes a sub-task	Write
complete_standalone_task_sub_task	Ticks a sub-task	Write
uncomplete_standalone_task_sub_task	Unticks a sub-task	Write
get_standalone_task_snooze	Reads the acting member's snooze on a task	Read
set_standalone_task_snooze	Snoozes a task for the acting member	Write
end_standalone_task_snooze	Ends the acting member's snooze on a task	Write

raise_task

Raises a task that belongs to no template. You can attach it to a checklist, which makes the checklist wait for it before it can complete — that is how a task raised while working through a checklist stays with the work it came from — or leave it hanging off nothing.

Everyone assigned is notified. Tags can be set here and nowhere else on the task itself: update_standalone_task does not touch tags, so after this they are managed with add_standalone_task_tags and remove_standalone_task_tag.

This is not idempotent: calling it twice raises two tasks. Use idempotencyKey if you may need to retry.

Name	Type	Required	Description
name	string	Yes	What the task is. Blank is refused.
description	string	No	More about the task, shown under the name. Plain text.
attachedChecklistKey	string (GUID)	No	A checklist in this workspace to attach the task to. The checklist will not complete until the task is done or ruled out.
dueDateTime	string (date-time)	No	When the task is due, in UTC.
assignees	array of objects	No	Who the task is for, each { type, id } or { name }. Everyone named is notified by email and Slack. Omit to raise it unassigned.
tags	array of strings	No	Tags to put on it, 1 to 25. A name the workspace has not used before creates the tag.
idempotencyKey	string	No	Send the same key again to retry this call safely. Use a new key for each new task.

• Returns: the Standalone Task object — key, name, description, attachedChecklistKey, dueDateTime, status, isComplete, isNotApplicable, assignees, isAssignedExclusively, createdBy and tags, plus the completion and not-applicable stamps once they apply.
• Annotations: destructiveHint: false.
• REST equivalent: POST /v3/tasks.
• Example prompt: "Raise a task on Invoice Review — INV-2041 for James Okafor to chase the missing delivery note by Thursday, tagged urgent."

get_standalone_task

Reads one standalone task: what it is, its description, when it is due, who it is for, whether it is done, which checklist it is attached to (if any) and its tags. Comments, files and sub-tasks are not included — each has a tool of its own.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the standalone task, as raise_task returns it.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}.
• Example prompt: "What's the status of the delivery note task I raised for James?"

update_standalone_task

Changes a standalone task's name, description, attachment, due date or assignees. Send only what you mean to change; anything left out stays exactly as it is, and naming none of the five is refused. The member the connection acts as must be the person who raised the task or a workspace Administrator.

On the REST route, a property sent as null is cleared and an omitted one is left alone. A tool call cannot tell those two apart, so this tool spells out clearing:

• Send an empty string for description to remove it, or for attachedChecklistKey to detach the task from its checklist.
• Set clearDueDate to remove the due date, since a date argument has no empty value.
• assignees replaces everyone on the task, so an empty list unassigns it. There is no add or remove.

Tags are not changed here — use add_standalone_task_tags and remove_standalone_task_tag.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
name	string	No	A new name. Blank is refused.
description	string	No	New description. An empty string removes it.
attachedChecklistKey	string (GUID)	No	The checklist to attach the task to. An empty string detaches it, which lets a checklist waiting on this task complete.
dueDateTime	string (date-time)	No	A new due date, in UTC.
clearDueDate	boolean	No	Remove the due date. Default false; ignored unless true. Sending it together with dueDateTime is refused.
assignees	array of objects	No	Everyone the task is for, replacing the current assignees, each { type, id } or { name }. An empty list unassigns it.

• Returns: the standalone task after the change.
• Annotations: idempotentHint: true.
• REST equivalent: PATCH /v3/tasks/{taskKey}.
• Example prompt: "Move the delivery note task's due date to next Monday and give it to Priya Patel instead."

delete_standalone_task

Deletes a standalone task with its comments, files, sub-tasks and tags. There is no archive for standalone tasks. Whoever raised the task can delete it, and so can a workspace Administrator; nobody else can. A checklist that was waiting on the task has its completion settled afterwards, so deleting the last outstanding task can be what completes a checklist. A key that names nothing is reported as missing.

danger

Deleting a standalone task cannot be undone.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: nothing — {"result":null}.
• Annotations: destructiveHint: true, idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}.
• Example prompt: "Delete the duplicate delivery note task — I raised it twice."

complete_standalone_task

Marks a standalone task done. A task whose sub-tasks are not all ticked is refused, because its Sub-Tasks control is required — tick them first with complete_standalone_task_sub_task. A checklist the task is attached to may complete itself if this was the last thing outstanding on it. Asking for the state the task is already in changes nothing and notifies nobody.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the standalone task after the change.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/tasks/{taskKey}/complete.
• Example prompt: "Mark the delivery note task as done."

uncomplete_standalone_task

Returns a completed standalone task to incomplete. This means "not complete", not "back to the beginning": a task marked not applicable is left exactly as it is, because clear_standalone_task_not_applicable is what clears that state. A checklist that completed because this task did may reopen.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the standalone task after the change.
• Annotations: idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/complete.
• Example prompt: "Reopen the delivery note task — the note we received was for a different order."

set_standalone_task_not_applicable

Rules a standalone task out: it did not need doing. The task is recorded as skipped rather than done, with who ruled it out and when, and a checklist waiting on it stops waiting. The tool's description tells the model to use this rather than completing something that was never done, so the history says what actually happened.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the standalone task after the change, with notApplicableDateTime and notApplicableBy.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/tasks/{taskKey}/not-applicable.
• Example prompt: "The supplier sent the delivery note directly, so mark the chase task as not applicable."

clear_standalone_task_not_applicable

Brings a ruled-out standalone task back into play. A completed task is left complete — uncomplete_standalone_task is what undoes a completion.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the standalone task after the change.
• Annotations: idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/not-applicable.
• Example prompt: "We do need the delivery note after all — bring the chase task back."

get_standalone_task_activity

Reads what has happened to one standalone task, most recent first — the same feed, in the same shape, as a checklist task's history. Entries are prose with the names already filled in, so a renamed task reads under its current name throughout its history. 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
taskKey	string (GUID)	Yes	The task'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.

• Returns: a page of activity entries — items, nextCursor, hasMore — each with occurredAt, actor, description and, where they apply, taskKey, taskName, fieldKey, fieldName and dateTimeValue.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}/activity.
• Example prompt: "Who reassigned the delivery note task, and when?"

add_standalone_task_tags

Adds one or more tags to a standalone task. A name the workspace has not used before creates the tag, so the tool's description tells the model to check what exists first with list_tags. Matching is case-insensitive, so Urgent and urgent are one tag. Tags the task already has are not added twice.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
tags	array of strings	Yes	The tag names, 1 to 25 of them.

• Returns: tags (every tag now on the task, ordered by name) and created (names this call added to the workspace for the first time).
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/tasks/{taskKey}/tags.
• Example prompt: "Tag the delivery note task with q3-audit."

remove_standalone_task_tag

Removes one tag from a standalone task, by name. Removing a tag the task does not have succeeds and writes nothing. A tag that no task or checklist carries any more is removed from the workspace, so this can be the call that deletes the tag itself.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
name	string	Yes	The tag's name. Case-insensitive.

• Returns: tags (every tag now on the task) and tagDeleted.
• Annotations: idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/tags?name=….
• Example prompt: "Take the urgent tag off the delivery note task."

get_standalone_task_comments

Reads the comments on a standalone task, oldest first, with who wrote each one, when, and any attachment. Unlike a checklist task, a standalone task's read does not include its comments, so this is the only way to see them. The ids in the reply are what remove_standalone_task_comment takes.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: { "comments": [...] }, each with id, text, html, createdBy, createdDateTime, mentions and any attachment.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}/comments.
• Example prompt: "What has James said on the delivery note task?"

add_standalone_task_comment

Comments on a standalone task, attributed to the member the connection acts for. Send text unless you genuinely have markup: text is escaped and wrapped into paragraphs, so a blank line starts a new paragraph and anything that looks like a tag is shown rather than interpreted.

Mention people with mentions rather than typing an @ into the text — naming somebody in mentions composes the mention markup for you. Everyone mentioned is notified by email and Slack. A comment with no text and no mentions is refused.

This is not idempotent: calling it twice posts the comment twice. Use idempotencyKey if you may need to retry.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
text	string	No	The comment as plain text. Give this or html, not both.
html	string	No	The comment as HTML. Run through an allow-list — paragraphs, breaks, headings, lists, tables, inline emphasis and links to http, https or mailto. Anything else is dropped, keeping the text inside it.
mentions	array of objects	No	People and groups to mention, each { type, id } or { name }.
assignMentioned	boolean	No	Whether mentioning somebody on an exclusively assigned task also assigns them, so they can open it. True when omitted. Set it false when reporting rather than asking.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: comment (the new comment) and assignedMentioned — anyone this comment added to the task's assignees.
• Annotations: destructiveHint: false.
• REST equivalent: POST /v3/tasks/{taskKey}/comments.
• Example prompt: "Comment on the delivery note task and mention Priya Patel to say the supplier has been chased."

remove_standalone_task_comment

Deletes one comment from a standalone task, with its attachment. Nobody is told. Only the comment's author or a workspace Administrator can remove it — having raised the task does not grant this. The id comes from get_standalone_task_comments; a comment that is already gone, or that is on a different task, is reported as missing.

danger

Deleting a comment cannot be undone.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
commentId	integer	Yes	The comment's id, from get_standalone_task_comments.

• Returns: nothing — {"result":null}.
• Annotations: idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/comments/{commentId}.
• Example prompt: "Delete my last comment on the delivery note task."

get_standalone_task_files

Lists the files attached to a standalone task, with who uploaded each and a URL to download it. There is no field key, because a standalone task has exactly one place for files. A task with no files returns an empty list. The URLs are not behind the API key — the address itself is the secret — so treat one as a credential.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: { "files": [...] }, each with id, name, contentType, url, description, uploadedDateTime and uploadedBy.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}/files.
• Example prompt: "Which files are on the delivery note task?"

remove_standalone_task_file

Removes one file from a standalone task and deletes the stored file. The id comes from get_standalone_task_files; an id that is not on this task is reported as missing rather than acted on, because file ids are unique across the whole database and an id alone is not permission to delete anything.

There is no tool for uploading a file. The REST route takes the file base64-encoded, which through a tool call would pass up to 32 MB through the model's context window.

danger

Removing a file cannot be undone.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
fileId	integer	Yes	The file's id, from get_standalone_task_files.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: files (what remains on the task) and blobDeleted — true when the stored file was deleted, which is nearly always the case for a standalone task.
• Annotations: none declared.
• REST equivalent: DELETE /v3/tasks/{taskKey}/files/{fileId}.
• Example prompt: "Remove the blurry photo from the delivery note task."

get_standalone_task_sub_tasks

Reads the sub-tasks on a standalone task, in order, each with its key, wording, position and whether it is ticked. The tool's description tells the model to read this before completing a task that has sub-tasks: the control is required, so the task cannot be completed while an item is unticked, and this shows which. A task with no sub-tasks returns an empty list.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: the Sub-Tasks object — isRequired and items, each with key, text, isChecked and position.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}/sub-tasks.
• Example prompt: "What steps are left on the delivery note task?"

add_standalone_task_sub_tasks

Adds sub-tasks — the steps inside a task — to a standalone task. They are appended after any existing items, in the order given, so this cannot untick anything. Each item is trimmed, and refused if it is blank or longer than 2,000 characters. Adding the first item creates the Sub-Tasks control on a task that has never had one, which makes the task uncompletable until the item is ticked.

This is not idempotent: calling it twice adds the items twice. Use idempotencyKey if you may need to retry.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
items	array of strings	Yes	The wording of each sub-task, in the order they should appear.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: the whole list (isRequired and items) plus added — the items this call created.
• Annotations: destructiveHint: false.
• REST equivalent: POST /v3/tasks/{taskKey}/sub-tasks.
• Example prompt: "Add three steps to the delivery note task: email the supplier, call the warehouse, upload the note."

update_standalone_task_sub_task

Rewords a sub-task, moves it, or both. Give at least one of text and position; naming neither is refused. This cannot tick or untick anything, so correcting a typo never loses somebody's progress. A position outside the list is refused rather than clamped. Moving an item renumbers the rest, so the reply is the whole list.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
itemKey	string (GUID)	Yes	The sub-task's key, from get_standalone_task_sub_tasks.
text	string	No	New wording. Blank is refused; at most 2,000 characters.
position	integer	No	The zero-based place in the list the item should take.

• Returns: isRequired and items — the whole list after the change.
• Annotations: idempotentHint: true.
• REST equivalent: PATCH /v3/tasks/{taskKey}/sub-tasks/{itemKey}.
• Example prompt: "Move 'call the warehouse' to the top of the delivery note task's steps."

remove_standalone_task_sub_task

Removes one sub-task from a standalone task. The remaining items are renumbered so positions stay contiguous, which is why the reply is the whole list. Removing the last item removes the control, and the task then reads like one that never had sub-tasks — and can be completed.

danger

Removing a sub-task cannot be undone.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
itemKey	string (GUID)	Yes	The sub-task's key, from get_standalone_task_sub_tasks.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: isRequired and items — the whole list after the removal.
• Annotations: none declared.
• REST equivalent: DELETE /v3/tasks/{taskKey}/sub-tasks/{itemKey}.
• Example prompt: "Remove the 'call the warehouse' step from the delivery note task."

complete_standalone_task_sub_task

Ticks one sub-task. This is how a standalone task with sub-tasks becomes completable: complete_standalone_task is refused while any item is unticked. Ticking the last unticked item does not complete the task — the two are separate facts, so complete the task yourself afterwards. Ticking an item that is already ticked changes nothing and records nothing.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
itemKey	string (GUID)	Yes	The sub-task's key, from get_standalone_task_sub_tasks.

• Returns: isRequired and items — the whole list after the change.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/tasks/{taskKey}/sub-tasks/{itemKey}/complete.
• Example prompt: "Tick off 'email the supplier' on the delivery note task."

uncomplete_standalone_task_sub_task

Unticks one sub-task. This can make a task uncompletable again, and it leaves the task's own completion exactly as it is — the two are separate facts.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
itemKey	string (GUID)	Yes	The sub-task's key, from get_standalone_task_sub_tasks.

• Returns: isRequired and items — the whole list after the change.
• Annotations: idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/sub-tasks/{itemKey}/complete.
• Example prompt: "Untick 'upload the note' on the delivery note task — the upload failed."

get_standalone_task_snooze

Reads whether this standalone task is snoozed for the member the connection acts for, and until when. A snooze is personal: two connections acting for different members get different answers, and both are right — which is why it is not part of the task read.

Every snooze tool needs a key that acts as a member. A key that acts as the workspace is refused with API_KEY_ACTS_AS_WORKSPACE.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: isSnoozed and, when snoozed, snoozedUntil.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tasks/{taskKey}/snooze.
• Example prompt: "Is the delivery note task snoozed for me?"

set_standalone_task_snooze

Hides a standalone task from the acting member's own Tasks grid until a date. Nobody else sees any difference, nothing is recorded against the task, and its due date is unchanged. The date must be in the future. Sending the same date twice stores it again and announces nothing. Refused with API_KEY_ACTS_AS_WORKSPACE for a key that acts as the workspace.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.
snoozedUntil	string (date-time)	Yes	When the snooze runs out, in UTC. A null value does not clear a snooze — use end_standalone_task_snooze.

• Returns: isSnoozed and snoozedUntil.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: PUT /v3/tasks/{taskKey}/snooze.
• Example prompt: "Snooze the delivery note task until next Wednesday."

end_standalone_task_snooze

Brings a snoozed standalone task back into the acting member's Tasks grid now. A task that was not snoozed is left alone and the call still succeeds. Refused with API_KEY_ACTS_AS_WORKSPACE for a key that acts as the workspace.

Name	Type	Required	Description
taskKey	string (GUID)	Yes	The task's key.

• Returns: isSnoozed (false).
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: DELETE /v3/tasks/{taskKey}/snooze.
• Example prompt: "Unsnooze the delivery note task."

Routes Without a Tool

Route	Why there is no tool
GET /v3/tasks/{taskKey}/tags	get_standalone_task already returns the tags.
POST /v3/tasks/{taskKey}/files	The file is sent base64-encoded, which would pass up to 32 MB through the model's context.

Related Pages

• Standalone Tasks API — the REST routes behind these tools, with the full standalone task object and example responses.
• Attach a Task to a Checklist — how an attached task holds up its checklist's completion in the app.
• Checklist Task Tools — the tools for the tasks a template defines, which take a checklist key as well as a task key.
• Workspace, People and Tasks Grid Tools — finding standalone tasks across the workspace with list_my_work and snoozing several at once.