---
title: "Herramientas de intención"
description: "Las 21 herramientas de intención de la pasarela MCP, agrupadas por propósito: bootstrap, navegación, lectura, escritura, reorganización y escala."
---

# Herramientas de intención

La pasarela MCP no le entrega al agente un CRUD genérico, sino **21 herramientas orientadas a la intención**: cada una expresa una intención («crear una nota», «recuperar contexto», «renombrar un proyecto») en lugar de una operación sobre una tabla. Este conjunto traza los límites por construcción: el agente no elige el espacio ni la clase de la nota — eso lo impone la propia herramienta, y el alcance del token determina qué herramientas son siquiera visibles.

Los nombres y las descripciones que el agente ve en `tools/list` son estáticos: el contenido de las notas nunca se mezcla en ellos (protección contra el tool-poisoning).

## Alcance del token — el techo de visibilidad

Un token `read` solo ve las herramientas de lectura; las de escritura no aparecen en `tools/list` en absoluto. Además, cada llamada comprueba el acceso al espacio concreto. Por eso las tablas de abajo son el máximo; el conjunto real depende de tu token.

## Bootstrap

Herramientas de arranque de sesión: quién soy, qué tengo disponible, qué cambió.

| Herramienta | Propósito |
|---|---|
| `start_session` | Llámala **primero** en una sesión nueva. En una sola petición: el perfil del usuario (siempre se carga), los proyectos disponibles y —con una pista `project`— un índice compacto del proyecto (número de notas + carpetas de primer nivel), el delta de cambios desde tu última visita y `knownValues` (un diccionario de las categorías/etiquetas en uso). Idempotente; no es obligatorio llamarla — simplemente obtienes menos contexto. |
| `whoami` | Quién soy (principal id), mi techo de permisos (`read`/`write`), las membresías de proyecto y las `capabilities` del motor (`vector`/`trash`/`revisions`) — para no tantear a ciegas. |
| `get_my_projects` | Una lista plana de los proyectos disponibles con los handles ya listos — para el argumento `project`. Un handle suele tener la forma `space/slug`, pero en el proyecto raíz de un espacio se reduce a un único segmento, así que tómalo tal cual de la respuesta en lugar de deducirlo por una regla. El dominio personal no está en la lista (queda implícito por el token). |

> [!tip] Orden de llamadas
> `start_session` → (¿necesitas un proyecto?) `get_my_projects` → explora la estructura con `list_notes`/`recent_activity` → `search`/`recall` **antes de escribir** → `create_note`/`remember_*`/`edit_note`/`link`.

Este orden es una recomendación, no un mecanismo: qué herramienta llamar lo decide el modelo. Para que se respete sin recordárselo, fíjalo en las instrucciones permanentes del agente — [Reglas del agente](/docs/agents/agent-files/).

## Discover — navegación

| Herramienta | Propósito |
|---|---|
| `list_notes` | El `ls` de la base de conocimiento: las notas directas y las subcarpetas de una carpeta (determinista, paginado). `project` selecciona el espacio, `path` es la carpeta (tómala de la respuesta tal cual), `tag` filtra. Lista las notas visibles, no la memoria del agente. |
| `recent_activity` | Las notas editadas más recientemente («qué se tocó últimamente, hay que revisar»). Cada entrada: quién (humano/agente), cómo, dónde, cuándo. Esto no es el delta de `start_session`. |

## Read — lectura y recuperación

| Herramienta | Propósito |
|---|---|
| `search` | Búsqueda híbrida (semántica + léxica vía RRF); cuando el vector no está disponible, recurre a la búsqueda de texto completo (FTS) — sin error. También abarca **la propia memoria del agente** — «buscar antes de escribir» también evita duplicados allí. Devuelve fragmentos ordenados por relevancia con un `score` y un `path`, no notas completas. |
| `get_note` | La nota completa por ref (note-id o wiki-ref): contenido, frontmatter, `path`, `class`, `versionToken` (para escrituras seguras) y procedencia. En modo `detailed` — además `outline` (encabezados) y `links` (aristas del grafo). |
| `recall` | Ensambla un paquete de contexto en torno a un tema, dentro de un presupuesto de tokens: notas relevantes **más** sus vecinos en el grafo. Más rico que `search`, extrae del conocimiento y de la memoria privada. `budgetTokens` limita el tamaño. |

Más sobre la diferencia entre `search` y `recall` — [Memoria del agente](/docs/agents/memory/).

## Write — escritura e intención

| Herramienta | Propósito |
|---|---|
| `create_note` | Crea una nueva nota compartida (KB) en un proyecto, clase `user-doc`. El `body` (Markdown) fija el título de la nota a partir de un `# H1` inicial; `path?` es la carpeta de destino; `type?`/`tags?` son parámetros opcionales de sobrescritura; `links?` añade aristas tipadas de inmediato. El agente no elige la clase ni el espacio. |
| `remember_about_user` | Registra un hecho de larga duración sobre el usuario (preferencias, contexto) en su memoria privada. Añade una `observation` bajo una `category`. |
| `remember_about_project` | Registra un hecho sobre un proyecto en la memoria privada del agente (clase `agent-memory`, simétrica a `remember_about_user`). No es conocimiento compartido — para eso usa `create_note`. |
| `edit_note` | Edita una nota de forma incremental por palabras, no por posiciones: `append`/`prepend`, `replace` (todo el cuerpo), `replaceSection` (por encabezado), `findReplace` (un fragmento único; `content` vacío = eliminar). Requiere un `versionToken` (CAS). |
| `delete_note` | Mueve una nota **a la papelera** — la única acción destructiva del agente, reversible por diseño. Solo un humano restaura o vacía la papelera. |
| `link` | Un enlace tipado `from`→destino. El destino es `to` (note-id) o `toTitle` (una referencia adelantada por el título de una nota aún no creada). Ambas notas en el mismo espacio. |

> [!important] Escrituras protegidas por CAS
> `edit_note` requiere un `versionToken` de un `get_note` reciente. Una edición concurrente devuelve un error `versionConflict` — la herramienta no sobrescribe los cambios de otro en silencio; el agente vuelve a leer y reintenta.

## Reorganize

La gramática de las herramientas de reorganización es `verb_entity`. Una nota se direcciona por id, una carpeta por `path`, un proyecto por handle.

| Herramienta | Propósito |
|---|---|
| `move_note` | Mueve una nota a otra carpeta, conservando su nombre. El id y la URL permanecen estables, los enlaces entrantes no se rompen. |
| `rename_note` | Cambia el título de una nota. Es link-safe: el título antiguo pasa al historial de alias, los `[[enlaces]]` entrantes siguen resolviéndose. |
| `move_folder` | Mueve una carpeta entera con su contenido bajo otro padre. Los ids de todas las notas dentro permanecen estables. |
| `rename_folder` | Renombra una carpeta en su lugar. Si la carpeta es un proyecto, su handle no cambia (para el handle — `rename_project`). |
| `rename_project` | Cambia el handle de un proyecto y/o su nombre legible por humanos. Es link-safe: el handle antiguo pasa a un alias. |

## Scale — migración a escala

| Herramienta | Propósito |
|---|---|
| `create_notes` | Crea varias notas KB en un proyecto por llamada. Best-effort, no transaccional: `results[]` marca cada una como `ok`/`error` — reintenta solo las que fallaron. |
| `link_many` | Crea varios enlaces tipados por llamada. Best-effort, idempotente. |

## Siguiente

- [Memoria del agente](/docs/agents/memory/) — recordar y recuperar en detalle.
- [Conjuntos de contexto y pins](/docs/agents/context-pins/) — qué entra en `start_session`.
- [Seguridad y visibilidad](/docs/agents/security/) — cómo el conjunto rompe la «trifecta letal».