---
title: "Intent-Tools"
description: "Der vollständige Satz von 21 Intent-Tools im MCP-Gateway, nach Zweck gruppiert: Bootstrap, Navigation, Lesen, Schreiben, Reorganisation und Skalierung."
---

# 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). |

> [!tip] Aufrufreihenfolge
> `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](/docs/agents/agent-files/).

## 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](/docs/agents/memory/).

## 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. |

> [!important] Schreibvorgänge durch CAS geschützt
> `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](/docs/agents/memory/) — Erinnern und Abrufen im Detail.
- [Kontext-Sets und Pins](/docs/agents/context-pins/) — was in `start_session` einfließt.
- [Sicherheit und Sichtbarkeit](/docs/agents/security/) — wie dieses Toolset die „lethal trifecta“ durchbricht.