Intent-Tools
Das MCP-Gateway reicht dem Agenten kein generisches CRUD, sondern 21 intent-orientierte Tools — jedes drückt eine Absicht aus („eine Notiz anlegen“, „Kontext abrufen“, „ein Projekt umbenennen“) statt einer Operation auf einer Tabelle. Dieses Toolset zieht die Grenzen schon durch seine Konstruktion: Der Agent wählt weder den Space noch die Klasse der Notiz — das gibt das Tool selbst vor, und der Scope des Tokens entscheidet, welche Tools überhaupt sichtbar sind.
Die Namen und Beschreibungen, die der Agent in tools/list sieht, sind statisch — Notizinhalte fließen niemals hinein (Schutz vor Tool-Poisoning).
Token-Scope — die Obergrenze der Sichtbarkeit
Ein read-Token sieht nur die lesenden Tools; schreibende erscheinen in tools/list gar nicht erst. Zusätzlich prüft jeder Aufruf den Zugriff auf den konkreten Space. Die folgenden Tabellen sind also das Maximum; das tatsächlich verfügbare Toolset hängt von deinem Token ab.
Bootstrap
Tools für den Sessionstart: wer bin ich, was steht mir offen, was hat sich geändert.
| Tool | Zweck |
|---|---|
start_session | Als Erstes in einer neuen Session aufrufen. In einem einzigen Request: das Benutzerprofil (immer geladen), die verfügbaren Projekte und — mit einem project-Hinweis — ein kompakter Projektindex (Notizanzahl + Ordner der obersten Ebene), das Delta der Änderungen seit deinem letzten Besuch sowie knownValues (ein Wörterbuch der verwendeten Kategorien/Tags). Idempotent; nicht zwingend aufzurufen — du bekommst dann einfach weniger Kontext. |
whoami | Wer ich bin (Principal-ID), meine Obergrenze (read/write), meine Projekt-Mitgliedschaften und die capabilities der Engine (vector/trash/revisions) — damit du nicht blind herumprobierst. |
get_my_projects | Eine flache Liste der verfügbaren Projekte mit fertigen Handles — für das Argument project. Ein Handle sieht üblicherweise wie space/slug aus, schrumpft beim Wurzelprojekt eines Space aber auf ein einziges Segment zusammen; übernimm es deshalb wortwörtlich aus der Antwort, statt es aus einer Regel abzuleiten. Die persönliche Domäne steht nicht in der Liste (sie ist durch das Token impliziert). |
start_session → (ein Projekt nötig?) get_my_projects → Struktur mit list_notes/recent_activity sichten → search/recall vor dem Schreiben → create_note/remember_*/edit_note/link.
Diese Reihenfolge ist eine Empfehlung, kein Mechanismus: Welches Tool aufgerufen wird, entscheidet das Modell. Damit sie von selbst eingehalten wird, verankere sie in den ständigen Anweisungen des Agenten — Agenten-Regeln.
Discover — Navigation
| Tool | Zweck |
|---|---|
list_notes | Das ls der Wissensbasis: die direkten Notizen und Unterordner eines Ordners (deterministisch, paginiert). project wählt den Space, path ist der Ordner (aus der Antwort wortwörtlich übernehmen), tag filtert. Listet sichtbare Notizen auf, nicht das Gedächtnis des Agenten. |
recent_activity | Die zuletzt bearbeiteten Notizen („was kürzlich angefasst wurde, braucht ein Review“). Jeder Eintrag: wer (Mensch/Agent), wie, wo, wann. Das ist nicht das Delta aus start_session. |
Read — Lesen und Recall
| Tool | Zweck |
|---|---|
search | Hybride Suche (semantisch + lexikalisch via RRF); ist der Vektor nicht verfügbar, fällt sie auf die Volltextsuche (FTS) zurück — ohne Fehler. Die Suche erfasst auch das eigene Gedächtnis des Agenten — „vor dem Schreiben suchen“ dedupliziert auch dort. Liefert gerankte Snippets mit score und path, keine vollständigen Notizen. |
get_note | Die vollständige Notiz per Ref (Notiz-ID oder Wiki-Ref): Inhalt, Frontmatter, path, class, versionToken (für sicheres Schreiben) und Provenienz. Im detailed-Modus zusätzlich outline (Überschriften) und links (Kanten des Graphen). |
recall | Ein Kontextbündel um ein Thema herum zusammenstellen, innerhalb eines Token-Budgets: relevante Notizen plus ihre Nachbarn im Graphen. Reicher als search: Es schöpft aus dem Wissen und aus dem privaten Gedächtnis. budgetTokens begrenzt den Umfang. |
Mehr zum Unterschied zwischen search und recall — Agentengedächtnis.
Write — Schreiben und Intent
| Tool | Zweck |
|---|---|
create_note | Eine neue geteilte (KB-)Notiz in einem Projekt anlegen, Klasse user-doc. body (Markdown) setzt den Titel der Notiz aus einer führenden # H1; path? ist der Zielordner; type?/tags? sind optionale Override-Parameter; links? fügt gleich typisierte Kanten hinzu. Die Klasse und den Space wählt der Agent nicht. |
remember_about_user | Einen langlebigen Fakt über den Benutzer (Vorlieben, Kontext) in dessen privates Gedächtnis schreiben. Hängt eine observation unter einer category an. |
remember_about_project | Einen Fakt über ein Projekt in das private Gedächtnis des Agenten schreiben (Klasse agent-memory, symmetrisch zu remember_about_user). Kein geteiltes Wissen — dafür create_note. |
edit_note | Eine Notiz inkrementell nach Wörtern bearbeiten, nicht nach Positionen: append/prepend, replace (der gesamte Body), replaceSection (per Überschrift), findReplace (ein eindeutiges Snippet; leerer content = löschen). Erfordert einen versionToken (CAS). |
delete_note | Eine Notiz in den Papierkorb verschieben — die einzige destruktive Aktion des Agenten, konstruktionsbedingt umkehrbar. Wiederherstellen oder Leeren des Papierkorbs kann nur ein Mensch. |
link | Ein typisierter Link from→Ziel. Das Ziel ist to (Notiz-ID) oder toTitle (eine Vorwärtsreferenz über den Titel einer noch nicht angelegten Notiz). Beide Notizen im selben Space. |
edit_note erfordert einen versionToken aus einem frischen get_note. Eine nebenläufige Bearbeitung liefert einen versionConflict-Fehler — das Tool überschreibt fremde Änderungen nicht stillschweigend; der Agent liest neu und versucht es erneut.
Reorganize
Die Grammatik der Reorg-Tools ist verb_entity. Eine Notiz wird per ID adressiert, ein Ordner per path, ein Projekt per Handle.
| Tool | Zweck |
|---|---|
move_note | Eine Notiz in einen anderen Ordner verschieben, unter Beibehaltung ihres Namens. ID und URL bleiben stabil, eingehende Links brechen nicht. |
rename_note | Den Titel einer Notiz ändern. Link-sicher: Der alte Titel wandert in den Alias-Verlauf, eingehende [[links]] lösen sich weiterhin auf. |
move_folder | Einen ganzen Ordner samt Inhalt unter einen anderen übergeordneten Ordner verschieben. Die IDs aller Notizen darin bleiben stabil. |
rename_folder | Einen Ordner an Ort und Stelle umbenennen. Ist der Ordner ein Projekt, ändert sich sein Handle nicht (für das Handle — rename_project). |
rename_project | Das Handle und/oder den menschenlesbaren Namen eines Projekts ändern. Link-sicher: Das alte Handle wandert in einen Alias. |
Scale — Migration im großen Maßstab
| Tool | Zweck |
|---|---|
create_notes | Mehrere KB-Notizen in einem Projekt pro Aufruf anlegen. Best-Effort, nicht transaktional: results[] kennzeichnet jede als ok/error — nur die fehlgeschlagenen wiederholen. |
link_many | Mehrere typisierte Links pro Aufruf anlegen. Best-Effort, idempotent. |
Weiter
- Agentengedächtnis — Erinnern und Abrufen im Detail.
- Kontext-Sets und Pins — was in
start_sessioneinfließt. - Sicherheit und Sichtbarkeit — wie dieses Toolset die „lethal trifecta“ durchbricht.