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

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`, но у корневого проекта пространства схлопывается до одного сегмента, поэтому его берут из ответа дословно, а не выводят по правилу. Личный домен в список не входит (подразумевается из токена).

Порядок вызовов

start_session → (нужен проект?) get_my_projects → обзор структуры list_notes/recent_activity → search/recall перед записью → create_note/remember_*/edit_note/link.

Этот порядок — рекомендация, а не механизм: какой инструмент вызвать, решает модель. Чтобы он соблюдался сам, закрепите его в постоянной инструкции агента — Правила агента.

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 — Память агента.

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 по заголовку ещё-не-созданной заметки). Обе заметки в одном пространстве.

Запись под защитой 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, идемпотентен.

Дальше

Память агента — remember и recall в деталях.
Контекст-наборы и пины — что попадает в start_session.
Безопасность и видимость — как набор разрывает «lethal trifecta».