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
| Parameter | Type | Default | Description |
|---|---|---|---|
listId | string | – | Filter by list |
parent | string | – | Only the direct children of this item. With state=open this gives the open sub-tasks of a task |
descendants | boolean | false | With parent: the whole subtree instead of only direct children. Each item then carries its own parent |
state | enum open | done | all | all | open = not completed (status not done/completed) |
status | string | – | Exact status (e.g. todo). For "not finished", prefer state |
priority | number (1–9) | – | Filter by priority |
assigned_to | string | – | Filter by assigned user (refs, type=user) |
assigned_to_me | boolean | – | Only items assigned to me (no get_me needed) |
tag | string | – | Exact tag |
search | string | – | Search in text and description |
due_within_days | number | – | Due within N days (including overdue) |
due_before | string (ISO) | – | Due before a date |
includeArchived | boolean | false | Include archived items |
sort | enum default | priority | due_date | created | modified | default | Sort order |
compact | boolean | false | Core fields + assignees only |
limit | number | 50 | Count |
offset | number | 0 | Skip |
Response: { items, total, limit, offset, has_more }.
get_list_item
A single item. read · follower
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
get_item_dashboard
The dashboard page of a task: requirements, outline and notes from its "Dashboard" tab. read · follower
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID of the task |
get_list_item does not include this page: it hangs off the task as a box via anchor/layer and is hidden from the task tree. The result carries dashboard.markdown (the outline) and dashboard.blocks (per row id, type, depth, number, text). The numbers match the UI ("1", "1.3.1"): only consecutive numbered rows are counted, and a numbered row passes its number on to its sub-points. Without a dashboard, or with an empty page, dashboard is null and note says why.
create_list_item
Create a new item. write · user
| Parameter | Type | Description |
|---|---|---|
listId | string (required) | UUID or SID of the list |
text | string (required) | Title (min. 1 character) |
description | string | Description |
status | string | Status |
priority | number (1–9) | Priority (9 = urgent) |
assigned_to | string[] | Assigned user IDs |
tags | string[] | Tags |
target_date | string (ISO) | Due date |
parent | string | Parent 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. |
type | string | Type (free-form, e.g. a box-type key for info-column boxes) |
anchor | string | Item 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. |
layer | number ≥ 0 | Display layer for the anchor mechanism (0 = main list). Only meaningful together with anchor. |
content | object | array | string | Structured content payload (e.g. box-type-specific data). Objects/arrays are stored as JSON. |
update_list_item
Update an item. write · user
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
text, description, status | string | new values |
priority | number (1–9) | new priority |
assigned_to | string[] | new assignments |
tags | string[] | new tags |
target_date | string | null | new date |
progress | number (0–100) | Progress |
archived | boolean | archive |
type | string | new type |
anchor | string | null | new anchor item (or null to clear) |
layer | number | null | new display layer (or null to clear) |
content | object | array | string | new structured content payload |
expectedVersion | integer | Optimistic 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.
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
userIds | string[] | User IDs. Omit = the calling user ("assign to me") |
unassign | boolean | true = remove the given users instead of adding them |
split_task
Spin side topics of the current work off into separate tasks.
write · user| Parameter | Type | Description |
|---|---|---|
sourceItemId | string (required) | Source item (UUID or SID) |
tasks | object[] (required) | Per entry: text (required), description, status, priority (1–9), assigned_to[], target_date |
mode | enum child | sibling | child (default) = sub-items of the source, sibling = same level |
listId | string | Target 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
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
filename | string (required) | File name including extension, e.g. summary.md |
content_text | string | UTF-8 content (for .md/.txt/.json …) |
content_base64 | string | Base64 bytes (for PDFs/images) |
mime | string | MIME type; inferred from the extension when omitted |
target | enum files_box | subitem | item | files_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
| Parameter | Type | Default | Description |
|---|---|---|---|
itemId | string (required) | – | UUID or SID |
reopen | boolean | false | Reopen (status open, progress 0) |
expectedVersion | integer | – | Optimistic Lock |
complete_list_items
Complete/reopen multiple items (bulk). write · user
| Parameter | Type | Default | Description |
|---|---|---|---|
itemIds | string[] (required) | – | UUIDs/SIDs (min. 1) |
reopen | boolean | false | Reopen instead of completing |
Response: { succeeded, failed, results[] } (per-item result).
update_list_items
Apply the same field updates to multiple items (bulk). write · user
| Parameter | Type | Description |
|---|---|---|
itemIds | string[] (required) | UUIDs/SIDs (min. 1) |
status | string | for all |
priority | number (1–9) | for all |
assigned_to | string[] | for all |
tags | string[] | for all |
target_date | string | null | for all |
progress | number (0–100) | for all |
archived | boolean | for all |
delete_list_item
Move to the trash. destructive · admin
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
expectedVersion | integer | Optimistic Lock |
get_overdue_list_items
Overdue items. read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
listId | string | – | By list |
compact | boolean | false | Core fields + days_overdue |
limit | number | 50 | Count |
get_my_open_items
My open tasks (overdue → due → priority). read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
listId | string | – | Restrict to a single list |
includeUndated | boolean | true | Include items without a date |
compact | boolean | false | Core fields |
limit | number | 50 | Count |
list_recent_changes
Recently changed items (sync/polling). read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
since | string (ISO) | – | Only items changed since this point in time |
listId | string | – | Restrict to a single list |
compact | boolean | false | Core fields + modified |
limit | number | 50 | Count |
search_list_items
Full-text search across items. read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string (required) | – | Search term (min. 1 character) |
compact | boolean | false | Core fields |
limit | number | 20 | Count |
post_chat_message
Post a message to an item's chat (or a list's chat). write · user
| Parameter | Type | Description |
|---|---|---|
itemId | string | Target item (UUID/SID) |
listId | string | Target list (alternative to itemId) |
text | string (required) | Message text |
post_activity_summary
Write a closing summary into the item's activity feed — without disturbing the team chat. write · user
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID |
summary | string (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
| Parameter | Type | Default | Description |
|---|---|---|---|
itemId | string | – | Item chat |
listId | string | – | List chat (alternative) |
limit | number | 50 | Max. messages |
offset | number | 0 | Skip |
get_metadata
Reference: valid status/priority/scope/filter values. read · guest
No parameters. Call before creating/updating to use correct values.