---
title: "Intent Tools"
description: "The full set of 21 intent tools in the MCP gateway, grouped by purpose: bootstrap, navigation, reading, writing, reorganization, and scale."
---

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

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

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

> [!important] Writes protected by CAS
> `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](/docs/agents/memory/) — remember and recall in detail.
- [Context sets and pins](/docs/agents/context-pins/) — what goes into `start_session`.
- [Security and visibility](/docs/agents/security/) — how the set breaks the "lethal trifecta."