Workspace, People and Tasks Grid Tools

These tools are what a model needs before it starts working through a template, checklist and task — what the tags are called, who the people are — or instead of that entirely: what is outstanding across the whole workspace for the member the connection acts for. They mirror three REST pages: Tags, Team (members and groups) and My Work (the Tasks grid, bulk snooze and saved views). Each tool calls the same handler as its route, so a tool and its route give the same answer and refuse in the same words.

Names are not free text. Members, groups and tags are resolved against what the workspace actually contains, so the server's instructions tell a model to read them before sending one. list_tags, list_members and list_groups are where those names and ids come from; get_workspace_info returns the members, groups, tags and templates in one unpaged call, which suits a model about to write a template document.

list_my_work is the one tool that answers "what should I be doing" without being told where to look. An agent with no starting point starts there, and every row it returns is an address it can act on with the Checklist Task Tools or the Standalone Task Tools.

How These Tools Behave

• 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}, and a tool whose route answers with a bare array returns it wrapped as {"result":[...]}.
• 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.
• The Tasks grid tools — list_my_work, snooze_tasks, end_snooze_tasks and the four view tools — answer for a particular person, so they need a key that acts as a member. A key that acts as the workspace is refused with API_KEY_ACTS_AS_WORKSPACE. See Authentication.
• idempotencyKey is accepted by create_my_work_view. 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 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.

Tools

Tool	What it does	Read/Write
list_tags	Lists the workspace's tags with usage counts	Read
list_members	Lists the workspace's members	Read
get_member	Reads one member by id	Read
list_groups	Lists the workspace's groups	Read
get_group	Reads one group and its members	Read
list_my_work	Lists outstanding work across the workspace for the acting member	Read
snooze_tasks	Snoozes a set of tasks for the acting member	Write
end_snooze_tasks	Ends the acting member's snooze on a set of tasks	Write
list_my_work_views	Lists the saved Tasks grid views the acting member can see	Read
create_my_work_view	Saves a new Tasks grid view	Write
update_my_work_view	Replaces a saved view	Write
delete_my_work_view	Deletes a saved view	Write

list_tags

Lists every tag the workspace uses, with how many checklists, templates and tasks carry each one. The tool's description tells the model to read this before tagging anything: there is no separate step for creating a tag, so a name invented because it seemed reasonable does not fail — it adds a near-duplicate of a word already in use. The counts help avoid that; sort=usage:desc puts the most-used tags first.

Tags are names rather than keys, and a name from this list goes straight into add_checklist_tags, add_task_tags or add_standalone_task_tags. total is not the sum of the other three counts, because tags also sit on knowledge base articles and library files, which the API does not reach.

Name	Type	Required	Description
search	string	No	Match anywhere in the tag name, case-insensitively. No match is an empty list.
sort	string	No	field, field:asc or field:desc, where the field is name or usage (the total across everything). Default name:asc.
after	string	No	The nextCursor from the previous reply.
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.

• Returns: a page of Tag objects — items, nextCursor, hasMore, total — each with name, checklists, templates, tasks and total. See Pagination.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/tags.
• Example prompt: "Which tags do we use most? I want to tag this invoice consistently."

list_members

Lists the people in the workspace: the id and type every assignee and mention argument takes, plus name, email address, role and whether they are still active. Everyone listed can be assigned work and nobody who cannot is listed, so a name resolved against this list will not be refused later by an assignee argument.

Deactivated members are left out unless includeInactive is true — they are still worth looking up, because they wrote the comments and completed the tasks they did. The anonymous member each workspace has for unattributed work is never listed.

Name	Type	Required	Description
search	string	No	Match anywhere in the full name, either part of it, or the email address, case-insensitively.
role	string	No	One of Administrator, Member, Guest. Any other value is refused.
includeInactive	boolean	No	Include deactivated members. Default false.
sort	string	No	field, field:asc or field:desc, where the field is name or email. Default name:asc.
after	string	No	The nextCursor from the previous reply. Send every other argument unchanged alongside it.
pageSize	integer	No	Results per page, 1–100. Default 50.

• Returns: a page of Member objects, each with id, type, name, firstName, lastName, email, role and isActive. See Team.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/members.
• Example prompt: "Who are the Administrators in our workspace?"

get_member

Reads one member by id — the way to turn an id from a comment's mentions, a task's assignees or an activity entry into a name and email address without reading the whole directory. A deactivated member is returned with isActive false rather than refused.

Name	Type	Required	Description
memberId	integer	Yes	The member's id, as it appears on an assignee, a mention or list_members.

• Returns: the member — id, type, name, firstName, lastName, email, role and isActive.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/members/{id}.
• Example prompt: "Who is the person mentioned on that comment, and are they still active?"

list_groups

Lists the workspace's groups by name and id — the other half of what an assignee argument takes. Members are not included; the membership of the one group that matters is one get_group call away.

Name	Type	Required	Description
search	string	No	Match anywhere in the group name, case-insensitively.
sort	string	No	name, name:asc or name:desc. Default name:asc.
after	string	No	The nextCursor from the previous reply.
pageSize	integer	No	Results per page, 1–100. Default 50.

• Returns: a page of Group objects, each with id, type and name.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/groups.
• Example prompt: "What groups do we have in CheckFlow?"

get_group

Reads one group and who is in it. The membership is the same set list_members would show, so everyone named can be assigned work. Assigning a task to the group is not the same as assigning it to each of these people: a group assignment follows the group as people join and leave it.

Name	Type	Required	Description
groupId	integer	Yes	The group's id, as it appears on an assignee or list_groups.

• Returns: id, type, name and members — each member as list_members returns them.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/groups/{id}.
• Example prompt: "Who's in the Finance Team?"

list_my_work

Lists outstanding work across every checklist the acting member can see, plus standalone tasks — the Tasks grid as an API. It is the one read that finds tasks without being told which checklist to look in, so start here when the question is "what needs doing" rather than "what is on this checklist".

The answer belongs to whoever the connection acts for: that member decides which checklists are in scope, whose snoozes hide rows and whether isAssignedToActor is true. A key that acts as the workspace is refused with API_KEY_ACTS_AS_WORKSPACE rather than answered with an empty-looking grid. By default the list is that member's own open work, soonest due first; widen it with assignee=all and status=all.

Each row carries the address to act on. Use the Checklist Task Tools when isStandalone is false — with the row's key and checklist.key — and the Standalone Task Tools when it is true, because a task key is unique on its own only for a standalone task. canActorAccess false means the row is visible here but every write to it will be refused.

Name	Type	Required	Description
status	string	No	Comma-separated statuses: Incomplete, Complete, NotApplicable, DueToday, Overdue, Halted, DueInFuture, Snoozed — or all. These are the values a row's own status reads back as. Default is the four open ones: Incomplete, DueInFuture, DueToday, Overdue. An unknown status is refused. DueToday and DueInFuture are judged against the end of the day in the acting member's time zone, or the connection's X-CF-Timezone if it sends one.
assignee	string	No	Whose tasks: me (default), all, unassigned, TeamMember:<id>, Group:<id>, comma-separated. all cannot be combined with anything else. Widening this does not widen what the acting member is permitted to see.
template	string	No	Comma-separated template keys. Narrows the checklist tasks only — standalone tasks belong to no template and are governed by includeStandalone.
checklist	string	No	Comma-separated checklist keys.
includeStandalone	boolean	No	Include tasks that exist outside any checklist. Default true.
sort	string	No	field, field:asc or field:desc, where the field is one of dueDateTime, name, checklistName, templateName, commentCount. Default dueDateTime:asc. A task with no due date sorts last in both directions.
after	string	No	The nextCursor from the previous reply. Send the same filters, sort and pageSize alongside it; a cursor used with a different query, or by a different member, is refused.
pageSize	integer	No	Results per page, 1–100. Default 50. Use hasMore, not the page length, to decide whether to continue.

• Returns: a page of Work Item objects, each with key, name, status, isStandalone, assignees, isAssignedExclusively, isAssignedToActor, canActorAccess, tags, commentCount, url and, where they apply, dueDateTime, completedDateTime, notApplicableDateTime, snoozedUntilDateTime and checklist (its key, name, url and template). See My Work.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/my-work.
• Example prompt: "What's overdue for me or the Finance Team?"

snooze_tasks

Snoozes a set of tasks — hides them from the acting member's own Tasks grid until a date. The snooze is personal and invisible to everyone else: no activity is recorded, nothing is announced, and the tasks keep appearing on everyone else's grid. Use this rather than set_task_snooze when clearing several rows of a list at once.

The call is all or nothing: a reference that names nothing refuses the whole call, so a successful reply means every task named was snoozed. Name each task by the pair a list_my_work row gives you — its key and its checklist.key. A checklist copies its tasks' keys from its template, so one task key names a task in every checklist run from that template and is not an address on its own.

Name	Type	Required	Description
snoozedUntil	string (date-time)	Yes	When the snooze runs out, in UTC, for example 2026-11-02T08:00:00Z. Must be in the future. One date for the whole call.
tasks	array of objects	Yes	The tasks to snooze, at most 200. Each is { taskKey, checklistKey }; omit checklistKey only for a standalone task attached to no checklist. A heading is refused by name.

• Returns: the Snooze Result object — snoozedUntil and tasks, each with key, checklistKey, name, isStandalone and isSnoozed.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: POST /v3/my-work/snooze.
• Example prompt: "Snooze everything on my list that's due today until Monday morning."

end_snooze_tasks

Brings a set of snoozed tasks back into the acting member's Tasks grid now. A task that was not snoozed is left as it is and the call still succeeds, so a mixed selection needs no sorting first. Tasks are named as for snooze_tasks, and a reference that names nothing still refuses the whole call.

Name	Type	Required	Description
tasks	array of objects	Yes	The tasks to bring back, at most 200. Each is { taskKey, checklistKey }.

• Returns: tasks — each with key, checklistKey, name, isStandalone and isSnoozed.
• Annotations: destructiveHint: false, idempotentHint: true.
• REST equivalent: DELETE /v3/my-work/snooze.
• Example prompt: "Unsnooze all the Invoice Review tasks I snoozed last week."

list_my_work_views

Lists the saved Tasks grid views the acting member can see, each with everything it filters on. A view is a list_my_work query saved under a name, so its statuses, templates, assignees and sort can be sent straight to list_my_work to reproduce it. The five views the product ships come first and cannot be changed or deleted.

Two fields do not translate: search is applied by the app in the browser and has no list_my_work equivalent, and sort may name status, assignees or tags, which list_my_work cannot sort by. There is no tool for reading one view, because this one returns every view in full.

This tool takes no arguments.

• Returns: {"result":[...]} — an array of Saved View objects, each with key, name, type, isCore, isDefault, canEdit, createdBy, search, statuses, allTemplates, templates, includeStandalone, allAssignees, includeUnassigned, assignees, sort and visibleTo.
• Annotations: readOnlyHint: true, idempotentHint: true.
• REST equivalent: GET /v3/my-work/views. The single-view route, GET /v3/my-work/views/{viewKey}, has no tool.
• Example prompt: "Run my Finance Overdue view and tell me what's on it."

create_my_work_view

Saves a Tasks grid query under a name, so a person can pick it from the view list on their Tasks page. The arguments use list_my_work's vocabulary, so a filter that worked there can be saved here unchanged.

Anyone can save a Private view. Sharing a view with others — type Team or UsersGroups — requires the acting member to be a workspace Administrator. This is stricter than the app, deliberately: the other half of the app's rule is a permission this connection cannot see.

This is not idempotent: calling it twice saves two views with the same name. Use idempotencyKey if you may need to retry.

Name	Type	Required	Description
name	string	Yes	The view's name in the view picker. At most 200 characters.
type	string	No	Private (default), UsersGroups or Team. Core is refused.
search	string	No	Free text saved with the view, at most 1,000 characters. Stored and returned but applied by nothing in the API — the app filters on it in the browser.
statuses	array of strings	No	The statuses the view shows, by the names list_my_work takes. Omit for the four open ones. An empty list is refused.
allTemplates	boolean	No	True to show every template, including ones created after the view is saved. When omitted it follows templates: true when none are named, false when some are. True alongside a non-empty templates is refused.
templates	array of strings	No	Template keys to narrow the view to. Duplicates are dropped.
includeStandalone	boolean	No	Whether tasks outside any checklist are shown. Default true.
allAssignees	boolean	No	True to show everybody's tasks. Default false, which with an empty assignees means the member reading the view. True alongside a non-empty assignees is refused.
includeUnassigned	boolean	No	True to show tasks assigned to nobody. Default false.
assignees	array of objects	No	Whose tasks the view shows, each { type, id } or { name }. An ambiguous name is refused.
sort	string	No	field, field:asc or field:desc, where the field is one of name, status, dueDateTime, checklistName, templateName, assignees, commentCount, tags. Default dueDateTime:asc.
visibleTo	array of objects	No	Who the view is shared with, for a UsersGroups view only — sending it with any other type is refused. A group shares the view with whoever is in it when the views are listed.
idempotencyKey	string	No	Send the same key again to retry this call safely.

• Returns: the saved view, in the shape list_my_work_views returns.
• Annotations: destructiveHint: false.
• REST equivalent: POST /v3/my-work/views.
• Example prompt: "Save a view called Finance Overdue that shows overdue tasks assigned to the Finance Team, soonest first."

update_my_work_view

Replaces a saved view with a new definition under the same key. This is a replacement, not an amendment: every argument left out goes back to its default rather than keeping the view's current value, so read the view with list_my_work_views first and send back everything worth keeping. The write underneath deletes the view and writes it again, because its statuses, templates and assignees are stored as child rows with nothing an amendment could be addressed to.

The five views the product ships cannot be changed. A member can change the Private and UsersGroups views they created; an Administrator can change any saved view, and the view keeps its original author.

Name	Type	Required	Description
viewKey	string (GUID)	Yes	The view's key, from list_my_work_views. The five core views are not saved views and cannot be written to.
name	string	Yes	The view's name. At most 200 characters.
type	string	No	Private, UsersGroups or Team. Default Private.
search	string	No	Free text saved with the view, at most 1,000 characters.
statuses	array of strings	No	The statuses the view shows. Omit for the four open ones; an empty list is refused.
allTemplates	boolean	No	True to show every template. When omitted it follows templates.
templates	array of strings	No	Template keys to narrow the view to.
includeStandalone	boolean	No	Whether tasks outside any checklist are shown. Default true.
allAssignees	boolean	No	True to show everybody's tasks. Default false, which with an empty assignees means the member reading the view.
includeUnassigned	boolean	No	True to show tasks assigned to nobody. Default false.
assignees	array of objects	No	Whose tasks the view shows, each { type, id } or { name }.
sort	string	No	field, field:asc or field:desc. Default dueDateTime:asc.
visibleTo	array of objects	No	Who the view is shared with, for a UsersGroups view only.

• Returns: the saved view, in the shape list_my_work_views returns.
• Annotations: idempotentHint: true.
• REST equivalent: PUT /v3/my-work/views/{viewKey}.
• Example prompt: "Change my Finance Overdue view so it also shows tasks due today."

delete_my_work_view

Deletes a saved view. Nothing else refers to a view, so deleting one cannot affect any task. A member whose default view this was lands on My Open Tasks next time. The five views the product ships cannot be deleted, and a saved view somebody else created can only be deleted by an Administrator.

Name	Type	Required	Description
viewKey	string (GUID)	Yes	The view's key, from list_my_work_views.

• Returns: nothing — {"result":null}.
• Annotations: destructiveHint: true, idempotentHint: true.
• REST equivalent: DELETE /v3/my-work/views/{viewKey}.
• Example prompt: "Delete my old Q2 Invoices view."

Related Pages

• My Work API — the REST routes behind the Tasks grid, bulk snooze and saved view tools, with full row and view objects.
• Team API — the member and group objects in full, and how roles appear on them.
• The Tasks Grid — what a person sees in the app for the same query list_my_work answers.
• Checklist Task Tools — acting on a list_my_work row whose isStandalone is false.