Tools & Annotations

Last updated About 3 hours ago

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:

ParameterEffect
stateopen / done / all
assigned_to_meonly items assigned to me (no get_me needed)
due_within_daysdue soon (including overdue)
due_beforedue before an ISO date
sortpriority / due_date / created / modified
compactlean response (fewer tokens)
json

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):

ParameterEffect
queryfree-text search in the message content (optional — without query it just filters/lists)
listIdrestrict to a list — UUID, SID, or list number ("177"/"#177")
itemIdrestrict 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
userIdonly conversations created by this user
roleuser / assistant / tool
dateFrom / dateTodate range (ISO 8601)
limit / offsetpagination (max 200)
json

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:

ParameterEffect
itemIdUUID or SID of the item (required)
dateFrom / dateTodate range (ISO 8601) — restrict this so you don't have to load the entire history every time
json

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:

ToolType
list_list_itemsread-only
update_list_itemwrite · idempotent
delete_list_itemdestructive

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.