---
title: "Интент-инструменты"
description: "Полный набор из 21 интент-инструмента MCP-гейтвея, сгруппированный по назначению: bootstrap, навигация, чтение, запись, реорганизация и масштаб."
---

# Интент-инструменты

MCP-гейтвей отдаёт агенту не generic-CRUD, а **21 интент-ориентированный инструмент** — каждый выражает намерение («создать заметку», «вспомнить контекст», «переименовать проект»), а не операцию над таблицей. Такой набор конструктивно задаёт границы: агент не выбирает пространство или класс заметки — это навязывает сам инструмент, а права токена определяют, какие инструменты вообще видны.

Имена и описания, которые агент видит в `tools/list`, статичны — контент заметок в них никогда не подмешивается (защита от tool-poisoning).

## Права токена — потолок видимости

`read`-токен видит только читающие инструменты; пишущие не появляются в `tools/list` вовсе. Дополнительно каждый вызов проверяет доступ к конкретному пространству. Поэтому таблицы ниже — это максимум; реальный набор зависит от вашего токена.

## Bootstrap

Инструменты старта сессии: кто я, что мне доступно, что изменилось.

| Инструмент | Назначение |
|---|---|
| `start_session` | Звать **первым** в новой сессии. За один запрос: профиль пользователя (загружается всегда), доступные проекты, при указании `project` — компактный индекс проекта (счётчик заметок + папки верхнего уровня), дельта изменений с прошлого визита и `knownValues` (словарь используемых категорий/тегов). Идемпотентен; звать не обязательно — просто меньше контекста. |
| `whoami` | Кто я (principal-id), мой потолок (`read`/`write`), проекты-членства и `capabilities` движка (`vector`/`trash`/`revisions`) — чтобы не пробовать вслепую. |
| `get_my_projects` | Плоский список доступных проектов с готовыми хэндлами — для аргумента `project`. Хэндл обычно имеет вид `space/slug`, но у корневого проекта пространства схлопывается до одного сегмента, поэтому его берут из ответа дословно, а не выводят по правилу. Личный домен в список не входит (подразумевается из токена). |

> [!tip] Порядок вызовов
> `start_session` → (нужен проект?) `get_my_projects` → обзор структуры `list_notes`/`recent_activity` → `search`/`recall` **перед записью** → `create_note`/`remember_*`/`edit_note`/`link`.

Этот порядок — рекомендация, а не механизм: какой инструмент вызвать, решает модель. Чтобы он соблюдался сам, закрепите его в постоянной инструкции агента — [Правила агента](/docs/agents/agent-files/).

## Discover — навигация

| Инструмент | Назначение |
|---|---|
| `list_notes` | `ls` базы знаний: прямые заметки и подпапки папки (детерминированно, пагинируемо). `project` выбирает пространство, `path` — папка (брать из ответа verbatim), `tag` фильтрует. Листит видимые заметки, не память агента. |
| `recent_activity` | Самые свежеправленные заметки («что недавно трогали, надо ревью»). Каждая запись: кто (человек/агент), как, где, когда. Это не дельта из `start_session`. |

## Read — чтение и recall

| Инструмент | Назначение |
|---|---|
| `search` | Гибридный поиск (семантика + лексика через RRF); когда вектор недоступен, поиск продолжает работать по полному тексту (FTS) — без ошибки. Покрывает **и собственную память агента** — «искать перед записью» убирает дубли и в ней. Возвращает ранжированные сниппеты со `score` и `path`, не полные заметки. |
| `get_note` | Полная заметка по ref (note-id или wiki-ref): контент, frontmatter, `path`, `class`, `versionToken` (для безопасной записи) и провенанс. В режиме `detailed` — ещё `outline` (заголовки) и `links` (рёбра графа). |
| `recall` | Собрать контекст-бандл под токен-бюджет вокруг темы: релевантные заметки **плюс** их граф-соседи. Богаче `search`, тянет из знания и из личной памяти. `budgetTokens` ограничивает размер. |

Подробнее о разнице `search` и `recall` — [Память агента](/docs/agents/memory/).

## Write — запись и интент

| Инструмент | Назначение |
|---|---|
| `create_note` | Создать новую общую (KB) заметку в проекте, класс `user-doc`. `body` (Markdown) титулует заметку ведущим `# H1`; `path?` — папка назначения; `type?`/`tags?` — необязательные параметры-оверрайды; `links?` — типизированные рёбра сразу. Класс и пространство агент не выбирает. |
| `remember_about_user` | Записать долгоживущий факт о пользователе (предпочтения, контекст) в его приватную память. Дозапись `observation` под `category`. |
| `remember_about_project` | Записать приватную память агента о проекте (класс `agent-memory`, симметрично `remember_about_user`). Не общее знание — для него `create_note`. |
| `edit_note` | Инкрементально править заметку по словам, не по позициям: `append`/`prepend`, `replace` (тело целиком), `replaceSection` (по заголовку), `findReplace` (уникальный сниппет; пустой `content` = удалить). Требует `versionToken` (CAS). |
| `delete_note` | Переместить заметку **в корзину** — единственный деструктив агента, обратимый по конструкции. Восстанавливает и очищает корзину только человек. |
| `link` | Типизированная связь `from`→цель. Цель — `to` (note-id) или `toTitle` (forward-ref по заголовку ещё-не-созданной заметки). Обе заметки в одном пространстве. |

> [!important] Запись под защитой CAS
> `edit_note` требует `versionToken` из свежего `get_note`. Конкурентная правка возвращает ошибку `versionConflict` — инструмент не затирает чужие изменения молча, агент перечитывает и повторяет.

## Reorganize — реорганизация

Грамматика инструментов реорганизации — `verb_entity`. Заметка адресуется по id, папка — по `path`, проект — по хэндлу.

| Инструмент | Назначение |
|---|---|
| `move_note` | Переместить заметку в другую папку, сохранив имя. id и URL стабильны, входящие ссылки не рвутся. |
| `rename_note` | Сменить заголовок заметки. Link-safe: старый заголовок уходит в alias-историю, входящие `[[ссылки]]` продолжают резолвиться. |
| `move_folder` | Переместить папку целиком с содержимым под другого родителя. id всех заметок внутри стабильны. |
| `rename_folder` | Сменить имя папки на месте. Если папка — проект, её handle не меняется (для handle — `rename_project`). |
| `rename_project` | Сменить handle и/или человеческое имя проекта. Link-safe: старый handle уходит в alias. |

## Scale — масштаб миграции

| Инструмент | Назначение |
|---|---|
| `create_notes` | Создать несколько KB-заметок в одном проекте за вызов. Best-effort, не транзакционно: `results[]` помечает каждую `ok`/`error` — повторять только упавшие. |
| `link_many` | Создать несколько типизированных связей за вызов. Best-effort, идемпотентен. |

## Дальше

- [Память агента](/docs/agents/memory/) — remember и recall в деталях.
- [Контекст-наборы и пины](/docs/agents/context-pins/) — что попадает в `start_session`.
- [Безопасность и видимость](/docs/agents/security/) — как набор разрывает «lethal trifecta».