Intent Tools
The MCP gateway hands the agent not generic CRUD but 21 intent-oriented tools — each one expresses an intent ("create a note," "recall context," "rename a project") rather than an operation on a table. This set draws boundaries by construction: the agent doesn't pick the space or the note's class — the tool itself imposes that, and the token's scope determines which tools are even visible.
The names and descriptions the agent sees in tools/list are static — note content is never mixed into them (protection against tool-poisoning).
Token scope — the visibility ceiling
A read token sees only the reading tools; writing tools don't appear in tools/list at all. On top of that, every call checks access to the specific space. So the tables below are the maximum; the actual set depends on your token.
Bootstrap
Session-start tools: who am I, what's available to me, what changed.
| Tool | Purpose |
|---|---|
start_session | Call it first in a new session. In a single request: the user profile (always loaded), available projects, and — with a project hint — a compact project index (note count + top-level folders), the delta of changes since your last visit, and knownValues (a dictionary of the categories/tags in use). Idempotent; not required to call — you just get less context. |
whoami | Who I am (principal id), my ceiling (read/write), project memberships, and the engine's capabilities (vector/trash/revisions) — so you don't probe blindly. |
get_my_projects | A flat list of available projects with ready-made handles — for the project argument. A handle usually looks like space/slug, but for a space's root project it collapses to a single segment, so take it from the response verbatim rather than deriving it from a rule. The personal domain isn't in the list (it's implied by the token). |
start_session → (need a project?) get_my_projects → survey the structure with list_notes/recent_activity → search/recall before writing → create_note/remember_*/edit_note/link.
This order is a recommendation, not a mechanism: the model decides which tool to call. To have it followed without prompting, pin it in the agent's standing instructions — Agent rules.
Discover — navigation
| Tool | Purpose |
|---|---|
list_notes | ls for the knowledge base: a folder's direct notes and subfolders (deterministic, paginated). project selects the space, path is the folder (take it from the response verbatim), tag filters. Lists visible notes, not the agent's memory. |
recent_activity | The most recently edited notes ("what was touched lately, needs review"). Each entry: who (human/agent), how, where, when. This isn't the delta from start_session. |
Read — reading and recall
| Tool | Purpose |
|---|---|
search | Hybrid search (semantic + lexical via RRF); when the vector is unavailable, it falls back to full-text search (FTS) — without an error. It also covers the agent's own memory — "search before writing" dedupes that too. Returns ranked snippets with a score and path, not full notes. |
get_note | The full note by ref (note-id or wiki-ref): content, frontmatter, path, class, versionToken (for safe writes), and provenance. In detailed mode — also outline (headings) and links (graph edges). |
recall | Assemble a context bundle around a topic, within a token budget: relevant notes plus their graph neighbors. Richer than search, it pulls from knowledge and from private memory. budgetTokens caps the size. |
More on the difference between search and recall — Agent memory.
Write — writing and intent
| Tool | Purpose |
|---|---|
create_note | Create a new shared (KB) note in a project, class user-doc. body (Markdown) sets the note's title from a leading # H1; path? is the destination folder; type?/tags? are optional override parameters; links? adds typed edges right away. The agent doesn't pick the class or the space. |
remember_about_user | Record a long-lived fact about the user (preferences, context) into their private memory. Appends an observation under a category. |
remember_about_project | Record a fact about a project into the agent's private memory (class agent-memory, symmetric to remember_about_user). Not shared knowledge — use create_note for that. |
edit_note | Edit a note incrementally by words, not by positions: append/prepend, replace (the whole body), replaceSection (by heading), findReplace (a unique snippet; empty content = delete). Requires a versionToken (CAS). |
delete_note | Move a note to the trash — the agent's only destructive action, reversible by design. Only a human restores or empties the trash. |
link | A typed link from→target. The target is to (note-id) or toTitle (a forward-ref by the title of a not-yet-created note). Both notes in the same space. |
edit_note requires a versionToken from a fresh get_note. A concurrent edit returns a versionConflict error — the tool doesn't silently overwrite someone else's changes; the agent re-reads and retries.
Reorganize
The grammar of the reorg tools is verb_entity. A note is addressed by id, a folder by path, a project by handle.
| Tool | Purpose |
|---|---|
move_note | Move a note to another folder, keeping its name. The id and URL stay stable, incoming links don't break. |
rename_note | Change a note's title. Link-safe: the old title goes into alias history, incoming [[links]] keep resolving. |
move_folder | Move an entire folder with its contents under a different parent. The ids of all notes inside stay stable. |
rename_folder | Rename a folder in place. If the folder is a project, its handle doesn't change (for the handle — rename_project). |
rename_project | Change a project's handle and/or its human-readable name. Link-safe: the old handle goes into an alias. |
Scale — migration at scale
| Tool | Purpose |
|---|---|
create_notes | Create several KB notes in one project per call. Best-effort, not transactional: results[] marks each one ok/error — retry only the failed ones. |
link_many | Create several typed links per call. Best-effort, idempotent. |
Next
- Agent memory — remember and recall in detail.
- Context sets and pins — what goes into
start_session. - Security and visibility — how the set breaks the "lethal trifecta."