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). |
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.
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.
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. |
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 — recordar y recuperar en detalle.
- Conjuntos de contexto y pins — qué entra en
start_session. - Seguridad y visibilidad — cómo el conjunto rompe la «trifecta letal».