Skip to content

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
includeSubprojectsbooleanfalseWith listId: also the items of all sub-projects (any depth); each item carries list_name
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
completed_fromstring (ISO)–Only items completed at or after this time (and still done); each carries completed_at. This is how to answer "what was finished yesterday / this week" — not via modified
completed_tostring (ISO)–With completed_from: completed before this time
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

get_item_dashboard ​

The dashboard page of a task: requirements, outline and notes from its "Dashboard" tab. read · follower

ParameterTypeDescription
itemIdstring (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.

edit_item_dashboard ​

Edit the dashboard page of a task. write · user

ParameterTypeDescription
itemIdstring (required)UUID or SID of the task
operationsobject[] (1–100) (required)Operations, applied in this order

Per operation:

FieldTypeDescription
openum add | update | delete (required)Add, change or delete a row (delete moves it and its sub-points to the trash)
blockstringupdate/delete: the row — ID, SID, outline number ("2.1") or "$n"
textstringadd (required) / update: the text, one line
typeenum "" | H1 | H2 | H3 | ol | ul | blockquote | code-blockRow type; default "" (text) on add
statusstringTurns the row into a checkbox: open = unchecked, done = checked, "" = plain row again
parentstringadd: nest under this row; omit for the top level
afterstringadd: insert directly after this row (same level)
positionenum start | endadd without after: first or last child, default end

Read it first with get_item_dashboard. Outline numbers always refer to the state before the call; "$n" is the row that operation number n of the same call created. Box and page are created on the first write. All operations are checked before anything is written — one invalid operation rejects the whole call. The response is the updated page.

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_token_usage ​

Token usage and cost of one task or a whole project, across all AI runs.

read · follower
ParameterTypeDefaultDescription
itemIdstring–The task: UUID, SID or #<listNum>.<itemNum>
listIdstring–Alternative: the whole project, UUID, SID or #<listNum>
from / tostring (ISO)–Time range (to exclusive)
includeRowsbooleanfalseAlso the individual records (when, who, model, billing, tokens, cost), newest first
limitnumber50Max. records with includeRows (max 500)

It covers Claude Code and Codex runs (per prompt) and Liza AI calls (per model call, including the in-app chat). The response sums up per token type (input, output, cache read, cache write) and in total, plus by_user and, for a project, by_item. Never mix the cost figures: cost.eur is Liza AI, exactly as booked; cost.usd_estimate is the provider tool's estimate at list prices, split into usd_api_key (own API key — roughly the real bill) and usd_subscription (subscription — only the equivalent value, no extra cost). Codex reports tokens only, no cost.

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.