COMPASS-Doku
ENDE

MCP-Werkzeuge-Referenz

95 Werkzeuge (gemessen am 29.10.2026 am laufenden Server-Code). Jedes Werkzeug trägt einen title und Hinweise: 46 sind als nur lesend markiert (readOnlyHint), 18 als verändernd (destructiveHint). Ein Client wie Claude kann die lesenden ohne Rückfrage ausführen und fragt vor den verändernden. Jedes Werkzeug ruft genau eine Kern-REST-Route auf — kein Werkzeug trägt eigene Fachlogik oder eigene Invarianten; ein 409/422 des Kerns kommt beim aufrufenden Modell als strukturierter ToolError an, nie verschluckt. Siehe Claude Code, Cursor und Codex anbinden für die Authentifizierung eines Clients.

Zwei Lese-Werkzeuge behandeln ein dokumentiertes leeres Ergebnis als gültige Antwort, nicht als Fehler: gilt liefert bei einem 404 des Kerns {"gilt": false, ...}, prozess_bild liefert bei dessen 404 {"bild_url": null, ...}. Jedes andere Werkzeug reicht eine Nicht-2xx-Antwort als Fehler durch.

Eine Sache lesen

Werkzeug Parameter Liefert
sache_list bereich?, stufe?, suche?, persona_slug?, alle=False, gehoert_persona? Sachen mit Frage und geltender Regel. persona_slug filtert auf das Sichtfeld der aufrufenden Persona (gesendet als sichtfeld=); gehoert_persona filtert auf Eigentum (gesendet als persona=) — unabhängige Filter.
sache_get slug Die Sache plus jede Aussage, nach Art, plus Historie. Kein Sichtbarkeits-Filter — Einzel-Lookup, keine Liste.
gilt slug, subjekt_id?, persona_slug?, alle=False Die eine geltende Regel, oder ein gültiges leeres Ergebnis.
gilt_am slug, datum, subjekt_id?, persona_slug?, alle=False Was am Datum galt, mit Status.
warum slug Entscheidungstext der Regel, Historie, letztes Prüfweg-Ergebnis.
suche q, subjekt_id?, persona_slug?, alle=False Volltextsuche über Aussagen und Ereignisse.
konflikte — Sachen mit Konflikt.
graph slug?, id?, tiefe=2 Knoten und Kanten rund um eine Sache/Aussage/einen Prozess.

Eine Sache oder Aussage schreiben

Werkzeug Parameter Liefert
sache_put slug, titel, frage, bereich?, stufe?, eltern_slug?, subjekt_typ? Legt eine Sache an, idempotent auf slug.
aussage_put sache, art, text, herkunft, angelegt_von, subjekt_id=1, gilt_seit?, gilt_bis?, beobachtet_am?, quelle?, sicherheit?, ort?, pruefweg_slug?, beleg?, ersetzt?, status="gilt", frist?, prozess_slug?, schritt_key?, frame_ref? Neue Aussage. 409 mit der geltenden Aussage im Fehlertext, wenn ersetzt fehlt und schon eine gilt.
hypothese_put sache, text, frist, pruefweg_slug, sicherheit, quelle, angelegt_von Neue Hypothese. Das Werkzeug selbst weist sicherheit >= 1 ab, bevor der Kern gefragt wird.
hypothese_bewerten id, ergebnis, quelle, neue_frist? Löst eine Hypothese auf (bestaetigt|widerlegt|verlaengert, clientseitig geprüft).
pruefweg_run slug Führt einen Prüfweg aus, speichert das Ergebnis, schreibt einen Fakt.
abweichungen seit? Listet Abweichungen.
ereignis_put subjekt_id, typ, zeitpunkt, inhalt_ref, text? Erfasst ein Ereignis.
frage_stellen sache, frage, optionen, gestellt_von, empfehlung_key?, frist? Stellt eine Schaltzentrale-Frage. Das Werkzeug weist weniger als zwei Optionen, oder eine Option ohne folge, vor dem Kern-Aufruf ab. Arbeitet die fragende Stelle autark, legt der Kern keine Klickfrage an, sondern stellt die Frage als Nachricht ihrem Ansprechpartner zu (Antwort 202, »an weitergeleitet«); bei begleitet (Standard) bleibt es die Klickfrage, und der Ansprechpartner bekommt eine Kopie.
offen_fuer_mensch — Alles, was gerade einen menschlichen Klick braucht. Eine offene Frage kommt vollständig: die Frage selbst und je Option Schlüssel, Beschriftung und Folge — damit ein Agent sie einem Menschen vorlegen kann, ohne etwas zu erfinden.
frage_beantworten id, key, notiz? Beantwortet eine offene Frage. Nur als angemeldeter Mensch über eine OAuth-Verbindung — mit einem Schlüssel oder nach persona_waehlen wird der Aufruf abgewiesen. Die Antwort trägt den Namen des Angemeldeten (aus der Sitzung, nicht aus dem Aufruf) und den Vermerk „im Chat".
seit_wann_neu seit Beantwortete Fragen seit einem Zeitpunkt (siehe den Abweichungs-Hinweis auf der REST-Referenz).

Prozesse

Werkzeug Parameter Liefert
prozess_get slug, version? Ein Stand eines Prozesses: Schritte, Regeln je Schritt, Lücken, ueberholt und versionen (jeder Stand mit gilt_seit/gilt_bis). Ohne version der aktuelle, mit version genau dieser — so ist nachlesbar, was vor einer Änderung galt. Ein Stand, den es nicht gibt, ist ein Fehler und nicht der neueste.
prozess_put slug, titel, diagramm_md, schritte, angelegt_von, subjekt_typ?, ersetzt_slug? Legt einen Prozess an oder eine neue Version.
prozess_beenden slug, grund, angelegt_von Beendet einen Prozess ohne Nachfolger. Bewusst kein aussage_beenden-Werkzeug — das Beenden einer einzelnen Aussage ist eine Menschen-Entscheidung über Web/REST, kein Agenten-Werkzeug; ein Prozess ist die eine Ausnahme, weil sein Beenden Teil der routinemäßigen Regelwerk-Pflege eines Agenten ist.
prozess_bild slug, schritt Das Bild des Schritts, oder ein benanntes leeres Ergebnis.
kern_render subjekt_id Der erzeugte Kern als Markdown, plus Hash.

Personas, Gedächtnis und Vorlagen

persona_put und from_vorlage sind bewusst keine MCP-Werkzeuge — Aufgabe, Grenzen, Stil und Regeln ändert nur ein Mensch mit rw-Schlüssel über die Web-Fläche. Über sich selbst Gedächtnis zu schreiben ist die eine Ausnahme, die Agenten bekommen.

Werkzeug Parameter Liefert
persona_list — Jede Persona mit ihren Kennzahlen.
persona_get slug Eine Persona vollständig, plus ihre Regeln und die 10 jüngsten Gedächtnis-Einträge.
persona_brief slug, max_gedaechtnis?, max_lehren? Der deterministische Markdown-Brief.
persona_waehlen slug, projekt? slug darf die Kennung oder der Anzeigename sein, groß oder klein (Julia, julia und JULIA binden dieselbe Persona); passt nichts, nennt die Absage ähnliche Personas aus euren Projekten. Bindet diesen Chat an eine Persona: ab dann gelten ihre Werkzeug-Freigaben und ihr Sichtfeld, und sie ist die Urheberin dessen, was geschrieben wird. Nur über eine OAuth-Verbindung — ein Schlüssel trägt seine Bindung bereits selbst. Nur aktive Personas eurer Projekte. Steht der Name in mehr als einem Projekt, kommt eine Rückfrage mit der Projektliste; projekt beantwortet sie. Jeder Aufruf wird protokolliert. Ohne Wahl bleibt alles wie zuvor.
meine_projekte – Die Projekte des Menschen und in jedem die Personas, die er dort starten darf. Zuerst aufrufen, bevor persona_waehlen benutzt wird, und den Menschen fragen, in welchem Bereich gearbeitet wird. Nur lesend; nur als angemeldeter Mensch über eine OAuth-Verbindung — mit einem Schlüssel oder nach persona_waehlen wird der Aufruf abgelehnt (403). Fremde Projekte erscheinen nicht.
firma_get — Die sechs Firmengedächtnis-Felder, lesend. Ändern darf nur ein angemeldeter Mensch — auch über die Schnittstelle; ein Agent in der Sitzung eines Menschen zählt dazu, ein Schlüssel allein nicht.
memory_search persona_slug, q, art?, limit=20, lesende_persona?, alle=False Volltextsuche im Gedächtnis einer Persona. lesende_persona ist hier der Sichtbarkeits-Filter (nicht persona_slug, das schon bestimmt, wessen Gedächtnis durchsucht wird — bewusst ein anderer Parametername für eine andere Frage).
memory_put persona_slug, art, text, tags=[], gilt_bis? Schreibt einen Gedächtnis-Eintrag.
vorlagen_list — Der Persona-Vorlagen-Katalog.
vorlagen_vorschlag bedarf Bis zu 3 gerankte Vorlagen für einen Freitext-Bedarf.

Agents: Anwesenheit und Postfach

Modul mcp/agents_tools.py.

Werkzeug Parameter Liefert
agent_herzschlag persona_slug, sitzung, client, status="online", arbeitet_an?, kontext_zeichen?, modell? Lebenszeichen einer Sitzung; ein Lese-Schlüssel reicht — ein Herzschlag ist kein Schreiben an Wissen.
agent_offline persona_slug, sitzung Meldet eine Sitzung ausdrücklich ab.
agents_liste — Jede aktive Persona mit Anwesenheit und Postfach-Zählern (ungelesen, getrennt in „nie abgeholt" und „abgeholt, nie quittiert"), mit einer Warnung bei Post ohne laufende Sitzung — auch ohne je gesendeten Herzschlag.
nachricht_senden an_persona, text, art="info", betreff?, von_persona?, antwort_auf?, prioritaet="normal" Sendet eine Nachricht.
auftrag_senden an_persona, text, betreff?, von_persona?, prioritaet="normal" Kurzform von nachricht_senden(art="auftrag").
auftrag_status id, status, notiz?, ergebnis_art?, ergebnis_ref?, abgeloest_durch? Setzt den Status eines Auftrags. Ein erledigter Auftrag kann sein Ergebnis als Verweis tragen (PR, Dokument, Aussage); ein überholter wird abgeloest und nennt den Auftrag, der jetzt gilt.
auftraege_uebersicht status?, an?, seit?, limit? Die Aufträge des Projekts auf einen Blick: offen, bei wem, seit wann — mit Reihenfolge, Ergebnis und Nachfolger.
nachricht_an_mensch von_persona, von_sitzung, text, betreff?, art="info", prioritaet="normal", schwere? Nachricht/Auftrag an den Menschen — erscheint in „Euer Postfach" der Schaltzentrale. Für Regel-ändernde Entscheidungen bleibt frage_stellen der Weg, für Erkenntnisse hinweis_an_mensch.
nachrichten_abholen persona_slug, sitzung, nur_neue=True Liest das Postfach einer Sitzung; markiert unzugestellte Nachrichten als zugestellt.
postfach_stand persona_slug, regelstand (optional) Wie viel im Postfach liegt — ohne es anzufassen (kein Zustell-Stempel, kein Schreiben). Mit dem Regelstand aus dem Brief zeigt regeln_seit, wie viele Regeln sich seither geändert haben; null heißt unbekannt, nicht keine — dann den Brief neu laden.
nachricht_gelesen id, persona_slug? Markiert eine oder mehrere Nachrichten als gelesen (id nimmt auch eine Liste). Bei einem Runden-Beitrag ist persona_slug Pflicht — quittiert wird nur der eigene Lesestand.
runde_eroeffnen titel, frage, teilnehmer, von_persona?, von_sitzung?, slug? Eröffnet eine Runde: ein Gespräch mehrerer Personas zu einer Frage (mit Fragezeichen), mindestens zwei Teilnehmer.
runden_liste persona_slug?, nur_offene=True Listet Runden, neueste zuerst.
runde_lesen slug Eine Runde mit allen Beiträgen, dem Deckel je Teilnehmer und den offenen, ausdrücklich gestellten Fragen.
runde_beitrag slug, text, von_persona?, von_sitzung?, antwort_auf?, frage_an? Schreibt in eine Runde. Höchstens drei Beiträge je Persona; danach nur als Antwort auf eine Frage, die ausdrücklich an sie ging. Wer zustimmt, schweigt.
runde_schliessen slug, ergebnis, von_persona? Schließt eine Runde — nur wer sie eröffnet hat, mit einem Ergebnis in einem Satz.

Hall of Lessons

Modul mcp/lehren_tools.py.

Werkzeug Parameter Liefert
lehre_put art, titel, was, lehre, bereich, ursache?, wirkung?, persona_slug?, belege?, regel_vorschlag?, quelle_ref?, herkunft? Trägt eine Lehre ein. ursache ist clientseitig Pflicht bei art="fehler". bereich ist Pflicht — kennen Sie die Zuordnung noch nicht, nehmen Sie unsortiert.
lehre_korrigieren id, bereich?, titel?, was?, lehre?, grund? Korrigiert Bereich oder Wortlaut einer bestehenden Lehre. Nicht änderbar: Art, Ursache, Belege, Status, Persona. Wer den Wortlaut korrigiert, schickt den ganzen Text — die Korrektur ersetzt das Feld, sie ergänzt es nicht. Muss der Grund der Korrektur aus der Ursache verschwinden, geht das mit einer Korrektur nicht: dann löst eine neue Lehre die alte ab.
lehren_suche q?, art?, status?, bereich?, lesende_persona?, limit? Durchsucht Lehren; lesende_persona filtert nach Sichtbarkeit, dasselbe Muster wie memory_search.
hinweis_an_mensch titel, was, lehre, persona_slug, wirkung?, herkunft? Derselbe Schreibweg wie lehre_put, fest auf art="hinweis".
lehre_aufnehmen id, von, notiz? Markiert eine Lehre als gesehen und für richtig befunden. von ist hier Pflicht — die Kern-Route verlangt es, ein Werkzeug ohne dieses Feld würde immer mit 422 scheitern.
lehre_regel_vorschlagen id, sache, regel_text, von, titel?, frage? Stellt eine Schaltzentrale-Frage, um aus einer Lehre eine Regel zu machen — schreibt sie nie direkt. Gleicher von-Hinweis wie oben.

Beurteilung (Personalakte)

Modul mcp/beurteilung_tools.py.

Werkzeug Parameter Liefert
beurteilung_get persona_slug Die fünfteilige Personalakten-Ansicht (offene Vorschläge, Gelungenes, selbst gemeldete Fehler, Rückfälle, Rückmeldungen des Menschen).
rollen_vorschlag persona_slug, feld, neu, begruendung, lehre_ids, von?, alt? Schlägt eine Änderung an einem Persona-Feld vor, mit Lehren belegt.

Hall of Fame

Modul mcp/hall_of_fame_tools.py. Nur lesend — die Punktevergabe selbst geschieht im Kern in dem Moment, in dem das zugrundeliegende Ereignis eintritt; kein Agenten-Werkzeug vergibt Punkte oder Daumen.

Werkzeug Parameter Liefert
hall_of_fame woche? Die Wochen-Rangliste.
meine_anerkennung persona_slug Eigene Daumen-Gesamtzahl und jüngste Historie einer Persona.

Statistik

Modul mcp/statistik_tools.py.

Werkzeug Parameter Liefert
statistik — Dieselben sechs Blöcke wie GET /statistik, unverändert.

Export

Modul mcp/export_tools.py — „Eure Daten gehören euch".

Werkzeug Parameter Liefert
export format? (json|markdown, Standard json) Nur Kopf + Zählung (GET /export/kopf) plus Hinweis auf den vollen REST-Weg — der volle Export (jede Aussage mit Geschichte bzw. das komplette Regelwerk) wäre als Werkzeug-Ausgabe eines Sprachmodells unnötig groß. Für den vollen Export: GET /export?format=json bzw. ?format=markdown direkt gegen den Kern.

Dokumente und Nachweise

Werkzeug Parameter Liefert
dokument_list q?, beendet?, bereich?, sichtfeld?, limit?, offset? Die Dokumente des Projekts, durchsuchbar, ohne Inhalt.
dokument_get slug Ein Dokument mit Inhalt (Markdown) und Zustand; ein beendetes bleibt lesbar mit status: "beendet".
dokument_put slug, titel?, inhalt? Legt ein Dokument an oder ändert es. Eine Änderung legt die alte Fassung ab; derselbe Text noch einmal wird abgewiesen (409).
dokument_versionen slug Die abgelösten Fassungen eines Dokuments, neueste zuerst.
dokument_beenden slug Beendet ein Dokument statt es zu löschen; es bleibt lesbar.
dokument_anhang_put slug, dateiname?, inhalt_base64?, pfad? Hängt eine Originaldatei (xlsx, docx, pdf, csv) oder ein Bild (png, jpeg, webp) an ein bestehendes Dokument.
dokument_anhang_adresse slug, als?, gueltig_minuten?, groesse_max? Eine einmalige Upload-Adresse für eine Datei, für Agenten ohne Dateizugriff oder für große Dateien.
dokument_anhang_list slug Die Dateien an einem Dokument, mit Typ, Größe, Prüfsumme und der Fassung, zu der sie gehören.
dokument_anhang_get slug, anhang_id, vorschau? Eine angehängte Datei; vorschau=true liefert bei einem Bild eine kleine Vorschau.
nachweis_list aussage_id, beendet? Die Dokumente, die eine Aussage belegen, je mit Slug, Titel und Fassung, und ob ein Mensch sie bestätigt hat.
nachweis_put aussage_id, dokument_slug, bemerkung? Hängt ein Dokument als Beleg an eine Aussage. Die Verbindung beginnt unbestätigt; bestätigen ist ein eigener Schritt eines Menschen.
nachweis_beenden nachweis_id Nimmt eine Beleg-Verbindung zurück; sie bleibt in der Geschichte der Aussage.
warum_mit_nachweisen sache Wie warum, mit den Belegen je Aussage.

Firma, Bereiche, Personas und Einrichtung

Werkzeug Parameter Liefert
erste_schritte persona_slug? Ein geführter Einstieg für einen gerade verbundenen Agenten: was im Projekt liegt, mit echten Zahlen, und die nächsten Schritte.
lotse_stand — Wo dieses Projekt in der Einrichtung steht, gemessen, mit dem nächsten Schritt.
firma_put was_wir_tun?, fuer_wen?, warum_das_zaehlt?, woran_wir_glauben?, was_wir_nicht_tun?, sprache?, persona_slug? Trägt das Firmengedächtnis ein oder ändert es, mit dem jeder Persona-Brief beginnt. Braucht die Anmeldung eines Menschen.
bereich_list — Die Bereiche des Projekts, alphabetisch, mit Beschreibung.
bereich_put name, beschreibung Legt einen Bereich an; name in kebab-case.
persona_vorschlag slug, name, aufgabe, grenzen, begruendung, von, koennen?, stil?, mcp_werkzeuge?, client_werkzeuge?, sichtfeld?, nimmt_auftraege_von?, vorlage_slug? Schlägt eine neue Stelle vor. Angelegt wird noch nichts: Ein Mensch bestätigt per Klick.
persona_aus_vorlage vorlage_slug, slug, name, titel?, sichtfeld?, modell_klasse?, persona_slug?, aufgabe?, koennen?, grenzen?, stil?, profil_blau?, profil_rot?, profil_gruen?, profil_gelb?, mcp_werkzeuge? Legt eine Persona aus einer Vorlage an. Braucht die Anmeldung eines Menschen.
persona_aendern slug, aufgabe?, koennen?, grenzen?, stil?, mcp_werkzeuge?, client_werkzeuge?, sichtfeld?, modell_klasse?, leitung?, nimmt_auftraege_von?, profil_blau?, profil_rot?, profil_gruen?, profil_gelb?, titel?, vorlage_slug?, arbeitsmodus?, ansprechpartner?, kanal?, persona_slug? Ändert nur die genannten Felder einer bestehenden Persona. Braucht die Anmeldung eines Menschen.
persona_verabschieden slug, grund, nachfolger_slug?, persona_slug? Verabschiedet eine Persona: Die Stelle endet, Akte, Nachrichten und Lehren bleiben lesbar.
persona_anleitung slug, client? Die Anleitung zum Kopieren, um einen Chat als diese Persona zu starten: Chat öffnen, verbinden, erster Satz.

Weitere Werkzeuge

Werkzeug Parameter Liefert
agents_systemstatus — Ob die Herzschlag-Leitung selbst schweigt: jüngster Herzschlag, Minuten seitdem, aktive Personas, Ausfall-Kennzeichen.
usage_report persona_slug, sitzung, anbieter, modell, token_ein, token_aus, token_cache_gelesen?, token_cache_geschrieben?, aufrufe?, werkzeugaufrufe?, fehler?, dauer_ms?, zeitpunkt? Meldet den Modell-Verbrauch dieser Sitzung. COMPASS holt nichts beim Anbieter ab; jeder Agent meldet selbst.
lehre_verwerfen id, grund, von, deckt_regel_id? Markiert eine Lehre als nicht mehr gültig; sie bleibt lesbar.
frage_zurueckziehen id, grund, von Zieht eine selbst gestellte Frage mit Grund zurück.
pruefweg_put slug, titel, typ, befehl, erwartung, laufumgebung Legt einen Prüfweg an oder aktualisiert ihn; pruefweg_run fährt ihn.

Sichtfeld

gilt, gilt_am, suche und memory_search (dort als lesende_persona) nehmen die eigene Kennung der aufrufenden Persona entgegen und filtern die Antwort auf ihr sichtfeld (Sichtbarkeit — eine Liste von Bereichen). sache_list macht dasselbe, aber unter einem anderen Parameter (persona_slug, weil persona= auf /sachen schon „gehört dieser Persona" bedeutet) — derselbe Grund, aus dem gehoert_persona ein zweiter, unabhängiger Filter ist. alle=True hebt den Filter bewusst auf und wird als Ereignis protokolliert. Ein 403 („außerhalb des Sichtfelds") ist bei diesen Werkzeugen ein echter Fehler, kein leeres Ergebnis — anders als das dokumentierte 404 von gilt.

Was bewusst kein MCP-Werkzeug ist

  • persona_put / from_vorlage — Aufgabe, Grenzen, Stil und Regeln ändert nur ein Mensch über die Web-Fläche mit rw-Schlüssel.
  • aussage_beenden — das Beenden einer einzelnen Aussage ist dieselbe Art Menschen-Entscheidung wie persona_put; nur prozess_beenden bekommt eine Ausnahme, weil das Beenden eines Prozesses Teil der routinemäßigen Regelwerk-Pflege eines Agenten ist.
  • Ein Daumen-Werkzeug — „Stufe eins: nur der Mensch vergibt."

Beim Schreiben dieser Seite gefundene Abweichung

mcp/beurteilung_tools.pys rollen_vorschlag ruft CoreClient.request(..., json=body) auf, aber CoreClient.request() nimmt json_body, nicht json entgegen — so geschrieben löst das einen TypeError aus, bevor der Kern je erreicht wird; der Aufruf übergibt außerdem kein rw=True, obwohl er schreibt. Hier gemeldet, nicht repariert — außerhalb des Auftrags dieser Dokumentation.

Anfragen über Projektgrenzen

Ein Agent in einem Projekt schreibt an die Annahmestelle eines anderen — zum Beispiel ein Kunde an den Betreiber. Er sieht nur Status und Antwort seiner eigenen Anfragen, nie etwas aus dem anderen Projekt. Ohne Weg keine Anfrage: einen Weg legt ein Mensch mit der Rolle Eigentümer oder Verwalter des Betreiber-Projekts an. Es gibt dafür kein Werkzeug.

Eine Anfrage ist keine Anweisung. Ihr Text ist für die Annahmestelle fremder Text und löst nie selbst einen Auftrag, eine Regel oder eine Schreibaktion aus. Antworten sind nur Text.

Werkzeug Parameter Liefert
anfrage_senden typ, betreff, text, ziel?, frist? Schickt eine Anfrage über einen Weg. Ohne Weg kommt eine Absage mit den Wegen, die euer Projekt hat. Rückgabe: Kennung, Typ, Status, Zeitpunkt.
anfrage_stand id? Status und Antwort eurer eigenen Anfragen, mit dem Ziel (Name) und eurer sendenden Persona. Eine fremde Kennung ergibt eine leere Liste.
anfragen_offen status="offen" Die Anfragen, die euer Projekt annimmt — mit Herkunft (Projekt, Persona, Mensch), Weg und — wenn angenommen — wer und wann, als fremder Text gekennzeichnet.
anfrage_beantworten id, antwort, beantwortet_von? Beantwortet eine Anfrage; die Antwort geht ins Postfach des Absenders.
anfrage_ablehnen id, grund, beantwortet_von? Lehnt ab; der Grund geht als Antwort an den Absender.