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:

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)
• get_item_ai_status — run state of an item: running / waiting / done / crashed, and since when
• get_item_ai_summaries — read the closing summaries of runs (counterpart to post_activity_summary)

search_ai_messages ​

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

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:

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.

get_item_ai_status ​

Reads the run state of one or more items — the channel to poll while another item works on an order. get_ai_chat_history tells you what a run said; this tells you whether it is still running.

One state per item to branch on — precedence waiting > running > queued > error > done > idle > no_thread:

Plus statusAt / doneAt / liveAt — the only timestamps of a run that survive a restart. list_recent_changes and list_items.modified are blind to AI runs (see api/lib/claudeCode/util/aiMetaTimestamps.js) and cannot be used for this.

A projection of api/lib/claudeCode/thread/items.js — the same derivation that feeds the AI pill on the item. Two differences: it cleans up nothing (a read tool does not write; orphaned runs are reported as stale instead of being swept away silently), and the heartbeat is checked for freshness. Run state is per creator — other people's runs are not visible.

report_decision_needed ​

The write path to needs_decision. An unattended run (started from a queued order, nobody watching) must not use ask_user: nobody sees the dialog and the run hangs until the stale sweep. It calls this tool instead, finishes everything that does not depend on the decision, and ends with the same findings in text.

In an interactive session use ask_user instead — a human is present there, and answering continues the same run without rebuilding its context.

Why the tool is needed at all: findings that live only in the closing message do not exist for a machine. The run ends normally, its queue row goes to done, and the status channel reported done — an orchestrator considered the task finished although its own summary said otherwise (observed in the field, #216.197). Deliberately no pattern matching on model output: a matcher over free-form text fails silently as soon as the wording drifts.

A new run on the same item clears the note automatically.

get_item_ai_summaries ​

Reads the closing summaries from the Activity feed (list_history, action ai_summary) — the read side of post_activity_summary. The right channel for an orchestrator: a few sentences per item instead of a whole transcript.

There is exactly one entry per item and author: a later run overwrites its own summary and refreshes created. For the history, use get_ai_chat_history. No creator filter — the Activity feed is team-visible in the UI, and post_activity_summary writes nothing for a private conversation anyway; isOwn shows the origin.

Profiles & progressive disclosure ​

The tool schema block goes into every request an agent makes — and one turn consists of several requests. Carrying all tools permanently therefore costs tokens at every step. A client can request a curated profile:

Everything outside the profile stays reachable through two meta tools:

This keeps the schema budget small without making any tool unreachable. A client without token worries simply omits the header.

Context headers ​

Three optional headers tell the server which conversation a call comes from. Tools use them as defaults instead of forcing you to pass them:

Annotations ​

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

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.