---
title: "Outils d'intention"
description: "Les 21 outils d'intention de la passerelle MCP, regroupés par usage : bootstrap, navigation, lecture, écriture, réorganisation et passage à l'échelle."
---

# Outils d'intention

La passerelle MCP ne remet pas à l'agent un CRUD générique, mais **21 outils orientés intention** — chacun exprime une intention (« créer une note », « rappeler un contexte », « renommer un projet ») plutôt qu'une opération sur une table. Cet ensemble trace des limites par construction : l'agent ne choisit ni l'espace ni la classe de la note — c'est l'outil lui-même qui l'impose, et la portée du jeton détermine quels outils sont visibles tout court.

Les noms et descriptions que l'agent voit dans `tools/list` sont statiques — le contenu des notes n'y est jamais mélangé (protection contre le tool-poisoning).

## Portée du jeton — le plafond de visibilité

Un jeton `read` ne voit que les outils de lecture ; les outils d'écriture n'apparaissent pas du tout dans `tools/list`. De plus, chaque appel vérifie l'accès à l'espace concerné. Les tableaux ci-dessous représentent donc le maximum ; l'ensemble réel dépend de votre jeton.

## Bootstrap

Outils de démarrage de session : qui suis-je, ce qui m'est accessible, ce qui a changé.

| Outil | Fonction |
|---|---|
| `start_session` | À appeler **en premier** dans une nouvelle session. En une seule requête : le profil de l'utilisateur (toujours chargé), les projets accessibles et — si vous précisez `project` — un index compact du projet (nombre de notes + dossiers de premier niveau), le delta des changements depuis votre dernière visite, ainsi que `knownValues` (un dictionnaire des catégories/tags utilisés). Idempotent ; son appel n'est pas obligatoire — vous obtenez simplement moins de contexte. |
| `whoami` | Qui je suis (id du principal), mon plafond (`read`/`write`), mes appartenances aux projets et les `capabilities` du moteur (`vector`/`trash`/`revisions`) — pour ne pas tâtonner à l'aveugle. |
| `get_my_projects` | Une liste à plat des projets accessibles avec leurs handles prêts à l'emploi — pour l'argument `project`. Un handle a généralement la forme `space/slug`, mais pour le projet racine d'un espace il se réduit à un seul segment : reprenez-le tel quel depuis la réponse plutôt que de le déduire d'une règle. Le domaine personnel ne figure pas dans la liste (il est implicite dans le jeton). |

> [!tip] Ordre des appels
> `start_session` → (besoin d'un projet ?) `get_my_projects` → parcourir la structure avec `list_notes`/`recent_activity` → `search`/`recall` **avant d'écrire** → `create_note`/`remember_*`/`edit_note`/`link`.

Cet ordre est une recommandation, pas un mécanisme : c'est le modèle qui décide quel outil appeler. Pour qu'il soit respecté sans rappel de votre part, inscrivez-le dans les instructions permanentes de l'agent — [Règles de l'agent](/docs/agents/agent-files/).

## Discover — navigation

| Outil | Fonction |
|---|---|
| `list_notes` | Le `ls` de la base de connaissances : les notes directes et sous-dossiers d'un dossier (déterministe, paginé). `project` sélectionne l'espace, `path` désigne le dossier (à reprendre tel quel depuis la réponse), `tag` filtre. Liste les notes visibles, pas la mémoire de l'agent. |
| `recent_activity` | Les notes modifiées le plus récemment (« ce qui a été touché dernièrement, à relire »). Chaque entrée : qui (humain/agent), comment, où, quand. Ce n'est pas le delta de `start_session`. |

## Read — lecture et rappel

| Outil | Fonction |
|---|---|
| `search` | Recherche hybride (sémantique + lexicale via RRF) ; quand la recherche vectorielle est indisponible, elle se rabat sur la recherche plein texte (FTS) — sans erreur. Elle couvre aussi **la mémoire propre de l'agent** — « chercher avant d'écrire » y élimine également les doublons. Renvoie des extraits classés avec un `score` et un `path`, pas des notes entières. |
| `get_note` | La note complète par ref (note-id ou wiki-ref) : contenu, frontmatter, `path`, `class`, `versionToken` (pour des écritures sûres) et provenance. En mode `detailed` — aussi `outline` (les titres) et `links` (les arêtes du graphe). |
| `recall` | Assembler un bloc de contexte autour d'un sujet, dans un budget de tokens : les notes pertinentes **plus** leurs voisines dans le graphe. Plus riche que `search`, il puise dans la connaissance et dans la mémoire privée. `budgetTokens` en plafonne la taille. |

Plus de détails sur la différence entre `search` et `recall` — [Mémoire de l'agent](/docs/agents/memory/).

## Write — écriture et intention

| Outil | Fonction |
|---|---|
| `create_note` | Créer une nouvelle note partagée (KB) dans un projet, classe `user-doc`. `body` (Markdown) définit le titre de la note à partir d'un `# H1` en tête ; `path?` est le dossier de destination ; `type?`/`tags?` sont des paramètres de surcharge optionnels ; `links?` ajoute d'emblée des arêtes typées. L'agent ne choisit ni la classe ni l'espace. |
| `remember_about_user` | Enregistrer un fait durable sur l'utilisateur (préférences, contexte) dans sa mémoire privée. Ajoute une `observation` sous une `category`. |
| `remember_about_project` | Enregistrer un fait sur un projet dans la mémoire privée de l'agent (classe `agent-memory`, symétrique de `remember_about_user`). Ce n'est pas de la connaissance partagée — pour cela, utilisez `create_note`. |
| `edit_note` | Modifier une note de façon incrémentale par mots, pas par positions : `append`/`prepend`, `replace` (le corps entier), `replaceSection` (par titre de section), `findReplace` (un extrait unique ; `content` vide = supprimer). Requiert un `versionToken` (CAS). |
| `delete_note` | Déplacer une note **vers la corbeille** — la seule action destructrice de l'agent, réversible par conception. Seul un humain restaure ou vide la corbeille. |
| `link` | Un lien typé `from`→cible. La cible est `to` (note-id) ou `toTitle` (une référence anticipée par le titre d'une note pas encore créée). Les deux notes dans le même espace. |

> [!important] Écritures protégées par CAS
> `edit_note` requiert un `versionToken` issu d'un `get_note` récent. Une modification concurrente renvoie une erreur `versionConflict` — l'outil n'écrase pas silencieusement les changements d'autrui ; l'agent relit et réessaie.

## Reorganize

La grammaire des outils de réorganisation est `verb_entity`. Une note se désigne par son id, un dossier par `path`, un projet par son handle.

| Outil | Fonction |
|---|---|
| `move_note` | Déplacer une note vers un autre dossier, en conservant son nom. L'id et l'URL restent stables, les liens entrants ne se cassent pas. |
| `rename_note` | Changer le titre d'une note. Link-safe : l'ancien titre passe dans l'historique des alias, les `[[links]]` entrants continuent de se résoudre. |
| `move_folder` | Déplacer un dossier entier avec son contenu sous un autre parent. Les id de toutes les notes qu'il contient restent stables. |
| `rename_folder` | Renommer un dossier sur place. Si le dossier est un projet, son handle ne change pas (pour le handle — `rename_project`). |
| `rename_project` | Changer le handle et/ou le nom lisible d'un projet. Link-safe : l'ancien handle passe dans un alias. |

## Scale — migration à grande échelle

| Outil | Fonction |
|---|---|
| `create_notes` | Créer plusieurs notes KB dans un même projet par appel. Best-effort, non transactionnel : `results[]` marque chacune `ok`/`error` — ne réessayer que celles en échec. |
| `link_many` | Créer plusieurs liens typés par appel. Best-effort, idempotent. |

## Ensuite

- [Mémoire de l'agent](/docs/agents/memory/) — remember et recall en détail.
- [Jeux de contexte et épingles](/docs/agents/context-pins/) — ce qui entre dans `start_session`.
- [Sécurité et visibilité](/docs/agents/security/) — comment l'ensemble brise la « lethal trifecta ».