MCP Tools: List Items

Last updated 1 day ago

MCP Tools: List Items ​

Tasks ("items") live inside lists. Assignments are stored in refs ({type:'user',id}) and are returned as assignees.

list_list_items ​

Filter items. read · follower

ParameterTypeDefaultDescription
listIdstring–Filter by list
parentstring–Only the direct children of this item. With state=open this gives the open sub-tasks of a task
descendantsbooleanfalseWith parent: the whole subtree instead of only direct children. Each item then carries its own parent
stateenum open | done | allallopen = not completed (status not done/completed)
statusstring–Exact status (e.g. todo). For "not finished", prefer state
prioritynumber (1–9)–Filter by priority
assigned_tostring–Filter by assigned user (refs, type=user)
assigned_to_meboolean–Only items assigned to me (no get_me needed)
tagstring–Exact tag
searchstring–Search in text and description
due_within_daysnumber–Due within N days (including overdue)
due_beforestring (ISO)–Due before a date
includeArchivedbooleanfalseInclude archived items
sortenum default | priority | due_date | created | modifieddefaultSort order
compactbooleanfalseCore fields + assignees only
limitnumber50Count
offsetnumber0Skip

Response: { items, total, limit, offset, has_more }.

get_list_item ​

A single item. read · follower

ParameterTypeDescription
itemIdstring (required)UUID or SID

create_list_item ​

Create a new item. write · user

ParameterTypeDescription
listIdstring (required)UUID or SID of the list
textstring (required)Title (min. 1 character)
descriptionstringDescription
statusstringStatus
prioritynumber (1–9)Priority (9 = urgent)
assigned_tostring[]Assigned user IDs
tagsstring[]Tags
target_datestring (ISO)Due date
parentstringParent item. Without parent the item lands in the project inbox — the zone for work nobody has filed into the project structure yet. That is the honest default when the place is unclear; when it is clear, set parent. anchor/layer items (right-hand column boxes) never go to the inbox.
typestringType (free-form, e.g. a box-type key for info-column boxes)
anchorstringItem this item docks onto (info-/detail-column mechanism). Set together with parent when the item should also be a structural child of it — anchor only drives the display layer, parent remains the source of truth for the overall tree.
layernumber ≥ 0Display layer for the anchor mechanism (0 = main list). Only meaningful together with anchor.
contentobject | array | stringStructured content payload (e.g. box-type-specific data). Objects/arrays are stored as JSON.

update_list_item ​

Update an item. write · user

ParameterTypeDescription
itemIdstring (required)UUID or SID
text, description, statusstringnew values
prioritynumber (1–9)new priority
assigned_tostring[]new assignments
tagsstring[]new tags
target_datestring | nullnew date
progressnumber (0–100)Progress
archivedbooleanarchive
typestringnew type
anchorstring | nullnew anchor item (or null to clear)
layernumber | nullnew display layer (or null to clear)
contentobject | array | stringnew structured content payload
expectedVersionintegerOptimistic Lock

assign_list_item ​

Add people to an item or remove them. write · user

The incremental counterpart to update_list_item({assigned_to}), which replaces the whole list — here the other assignees stay untouched.

ParameterTypeDescription
itemIdstring (required)UUID or SID
userIdsstring[]User IDs. Omit = the calling user ("assign to me")
unassignbooleantrue = remove the given users instead of adding them

split_task ​

Spin side topics of the current work off into separate tasks.

write · user
ParameterTypeDescription
sourceItemIdstring (required)Source item (UUID or SID)
tasksobject[] (required)Per entry: text (required), description, status, priority (1–9), assigned_to[], target_date
modeenum child | siblingchild (default) = sub-items of the source, sibling = same level
listIdstringTarget list. Default = the source item's list

New items inherit the visibility (scope) of the source and are linked back to it via refs. With a different target list they are created there as top-level items (an item cannot be the child of an item in another list) — mode is then ignored.

Confirm first

Agree the proposed split with the user before calling this.

attach_file_to_list_item ​

Upload a file and attach it to an item — e.g. a Markdown summary or a PDF the agent produced. write · user

ParameterTypeDescription
itemIdstring (required)UUID or SID
filenamestring (required)File name including extension, e.g. summary.md
content_textstringUTF-8 content (for .md/.txt/.json …)
content_base64stringBase64 bytes (for PDFs/images)
mimestringMIME type; inferred from the extension when omitted
targetenum files_box | subitem | itemfiles_box (default) = the item's file box in the right-hand column (created if missing); subitem = as a sub-item; item = reference on the item itself

Provide either content_text or content_base64 — not both.

TIP

Use subitem only when explicitly asked for: a sub-item is a piece of work, not a storage place.

complete_list_item ​

Mark as completed (status done, progress 100). write · user

ParameterTypeDefaultDescription
itemIdstring (required)–UUID or SID
reopenbooleanfalseReopen (status open, progress 0)
expectedVersioninteger–Optimistic Lock

complete_list_items ​

Complete/reopen multiple items (bulk). write · user

ParameterTypeDefaultDescription
itemIdsstring[] (required)–UUIDs/SIDs (min. 1)
reopenbooleanfalseReopen instead of completing

Response: { succeeded, failed, results[] } (per-item result).

update_list_items ​

Apply the same field updates to multiple items (bulk). write · user

ParameterTypeDescription
itemIdsstring[] (required)UUIDs/SIDs (min. 1)
statusstringfor all
prioritynumber (1–9)for all
assigned_tostring[]for all
tagsstring[]for all
target_datestring | nullfor all
progressnumber (0–100)for all
archivedbooleanfor all

delete_list_item ​

Move to the trash. destructive · admin

ParameterTypeDescription
itemIdstring (required)UUID or SID
expectedVersionintegerOptimistic Lock

get_overdue_list_items ​

Overdue items. read · follower

ParameterTypeDefaultDescription
listIdstring–By list
compactbooleanfalseCore fields + days_overdue
limitnumber50Count

get_my_open_items ​

My open tasks (overdue → due → priority). read · follower

ParameterTypeDefaultDescription
listIdstring–Restrict to a single list
includeUndatedbooleantrueInclude items without a date
compactbooleanfalseCore fields
limitnumber50Count

list_recent_changes ​

Recently changed items (sync/polling). read · follower

ParameterTypeDefaultDescription
sincestring (ISO)–Only items changed since this point in time
listIdstring–Restrict to a single list
compactbooleanfalseCore fields + modified
limitnumber50Count

search_list_items ​

Full-text search across items. read · follower

ParameterTypeDefaultDescription
querystring (required)–Search term (min. 1 character)
compactbooleanfalseCore fields
limitnumber20Count

post_chat_message ​

Post a message to an item's chat (or a list's chat). write · user

ParameterTypeDescription
itemIdstringTarget item (UUID/SID)
listIdstringTarget list (alternative to itemId)
textstring (required)Message text

post_activity_summary ​

Write a closing summary into the item's activity feed — without disturbing the team chat. write · user

ParameterTypeDescription
itemIdstring (required)UUID or SID
summarystring (required)What was done, in a few sentences

There is exactly one entry per item and author: a later run overwrites its own summary. Read it back via get_item_ai_summaries. Nothing is written for a private conversation.

get_chat_messages ​

Read the chat history (oldest first). read · follower

ParameterTypeDefaultDescription
itemIdstring–Item chat
listIdstring–List chat (alternative)
limitnumber50Max. messages
offsetnumber0Skip

get_metadata ​

Reference: valid status/priority/scope/filter values. read · guest

No parameters. Call before creating/updating to use correct values.