Tools & Annotations

Die vollständige Liste kommt live aus tools/list. Hier die wichtigsten Konzepte für den Umgang mit den Listen-/Aufgaben-Tools.

Filter auf list_list_items

Serverseitige Filter sparen das Nachfiltern und reduzieren die Antwortgröße:

Parameter	Wirkung
state	open / done / all
assigned_to_me	nur mir zugewiesene Items (kein get_me nötig)
due_within_days	bald fällige (inkl. überfällige)
due_before	fällig vor ISO-Datum
sort	priority / due_date / created / modified
compact	schlanke Antwort (weniger Tokens)

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

Nützliche dedizierte Tools

• get_my_open_items — „Was steht bei mir an?" (überfällig → fällig → Priorität)
• complete_list_item / complete_list_items — abhaken (einzeln/Bulk)
• list_recent_changes — Sync/Polling: was hat sich seit since geändert
• get_metadata — gültige Status/Priorität/scope-Werte
• get_item_dashboard — die Dashboard-Seite einer Aufgabe (Anforderungen, Gliederung) mit den Nummern der Oberfläche; get_list_item enthält sie nicht
• search_ai_messages — Claude-Code-KI-Chatverlauf durchsuchen/filtern
• get_ai_chat_history — vollständigen KI-Chat-Verlauf eines Items lesen (ohne Kürzung)
• get_item_ai_status — Laufzustand eines Items: läuft / wartet / fertig / abgestürzt, und seit wann
• get_item_ai_summaries — die Abschluss-Fazits von Läufen lesen (Gegenstück zu post_activity_summary)

search_ai_messages

Durchsucht/filtert den Claude-Code-KI-Chatverlauf des Teams (Konversationen an List-Items/Listen):

Parameter	Wirkung
query	Volltext-Suche im Message-Content (optional — ohne query wird nur gefiltert)
listId	auf eine Liste einschränken — UUID, SID oder Listen-Nummer ("177"/"#177")
itemId	auf ein Item einschränken — UUID, SID, oder "#<listNum>.<itemNum>" (z. B. "#177.252", wie in UI/Commit-Titeln); eine blanke Item-Nummer nur zusammen mit listId, da list_items.num nur pro Liste eindeutig ist
userId	nur Konversationen dieses Erstellers
role	user / assistant / tool
dateFrom / dateTo	Zeitraum (ISO 8601)
limit / offset	Pagination (max. 200)

{"name":"search_ai_messages",
 "arguments":{"itemId":"#177.252","query":"Rate Limit","role":"assistant"}}

Sichtbarkeit ist fest verdrahtet, nicht per Rolle umgehbar: Eine Konversation ist entweder public (sichtbar für jeden mit Zugriff auf das zugrunde liegende Item/die Liste) oder private (Default — ausschließlich für den eigenen Ersteller sichtbar, kein Bypass für admin/owner). Details: public-api/docs/MCP-TOOL-AI-MESSAGES.md.

get_ai_chat_history

Liest den vollständigen KI-Chat-Verlauf eines Items — über alle seine Threads hinweg, mit vollem Message-Content statt gekürztem Snippet:

Parameter	Wirkung
itemId	UUID oder SID des Items (erforderlich)
dateFrom / dateTo	Zeitraum (ISO 8601) — schränkt ein, damit nicht immer der gesamte Verlauf geladen werden muss

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

Gleiche Sichtbarkeitsregel wie search_ai_messages (public vs. private pro Thread, kein Rollen-Bypass). Details: public-api/docs/MCP-TOOL-AI-CHAT-HISTORY.md.

get_item_ai_status

Liest den Laufzustand eines oder mehrerer Items — der Kanal zum Pollen, während ein anderes Item an einem Auftrag arbeitet. get_ai_chat_history sagt, was ein Lauf gesagt hat; dieses Tool sagt, ob er noch läuft.

Parameter	Wirkung
itemIds	UUID, SID oder Referenz #<listNum>.<itemNum> (z. B. #216.114), max. 200
listId	Alternative: alle Items einer Liste mit KI-Thread. UUID, SID oder #<listNum>

Pro Item ein state, auf das man verzweigen kann — Vorrang waiting > running > queued > error > done > idle > no_thread:

state	Bedeutung
waiting	Der Lauf wartet auf eine Antwort (questionText sagt worauf). Sticht running, weil es der Grund ist, warum nichts vorangeht
running	Läuft, Herzschlag frisch
stale	Die DB sagt „läuft", das letzte Lebenszeichen ist aber älter als staleAfterMs (35 min) — als vermutlich tot behandeln
queued	Auftrag scharf, aber noch nicht gestartet (wartende Aufträge timen bewusst nicht weg)
needs_decision	Der Lauf ist fertig, die Aufgabe aber nicht: es fehlt eine Entscheidung (decisionText). Antworten heißt hier neuer Auftrag — anders als bei waiting, wo ein lebender Lauf auf einen Dialog wartet. Gesetzt von report_decision_needed
error / done	abgeschlossen; errorMsg, doneAt
idle	Thread existiert, gerade läuft nichts
no_thread	An diesem Item hat (für dich) noch nie eine KI gearbeitet

Dazu statusAt / doneAt / liveAt — die einzigen Zeitstempel eines Laufs, die einen Neustart überleben. list_recent_changes und list_items.modified sind für KI-Läufe blind (siehe api/lib/claudeCode/util/aiMetaTimestamps.js) und taugen dafür nicht.

{"name":"get_item_ai_status",
 "arguments":{"itemIds":["#216.196","#216.199"]}}

Projektion von api/lib/claudeCode/thread/items.js — dieselbe Ableitung, die die AI-Pille am Item speist. Zwei Unterschiede: Es wird nichts aufgeräumt (ein Lesetool schreibt nicht; verwaiste Läufe werden als stale gemeldet statt stillschweigend abgeräumt), und der Herzschlag wird auf Frische geprüft. Laufzustand ist pro Ersteller — fremde Läufe sind nicht sichtbar.

report_decision_needed

Der Schreibweg zu needs_decision. Ein unbeaufsichtigter Lauf (aus einem eingereihten Auftrag, niemand sieht zu) darf ask_user nicht benutzen: Den Dialog sieht keiner, und der Lauf hängt bis zum Stale-Sweep. Er ruft stattdessen dieses Tool, erledigt alles Unabhängige und endet mit demselben Befund im Text.

Parameter	Wirkung
itemId	UUID, SID oder #<listNum>.<itemNum>
decision	Was zu entscheiden ist, mit den Optionen — so formuliert, dass man danach handeln kann, ohne das Transkript zu lesen
resolved	true löscht einen vorhandenen Vermerk (Entscheidung ist gefallen)

{"name":"report_decision_needed",
 "arguments":{"itemId":"#216.114","decision":"PR-Workflow oder Auto-Merge? Beides berührt finalizeWorktree."}}

In einer interaktiven Sitzung stattdessen ask_user — dort sitzt ein Mensch, und eine Antwort setzt denselben Lauf fort, ohne Kontext neu aufzubauen.

Warum es das Tool überhaupt braucht: Ein Befund, der nur im Abschlusstext steht, existiert für die Maschine nicht. Der Lauf endet regulär, seine Queue-Zeile geht auf done, und der Statuskanal meldete done — ein Orchestrator hielt die Aufgabe damit für erledigt, obwohl ihr eigenes Fazit das Gegenteil sagte (im Feld belegt, #216.197). Bewusst kein Textmustervergleich auf der Modellausgabe: ein Erkennungsmuster auf frei formulierten Text versagt still, sobald die Formulierung abweicht.

Ein neuer Lauf am selben Item hebt den Vermerk automatisch auf.

get_item_ai_summaries

Liest die Abschluss-Fazits aus dem Aktivität-Feed (list_history, action ai_summary) — die Leseseite von post_activity_summary. Für einen Orchestrator der richtige Kanal: ein paar Sätze pro Item statt eines ganzen Transkripts.

Parameter	Wirkung
itemIds	UUID oder SID, max. 200
listId	Alternative: alle Items einer Liste mit Fazit
since	Nur Fazits ab diesem Zeitpunkt (ISO 8601) — beim Pollen benutzen

{"name":"get_item_ai_summaries",
 "arguments":{"itemIds":["<UUID>"],"since":"2026-08-23T07:00:00Z"}}

Pro Item und Autor gibt es genau einen Eintrag: ein späterer Lauf überschreibt sein eigenes Fazit und setzt created neu. Wer die Historie braucht, ist bei get_ai_chat_history richtig. Kein Ersteller-Filter — der Aktivität-Feed ist im UI team-sichtbar, und post_activity_summary schreibt bei privater Konversation ohnehin nichts; isOwn zeigt die Herkunft.

Profile & progressive disclosure

Der Tool-Schema-Block geht in jeden Request eines Agenten ein — und ein Turn besteht aus mehreren Requests. Alle Tools dauerhaft mitzuschleppen kostet deshalb bei jedem Schritt Tokens. Ein Client kann darum ein kuratiertes Profil anfordern:

x-liza-mcp-profile: agent

Profil	Inhalt
(kein Header)	alle rollen-erlaubten Tools
agent	die Tools, die ein Coding-Agent in fast jedem Lauf braucht: Listen/Items lesen & ändern (inkl. Batch), post_activity_summary, get_me, get_widget_spec, search_memory/save_memory
onboarding	minimales Set für den Onboarding-Guide: Items abhaken, Listen/Items anlegen, invite_user, search_docs, get_me, post_chat_message

Alles, was nicht im Profil steht, bleibt über zwei Meta-Tools erreichbar:

Tool	Zweck
list_liza_tools	Katalog der nicht geladenen Tools inkl. Beschreibung und Input-Schema. Optionaler query-Filter (z. B. "crm", "kalender").
call_liza_tool	Ruft jedes Tool per Name auf: { name, arguments }. Rolle und Argument-Schema werden dabei genauso geprüft wie beim direkten Aufruf.

{"name":"call_liza_tool",
 "arguments":{"name":"schedule_task",
              "arguments":{"title":"Wochenbericht","action_type":"reminder",
                           "rrule":"FREQ=WEEKLY;BYDAY=MO","message":"Bericht schreiben"}}}

So bleibt das Schema-Budget klein, ohne dass ein Tool unerreichbar wird. Ein Client ohne Token-Sorgen lässt den Header einfach weg.

Kontext-Header

Drei optionale Header geben dem Server mit, aus welcher Unterhaltung ein Aufruf kommt. Tools nutzen sie als Default, statt Angaben zu erzwingen:

Header	Wirkung
x-liza-conversation	Aktuelle KI-Konversation (scope_key). schedule_task plant damit „für diese Konversation", ohne dass der Client eine ID kennt.
x-liza-provider	KI-Engine der Konversation (claude, codex, liza, …). Default-Provider für geplante KI-Aufgaben.
x-liza-model	Konkretes Modell. Wird auf von der KI geposteten Chat-Blöcken als ai_model gespeichert und im UI angezeigt.

Annotations

Jedes Tool trägt in tools/list Verhaltens-Hinweise, damit Clients Read-Tools automatisch erlauben und vor destruktiven warnen:

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

readOnlyHint, destructiveHint, idempotentHint, openWorldHint.

Paginierung & compact

Alle List-Tools unterstützen compact:true. Paginierte Tools liefern has_more — danach offset erhöhen, bis has_more:false.