Tools & Annotations

The complete list comes live from tools/list. Below are the most important concepts for working with the list/task tools.

Filters on list_list_items

Server-side filters save you from post-filtering and reduce the response size:

Parameter	Effect
state	open / done / all
assigned_to_me	only items assigned to me (no get_me needed)
due_within_days	due soon (including overdue)
due_before	due before an ISO date
sort	priority / due_date / created / modified
compact	lean response (fewer tokens)

{"name":"list_list_items",
 "arguments":{"state":"open","assigned_to_me":true,"compact":true}}

Useful dedicated tools

• get_my_open_items — "What's on my plate?" (overdue → due → priority)
• complete_list_item / complete_list_items — check off (single/bulk)
• list_recent_changes — sync/polling: what has changed since since
• get_metadata — valid status/priority/scope values
• search_ai_messages — search/filter the Claude Code AI chat history
• get_ai_chat_history — read the full AI chat history of an item (no truncation)

search_ai_messages

Searches/filters the team's Claude Code AI chat history (conversations attached to list items/lists):

Parameter	Effect
query	free-text search in the message content (optional — without query it just filters/lists)
listId	restrict to a list — UUID, SID, or list number ("177"/"#177")
itemId	restrict to a single item — UUID, SID, or "#<listNum>.<itemNum>" (e.g. "#177.252", as shown in the UI/commit titles); a bare item number only works together with listId, since list_items.num is only unique within a list
userId	only conversations created by this user
role	user / assistant / tool
dateFrom / dateTo	date range (ISO 8601)
limit / offset	pagination (max 200)

{"name":"search_ai_messages",
 "arguments":{"itemId":"#177.252","query":"rate limit","role":"assistant"}}

Visibility is hard-wired, not a role bypass: a conversation is either public (visible to anyone with access to the underlying item/list) or private (default — visible only to its own creator, no bypass for admin/owner). Details: public-api/docs/MCP-TOOL-AI-MESSAGES.md.

get_ai_chat_history

Reads the full AI chat history of a single item — across all its threads, with the complete message content instead of a truncated snippet:

Parameter	Effect
itemId	UUID or SID of the item (required)
dateFrom / dateTo	date range (ISO 8601) — restrict this so you don't have to load the entire history every time

{"name":"get_ai_chat_history",
 "arguments":{"itemId":"<UUID>","dateFrom":"2026-07-04T00:00:00Z"}}

Same visibility rule as search_ai_messages (public vs. private per thread, no role bypass). Details: public-api/docs/MCP-TOOL-AI-CHAT-HISTORY.md.

Annotations

Every tool carries behavior hints in tools/list, so that clients can allow read tools automatically and warn before destructive ones:

Tool	Type
list_list_items	read-only
update_list_item	write · idempotent
delete_list_item	destructive

readOnlyHint, destructiveHint, idempotentHint, openWorldHint.

Pagination & compact

All list tools support compact:true. Paginated tools return has_more — after that, increase offset until has_more:false.