BovedIA is a persistent, Markdown-based memory server for Claude and other MCP clients, storing and managing notes as plain Markdown files on your local disk.
Read & Write Notes
Read, create, overwrite, or delete notes; delete warns if other notes link to it
Search full-text across titles, content, and tags (AND logic); list notes by category or tag
Get a full vault index (get_index) to orient at session start
Targeted / Partial Editing
Find-and-replace a snippet, append, prepend, update a section by heading, or insert after a section
Lightweight Reads
Peek (frontmatter + first paragraph), read a single section, or read frontmatter only
Category / Folder Management
Create, delete, move, or rename categories; move a single note or bulk-move multiple notes at once (wikilinks auto-updated)
Wikilink & Tag Maintenance
List broken wikilinks, find backlinks, find orphans, globally rename wikilinks
List all hashtags with counts, audit/prune tags, migrate YAML tags to body, update frontmatter fields without touching the body
Vault Health & Maintenance
Validate individual notes, run a full vault health report, list recently updated notes, surface due/scheduled notes
Create, list, and restore snapshots (dry-run by default)
Authorship Tracking (optional, requires KB_ENABLE_ANNOTATIONS=1)
Track which author wrote which ranges of a note (read_authorship); migrate existing notes to include authorship annotations
Memoria personal para Claude Code: tus notas en Markdown, tuyas y para siempre.
Estado del proyecto (28 de agosto de 2026). BovedIA se sigue desarrollando a diario, pero en un repositorio privado: el trabajo del día a día se hace sobre una instalación real y sus pruebas contienen datos de clientes y agenda personal, así que publicarlo tal cual no es una opción responsable.
Lo que hay aquí es una versión estable, completa y probada (v2.8.1, 89 pruebas): funciona, se mantiene instalable y su licencia MIT no cambia. No está abandonada — está congelada a propósito.
Cuando haya material que pueda salir limpio (el módulo de agenda para Apple, la memoria por activación, la búsqueda semántica local), se publicará aquí. Sin fecha comprometida.
BovedIA (bóveda + IA) es un servidor MCP que le da a Claude Code —y a cualquier cliente MCP— memoria persistente. Tus notas viven en archivos Markdown planos, en tu disco, sincronizados en la nube si quieres. La IA puede leerlas, crearlas, buscarlas y organizarlas durante cualquier sesión de trabajo.
Pero BovedIA no es solo el motor. Es también una forma de organizar la memoria para que la IA llegue a cada conversación ligera y enfocada, en vez de arrastrar todo el contexto de golpe. Esa forma va incluida en el vault-example/ de este repositorio, lista para adaptar.
Related MCP server: stickyrice-mcp
Casi todos los sistemas de memoria vuelcan todo el contexto en cada sesión. BovedIA parte de lo contrario: traer solo lo que el caso pide, en el momento en que lo pide. Cargar de más no es solo trabajo desperdiciado — condiciona y ensucia la respuesta.
Para lograrlo, la bóveda se recorre por niveles (la pirámide):
El router (Inicio). La única nota que se lee siempre, al empezar cada conversación. No contiene el trabajo: contiene el criterio para decidir qué cargar y cuándo. Si la señal es clara, la IA actúa; si no, pregunta.
Las portadas de rama. Cada gran área (proyectos, clientes, infraestructura…) tiene una portada que el router carga solo cuando el tema entra por ahí.
Las notas. El contenido real, al que se llega desde su portada o por búsqueda.
Y una capa aparte, el alma: la carpeta donde se vuelca lo que uno piensa y siente — el porqué de fondo, la mentalidad, la manera de mirar el trabajo. No es documentación: es lo que hace que la memoria deje de ser un archivador y empiece a ser continuidad.
Simple: un solo archivo de servidor (index.js), una sola dependencia.
Tuyo: las notas son archivos .md en tu disco — sin bases de datos, sin APIs externas.
Portátil: funciona con iCloud, OneDrive, Google Drive, Dropbox o cualquier carpeta local.
Transparente: abres y editas tus notas en cualquier editor de texto.
El vault-example/ trae una estructura de referencia lista para usar. No es una jaula: crea las categorías que tu trabajo pida. Pero enseña el método completo.
Carpeta / archivo | Para qué sirve |
| El router. Primera nota que se lee en cada sesión: decide qué cargar y cuándo. No carga a ciegas. |
| El mapa. Qué carpeta es qué y dónde va cada cosa. |
| Ejemplo de pendiente sin fecha, en la raíz, marcado con |
| Notas con fecha de activación ( |
| Cómo funciona todo: la pirámide (regla madre), las portadas de rama y los protocolos de sesión. |
| Filosofía y mentalidad; dónde se vuelca lo que uno piensa y siente. Fondo, no operativa. |
| Tus proyectos propios. |
| Una subcarpeta por cliente, con su perfil y contexto. |
| Saber de oficio reutilizable, incluidos los |
| Guías, técnicas y recursos que se consultan pero no cambian a menudo. |
No necesitas clonar nada. Añade esto a la configuración MCP de tu cliente (Claude Code, Claude Desktop…) y copia el vault-example/ a tu carpeta como punto de partida:
{
"mcpServers": {
"bovedia": {
"command": "npx",
"args": ["-y", "bovedia"],
"env": { "KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/boveda" }
}
}
}El resto de esta sección es la instalación manual (clonando el repo), útil si quieres modificar el código.
Node.js 18 o superior
Claude Code (npm install -g @anthropic-ai/claude-code)
Una carpeta sincronizada en la nube (iCloud, OneDrive, Google Drive, Dropbox) — o cualquier carpeta local
git clone https://github.com/jmpdsevilla/BovedIA.git
cd BovedIA/server
npm installCopia la bóveda de ejemplo a tu carpeta sincronizada y personaliza HOME.md e Inicio.md:
# Mac + iCloud
cp -r vault-example ~/Library/Mobile\ Documents/com~apple~CloudDocs/mi-boveda
# Windows + OneDrive (PowerShell)
xcopy /E /I vault-example "%USERPROFILE%\OneDrive\mi-boveda"
# Linux + Dropbox
cp -r vault-example ~/Dropbox/mi-bovedaApunta el servidor a tu bóveda con la variable KB_MEMORY_ROOT (acepta rutas con ~):
{
"mcpServers": {
"bovedia": {
"command": "node",
"args": ["/ruta/absoluta/a/BovedIA/server/index.js"],
"env": {
"KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/mi-boveda"
}
}
}
}Si no defines KB_MEMORY_ROOT (ni su alias MEMORY_PATH), BovedIA usa ~/Documents/bovedia por defecto.
Reinicia Claude Code y pide leer Inicio, o ejecutar get_index. Deberías ver tu bóveda.
BovedIA soporta opcionalmente Markdown Annotations, una spec abierta originalmente de iA Writer que registra qué autor escribió qué parte de cada nota. Cuando se activa, las notas escritas por la IA llevan al final un bloque que atribuye el cuerpo a &Claude; cuando un humano edita la nota en un editor compatible, sus rangos quedan marcados como @nombre, y la siguiente vez que BovedIA toque la nota preserva esa autoría en vez de sobrescribirla.
Está desactivado por defecto. Para activarlo, añade KB_ENABLE_ANNOTATIONS=1 al entorno del servidor:
{
"mcpServers": {
"bovedia": {
"command": "node",
"args": ["/ruta/absoluta/a/BovedIA/server/index.js"],
"env": {
"KB_MEMORY_ROOT": "/ruta/absoluta/a/tu/mi-boveda",
"KB_ENABLE_ANNOTATIONS": "1"
}
}
}
}Con la opción activa se desbloquean dos herramientas: read_authorship (resumen de quién escribió qué) y migrate_annotations (añade el bloque a todas las notas existentes; ejecútala con dry_run: true primero). La firma se puede personalizar con KB_AUTHOR_NAME y KB_AUTHOR_EMAIL.
Solo actívalo si usas un editor compatible con la spec: los que no la soportan mostrarán el bloque como texto plano al final del archivo.
38 en total. Las 36 primeras funcionan siempre. Las 2 de autoría (read_authorship, migrate_annotations) solo se exponen si arrancas el servidor con KB_ENABLE_ANNOTATIONS=1.
El listado de herramientas viaja en cada sesión y ocupa contexto. Si tu cliente tiene poca ventana, arranca con KB_TOOLS=core y se expondrán solo las 15 de uso diario (la mitad de tokens). Por defecto se exponen todas.
Herramienta | Qué hace |
| Crear o actualizar una nota (upsert completo) |
| Leer una nota (busca en todas las categorías) |
| Buscar por texto libre (lógica AND, sin distinguir acentos) |
| Listar notas, filtradas por categoría o etiqueta |
| Mapa de categorías ( |
| Eliminar una nota (avisa de backlinks) |
| Crear una carpeta |
| Mover/renombrar una nota (actualiza wikilinks) |
| Eliminar una carpeta vacía |
Herramienta | Qué hace |
| Buscar/reemplazar dentro de una nota |
| Añadir contenido al final |
| Insertar contenido al principio |
| Reemplazar una sección por su encabezado |
| Insertar una sección nueva tras otra |
Herramienta | Qué hace |
| Todos los wikilinks rotos de la bóveda |
| Backlinks de una nota (sin cargar su contenido) |
| Notas sin backlinks ni enlaces salientes |
| Sustituir |
| Todos los hashtags |
| Actualizar campos YAML sin tocar el cuerpo |
Herramienta | Qué hace |
| Frontmatter + primer párrafo |
| Solo una sección |
| Índice de encabezados de una nota, sin su contenido |
| Solo el YAML |
Herramienta | Qué hace |
| Notas modificadas en los últimos N días |
| Renombrar una carpeta (actualiza el frontmatter de cada nota) |
| Revisar frontmatter, hashtags, "Ver también" y enlaces rotos |
| Mover varias notas a la misma categoría |
| La lista de notas programadas que ya toca sacar hoy, avisando de las que parecen ya hechas o duplicadas. Solo la lista: el contenido se lee al elegir una tarea |
| Salud de las etiquetas (y corrección de las mal formadas) |
| Fusionar variantes y recortar las notas con etiquetas de más |
| Parte de salud de la bóveda en una sola llamada |
| Copia de seguridad completa, a demanda |
| Ver las copias disponibles |
| Volver a una copia anterior (simula por defecto) |
| Bajar al cuerpo las etiquetas que quedan en el frontmatter YAML |
KB_ENABLE_ANNOTATIONS=1)Herramienta | Qué hace |
| Resumen de qué autor escribió qué rangos |
| Añadir el bloque de autoría a las notas existentes |
Referencia completa en docs/tools-reference.md.
Añade esta instrucción a tu CLAUDE.md o a la configuración del asistente para sacarle todo el partido:
Al empezar cada sesión: leer Inicio (el router). Revisar la carpeta programado/
y avisar de lo que ya toca. No cargar nada más "por si acaso".
Guardar lo que merezca recordarse: credenciales, soluciones, decisiones, comandos.
Enlazar las notas con wikilinks [[slug]]. Cada nota termina con una sección
"Ver también" con 2-5 wikilinks.Las notas se enlazan entre sí con el formato [[slug]]:
## Ver también
- [[proyecto-ejemplo]] — proyecto donde se usa esto
- [[cliente-ejemplo]] — cliente al que perteneceReglas:
Usa el slug del nombre de archivo (kebab-case, sin .md).
Sin rutas: [[referencias/x]][[x]].
Sin alias: [[x|otro texto]][[x]].
Cuando una nota se renombra, sus wikilinks se actualizan automáticamente.
Creado por José Manuel Pérez, fundador de santa marta crea — agencia digital. Santa Marta, Colombia.
Web: santamartacrea.com
GitHub: @jmpdsevilla
MIT — libre para usar, modificar y distribuir.
Añadir, agregar, anexar o concatenar contenido al final del cuerpo de una nota sin tocar el resto. Si la nota termina en una línea de hashtags #snake_case, el contenido se inserta antes de los hashtags (preservando la convención de la bóveda). Ideal para notas-bandeja, listas crecientes y logs.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| content | Yes | Contenido Markdown a añadir al final |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It does so by explaining that content is appended to the end, except when the note ends with a hashtag line, in which case content is inserted before the hashtags. This is a non-obvious behavior that is crucial for correct usage. However, it lacks information about idempotency, authorization, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two clear sentences. The first sentence captures the core action efficiently, and the second adds an important edge case. The use of multiple synonyms for 'append' is slightly redundant but does not harm clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description covers the essential usage context and one important edge case. It could improved by mentioning what the tool returns (e.g., success/failure) or error conditions, but for a simple append operation, the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description does not add significant new information about parameters beyond what is in the schema, though it does reinforce that content is Markdown and name is without extension. This is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: appending content to the end of a note body, using multiple synonyms for emphasis. It distinguishes itself from siblings (prepend_to_note, insert_after_section) by specifying 'al final del cuerpo' and describes a special case with hashtags, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit ideal use cases: tray notes, growing lists, and logs. While it doesn't directly mention when not to use or name alternatives, the sibling list makes it clear that prepend_to_note and insert_after_section are alternatives for other insertion positions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auditar, revisar o comprobar la salud de las etiquetas de la bóveda: hashtags mal formados con guión medio (que los editores no agrupan y el extractor trunca), variantes del mismo concepto, etiquetas usadas una sola vez y notas que aún conservan tags en el frontmatter YAML. Devuelve un informe para limpiar la taxonomía.
| Name | Required | Description | Default |
|---|---|---|---|
| fix_dashes | No | Si true, corrige en las notas los hashtags con guión medio pasándolos a snake_case (#nano-banana → #nano_banana). Por defecto false: solo informa. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that by default the tool only reports, and optionally fixes dashes when fix_dashes=true. It lists what issues are checked, providing transparency about its non-destructive default mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the purpose, and the second adds the optional behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description is complete. It states what the tool does, what it returns (a report), and the optional fix_dashes behavior. Could be slightly richer on report format, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter fix_dashes is fully explained in the description, including its effect and an example (#nano-banana → #nano_banana). Schema coverage is 100% and the description adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's purpose: auditing tag health in the vault, including specific issues like malformed hashtags, variants, single-use tags, and YAML frontmatter tags. It uses a specific verb (auditar/revisar/comprobar) and distinguishes from related tools like prune_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for tag cleanup but does not explicitly state when to use this tool versus alternatives like prune_tags or list_tags. No exclusion criteria or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mover, reubicar o desplazar varias notas a la vez a una misma categoría destino. Procesa el array de slugs en una sola llamada. Útil al procesar la bandeja de entrada cuando hay varias notas para la misma carpeta. No renombra — para renombrar usa move_note una a una.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | Lista de slugs (sin extensión .md) a mover | |
| new_category | Yes | Categoría destino para todas las notas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states that the tool processes the array in a single call, implying efficiency, but does not disclose behavior on error (e.g., invalid slug), return values, or side effects like overwriting. Acceptable for a simple move operation but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serves a distinct purpose: action description, efficiency note, and usage guidance with exclusion. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (batch move), and the description covers core purpose, usage context, and differentiation from siblings. No output schema is needed. Minor gaps like error handling are not critical for a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description restates schema descriptions ('Lista de slugs (sin extensión .md) a mover' and 'Categoría destino para todas las notas') without adding new semantic detail, so score remains 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves multiple notes at once to a single destination category, using verbs like 'mover, reubicar o desplazar'. It distinguishes from sibling move_note by explicitly saying 'No renombra — para renombrar usa move_note una a una', making the batch purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Útil al procesar la bandeja de entrada cuando hay varias notas para la misma carpeta' suggests when to use, and the note about not renaming and the alternative move_note clarifies when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crear una nueva subcarpeta o categoría en la base de conocimiento. Úsala antes de guardar la primera nota en una categoría que aún no exista.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nueva categoría |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states creation of a new category, implying no side effects, but does not specify behavior on duplicate names or permissions. Adequate for a simple creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action. Every sentence is purposeful with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 param, no output schema). The description covers what it does and when to use it. It could mention return value but is sufficiently complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'name' described as 'Nombre de la nueva categoría'. The description adds no additional semantics beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Crear una nueva subcarpeta o categoría' (create a new subfolder or category), providing a specific verb and resource. It distinguishes from siblings like move_category or delete_category by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Úsala antes de guardar la primera nota en una categoría que aún no exista' (Use it before saving the first note in a category that doesn't exist yet), giving clear when-to-use context. It lacks explicit alternatives, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crear ahora una copia de seguridad completa de la bóveda, antes de hacer algo arriesgado. Se guarda fuera de la bóveda, con fecha y motivo, y se puede volver a ella con restore_snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Motivo, para reconocerla luego (ej. "antes de reorganizar clientes") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that snapshots are stored outside the vault, with date and reason ('Se guarda fuera de la bóveda, con fecha y motivo'). This is transparent for a backup creation tool, though it could clarify if it overwrites existing snapshots.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main purpose. No unnecessary information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description covers the functionality, behavior, usage context, and relation to siblings. It is complete and sufficient for an AI agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (reason parameter documented). The description adds context by stating that the reason is used 'para reconocerla luego' (to recognize it later), supplementing the schema's 'Motivo, para reconocerla luego (ej. ...)'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: creating a complete backup ('copia de seguridad completa') of the vault, especially before risky actions. It distinguishes itself from siblings like 'restore_snapshot' and 'list_snapshots'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool 'antes de hacer algo arriesgado' (before doing something risky) and mentions the corresponding restore tool ('restore_snapshot') for returning to the snapshot. This provides clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Eliminar o borrar una categoría/subcarpeta vacía. Solo funciona si la carpeta no tiene notas dentro.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la categoría a eliminar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the emptiness constraint, but omits details about what happens if not empty, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently front-load the purpose and condition, with no wasted words. Ideal conciseness for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers the essential purpose and prerequisite. It lacks error handling details but is adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already describes the 'name' parameter. The description adds minimal extra meaning by reaffirming the emptiness condition, but does not provide format or syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Eliminar o borrar') and the resource ('categoría/subcarpeta vacía'), distinguishing it from sibling tools like create_category or move_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the prerequisite (only works if the folder is empty), providing clear context for when to use. It does not explicitly mention when not to use or alternatives, but the condition is strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Eliminar, borrar o quitar una nota de la base de conocimiento. La nota va a la papelera (fuera de la bóveda), así que se puede recuperar. Avisa si otras notas la referencian con wikilinks.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| permanent | No | Si true, borra definitivamente sin pasar por la papelera. Por defecto false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must disclose behaviors. It does so by stating that the note goes to trash (recoverable) and warns about wikilink references. The description could improve by explicitly mentioning the effect of the 'permanent' parameter, but the provided information is sufficient for understanding default behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with three sentences, each serving a distinct purpose: action, result (trash), and side effect (warning). No superfluous information, and it is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description covers the key aspects: what happens to the note (trash), recovery possibility, and a warning feature. It does not explicitly mention the permanent deletion option, but the schema covers it. Overall, it provides adequate context for an AI agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add significant extra meaning beyond the schema; it mentions trash behavior which aligns with the default 'permanent=false', but otherwise the parameter definitions in the schema are already clear. The description does not elaborate on parameter formatting or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('eliminar', 'borrar', 'quitar') to clearly indicate deletion of a note, and it distinguishes this tool from siblings like read_note or write_note by specifying the action and the result (moving to trash). It leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description effectively states when to use this tool (to delete a note) and mentions key behaviors (trash, recoverability, wikilink warnings). However, it does not explicitly advise against using this tool for permanent deletion without the 'permanent' parameter or compare it to alternative tools like 'delete_category'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revisar las notas programadas y devolver SOLO las que ya toca sacar hoy. Lee la fecha > APARECER: AAAA-MM-DD del principio de cada nota de la carpeta de programados y la compara con la fecha actual. Sustituye a mirar una por una: una sola llamada barata para la comprobación de arranque de sesión.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Carpeta de notas programadas. Por defecto "programado". | |
| include_upcoming | No | Si true, incluye también las que aún no han vencido, con su fecha y los días que faltan. Por defecto false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses the tool's read-only behavior: it reads notes from a specified folder, parses a date format, and compares with the current date. It does not mention side effects, which are absent, and describes the logic clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description does not specify the return format (e.g., list of note titles, paths, or full content). It also lacks details about error handling or edge cases like empty folders.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds context about defaults and the meaning of include_upcoming, but does not provide significant extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to review scheduled notes and return only those due today. It specifies the mechanism (reading a date marker from each note) and distinguishes it from manual checking or other tools like read_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is meant for session startup checks ('comprobación de arranque de sesión'), replacing manual per-note inspection. However, it does not explicitly exclude other use cases or compare to siblings like search_notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Editar, modificar, retocar o cambiar una porción concreta de una nota mediante find/replace exacto. Reemplaza old_text por new_text dentro del cuerpo de la nota sin reenviar el archivo entero. Falla si old_text no aparece o aparece más de una vez (ambigüedad). Es la operación más eficiente para correcciones puntuales: una palabra, una línea, una entrada de tabla. Para añadir contenido al final usa append_to_note; para reemplazar una sección entera usa update_section.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| new_text | Yes | Texto nuevo que sustituye a old_text | |
| old_text | Yes | Texto exacto a reemplazar. Debe ser único en la nota — incluye contexto suficiente si la cadena corta podría aparecer varias veces | |
| replace_all | No | Si es true, reemplaza todas las ocurrencias en lugar de fallar por ambigüedad. Por defecto false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively covers key behaviors: exact replacement, failure on missing/ambiguous text, efficiency of not resending the file. Lacks details on permissions or side effects but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with valuable content; slightly verbose but each sentence serves a purpose. Front-loaded with synonyms and key constraints. Could be broken into bullets but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity, the description covers operation, constraints, and alternatives. Missing details like case sensitivity or markdown handling, but largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters (100% coverage). The description adds meaning: explains uniqueness requirement for old_text, context tip, and replace_all behavior. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs an exact find/replace on a note body, using verbs like 'modificar' and 'cambiar'. It explicitly distinguishes from siblings by naming append_to_note and update_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use for precise corrections (word, line, table entry), and not for appending or replacing whole sections. Also warns about failure conditions (ambiguous or missing old_text).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Devolver únicamente los backlinks de una nota (qué notas la referencian), sin cargar su contenido. Más rápido y económico en tokens que read_note cuando solo se quieren los backlinks.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries burden. It discloses it returns only backlinks (no content) and is efficient. No contradictions, but lacks details on output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Purpose and efficiency are front-loaded. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, description is fairly complete: explains purpose, alternative, and benefit. Lacks specification of return format, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'name' with complete schema description. Description adds that it's without .md extension, but schema already covers that. Baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns backlinks of a note without loading content, using specific verb 'Devolver' and resource 'backlinks'. It also distinguishes itself from read_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly compares to read_note, stating it's faster and more token-efficient when only backlinks are needed. However, does not mention other sibling tools like list_broken_links or search_notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar notas huérfanas: notas que no tienen backlinks ni outlinks (no enlazan a ninguna nota ni son enlazadas por nadie). Útil para auditar notas aisladas que probablemente deberían integrarse o eliminarse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the tool's behavior (listing orphans based on link criteria) but does not mention permissions, side effects, or whether it is read-only. Since the operation is inherently non-destructive, the lack of explicit disclosure is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences in Spanish that front-load the purpose and immediately provide the definition and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description is complete. It explains the tool's output (list of orphans) and its utility. The absence of an output schema does not detract from completeness, as the description gives sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100%. The description adds no parameter-specific information, but this is unnecessary. Baseline score of 4 is appropriate per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's function: listing orphan notes (notes with no backlinks or outlinks). It specifies the resource and the filtering criteria, effectively distinguishing it from sibling tools like find_backlinks or list_broken_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: auditing isolated notes that should be integrated or deleted. However, it does not explicitly state when not to use this tool or compare it with alternatives, though the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtener el mapa de categorías de la base de conocimiento con el número de notas de cada una. Devuelve solo el árbol, que es barato; el listado nota a nota (caro en bóvedas grandes) hay que pedirlo con full:true y conviene acotarlo con category.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Si true, lista además cada nota con sus tags y backlinks. Puede ser muy largo: úsalo junto a category. Por defecto false. | |
| category | No | Acotar a una categoría y sus subcarpetas (opcional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that full mode can be very long and expensive, and suggests limiting with category. It lacks mention of permissions or rate limits, but given the context, it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core purpose, then expands on nuances. No unnecessary words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description hints at return structure (category map with note counts, optionally full list). Covers the key trade-offs and usage patterns. Could mention format but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, but description adds value by explaining cost implications for 'full' and scoping for 'category', going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the category map of the knowledge base with note counts, distinguishes between the cheap tree version and expensive full listing, and differs from siblings like list_notes or search_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use tree (cheap) vs full (expensive), recommends using full with category filter to limit impact, and provides context for cost-conscious usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insertar, añadir o intercalar una nueva sección Markdown justo después de otra sección existente, identificada por su título. La sección nueva incluye su propio encabezado dentro de new_content. Útil para añadir entradas en orden a un inventario sin reescribir todo el archivo.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| new_content | Yes | Bloque Markdown nuevo, normalmente empezando por su propio encabezado (ej. "### Adle\n\nDescripción...") | |
| after_section_title | Yes | Título exacto de la sección tras la cual se inserta el contenido nuevo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains that new_content must include its own header and inserts after a title. However, it does not disclose behavior if the after_section_title is not found or any other edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences: the first states the core function, the second provides a use case. No redundant information, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description covers the essential functionality. It explains when to use it and the structure of new_content. Missing error behavior details, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds meaningful context beyond the schema, such as implying the new_content should start with a header and giving an example. This helps the agent understand the expected format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: insert a new Markdown section after an existing section identified by title. It uses specific verbs (insertar, añadir, intercalar) and distinguishes from siblings like append_to_note and prepend_to_note by targeting a specific insertion point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case (adding entries in order to an inventory without rewriting the whole file) but does not explicitly exclude alternatives or state when not to use the tool. Context from sibling tools allows inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar todos los wikilinks rotos de la bóveda (referencias [[slug]] que apuntan a notas inexistentes), agrupados por la nota que los contiene. Operación de mantenimiento: úsala periódicamente para limpiar la bóveda.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It explains the tool lists and groups results by containing note, implying a read-only scan. Though it doesn't detail side effects or auth requirements, for a zero-parameter listing tool, the behavior is adequately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that immediately convey the tool's purpose and usage. Every word serves a purpose, with no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with no parameters and no output schema, the description fully explains what the tool returns (broken links grouped by containing note) and its intended use. It is complete enough for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description adds no parameter info since none exist, matching the baseline expectation for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all broken wikilinks ([[slug]] references to nonexistent notes), grouped by the containing note. This is a specific verb and resource, distinct from sibling tools like find_backlinks or find_orphans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it's a maintenance operation to be used periodically for cleaning the vault, providing clear usage context. While it doesn't explicitly state when not to use it or mention alternatives, the advice is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar notas con sus metadatos, filtradas opcionalmente por categoría y/o tag. El filtro de categoría es RECURSIVO: incluye la categoría indicada y todas sus subcarpetas. Por ejemplo, category "conocimiento" devuelve las notas sueltas en su raíz Y todas las de subcarpetas como "conocimiento/problemas-resueltos". Para ver la estructura completa de carpetas, usa get_index.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Etiqueta opcional para filtrar. Busca tanto en los hashtags del cuerpo (#tipo_proceso) como en los tags del frontmatter YAML de las notas antiguas. Se puede escribir con o sin almohadilla. | |
| category | No | Categoría para filtrar (recursiva): devuelve las notas de esa categoría y de todas sus subcarpetas. Usa la categoría raíz (p. ej. "conocimiento") para todo el árbol, o una subcategoría completa (p. ej. "conocimiento/problemas-resueltos") para acotar a una subcarpeta. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses key behavioral traits: the category filter is recursive and the tag filter searches both hashtags in the body and frontmatter tags. This exceeds the minimum but could mention that the tool is read-only (implied by listing) and what 'metadata' specifically includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each serving a clear purpose: purpose statement, recursive behavior explanation, example, and pointer to sibling tool. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately mentions that notes come with metadata and provides usage guidance. It could be more complete by specifying what metadata is included or noting that the tool is read-only, but it remains sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context: explains the recursive nature of the category filter, provides an example, and clarifies that the tag filter searches both hashtags and frontmatter tags, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists notes with metadata, optionally filtered by category and/or tag. It implicitly distinguishes from siblings like get_index (folder structure) and search_notes (full-text search) by its specific filtering capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (e.g., for listing with optional filters) and explicitly suggests get_index as an alternative for viewing the full folder structure. However, it does not explain when NOT to use this tool compared to siblings like search_notes or list_tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar el índice de secciones (los encabezados) de una nota, con su nivel y su tamaño en líneas, sin devolver el contenido. Sirve para orientarse en notas largas y decidir qué leer: después se lee solo lo necesario con read_section en vez de cargar la nota entera.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool returns a heading index without content, which is the key behavioral trait. No mention of side effects or permissions, but given the read-only nature, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no redundant information. Every sentence adds value: the first defines the tool's output, the second gives usage context. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is complete. It explains the function, what it returns, and how to use it in conjunction with a sibling tool. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is described in the schema as 'Nombre de la nota sin extensión .md'. The description adds no further explanation, but schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'listar' (list) and the resource 'secciones (encabezados) de una nota'. It specifies what is returned (level and line size) and what is not (content). This distinguishes it from siblings like read_note and read_section, which retrieve content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool to orient in long notes and then read only necessary sections via read_section. It provides a clear use case and follow-up action, though it does not explicitly list when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar las copias de seguridad (instantáneas) disponibles de la bóveda, con su fecha y el motivo por el que se hicieron. Se crean solas antes de cada operación masiva, y también se puede crear una a mano con create_snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must cover behavioral traits. It mentions the output (date and reason), but does not disclose if the tool is safe or any side effects. As a simple list operation, it is likely safe, but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, clear and concise. The purpose is front-loaded. Slightly more structure could improve readability, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description adequately covers what it lists (date, reason). It could mention ordering or limits, but is fairly complete given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters, so description is not required to explain parameters. Baseline for 0 params is 4, and the description adds value by explaining what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available snapshots with their date and reason. It distinguishes from siblings by mentioning create_snapshot for manual creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains snapshots are auto-created before bulk operations and can be manually created via create_snapshot, providing context for when snapshots exist. However, it does not explicitly state when to use this tool vs restore_snapshot or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar todos los hashtags #snake_case presentes en el cuerpo de las notas, con el número de notas en que aparece cada uno. Útil para auditar la taxonomía, detectar variantes y mantener consistencia.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description is basic and doesn't disclose scope or access limitations, but for a read-only list it's reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with no parameters, no output schema. Description covers what it does and why it's useful; no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds meaning by explaining the output format (tags with counts).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all hashtags in snake_case from note bodies with counts, which is a specific verb+resource. No sibling tool appears to do this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides use cases (audit taxonomy, detect variants, maintain consistency) but does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Migrar, trasladar o bajar al cuerpo los tags que quedan en el frontmatter YAML, convirtiéndolos en hashtags #snake_case al final de la nota, y dejar el frontmatter limpio. Los tags que ya existen como hashtag no se duplican. Operación one-shot e idempotente: conserva la fecha de modificación y la autoría. Por defecto corre en dry_run para ver qué haría sin tocar nada.
| Name | Required | Description | Default |
|---|---|---|---|
| drop | No | Etiquetas que NO se rescatan al cuerpo: se descartan al vaciar el frontmatter. Útil para ruido genérico. | |
| dry_run | No | Si true (por defecto), no escribe nada y devuelve el informe de lo que haría. Con false ejecuta la migración real. | |
| category | No | Acotar a una categoría y sus subcarpetas (opcional). Útil para migrar por partes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: one-shot operation, idempotent, preserves modification date and authorship, defaults to dry_run, no duplication of existing hashtags, and conversion to snake_case. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of about 5 sentences, front-loaded with the core purpose. It efficiently covers key details without unnecessary repetition, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (3 parameters, no output schema, no annotations), the description adequately explains the operation, including dry-run mode, category filtering, and drop list. It does not specify the output format of dry_run reports, which is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The tool description does not add extra parameter-level meaning beyond the schema (e.g., syntax or examples). Baseline 3 is appropriate as the schema already provides sufficient parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (migrate/trasladar) and resource (YAML frontmatter tags), specifying conversion to hashtags in snake_case, idempotency, and default dry-run behavior. It distinguishes itself from sibling tools like list_tags, prune_tags, or audit_tags by focusing on moving tags from frontmatter to body.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (to migrate tags), notes default dry-run mode for preview, and mentions idempotency and preservation of modification date. However, it does not explicitly state when NOT to use or compare with alternative tools like prune_tags or update_frontmatter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mover, renombrar o reubicar una categoría/carpeta entera con todas sus notas dentro. Actualiza el campo category del frontmatter de cada nota. Más eficiente que mover una a una. No actualiza wikilinks porque los slugs no cambian.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Categoría actual (puede ser anidada como "conocimiento/problemas-resueltos") | |
| new_name | Yes | Nueva ruta de categoría |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It explains that frontmatter is updated, wikilinks are not changed because slugs remain the same, and it's efficient. Could mention side effects on subcategories or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main action. Each sentence provides distinct information, though the last two could be consolidated. Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, effect on notes, and limitations. No output schema, but return value is implied. Adequate for a moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, only noting nesting possibility (anidada) and new path (nueva ruta).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (mover/renombrar/reubicar) and the resource (categoría/carpeta entera con todas sus notas). It distinguishes from alternatives by noting it's more efficient than moving one by one and doesn't update wikilinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (moving an entire category efficiently) and what it doesn't do (no wikilink update). However, it omits explicit guidance on when not to use or comparison to sibling tools like move_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mover, renombrar o reubicar una nota — cambiarla de categoría y/o cambiarle el título. Actualiza automáticamente los wikilinks de otras notas que la referencien.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre actual de la nota (sin extensión .md) | |
| new_title | No | Nuevo título para la nota, si se quiere renombrar (opcional) | |
| new_category | No | Nueva categoría/carpeta destino (opcional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: automatic updating of wikilinks in other notes that reference the moved note. This adds significant value beyond the basic move operation, though it could mention error handling or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences, front-loaded with the action, and efficient. Every sentence adds value, including the side effect of wikilink updates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage and no output schema, the description covers the main purpose and an important side effect. It could be more explicit about required combination of parameters (at least one of new_title or new_category) and error cases, but it's sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter (name, new_title, new_category). The tool description adds no extra parameter information beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: move, rename, or relocate a note by changing its category and/or title. It also mentions automatic wikilink updates. This distinguishes it from sibling tools like move_category and edit_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a note needs to be moved or renamed. It does not explicitly list when not to use or mention alternatives, but the context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Echar un vistazo rápido a una nota: devuelve solo frontmatter + primer párrafo del cuerpo. Ahorra tokens cuando solo se quiere comprobar la categoría, tags o de qué trata la nota antes de decidir si leerla entera.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It transparently explains the tool returns only frontmatter and first paragraph, saving tokens. No side effects mentioned, but it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value (frontmatter + first paragraph) and use case. It lacks details on output format but is sufficient for a preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'name' is clearly described in the schema. The tool description adds no additional semantic value beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns frontmatter and first paragraph for quick note inspection. It distinguishes from reading full notes by specifying the token-saving intent and the conditions for use (checking category, tags, topic).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (for quick checks before deciding to read fully). It implies not for full content but does not explicitly list alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Añadir, insertar o anteponer contenido al principio del cuerpo de una nota (justo después del título h1, antes del resto del contenido). Útil para entradas tipo log invertido donde lo más nuevo va arriba.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| content | Yes | Contenido Markdown a insertar al inicio |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the exact insertion position after the h1 title, which is good. However, it does not mention error handling (e.g., note not found), idempotency, or whether the note must already exist. For a mutation tool, this is a moderate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of exactly two sentences: the first defines the action and precise location, the second provides a concrete use case. No superfluous words; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 required params, no output schema, no annotations), the description covers the essential points: what the tool does, where it inserts, and a typical use case. The omission of whether the note must pre-exist is minor, but overall it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters named and described clearly. The tool description adds no extra semantics beyond the schema (e.g., it confirms content is Markdown but this is already in schema). Baseline 3 is appropriate as the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'prepend content to the beginning of the note body' and distinguishes itself by stating the exact insertion point (just after the h1 title, before the rest). This differentiates it from siblings like append_to_note or insert_after_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a specific use case ('inverted log entries'), which implies when to use this tool. While it does not explicitly state when not to use or list alternatives, the context of sibling tools makes the differentiation clear. A small improvement would be to mention that append_to_note is the alternative for adding at the end.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Podar, limpiar o simplificar las etiquetas de la bóveda: fusionar variantes que significan lo mismo (#tipo_filosofia → #tipo_doctrina) y recortar las notas que llevan más etiquetas de la cuenta, quedándose con las que de verdad agrupan. Conserva siempre el #tipo_*, lo que se indique en keep y las etiquetas más usadas; las que sobran se retiran empezando por las de uso único, que no agrupan nada. Preserva la fecha de modificación y la autoría. Por defecto corre en dry_run.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Máximo de etiquetas por nota. Por defecto 6. | |
| keep | No | Etiquetas que nunca se retiran (autor, dominio, estado…), sin la almohadilla. | |
| merge | No | Fusiones a aplicar, como pares {etiqueta_vieja: etiqueta_nueva} sin la almohadilla. Por ejemplo {"tipo_runbook": "tipo_proceso"}. | |
| dry_run | No | Si true (por defecto), no escribe nada y devuelve el informe de lo que haría. | |
| category | No | Acotar a una categoría y sus subcarpetas (opcional). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors: preserves specific tags ('#tipo_*', 'keep', most used), removes single-use tags first, preserves modification date and authorship, and defaults to dry_run. However, it does not explicitly state scope of tag merging (e.g., affecting all notes) or side effects on note content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences to cover purpose, options, and default behavior. It is front-loaded with the main action. Could benefit from structuring (e.g., bullet points) but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return value (only mentions dry_run report), error handling, or whether the operation is reversible. For a tool that merges tags and modifies notes, more guidance on output and side effects would be beneficial. Output schema is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description provides examples for 'keep' and 'merge' but does not add significant meaning beyond the schema. It confirms the dry_run default, but this is already in the schema as a boolean description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to prune, clean, or simplify tags by merging variants and trimming excess tags from notes. It provides specific examples ('#tipo_filosofia → #tipo_doctrina') and distinguishes itself from sibling tools like 'audit_tags' (audit only) and 'list_tags' (read-only) by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for cleaning up tags but does not explicitly state when to use this tool versus alternatives like 'audit_tags' (which only reports issues) or manual editing. It mentions a default dry_run, indicating caution, but lacks a clear when/when-not directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leer únicamente el frontmatter YAML de una nota, sin el cuerpo. Útil para validaciones rápidas o cuando solo se necesitan los metadatos.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses that it reads only frontmatter, but does not mention return format or potential errors. Adequate for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no wasted words. Front-loads the core action and adds practical usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains what the tool does and when to use it. Could optionally mention return format, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the parameter description already explains it's the note name without .md extension. The tool description adds no further semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads only the YAML frontmatter of a note, excluding the body. Distinguishes from sibling read_note by specifying 'sin el cuerpo'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: quick validations and metadata needs. Does not mention when not to use, but the context is clear that for full notes, use read_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leer el contenido completo de una nota. Busca en todas las categorías.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the basic function without mentioning error scenarios, read-only nature, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no fluff, and front-loads the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core functionality adequately. Minor missing context about error handling or content format, but acceptable for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not add meaning beyond the existing parameter description (already states 'sin extensión .md'). The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Leer el contenido completo') and the resource ('una nota'), and specifies it searches across all categories. This distinguishes it from sibling tools like 'peek_note' or 'read_section'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only mentions 'Busca en todas las categorías' but does not explain when not to use it or compare with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leer únicamente una sección Markdown de una nota, identificada por el título exacto de su encabezado. Devuelve desde ese encabezado hasta el siguiente del mismo nivel o superior. Ideal para notas largas (inventarios, capturas) cuando solo interesa una parte.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| section_title | Yes | Título exacto del encabezado, sin los # iniciales |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that it returns from the section heading to the next same level or above, disclosing behavior. No annotations are provided, so the description carries the burden and does so adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each with purpose: first describes the action and mechanism, second provides a use case. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two well-documented parameters and no output schema, the description covers all necessary behavioral and usage aspects. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have clear schema descriptions, and the tool description reinforces that section_title is exact and case-sensitive. With 100% schema coverage, the description adds value by clarifying usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a specific Markdown section of a note identified by exact heading title, distinguishing it from sibling read_note (whole note) and list_sections (lists sections).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Ideal for long notes... when only part is of interest,' providing a clear use case. It does not explicitly mention alternatives, but the sibling context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listar notas modificadas recientemente, en los últimos N días (por defecto 7). Útil para retomar contexto de qué se ha tocado últimamente sin leer toda la bóveda.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Número de días hacia atrás. Por defecto 7 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the default days and the fact that it lists recent modifications, but does not clarify ordering, output format, or performance implications. Adequate for a simple list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with the core action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, no output schema), the description adequately explains what it does and offers a use case. Could specify what the list contains (e.g., note names, timestamps), but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters (100%) with its own description. The description adds the default value of 7 days, which is helpful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('listar') and resource ('notas modificadas recientemente') with a specific time window (N días, default 7). This distinguishes it from siblings like 'list_broken_links' or 'search_notes' which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete use case: 'retomar contexto de qué se ha tocado últimamente sin leer toda la bóveda'. This tells the agent when to use it but does not explicitly mention when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renombrar, cambiar o sustituir globalmente un wikilink en todas las notas que lo referencian. Útil cuando se ha consolidado un concepto y hay que redirigir todas las referencias [[old_slug]] a [[new_slug]] sin tocar las notas origen ni destino. No mueve archivos — usa move_note si lo que quieres es renombrar la propia nota.
| Name | Required | Description | Default |
|---|---|---|---|
| new_slug | Yes | Wikilink nuevo que lo reemplaza (sin los corchetes) | |
| old_slug | Yes | Wikilink antiguo a sustituir (sin los corchetes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains that the tool substitutes globally without touching source/destination notes. However, it does not mention what happens if old_slug does not exist or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences in Spanish, efficient and front-loaded with the core purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not mention the return value (e.g., count of affected notes). For a simple rename tool, this is a gap but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds that parameters are slugs without brackets, which is already implied in schema descriptions. No additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (renombrar, cambiar o sustituir globalmente un wikilink) and the resource (en todas las notas que lo referencian). It distinguishes itself from move_note, which moves physical files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it (al consolidar un concepto y hay que redirigir todas las referencias) and what not to do (no mueve archivos, usa move_note para renombrar la nota). Provides clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restaurar, recuperar o volver a una copia de seguridad anterior de la bóveda: devuelve las notas al estado que tenían en esa instantánea. Antes de tocar nada guarda otra copia del estado actual, así que también se puede deshacer la restauración. Por defecto simula y dice qué cambiaría.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la instantánea (el que devuelve list_snapshots) | |
| dry_run | No | Si true (por defecto), solo informa de qué notas cambiarían. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behaviors: it creates a backup of the current state before restoring (enabling undo), and it defaults to a dry run (simulation). This is good transparency for a potentially destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, every sentence adds unique information (purpose, undo capability, default simulation). No fluff, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's purpose, effect, and default behavior for a simple 2-parameter tool with no output schema. It could optionally mention what the response looks like, but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema by explaining that the 'name' parameter corresponds to snapshot names from list_snapshots and that 'dry_run' defaults to true (simulation mode). This helps the agent understand the parameter semantics and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (restore, recover) and resource (previous backup/snapshot), and implicitly distinguishes from siblings like create_snapshot and list_snapshots by focusing on restoration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it mentions that the tool saves a backup before restoring (making it reversible) and that it simulates by default. However, it does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Buscar notas por texto libre. Con múltiples palabras busca notas que contengan TODAS (lógica AND). Busca en títulos, contenido y etiquetas, y no distingue mayúsculas ni acentos: "piramide" y "pirámide" devuelven lo mismo. Los resultados se ordenan por relevancia (título y etiquetas antes que cuerpo) y vienen limitados; usa limit o category para acotar.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Máximo de resultados. Por defecto 20 | |
| query | Yes | Término de búsqueda | |
| category | No | Acotar la búsqueda a una categoría y sus subcarpetas (opcional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully discloses sorting, case/accent insensitivity, and result limiting. It is a read operation and no destructive behavior is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph with no wasted words. It front-loads the main action and efficiently conveys all key behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers search behavior, parameter usage, and sorting. It does not detail the return format, but this is minor for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds meaning: explains category scoping to subfolders and default limit, which are not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool searches notes by free text with AND logic, covering titles, content, and tags. It clearly distinguishes from sibling tools like list_notes by emphasizing free-text search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that multi-word queries use AND logic and results are sorted by relevance. While it doesn't explicitly state when not to use, it provides clear context for typical search scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Actualizar, modificar o cambiar campos concretos del frontmatter YAML de una nota (title, category, tags, created) sin tocar el cuerpo. El campo updated se renueva automáticamente. Para mover de categoría usa move_note (mantiene wikilinks); este tool solo edita el YAML in situ sin mover archivos.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| fields | Yes | Objeto con los campos a actualizar. Claves válidas: title, category, tags (array), created. updated se ignora — siempre se pone a hoy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the updated field is automatically set, that only specific keys are valid, and that the tool does not move files. This is sufficient for a simple mutation tool, though it could mention error behavior or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences precisely convey purpose, scope, and key constraints without unnecessary text. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, schema covers everything, no output schema, no annotations), the description is complete. It covers valid fields, auto-behavior, and differentiates from a sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions). The description adds value by specifying valid keys for the fields object ('title, category, tags (array), created') and clarifying that 'updated se ignora'. This goes beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Actualizar, modificar o cambiar' targeting 'campos concretos del frontmatter YAML' (title, category, tags, created) and explicitly excludes body modification. It distinguishes from move_note by stating 'este tool solo edita el YAML in situ sin mover archivos'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use (to update frontmatter fields) and provides an explicit alternative for moving categories ('Para mover de categoría usa move_note'). Also notes that 'updated se renueva automáticamente' implying no need to set it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reemplazar, sustituir o reescribir una sección Markdown entera de una nota, identificada por el título exacto de su encabezado (sin los #). La sección abarca desde su encabezado hasta el siguiente encabezado del mismo nivel o superior. Conserva el encabezado original, sustituye solo el contenido entre encabezados. Es markdown-aware: ideal para regenerar tablas grandes, listas o párrafos largos sin tocar el resto del documento.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md | |
| new_content | Yes | Nuevo contenido de la sección, sin incluir el encabezado (que se conserva) | |
| section_title | Yes | Título exacto del encabezado, sin los # iniciales (ej. "Marketing y publicidad") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description adds behavior: preserves header, replaces content only, and is markdown-aware. However, it lacks disclosure on error handling (e.g., missing section), side effects, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph front-loaded with action, no redundant words. All sentences are informative and earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers purpose, parameter details, and key behavior. It does not explain return values or error conditions, but for a simple update tool it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds meaning: clarifies section_title excludes '#' prefixes, new_content excludes header, and name excludes .md extension. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replaces an entire Markdown section identified by header title, which is a specific verb-resource pair. It distinguishes from siblings like edit_note by emphasizing whole-section replacement and header preservation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for replacing entire sections without touching other parts, but does not explicitly state when to use or not use this tool versus alternatives like append_to_note or edit_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validar, comprobar o auditar la estructura de una nota según el protocolo de la bóveda: frontmatter completo (title, category, created, updated), presencia de sección "Ver también", presencia de hashtags #snake_case al final, y wikilinks no rotos. Devuelve un reporte con los problemas detectados.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre de la nota sin extensión .md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the checks performed and the output (report of problems). With no annotations, it clearly indicates a read-only validation with no destructive side effects. However, it does not specify the report format or behavior for non-existent notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first lists all validation points, the second states the output. Every phrase is meaningful, making it efficient and front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter with full schema coverage and no output schema, the description adequately explains what the tool does and returns. However, it lacks details on the exact format of the report and fails to address edge cases (e.g., missing note).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'name'. The description adds no extra meaning beyond the schema's 'Nombre de la nota sin extensión .md', so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates note structure with specific checks (frontmatter, 'Ver también' section, hashtags, wikilinks) and returns a report. This distinguishes it from sibling tools like read_note or audit_tags by focusing on comprehensive structural auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying note structure per vault protocol but does not explicitly state when to use this tool versus alternatives, such as audit_tags for tag-only checks. No guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revisar el estado de salud de toda la bóveda en una sola llamada: wikilinks rotos, notas huérfanas, notas sin etiquetar o con demasiadas, etiquetas mal formadas, restos de tags en el frontmatter y notas que incumplen el estándar (sin "Ver también"). Devuelve un parte corto con lo que está mal y qué herramienta lo arregla. Pensada para pasarla de vez en cuando y que el desorden no se acumule sin que nadie lo vea.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Si true, lista las notas afectadas de cada problema, no solo el recuento. | |
| max_tags | No | Máximo de etiquetas por nota que se considera correcto. Por defecto 6. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the tool is read-only (revisar/devuelve), lists the checks performed, and describes the output as a short report with problems and fix tools. It does not mention performance or rate limits, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first lists issues, second describes output, third states usage intent. It is front-loaded, efficient, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description explains the output format (short report with issues and fix tools). It covers all key aspects of the tool's behavior. Minor missing details (e.g., exact structure of report) but sufficient for a health check tool with simple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, so baseline is 3. The tool description adds no additional meaning to the parameters (detail, max_tags) beyond what the schema provides. That is acceptable but does not improve the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool reviews the health of the entire vault, listing specific issues like broken wikilinks, orphan notes, tag problems, and notes missing 'See also'. It clearly distinguishes from sibling tools that handle only individual issues (e.g., find_orphans, list_broken_links).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Pensada para pasarla de vez en cuando' (designed to run periodically), implying a maintenance use case. It does not explicitly compare to alternatives or state when not to use, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crear, guardar, anotar, añadir o actualizar una nota en la base de conocimiento (la bóveda). Operación de escritura — úsala cuando quieras guardar contenido nuevo o sobrescribir uno existente, incluyendo notas en la carpeta bandeja-de-entrada. Si la nota ya existe, la actualiza completa (sobrescribe el cuerpo entero). Para retoques puntuales sin reenviar todo, prefiere edit_note, append_to_note, prepend_to_note, update_section o insert_after_section. Usa "name" para actualizar una nota existente por su slug real (útil cuando el título nuevo difiere del nombre de archivo).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Slug del archivo existente a actualizar (sin extensión .md). Úsalo cuando el título no coincide con el nombre de archivo actual. Si se omite, el slug se genera automáticamente desde el título. | |
| tags | No | Etiquetas para el frontmatter YAML. Opcional y desaconsejado: los editores que agrupan por etiqueta no leen el frontmatter, así que la clasificación se pone como hashtags #snake_case en la última línea del cuerpo. Si se omite, no se escribe el campo. | |
| title | Yes | Título de la nota | |
| content | Yes | Contenido en Markdown, sin incluir frontmatter ni el título h1 | |
| category | Yes | Subcarpeta donde guardar la nota (p. ej. "proyectos", "clientes/nombre-cliente" o "conocimiento/problemas-resueltos"). La estructura de carpetas es libre: usa las categorías que tu trabajo pida. Para ver las que ya existen, usa get_index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool overwrites the entire body if the note exists. No side effects or permissions mentioned, but for a write operation without annotations, this is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-organized paragraphs. First paragraph states purpose and usage guidelines, second explains parameters. No fluff; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters all documented in schema, and no output schema, the description provides sufficient context. It references related tools for partial updates and explains key behaviors like overwriting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all parameters (100% coverage). Description adds valuable context: explains when to use 'name' (slug for existing notes), warns that 'tags' is discouraged, and suggests using get_index for categories.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates, saves, annotates, adds, or updates a note in the knowledge base. It specifies it is a write operation for new or overwritten content, and distinguishes from sibling tools for partial updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (save new or overwrite existing) and when not (for small tweaks, prefer specific tools like edit_note, append_to_note, etc.). Also provides guidance on using the 'name' parameter for existing notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose, from maintenance (list_broken_links) to note editing (edit_note, append_to_note) and metadata queries (list_tags). Even the editing tools are well-differentiated by their operation (find/replace, append, prepend, insert after section, update frontmatter). No two tools appear to do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_broken_links, peek_note, move_category). The verbs are descriptive and the nouns clearly indicate the target resource. No mix of camelCase or other styles.
18 tools is a reasonable number for a knowledge base MCP server covering notes, categories, tags, and maintenance operations. While slightly on the higher side, each tool serves a specific need and the set does not feel bloated. A few tools could be merged (e.g., append and prepend) but overall scope is appropriate.
The tool set has significant gaps: there is no tool to read the full content of a note (only peek_note which shows first paragraph) and no tool to create or delete a note. For a knowledge base server, these are critical missing operations that will cause agent failures. Backlinks and orphans are covered, but basic CRUD is incomplete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmpdsevilla/BovedIA'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
