Memoria cognitiva para agentes de IA. Funciona con Claude Code, Cursor, Windsurf y cualquier cliente compatible con MCP.
Sitio web: yantrikdb.com · Documentación: yantrikdb.com/guides/mcp · GitHub: yantrikos/yantrikdb-mcp
pip install yantrikdb-mcpRelated MCP server: memex
El servidor MCP tiene tres modos de despliegue. Elige el que mejor se adapte a tu configuración.
El servidor MCP ejecuta el motor en el mismo proceso con una base de datos SQLite local. Rápido, privado, sin dependencias.
{
"mcpServers": {
"yantrikdb": {
"command": "yantrikdb-mcp"
}
}
}Eso es todo. El agente recuerda automáticamente el contexto, las decisiones y detecta contradicciones; no se necesita realizar prompts.
Reenvía todas las llamadas a herramientas a un clúster HTTP de YantrikDB en lugar de usar un motor integrado. El servidor MCP es un cliente ligero sin estado: todas las memorias residen en el clúster, accesibles desde cualquier máquina.
Beneficios: memoria compartida entre máquinas, alta disponibilidad, sin descarga de embebedor local, sin base de datos local.
{
"mcpServers": {
"yantrikdb": {
"command": "yantrikdb-mcp",
"env": {
"YANTRIKDB_SERVER_URL": "http://node1:7438,http://node2:7438",
"YANTRIKDB_TOKEN": "ydb_your_database_token"
}
}
}
}Separa con comas múltiples nodos para el descubrimiento automático del clúster Raft
Seguimiento automático del líder en caso de conmutación por error (failover)
Tiempo de espera de solicitud de 15s
Obtén el token del clúster: yantrikdb token create --db tu_base_de_datos
Ejecuta el servidor MCP como un servidor SSE de larga duración con su propia base de datos integrada. Los clientes se conectan a través de streaming HTTP.
# Generate a secure API key
export YANTRIKDB_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
# Start SSE server
yantrikdb-mcp --transport sse --port 8420{
"mcpServers": {
"yantrikdb": {
"type": "sse",
"url": "http://your-server:8420/sse",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Admite transportes sse y streamable-http. Nota: Las conexiones SSE pueden caerse si están inactivas; el Modo 2 (Clúster HTTP) es más fiable para despliegues compartidos.
Variable | Usado en modo | Predeterminado | Descripción |
| Clúster | (sin establecer → modo local) | URLs de nodos del clúster separadas por comas |
| Clúster | (ninguno) | Token Bearer para la base de datos del clúster |
| Local |
| Ruta del archivo de base de datos |
| Local |
| Modelo de transformador de oraciones |
| Local |
| Dimensión de embedding |
| Servidor SSE | (ninguno) | Token Bearer al servir SSE/HTTP |
La memoria basada en archivos (CLAUDE.md, archivos de memoria) carga todo en el contexto en cada conversación. YantrikDB recuerda solo lo que es relevante.
Memorias | Basado en archivos | YantrikDB | Ahorro | Precisión |
100 | 1,770 tokens | 69 tokens | 96% | 66% |
500 | 9,807 tokens | 72 tokens | 99.3% | 77% |
1,000 | 19,988 tokens | 72 tokens | 99.6% | 84% |
5,000 | 101,739 tokens | 53 tokens | 99.9% | 88% |
El recuerdo selectivo es O(1). La memoria basada en archivos es O(n).
Con 500 memorias, la basada en archivos supera las ventanas de contexto de 32K
Con 5,000, no cabe en ninguna ventana de contexto, ni siquiera en 200K
YantrikDB se mantiene en ~70 tokens por consulta, con una latencia inferior a 60ms
La precisión mejora con más datos, lo opuesto al relleno de contexto
Ejecuta el benchmark tú mismo: python benchmarks/bench_token_savings.py
15 herramientas, cobertura total del motor:
Herramienta | Acciones | Propósito |
| single / batch | Almacenar memorias: decisiones, preferencias, hechos, correcciones |
| search / refine / feedback | Búsqueda semántica, refinamiento y retroalimentación de recuperación |
| single / batch | Eliminar memorias |
| — | Corregir memoria incorrecta (preserva el historial) |
| — | Consolidación + detección de conflictos + minería de patrones |
| get / list / search / update_importance / archive / hydrate | Gestionar memorias individuales + búsqueda por palabras clave |
| relate / edges / link / search / profile / depth | Operaciones de grafos de conocimiento |
| list / get / resolve / reclassify | Manejar contradicciones y enseñar patrones de sustitución |
| pending / history / acknowledge / deliver / act / dismiss | Perspectivas y advertencias proactivas |
| start / end / history / active / abandon_stale | Gestión del ciclo de vida de la sesión |
| stale / upcoming | Consultas de memoria basadas en tiempo |
| learn / surface / reinforce | Memoria procedimental: aprender y reutilizar estrategias |
| list / members / learn / reset | Categorías de sustitución para detección de conflictos |
| get / set | Rasgos de personalidad de la IA a partir de patrones de memoria |
| stats / health / weights / maintenance | Estadísticas del motor, salud, pesos y reconstrucción de índices |
Consulta yantrikdb.com/guides/mcp para la documentación completa.
Usuario: "¿Qué decidimos sobre la migración de la base de datos?"
El agente llama automáticamente a recall("database migration decision") y recupera las memorias relevantes antes de responder; no se necesita realizar prompts manuales.
Usuario: "Vamos a usar PostgreSQL para el nuevo servicio. Alice se encargará de la migración."
El agente llama a:
remember(text="Decided to use PostgreSQL for the new service", domain="architecture", importance=0.8)
remember(text="Alice owns the PostgreSQL migration", domain="people", importance=0.7)
graph(action="relate", entity="Alice", target="PostgreSQL Migration", relationship="owns")
Después de almacenar "Usamos Python 3.11" y más tarde "Actualizamos a Python 3.12", llamar a think() detecta el conflicto. El agente lo muestra:
"Encontré una contradicción: anteriormente dijiste Python 3.11, pero recientemente mencionaste Python 3.12. ¿Cuál es la actual?"
Luego se resuelve con conflict(action="resolve", conflict_id="...", strategy="keep_b").
El servidor MCP de YantrikDB almacena todos los datos localmente en tu máquina (predeterminado: ~/.yantrikdb/memory.db). No se envían datos a servidores externos, no se recopila telemetría y no se contacta a servicios de terceros durante la operación.
Recopilación de datos: Solo lo que almacenas explícitamente a través de la herramienta remember o lo que el agente de IA almacena en tu nombre.
Almacenamiento de datos: Base de datos SQLite local en tu sistema de archivos. Tú controlas la ruta a través de YANTRIKDB_DB_PATH.
Compartir con terceros: Ninguno. Los datos nunca salen de tu máquina en modo local (stdio).
Modo de red: Al usar transporte SSE/HTTP, los datos viajan entre tu cliente y tu servidor autoalojado. No intervienen servidores de Anthropic ni de terceros.
Modelo de embedding: Utiliza un modelo ONNX local (all-MiniLM-L6-v2). Los archivos del modelo se descargan una vez desde Hugging Face Hub en el primer uso y luego se almacenan en caché localmente.
Retención: Los datos persisten hasta que los eliminas (herramienta forget) o eliminas el archivo de la base de datos.
Contacto: developer@pranab.co.in
Política completa: yantrikdb.com/privacy
Consulta CONTRIBUTING.md para la configuración de venv, ejecutar pytest y abrir PRs.
Problemas: github.com/yantrikos/yantrikdb-mcp/issues
Correo electrónico: developer@pranab.co.in
Documentación: yantrikdb.com/guides/mcp
Este servidor MCP tiene licencia MIT: úsalo libremente en cualquier proyecto.
Nota: Este paquete depende de yantrikdb (el motor de memoria cognitiva), que tiene licencia AGPL-3.0. La AGPL se aplica al motor en sí; si modificas el motor y lo distribuyes o lo proporcionas como un servicio de red, esas modificaciones también deben ser AGPL-3.0. Usar el motor tal cual a través de este servidor MCP no activa obligaciones AGPL en tu código.
Substitution categories for conflict detection — list, inspect, teach, or reset.
ACTIONS:
"list": Show all categories with member counts.
"members": Show members of a specific category (needs category_name).
"learn": Teach new members (needs category_name + members as [[token, confidence], ...]).
"reset": Reset category to seed state (needs category_name).
EXAMPLES:
category() → list all categories
category(action="members", category_name="databases")
category(action="learn", category_name="databases", members=[["tidb", 0.35]])
category(action="reset", category_name="editors_tools")
Args: action: "list", "members", "learn", "reset". category_name: Required for members/learn/reset. members: For learn: [[token, confidence], ...]. source: For learn: "llm_suggested", "user_confirmed", "seed".
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | list | |
| source | No | llm_suggested | |
| members | No | ||
| category_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains each action's effect (e.g., 'reset' returns to seed state). The annotations include destructiveHint=true, which aligns with the 'reset' action. However, it does not explicitly state that 'list' and 'members' are read-only, nor does it disclose authorization requirements or rate limits.
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 well-structured: a one-line purpose, bulleted actions, clear examples, and an args list. Every sentence adds value, and it is front-loaded with the core purpose. No unnecessary text.
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 presence of an output schema, the description does not need to explain return values. It covers all parameters and actions adequately. However, it could mention the output format or how the tool integrates with conflict detection, though this is 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 description adds substantial meaning beyond the input schema, which has 0% coverage. It explains each parameter in detail: action options, category_name requirement, members format, and source values. This fully compensates for the lack of 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 it's for 'Substitution categories for conflict detection' and lists specific actions (list, members, learn, reset). However, it does not differentiate from sibling tools like 'conflict' or 'memory', which might have overlapping functionality.
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 actions and examples for each, giving clear usage context. However, it does not specify when NOT to use this tool or mention alternative tools for similar tasks, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage memory conflicts (contradictions) — list, resolve, dismiss, reclassify, or batch-burn-down the unambiguous ones (v0.8.0+).
ACTIONS:
"list": List conflicts. Optional status filter.
"get": Get single conflict by conflict_id.
"resolve": Resolve with strategy: "keep_a"/"keep_b"/"keep_both"/"merge"/"dismiss".
"reclassify": Reclassify conflict type.
"auto_resolve": v0.8.0 — burn down unambiguous conflicts in one pass. Set dry_run=False to actually persist.
Args: action: "list", "get", "resolve", "reclassify", "auto_resolve". conflict_id / status / strategy / winner_rid / new_text / resolution_note / new_type / limit: see action docs above. dry_run: For auto_resolve — preview without persisting.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| action | No | list | |
| status | No | ||
| dry_run | No | ||
| new_text | No | ||
| new_type | No | ||
| strategy | No | ||
| winner_rid | No | ||
| conflict_id | No | ||
| resolution_note | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, matching the description of conflicts being managed and resolved. The description adds context about auto_resolve's dry_run flag for previewing persistence, which is not in annotations. No contradiction.
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 structured with actions listed and parameters grouped. It is somewhat lengthy but each section adds value. The main purpose is front-loaded. A more streamlined format could improve conciseness.
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 10 parameters, 0 required, and no schema descriptions, the description provides adequate context for each action and parameter. The output schema exists but is not shown, so return values are not described. Overall, it covers the essential information for tool usage.
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 0%, so the description must compensate. It groups parameters by action and explains their roles (e.g., strategy for resolve, dry_run for auto_resolve). This adds meaning beyond the schema's default values and types, though individual parameter details are brief.
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 manages memory conflicts and lists specific actions (list, get, resolve, reclassify, auto_resolve). It distinguishes itself from sibling tools by its unique function. The purpose is clear but could be more concise.
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 for each action, e.g., listing with optional status filter and resolving with strategies. It mentions the auto_resolve action for v0.8.0+ and dry_run for previewing. While it doesn't explicitly state when not to use, it gives sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bounded encrypted working-memory ring buffer for raw conversation turns (v0.9.0 engine conversation primitive).
Unlike remember (which stores extracted semantic memories), this stores
verbatim turns — useful for short-horizon working memory, e.g. "what
exactly did the user say two messages ago". The ring is bounded per
namespace; oldest turns evict when max_turns is exceeded.
ACTIONS:
"record": Append a turn (needs role + content).
"recent": Retrieve last N turns, oldest-first.
"clear": Drop the buffer for a namespace.
Args: action: "record" | "recent" | "clear". namespace: Ring buffer namespace (separate buffers per agent / topic). role: "user" | "assistant" | "system" | "tool" — caller's choice. content: The verbatim turn text. max_turns: Ring size at record time (default 10). limit: How many recent turns to return.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | ||
| limit | No | ||
| action | Yes | ||
| content | No | ||
| max_turns | No | ||
| namespace | No | default |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses behavioral traits beyond annotations: bounded per namespace, oldest turns evict when max_turns exceeded, and 'encrypted'. Annotations only indicate destructiveHint=true and readOnlyHint=false, so the description adds significant context.
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 well-structured with actions listed in a bullet format and args explained clearly. Every sentence provides necessary information without 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?
Given 6 parameters, no schema descriptions, and an existing output schema (not detailed), the description covers all essential aspects: purpose, actions, parameters, and behavioral details. It is sufficiently complete for an AI agent to 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 0%, but the description explains every parameter: action options, namespace purpose, role choices, content as verbatim text, max_turns as ring size, and limit for recent retrieval. This fully compensates for the lack of 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 it is a 'bounded encrypted working-memory ring buffer for conversation turns', distinguishing it from the 'remember' sibling. It lists three specific actions (record, recent, clear) with their 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?
The description contrasts with 'remember' and explains it is for short-horizon working memory and verbatim turns. While it provides clear context, it does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct an existing memory in-place with a revision-history entry (engine v0.7.20+, Issue #47).
WHEN TO USE: When the user corrects a recalled fact.
"Actually, we're using Python 3.12, not 3.11" → correct the memory.
Preserves history via an append-only revision entry keyed on reason.
Entity relationships stay attached to the same rid (in-place mutation,
not a tombstone+new-rid dance).
Args: rid: The memory ID to correct. reason: Required — why the correction was made. Non-empty. Recorded on the revision-history entry so future recall + audit can reconstruct why the memory changed. new_text: Optional new text (pass None to keep existing). new_importance: Optional updated importance (0.0-1.0). new_valence: Optional updated valence (-1.0 to 1.0). metadata_merge: Optional dict to merge into existing metadata (None = keep as-is).
| Name | Required | Description | Default |
|---|---|---|---|
| rid | Yes | ||
| reason | Yes | ||
| new_text | No | ||
| new_valence | No | ||
| metadata_merge | No | ||
| new_importance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, and description explains the in-place mutation and append-only revision history, providing sufficient behavioral context beyond annotations. 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?
Well-structured with clear sections, but slightly verbose (e.g., version/issue reference). Every sentence adds value; no wasteful repetition.
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?
Covers behavioral traits, parameter semantics, and use cases adequately. Output schema exists and is not required to be explained. Could mention return behavior but not necessary.
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 0%, but description fully compensates with detailed Args section: explains 'rid', 'reason' (required, recorded for audit), 'new_text', 'new_importance', 'new_valence', and 'metadata_merge' with defaults and 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?
Description clearly states the tool corrects an existing memory in-place with revision history. It provides a concrete example ('Actually, we're using Python 3.12...') and distinguishes from siblings by noting in-place mutation vs tombstone approach.
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 'WHEN TO USE' section explicitly tells when to use (user corrects a recalled fact) with an example. Lacks explicit when-not-to-use, but the context is clear and sibling tool list implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently forget (tombstone) one or more memories.
WHEN TO USE: When the user explicitly asks to forget something, or when a memory
is clearly wrong and correction isn't appropriate. Prefer correct over forget
when the memory just needs updating.
Args: rid: Single memory ID to forget. rids: List of memory IDs to forget (batch mode).
| Name | Required | Description | Default |
|---|---|---|---|
| rid | No | ||
| rids | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context like 'permanently' and 'tombstone', reinforcing the irreversible nature. This is consistent and adds value beyond the annotations, though the annotations already convey the key safety profile.
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: a one-sentence purpose, a usage block, and parameter list. Every sentence carries essential information, and it is front-loaded for quick scanning. 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?
Given the existence of an output schema and the tool's destructive nature, the description adequately covers the key aspects: purpose, usage, parameters, and alternatives. It could mention that forget is irreversible (already implied by permanent/tombstone), but annotations cover that. No major 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?
Schema coverage is 0%, so the description must compensate. It explains 'rid' as single memory ID and 'rids' as batch mode. However, it does not specify the format or source of memory IDs, which are necessary for invocation. The explanation is adequate but lacks depth.
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?
Description explicitly states the action: 'Permanently forget (tombstone) one or more memories.' It also distinguishes from the sibling tool 'correct', clarifying that 'correct' is preferred for updates, making the purpose specific and differentiated.
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 when-to-use guidance: when user explicitly asks to forget or when a memory is clearly wrong and correction isn't appropriate. It also explicitly names the alternative ('prefer `correct` over `forget`'), which is excellent decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Surface knowledge gaps — frequently-asked, poorly-answered queries (v0.9.0 engine demand log).
The substrate logs every recall and tracks how often each query is asked
what top scores it surfaces. knowledge_gaps() returns the queries
that are asked often but answered poorly — the substrate's "known
unknowns". Use this to drive proactive learning: when the agent sees a
gap, it can ask the user, fetch info, or note the limitation.
Args: min_count: Only surface queries asked at least this many times. max_avg_top_score: Only surface queries whose best recall score averages below this (lower = poorer answer). limit: Max gaps to return.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| min_count | No | ||
| max_avg_top_score | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the internal mechanism ('substrate logs every recall...') and the nature of the output (frequently-asked, poorly-answered queries), which enhances transparency beyond what annotations provide.
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 reasonably concise, starting with the core purpose and then elaborating. It uses a bullet-like list for parameters. One minor point: the first sentence could be slightly more front-loaded, but overall it is efficient and well-structured.
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 has three parameters with defaults and an output schema. The description explains the tool's functionality, internal logging mechanism, and intended use case for proactive learning, which is fully adequate given the output schema provides return value details.
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 0%, but the description compensates by explaining each parameter's semantics: min_count surfaces queries asked at least N times, max_avg_top_score filters by average best recall score, and limit caps results. This adds essential meaning beyond the schema's type and default values.
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 as 'Surface knowledge gaps — frequently-asked, poorly-answered queries'. This is a specific verb-resource combination that distinguishes it from siblings like 'recall' and 'memory' which deal with storing or retrieving specific facts, while this tool identifies unknown areas.
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 usage context: 'Use this to drive proactive learning: when the agent sees a gap, it can ask the user, fetch info, or note the limitation.' However, it does not explicitly exclude cases where this tool should not be used or mention alternative sibling tools such as 'stats' for similar analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Knowledge graph operations — entity relationships, memory↔entity links, record-to-record links, co-occurrence auto-relate, and link-expanded recall.
ACTIONS:
"relate": Entity↔entity relationship (legacy).
"edges": Get all relationships for entity.
"link": Link a memory (rid) to an entity (legacy).
"search": Find entities by pattern.
"profile": Rich entity profile.
"depth": How deeply the system knows an entity.
"auto_relate": v0.8.0 — co-occurrence-driven edge backfill. Set dry_run=False to persist.
"record_link": v0.9.0 — add a record-to-record link (needs source_rid + target_rid + link_type).
"record_unlink": v0.9.0 — remove a record-to-record link.
"linked_records": v0.9.0 — traverse links from rid (direction = "outbound" | "inbound" | "both", optional link_type filter).
"recall_with_links": v0.9.0 — semantic recall with N-hop link expansion.
Args: action: One of the actions above. entity / target / relationship / weight / rid / pattern / limit / days / namespace: Legacy entity-graph args. source_rid / target_rid / link_type: For record_link / record_unlink. direction: For linked_records — "outbound" / "inbound" / "both". dry_run: For auto_relate — preview without persisting. max_edges: For auto_relate — cap edges proposed/created. query: For recall_with_links — natural language search. top_k: For recall_with_links — max seed results. expand_links: For recall_with_links — hop budget for traversal.
| Name | Required | Description | Default |
|---|---|---|---|
| rid | No | ||
| days | No | ||
| limit | No | ||
| query | No | ||
| top_k | No | ||
| action | Yes | ||
| entity | No | ||
| target | No | ||
| weight | No | ||
| dry_run | No | ||
| pattern | No | ||
| direction | No | both | |
| link_type | No | ||
| max_edges | No | ||
| namespace | No | ||
| source_rid | No | ||
| target_rid | No | ||
| expand_links | No | ||
| relationship | No | related_to |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: The description explicitly includes 'record_unlink: remove a record-to-record link' and auto_relate persistence, both of which are mutating/destructive operations, yet annotations declare destructiveHint=false. This directly contradicts the structured metadata, so the description fails to align with the tool's actual behavioral profile.
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 well-structured with a summary line, a bulleted action list, and a grouped args section. It is front-loaded and scannable despite its length. The length is justified by the tool's multi-action nature and 19 parameters, though some repetition could be trimmed.
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 high complexity (12 actions, 19 parameters) and the presence of an output schema, the description covers most actions and parameter groupings adequately. However, it lacks guidance on when to prefer this tool over sibling tools, and it does not describe return-value behavior or error conditions, leaving the overall context incomplete.
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 0%, so the description must compensate. It groups parameters by action (source_rid/target_rid/link_type for record_link, direction for linked_records, dry_run/max_edges for auto_relate, query/top_k/expand_links for recall_with_links), which adds useful meaning. However, many legacy parameters (weight, days, namespace, pattern, limit) are only listed without semantic explanation, leaving gaps.
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 identifies the tool as 'Knowledge graph operations' and enumerates 12 distinct actions with specific verbs and targets (relate, edges, link, search, profile, depth, auto_relate, record_link, record_unlink, linked_records, recall_with_links). This makes the tool's scope and capabilities immediately clear and distinguishes it from sibling memory/recall tools.
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 action-specific usage details, such as 'Set dry_run=False to persist' for auto_relate, direction values for linked_records, and 'legacy' labels for relate/link. However, it does not explicitly state when to use this tool versus alternatives like recall or memory, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage individual memories — get, list, search, update importance, archive, hydrate, relevance feedback, fetch a chain-shaped namespace's head, or query revision history.
ACTIONS:
"get": Retrieve a single memory by rid.
"list": Browse memories with filters.
"search": Keyword substring search.
"update_importance": Change a memory's importance score.
"archive": Move to cold storage.
"hydrate": Restore archived memory.
"feedback": v0.10 — relevance feedback on a recalled memory (needs rid + feedback="relevant"|"irrelevant"). Call after USING a recalled memory; it tunes future retrieval. (Moved here from recall, which is now read-only.)
"chain_head": The CURRENT value of a chain-shaped namespace (narrative / decision / config chains). Use this — not recall — for "what is the current/latest X": similarity search favors the most-similar revision, chain_head returns the newest.
"history": v0.8.0 — revision history for a single rid (needs rid).
Args: See action docs above. New args: namespace: Required for chain_head — the chain-shaped namespace. rid: Required for history/feedback — the record acted on. feedback: For feedback — "relevant" or "irrelevant". feedback_query: For feedback — the query that surfaced the memory. feedback_score / feedback_rank: For feedback — retrieval context.
| Name | Required | Description | Default |
|---|---|---|---|
| rid | No | ||
| limit | No | ||
| action | Yes | ||
| domain | No | ||
| offset | No | ||
| sort_by | No | created_at | |
| feedback | No | ||
| namespace | No | ||
| importance | No | ||
| memory_type | No | ||
| feedback_rank | No | ||
| text_contains | No | ||
| feedback_query | No | ||
| feedback_score | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations, such as that feedback tunes future retrieval, chain_head returns the newest revision, and feedback was moved from recall. Annotations (readOnlyHint false) are consistent with mutation actions described.
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?
Structured with a main sentence and bullet list of actions; front-loaded with purpose. Some redundancy (e.g., repeating 'action' in each bullet) and length, but organized.
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 (14 parameters, many actions) and that output schema exists, the description covers actions well but lacks full parameter documentation. Missing descriptions for common parameters like limit, offset, memory_type, etc. reduces completeness.
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 0% schema description coverage, the description partially compensates by documenting key parameters for specific actions (namespace for chain_head, rid for history/feedback, feedback-related fields) but omits descriptions for many other parameters (limit, offset, sort_by, domain, etc.).
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 manages individual memories and lists multiple specific actions (get, list, search, etc.), clearly distinguishing it from sibling tools like recall (e.g., notes feedback moved from recall, and chain_head vs recall).
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 usage guidance for key actions: feedback should be called after using a recalled memory; chain_head should be used instead of recall for current/latest values. Lacks comprehensive when-not-to-use notes for other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Signed, portable memory bundles — inspect, install, and trust packs.
A pack is a sealed corpus another agent or vendor published. Mounted pack memories are recallable alongside your own but are DOWN-WEIGHTED (tier_multiplier < 1.0): what the user told you locally always outranks imported knowledge.
READ ACTIONS (always available):
"list": Installed + mounted packs (id, name, origin, trust, rows).
"inspect": Read a pack file's manifest WITHOUT installing it. path=. Shows origin, signature, embedder, rows — always inspect before you install.
"publishers": Public keys this database trusts.
"embedder_identity": This database's embedding fingerprint. A pack must be sealed against a matching space to mount.
WRITE ACTIONS (operator-gated; set YANTRIKDB_ENABLE_PACK_WRITES=1):
"install": Install + mount a pack. path=.
"uninstall": Remove a pack and its rows. pack_id=.
"mount"/"unmount"/"unmount_all": Session-scoped mount control.
"trust": Trust a publisher key. pubkey=, label=.
"untrust": Revoke a publisher key. pubkey=.
Args: action: One of the read/write actions above. path: Pack file path (inspect / install / mount). pack_id: Pack identifier, e.g. "origin@1.0.0" (uninstall / unmount). pubkey: Publisher public key hex (trust / untrust). label: Human label for a trusted publisher (trust). allow_unverified_embedder: Mount despite an unverified embedder. Does NOT override a hard dimension mismatch.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| label | No | ||
| action | Yes | ||
| pubkey | No | ||
| pack_id | No | ||
| allow_unverified_embedder | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses destructive behaviors (uninstall removes rows, untrust revokes keys), write gating via YANTRIKDB_ENABLE_PACK_WRITES, down-weighting of pack memories, and embedder verification nuances. This goes far beyond the destructiveHint annotation, providing rich context about side effects and trust.
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 well-structured with clear sections (READ ACTIONS, WRITE ACTIONS) and a concise Args list. It is densely packed with useful information without fluff; 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?
The description covers all actions, parameters, environmental prerequisites, security model, and even edge cases like 'Does NOT override a hard dimension mismatch.' Given the tool's complexity, this is thorough, and an output schema exists to handle return details.
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 Args section explicitly describes each parameter's purpose and permissible actions: 'path: Pack file path (inspect / install / mount)', 'pack_id: Pack identifier, e.g. "origin@1.0.0" (uninstall / unmount)', etc. With schema description coverage at 0%, this fully compensates and adds valuable 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 opening line, 'Signed, portable memory bundles — inspect, install, and trust packs,' clearly identifies the tool's domain and operations. It distinguishes itself from sibling tools like 'remember' and 'skill' by focusing on external, signed memory bundles from other agents/vendors.
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 separates READ ACTIONS (always available) from WRITE ACTIONS (operator-gated) and advises 'always inspect before you install.' It also explains the trust hierarchy (local memories outrank packs), but it doesn't explicitly contrast with alternative tools or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI personality traits derived from memory patterns.
ACTIONS:
"get": Get current personality profile. Use recompute=True to refresh.
"set": Set a trait manually (needs trait_name + score).
Traits: warmth, depth, energy, attentiveness (0.0-1.0).
Args: action: "get" or "set". trait_name: For set: warmth, depth, energy, attentiveness. score: For set: 0.0-1.0. recompute: For get: re-derive from memory patterns first.
| Name | Required | Description | Default |
|---|---|---|---|
| score | No | ||
| action | No | get | |
| recompute | No | ||
| trait_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the dual nature of the tool (read/write), the trait names and ranges, and the effect of 'recompute'. Annotations indicate idempotentHint=true, which aligns with set being idempotent. No contradiction, and adds value beyond annotations.
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 structured with clear sections and bullet points for actions, traits, and args. It is somewhat long but well-organized. Every sentence adds value, though some redundancy exists (e.g., repeated trait names).
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 presence of an output schema (not shown), the description need not explain return values. It sufficiently covers all input aspects, including the recompute flag. For a tool with 4 parameters and no schema descriptions, this is 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?
With 0% schema description coverage, the description entirely compensates by listing all parameters, their types, defaults, and constraints (e.g., trait names, score range). Could mention default for action is 'get' but it's implied. Adequate for agent understanding.
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: 'AI personality traits derived from memory patterns.' It defines two distinct actions (get and set) with specific effects, and the tool name 'personality' aligns with the description. Different from sibling tools like 'memory' or 'recall'.
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 explains when to use 'get' vs 'set' and mentions optional parameters like 'recompute'. However, it does not provide guidance on when NOT to use this tool or compare directly with sibling tools for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Procedural memory — learn, surface, and reinforce strategies.
ACTIONS:
"learn": Store a procedure (needs text). What worked in a specific context.
"surface": Find relevant procedures (needs query). Returns ranked by effectiveness.
"reinforce": Update effectiveness (needs rid + outcome 0.0-1.0).
EXAMPLES:
procedure(action="learn", text="For this repo, always run tests before committing", domain="work")
procedure(action="surface", query="how to handle code review in this repo")
procedure(action="reinforce", rid="abc", outcome=0.9)
Args: action: "learn", "surface", "reinforce". text: Procedure description (for learn). query: What you're about to do (for surface). rid: Procedure ID (for reinforce). domain: Task domain. task_context: What kind of task (for learn). effectiveness: Initial effectiveness 0.0-1.0 (for learn). outcome: How well it worked 0.0-1.0 (for reinforce). top_k: Max results (for surface). namespace: Namespace.
| Name | Required | Description | Default |
|---|---|---|---|
| rid | No | ||
| text | No | ||
| query | No | ||
| top_k | No | ||
| action | Yes | ||
| domain | No | general | |
| outcome | No | ||
| namespace | No | ||
| task_context | No | ||
| effectiveness | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, etc. The description adds behavioral context by explaining that procedures are stored, retrieved, and updated with effectiveness scores. It does not contradict annotations and provides additional details about the reinforcement mechanism.
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 well-structured with sections (actions, examples, args). It is front-loaded with a clear purpose and uses bullet points and examples efficiently. Every sentence adds value without 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?
Given the tool has 10 parameters and an output schema, the description covers all necessary aspects: actions, parameter roles, examples, and defaults. The existence of an output schema reduces the need to describe return values. The description is complete for an agent to use effectively.
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 0%, so the description must compensate. It does so excellently by listing each parameter with its purpose and conditions (e.g., 'text' is for learn, 'query' for surface, 'rid' for reinforce). This fully clarifies parameter semantics where the schema is silent.
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 as 'procedural memory' with three distinct actions (learn, surface, reinforce), each with specific purposes. This differentiates it from sibling tools like 'memory', 'remember', and 'recall', which might have different scopes or behaviors.
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 examples and explains when to use each action (e.g., 'learn' for storing, 'surface' for retrieval, 'reinforce' for updating effectiveness). It does not explicitly state when not to use the tool, but the clarity of actions and parameters effectively guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories by semantic similarity, or refine low-confidence results.
MODES:
Search (default): recall("project architecture decisions")
Refine: recall("PostgreSQL vs MySQL decision", refine_from="database choice", refine_exclude=["rid1"])
ORDER: "recency" | "first_mention" (alias "chronological") | "certainty". Re-sorts the top_k already found; hints omitted. (Relevance feedback moved to memory(action="feedback") in v0.10 — recall is now purely read-only.)
WHEN TO USE: conversation start (summarize the user's first message); when the user references past decisions, people, preferences, or "last time"; when unsure about something the user assumes you know. Refine when first confidence < 0.5. After USING a recalled memory, reinforce it via memory(action="feedback", rid=..., feedback="relevant"). For "what is the CURRENT/latest X", prefer memory(action="chain_head") — similarity favors the most-similar revision, not the newest. For "what happened , in what order" ("tonight", "this week") use temporal(action="range") or since/until here — those words name the time frame, not the content; bare similarity cannot see the window.
QUERY: one short natural-language sentence (5-10 words), NOT a keyword list — keyword stuffing degrades quality. One focused question per call; separate calls for separate topics.
TRUST SIGNALS: each hit's why_retrieved may carry staleness warnings
("aged", "rarely confirmed", "superseded by a newer record"). Treat
flagged hits as weak evidence — prefer fresher results or chain_head,
and note the flag if you act on one anyway.
Args: query: Short natural language sentence (5-10 words). NOT a keyword list. top_k: Max results (default 10). 3-5 for focused, 10-20 for broad. memory_type: Filter: "semantic", "episodic", "procedural". domain: Filter: "work", "preference", "architecture", "people", etc. source: Filter: "user", "inference", "document", "system". namespace: Filter by namespace. include_consolidated: Include merged memories. include_superseded: v0.10 — recall EXCLUDES superseded records by default (current-by-default). Set True only for history / archaeology over a revision chain. expand_entities: Use knowledge graph boosting (default True). min_score_ratio: Drop hits scoring below this fraction of the TOP hit (0.8 = keep only near-as-good matches). Semantic search always returns top_k, even when one result is relevant and the rest are noise; this trims the tail instead of making you judge it. since: Only memories from this instant on — "2026-08-01", "2026-08-01T14:30:00Z", "6h"/"7d" (ago), or unix seconds. Filters BEFORE ranking: top_k is chosen inside the window. until: Window end (same formats; default now). Alone = up to then. refine_from: Original query text to refine from. query becomes the refinement. refine_exclude: Memory IDs to exclude when refining.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | ||
| query | Yes | ||
| since | No | ||
| top_k | No | ||
| until | No | ||
| domain | No | ||
| source | No | ||
| namespace | No | ||
| memory_type | No | ||
| refine_from | No | ||
| refine_exclude | No | ||
| expand_entities | No | ||
| min_score_ratio | No | ||
| include_superseded | No | ||
| include_consolidated | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful behavior: recall excludes superseded records by default, semantic search always returns top_k, since/until filter before ranking, and hits may carry staleness warnings. It explicitly notes the read-only refactor and the order parameter's role as a re-sort, enriching the annotation profile without contradicting it.
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?
Long but densely organized under clear headings (MODES, ORDER, WHEN TO USE, QUERY, TRUST SIGNALS, Args). Every section adds operational value and nothing is redundant with the schema; the structure lets an agent fast-path to the relevant section.
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 15-parameter tool with complex behavior, the description is complete: it explains modes, ordering, when to use alternatives, query quality, trust/staleness signals, and every parameter's meaning. The output schema exists, so return-value detail is not required, and the tool's only required param is fully specified.
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 0%, so the description carries the full burden and succeeds: the Args section documents all 15 parameters with formats, defaults, and behavioral nuance (e.g., min_score_ratio trims the tail, include_superseded for archaeology, since/until accepted formats). The query guidance ('5-10 words, not a keyword list') is especially valuable.
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 opens with a specific verb and resource: 'Search memories by semantic similarity, or refine low-confidence results.' It clearly distinguishes the tool's two modes and contrasts it with sibling tools like memory(action='chain_head') and temporal(action='range'), leaving no ambiguity about what recall does.
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?
A dedicated 'WHEN TO USE' section gives explicit triggers (conversation start, references to past decisions, low confidence) and names alternatives with conditions: prefer memory(action='chain_head') for current/latest and temporal(action='range') for time-window questions. It even instructs to reinforce recalled memories via memory(action='feedback').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store one or more memories in persistent cognitive memory.
WHEN TO USE: Call proactively whenever the conversation reveals something worth remembering — decisions, preferences, facts about people, project context. Do NOT store ephemeral task details, code snippets, or git-derivable info.
SINGLE: remember(text="User prefers dark mode", domain="preference", importance=0.7) BATCH: remember(memories=[{"text": "Alice is DevOps lead", "domain": "people"}, ...]) DRAFT: remember(summary="...long end-of-session summary...") — v0.8.0+ engine atomizes the summary into linked semantic facts; useful for the end-of-session auto-capture pattern.
IMPORTANCE: 0.8-1.0 critical decisions | 0.5-0.7 useful context | 0.3-0.5 background
Args: text: Memory text (for single memory). Be specific and searchable. memory_type: "semantic" (facts), "episodic" (events), "procedural" (how-to). importance: 0.0-1.0. Higher = remembered longer. domain: "work", "preference", "architecture", "people", "infrastructure", "health", "finance", "general". source: "user", "inference", "document", "system". valence: Emotional tone (-1.0 to 1.0). 0.0 neutral. metadata: Optional key-value pairs. namespace: For per-project isolation. certainty: Confidence 0.0-1.0. emotional_state: joy, frustration, excitement, concern, neutral. memories: List of memory dicts for batch. summary: For draft mode — long summary that the engine atomizes. idempotency_key: v0.10 engine — makes the write exactly-once: retrying with the same key + same text returns the SAME rid with no second write; same key + different text is an error. Engine-embedder (bundled) backend only. On batch, the key scopes per item as "{key}:{index}" if the atomic batch path is unavailable. created_at: v0.14 engine — BACKDATE the memory to when it was actually true, not when you imported it. Use for backfill (chat logs, migrations). Without it every imported memory stamps "now", which makes temporal(action="as_of") report history that never happened and flattens staleness/decay. Same formats as as_of: "2026-08-01", "2026-08-01T14:30:00Z", "7d" (ago), or unix seconds. Omit for anything learned in the present conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | ||
| domain | No | general | |
| source | No | user | |
| summary | No | ||
| valence | No | ||
| memories | No | ||
| metadata | No | ||
| certainty | No | ||
| namespace | No | default | |
| created_at | No | ||
| importance | No | ||
| memory_type | No | semantic | |
| emotional_state | No | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite minimal annotation detail, the description richly discloses behavior: exact-once write semantics with idempotency_key and version-specific engine behavior, batch key scoping, error conditions on key mismatch, backdating semantics for created_at, and the warning about temporal history distortion. This adds significant context beyond the annotations, which only state readOnlyHint=false and related booleans.
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 long but every sentence earns its place, covering use cases, modes, parameter semantics, and version-specific behaviors. It is front-loaded with the purpose and WHEN TO USE, uses clear headers, and includes compact examples. The density is justified by the tool's complexity (14 parameters, 3 modes).
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 complex write tool with 14 parameters and no required fields, the description provides comprehensive guidance: all parameters explained, mode selection, idempotency details, backdating semantics, and version notes. The presence of an output schema means return values need not be described, and the description handles the remaining context thoroughly.
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 0% schema description coverage, the description fully compensates by explaining every parameter in meaningful terms: types, defaults, value ranges (importance 0-1, valence -1 to 1), example values, and specific usage guidance (e.g., 'Be specific and searchable' for text). It also provides importance bands and created_at format options, which the schema does not convey.
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 opens with a clear, specific action: 'Store one or more memories in persistent cognitive memory.' It distinguishes between single, batch, and draft modes, which are the primary variants, and explicitly contrasts with sibling tools like recall and forget by defining when to proactively store. This goes well beyond a vague verb+noun, fully differentiating it from siblings.
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 WHEN TO USE guidance: 'Call proactively whenever the conversation reveals something worth remembering...' and negative guidance: 'Do NOT store ephemeral task details, code snippets, or git-derivable info.' It also includes usage patterns (SINGLE, BATCH, DRAFT) and an end-of-session auto-capture pattern, giving clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Session lifecycle — start, end, history, active check, stale cleanup, and the v0.9.0 boot-time digest.
ACTIONS:
"start": Begin a new session. Returns session_id.
"end": End a TRACKED session (needs session_id). Returns stats. This closes session bookkeeping — it does NOT capture memories.
"capture": Segment a free-text session summary into atomic candidate memories (needs summary; NO session_id — it operates on the text, not on tracked-session state). Returns drafted rids. Use at end of substantial work so the session leaves a trace.
"history": View past sessions.
"active": Check if there's a running session.
"abandon_stale": Clean up orphaned sessions older than abandon_stale_hours.
"digest": One-call boot-time briefing (v0.9.0) — narrative chain head, open decisions/conflicts/triggers, top stale memories. Call this at conversation start instead of N separate recalls. Set include_gaps=True to fold known-unknowns (frequently-asked, poorly-answered queries) into the briefing — the active-learning loop. Set scope to filter content aggregates to one namespace for a per-tenant digest.
Args: action: "start", "end", "capture", "history", "active", "abandon_stale", "digest". session_id: For end. namespace: Memory namespace. client_id: Client identifier. metadata: For start — optional dict. summary: For end — optional closing note. For capture — REQUIRED, the session summary to segment into memories. domain: For capture — domain stamped on drafted memories. limit: For history. abandon_stale_hours: For abandon_stale — max age in hours. narrative_namespace: For digest — namespace for the narrative chain. scope: For digest — filter content aggregates to one namespace (per-tenant isolation); omit for a whole-DB digest. include_gaps: For digest — fold top knowledge gaps into the briefing. max_gaps: For digest — cap on gaps surfaced when include_gaps=True. max_decisions / max_conflicts / max_triggers: For digest — surface caps. snippet_chars: For digest — text-snippet length per item.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| scope | No | ||
| action | Yes | ||
| domain | No | general | |
| summary | No | ||
| max_gaps | No | ||
| metadata | No | ||
| client_id | No | default | |
| namespace | No | default | |
| session_id | No | ||
| include_gaps | No | ||
| max_triggers | No | ||
| max_conflicts | No | ||
| max_decisions | No | ||
| snippet_chars | No | ||
| abandon_stale_hours | No | ||
| narrative_namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description comprehensively discloses behaviors beyond annotations: e.g., end 'closes session bookkeeping — it does NOT capture memories', and capture 'operates on the text, not on tracked-session state'. Annotations already show readOnlyHint=false, consistent with mutations. No contradictions. Could mention rate limits or permissions but still strong.
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 well-structured with a summary line, action bullet list, and parameter definitions. It is somewhat long but every sentence adds value. Minor redundancy: 'digest' action description includes parameter details repeated in the arg list, but acceptable.
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 (17 parameters, 7 actions) and the presence of an output schema, the description covers all actions and parameters thoroughly, including edge cases like abandon_stale and gaps in digest. No significant gaps for an agent to 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?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose per action, e.g., 'summary: For end — optional closing note. For capture — REQUIRED'. All 17 parameters are covered, providing critical context the schema lacks.
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 states 'Session lifecycle' and lists seven actions (start, end, capture, history, active, abandon_stale, digest), clearly defining the tool's scope. It differentiates from sibling tools like remember/recall by focusing on session management rather than direct memory operations, though capture could overlap with remember; a clearer distinction would raise the score.
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 usage guidance for each action, e.g., 'Use at end of substantial work so the session leaves a trace' for capture, and 'Call this at conversation start instead of N separate recalls' for digest. It contrasts digest with separate recalls, but does not explicitly state when not to use session versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Substrate-native agent skill catalog — define, surface, record outcomes.
Skills are structured catalog entries (skill_id, applies_to, body,
type) — different from loose how-to memories (use procedure for those).
Writes go to the skill_substrate namespace so every yantrikdb consumer
(this MCP, yantrikdb-hermes-plugin, Lane B SDK, WisePick) sees the same
catalog.
Schema-validated at write time:
skill_id: lowercase dot-separated segments, e.g. "workflow.git.commit_clean"
body: 50–5000 chars
applies_to: 1–10 lowercase_underscore identifiers (no hyphens)
skill_type: one of procedure | reference | lesson | pattern | rule
ACTIONS:
"define": Create a skill (needs skill_id, body, skill_type, applies_to).
"surface": Find relevant skills (needs query). Returns ranked by score.
"outcome": Append a use outcome (needs skill_id, succeeded).
"get": Fetch a single skill by id.
"list": Catalog browse (filter by applies_to / skill_type).
EXAMPLE: skill(action="define", skill_id="workflow.git.commit_clean", body="Before commit: run pytest + lint...", skill_type="procedure", applies_to=["git", "release"]) — then surface(query=...) before similar work, and outcome(skill_id=..., succeeded=True/False) after using one.
Args: action: "define", "surface", "outcome", "get", "list". skill_id: Dot-separated id (for define/get/outcome). body: Skill body, 50–5000 chars (for define). skill_type: procedure|reference|lesson|pattern|rule (for define). applies_to: Non-empty identifier list ≤10 entries (for define; optional filter for surface/list). triggers: Optional list of trigger phrases (for define). on_conflict: "reject" (default) or "replace" if skill_id exists. version: Optional semver-shaped version string. supersedes: Optional skill_id this one replaces. query: Natural-language search (for surface). top_k: Max results for surface. succeeded: Outcome boolean (for outcome). note: Optional outcome note. limit: Max results for list.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| note | No | ||
| limit | No | ||
| query | No | ||
| top_k | No | ||
| action | Yes | ||
| version | No | ||
| skill_id | No | ||
| triggers | No | ||
| succeeded | No | ||
| applies_to | No | ||
| skill_type | No | ||
| supersedes | No | ||
| on_conflict | No | reject |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety hints (all false), so the description carries the burden. It discloses that writes go to the `skill_substrate` namespace, that entries are schema-validated at write time, and that `on_conflict` can reject or replace. This gives useful behavioral context beyond the annotations, though it doesn't cover every edge case like permissions or rate limits, which is acceptable for this 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?
The description is long but well-structured with a summary, action list, example, and Args section. It is not wastefully verbose; every section covers a necessary aspect of a complex multi-action tool. It loses one point because it could be slightly tightened, but overall it remains readable and 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?
For a multi-action tool with 14 parameters and zero schema descriptions, the description is comprehensive. It covers all actions, parameter semantics, validation rules, an example, and the sibling differentiation. Since an output schema exists, the lack of return-value details is acceptable. The agent has enough context to select and invoke this 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 0%, but the description compensates fully. It lists every parameter with context: action values, skill_id format (dot-separated lowercase), body length constraints, applies_to rules (1–10 lowercase_underscore, no hyphens), skill_type enum, on_conflict options, and which params apply to which action. This adds meaning far beyond the bare 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 opens with a clear verb-resource statement: "Substrate-native agent skill catalog — define, surface, record outcomes." It also distinguishes itself from sibling 'procedure' by explicitly saying skills are structured catalog entries, not loose how-to memories. This leaves no doubt about what the tool does and how it differs from nearby tools.
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 states when to use each action and provides an explicit alternative: "different from loose how-to memories (use `procedure` for those)." It also gives a concrete workflow example (define → surface → outcome) that teaches the agent when to invoke which action, making usage guidance highly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Engine statistics, health check, learned weights, privacy/leak audit, and skill substrate counts. Read-only — index maintenance moved to think(maintenance_op=...) in v0.10.
ACTIONS:
"stats": Detailed memory statistics (default).
"health": Quick health check with latency.
"weights": Show adapted recall scoring weights.
"audit_leak": v0.8.0 windowed leak-candidate audit — surfaces recent records that may have leaked sensitive content. Use for privacy review.
"skill_outcomes": v0.9.0 — total skill outcomes recorded in the durable timeline.
Args: action: One of the actions above. namespace: Filter for stats. max_rids: For audit_leak — max candidate rids to inspect.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | stats | |
| max_rids | No | ||
| namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context: 'Read-only — index maintenance moved to think(maintenance_op=...) in v0.10', which explains the tool's non-destructive nature and where related operations occur.
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 well-structured with clear sections for actions and arguments. It uses bullet points for readability, though it is slightly verbose in listing actions. Every sentence adds value, but it could be slightly tighter.
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 (multiple actions, parameters, and an output schema), the description covers all necessary aspects: purpose, actions, parameter explanations, and behavioral notes. The output schema exists, so return values are not required in the description.
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?
Despite 0% schema description coverage, the description thoroughly explains each parameter: 'action' with a list of valid values and their meanings, 'namespace' as a filter for stats, and 'max_rids' for audit_leak actions. This fully compensates for the schema's lack of 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 is for 'Engine statistics, health check, learned weights, privacy/leak audit, and skill substrate counts'. It lists specific actions with distinct purposes, which differentiates it from sibling tools like 'memory' or 'recall'.
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 'Read-only' and directs index maintenance to 'think(maintenance_op=...)' in v0.10, providing context on when to use this tool versus alternatives. However, it does not explicitly state when not to use it or name specific sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Substrate-backed task / chore store (v0.9.0 engine).
A thin general-purpose to-do tracker baked into yantrikdb — survives sessions, lives next to memories so future agents see open tasks at session_digest time.
ACTIONS:
"add": Create a task (needs title; optional priority + parent_id).
"get": Fetch one task by id.
"list": List tasks in a namespace, optionally filtered by status.
"update": Update status and/or priority (needs task_id).
"delete": Delete a task (needs task_id).
PRIORITY: "low" | "medium" | "high" — priority-ordered in list.
STATUS: typically "open" | "doing" | "done" | "blocked".
Args: action: "add" | "get" | "list" | "update" | "delete". namespace: Per-project / per-agent isolation. title: Task description (for add). priority: "low" | "medium" | "high" (for add / update). parent_id: Optional parent task id (for add — sub-task tree). task_id: Task id (for get / update / delete). status: Filter (for list) or new value (for update).
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| action | Yes | ||
| status | No | ||
| task_id | No | ||
| priority | No | ||
| namespace | No | default | |
| parent_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive; the description adds behavioral context beyond annotations, noting persistence across sessions, priority ordering in list results, namespace isolation, and action-specific data requirements. It does not detail delete side effects (e.g., sub-task handling), but action-specific behavior is well covered.
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 well front-loaded, uses simple headers for actions and valid values, and every sentence contributes operational guidance. There is no redundant fluff or repeated schema data; the Arg list is concise and structured.
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 multi-action CRUD tool with 7 parameters and sparse schema descriptions, this is thorough: it covers all actions, parameter purposes, accepted enums for priority/status, namespace default, and the relation to session digest. The output schema exists, so return-value transcription is unnecessary.
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 0%, so the description fully compensates by defining each parameter in context of accepted actions. It explains that title is needed for add, task_id for get/update/delete, status is filter-vs-update-value, and parent_id creates a sub-task tree. This is exactly the kind of semantic clarity an agent needs.
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?
Description opens with 'Substrate-backed task / chore store' and labels it 'a thin general-purpose to-do tracker,' clearly identifying the resource and domain. It enumerates concrete actions (add/get/list/update/delete) and thereby distinguishes this tool from sibling memory/skill utilities.
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 strong context: tasks persist across sessions, are scoped by namespace, appear at session_digest time, and are used by future agents. However, it does not explicitly state when not to use this tool or name alternative sibling utilities, 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.
Find stale or upcoming memories, recall the past, or scan a time window.
ACTIONS:
"stale": Important memories not accessed recently.
"upcoming": Memories with approaching deadlines/events.
"as_of": Time-travel recall — excludes anything recorded after as_of,
so you see the belief held then, not today's. Engine v0.12+.
"range": Everything in a time window, oldest first — the surface for "what happened tonight / this week, in what order". Period and sequence questions are SET queries over a window; similarity search cannot answer them — route them here.
Args:
action: "stale", "upcoming", "as_of", or "range".
days: Inactivity threshold (stale) or look-ahead window (upcoming).
limit: Max results.
namespace: Optional filter.
query: Search text (required for "as_of"; optional for "range":
given = relevance-selected within the window, omitted =
the window's newest limit records).
as_of: Past instant (required for "as_of"): "2026-08-01",
"2026-08-01T14:30:00Z", "7d"/"24h" (ago), or unix seconds.
since: Window start (required for "range"), same formats as as_of.
until: Window end for "range" — defaults to now.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| as_of | No | ||
| limit | No | ||
| query | No | ||
| since | No | ||
| until | No | ||
| action | Yes | ||
| namespace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which align with the description's query-like actions. The description adds behavioral context beyond annotations by explaining that as_of excludes records after the given instant ('so you see the belief held then'), specifies the engine version, and notes that range returns oldest first. This enriches the agent's understanding without contradicting annotations.
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 well-structured with a clear summary line, an ACTIONS section explaining each mode, and an Args section detailing parameters. It is front-loaded with the main purpose, and every sentence contributes meaningful information—no fluff or redundancy. The density is justified by the tool's complexity.
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 4 actions, 8 parameters, and an output schema (presumably defining return format), the description covers all essential aspects: purpose, action semantics, parameter formats, default behaviors, and routing guidance. It also discloses the engine version constraint for as_of. The presence of an output schema means return-value explanation is unnecessary, and the description sufficiently equips an agent to select 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 coverage is 0%, so the description carries full responsibility for parameter meaning. It meticulously explains each parameter: action (allowed values), days (threshold/look-ahead), limit (max results), namespace (optional filter), query (required for as_of, optional for range with behavior for given/omitted), as_of/since/until (formats including relative days), thus exceeding what the bare schema provides.
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?
Description clearly states 'Find stale or upcoming memories, recall the past, or scan a time window' with four named actions (stale, upcoming, as_of, range). It distinguishes from sibling tools like 'recall' by focusing on temporal queries and explicitly contrasts with similarity search for range queries.
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 for when to use each action. The range action is described as the surface for 'what happened tonight / this week, in what order' and explicitly routes period/sequence questions here, contrasting with similarity search. as_of is described as time-travel recall, and stale/upcoming have clear use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run incremental cognitive maintenance — processes a small batch per call.
DESIGNED TO BE CALLED OFTEN: Each call processes ~5 memories (configurable). Running regularly (e.g. at end of conversation) gradually maintains the entire database without blocking. Safe to call frequently.
MODES:
Default: incremental think() — consolidation + conflict scan + (optional) pattern mining on a small batch.
maintenance_cycle=True: run the v0.9.0 autonomous-hygiene "sleep cycle" — think + burn-down-conflicts + prune-triggers + recalibrate-importance + backfill-entities + auto-relate (+ optional split_oversized + repair_artifacts).
last_cycle_only=True: just fetch the last persisted maintenance-cycle summary (read-only, no work performed).
maintenance_op="backfill_entities"|"rebuild_vec_index"|"rebuild_graph_index": run ONE targeted index-maintenance op and return. (Moved here from stats in v0.10 so stats could become read-only.)
Args: run_consolidation: Merge similar memories (default on). run_conflict_scan: Detect contradictions (default on). run_pattern_mining: Mine cross-domain patterns (default off, slow). consolidation_time_window_days: Only consolidate memories within this window (default 7 days). consolidation_limit: Batch size — max memories to process per call (default 5). Keep small for fast returns. maintenance_cycle: Run the full autonomous hygiene cycle instead. last_cycle_only: Just fetch the last cycle summary (read-only). dry_run: For maintenance_cycle — preview without persisting changes. burn_down_conflicts / prune_triggers_too / max_pending_triggers / recalibrate_importance / backfill_entities / auto_relate_in_cycle / max_auto_relate_edges / split_oversized / split_min_chars / repair_artifacts: Maintenance-cycle knobs.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| maintenance_op | No | ||
| last_cycle_only | No | ||
| split_min_chars | No | ||
| split_oversized | No | ||
| repair_artifacts | No | ||
| backfill_entities | No | ||
| maintenance_cycle | No | ||
| run_conflict_scan | No | ||
| run_consolidation | No | ||
| prune_triggers_too | No | ||
| run_pattern_mining | No | ||
| burn_down_conflicts | No | ||
| consolidation_limit | No | ||
| auto_relate_in_cycle | No | ||
| max_pending_triggers | No | ||
| max_auto_relate_edges | No | ||
| recalibrate_importance | No | ||
| consolidation_time_window_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given annotations only provide shallow hints (readOnlyHint=false, destructiveHint=false), the description carries the behavioral burden and does so thoroughly. It discloses side effects (consolidation, conflict scan, pruning, recalibration), the non-blocking incremental design, the slow pattern-mining option, dry-run behavior, and read-only last_cycle_only mode. This goes well beyond annotations and there is no contradiction.
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?
Although lengthy, the description earns its length through structured sections (MODES, Args) and immediately front-loads the core purpose and operational guidance. There is no redundant filler; each sentence adds necessary information for correct invocation of a complex 19-parameter 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?
The description is complete for the tool's complexity: it covers default behavior, alternative modes, per-parameter semantics, performance characteristics, read-only vs. mutating operations, and safe call frequency. Since an output schema exists, return-value details are not required. No meaningful 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?
Schema description coverage is 0%, so the description must compensate. It does: the 'Args' section explains all 19 parameters, including defaults and semantic intent. The MODES section additionally documents maintenance_op's accepted values and behavior. This turns an effectively opaque schema into a usable interface.
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 opens with a specific verb and resource: 'Run incremental cognitive maintenance — processes a small batch per call.' It clearly distinguishes the main behavior and further clarifies multiple modes (default, maintenance_cycle, last_cycle_only, maintenance_op), making the tool's purpose unambiguous even among sibling tools.
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 it: 'DESIGNED TO BE CALLED OFTEN' and 'Running regularly (e.g. at end of conversation) gradually maintains the entire database without blocking.' It also explains the different modes and when each is appropriate. It does not explicitly contrast with sibling tools, but the intended call cadence and mode selection provide strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage proactive triggers + v0.8.0 bounded-backlog pruning.
ACTIONS:
"pending": Get pending triggers (default).
"history": View past triggers.
"acknowledge": Mark trigger as seen.
"deliver": Mark as shown to user.
"act": Mark as acted upon.
"dismiss": Dismiss as irrelevant.
"prune": v0.8.0 — expire overdue triggers + evict oldest when over
max_pending. Set dry_run=False to actually persist.
Args: action: One of the actions above. trigger_id: Required for acknowledge/deliver/act/dismiss. trigger_type: Filter by type (for pending/history). limit: Max results. dry_run: For prune — preview without persisting. max_pending: For prune — soft cap on the pending backlog (default 64).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| action | No | pending | |
| dry_run | No | ||
| trigger_id | No | ||
| max_pending | No | ||
| trigger_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it explains that acknowledge/deliver/act/dismiss are marking operations, and prune has a dry_run mode to preview before persisting. Annotations already mark it as idempotent and non-destructive, and the description reinforces this with specifics like 'Set dry_run=False to actually persist'.
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 front-loaded with the overall purpose, then uses bullet points for actions and arguments, making it easy to scan. It is concise but covers all necessary details. Minor redundancy: the args section repeats action and parameter names, but overall it is well-structured.
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 6 parameters, multiple actions, and an output schema, the description is largely complete. It explains all actions and parameters, and the output schema fills any return-value gaps. Lacks mention of error conditions or prerequisites, but these are not critical for the agent's immediate 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 has 0% description coverage, so the description bears the full burden. It thoroughly explains each parameter: action lists valid options, trigger_id is required for certain actions, trigger_type filters, limit for max results, dry_run and max_pending specifically for prune. This fully compensates for the lack of 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 manages proactive triggers and bounded-backlog pruning. It lists specific actions (pending, history, acknowledge, deliver, act, dismiss, prune) that define the resource and operations, distinguishing it from sibling tools which cover different domains like memory or conversation.
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 details each action's purpose (e.g., 'Get pending triggers', 'Mark trigger as seen'), which implicitly guides when to use each. However, it does not explicitly compare this tool to siblings or provide decision heuristics for choosing alternatives, which would elevate clarity further.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Many tools share adjacent responsibilities (recall vs memory search vs graph recall_with_links; procedure vs skill; think vs conflict), so an agent could easily pick the wrong one. The extensive descriptions provide routing guidance, but the boundaries are subtle enough that selection requires reading deeply.
Names are uniformly lowercase single words, but they mix bare verbs (recall, remember, correct, think) with noun subsystem labels (memory, graph, session, skill, pack). There is no consistent verb_noun pattern, though the names remain short and readable.
With 20 tools, the server sits at the heavy end of a reasonable range. Because many tools are actually multi-action dispatchers, the effective surface area is considerably larger than 20, which makes the toolset feel sprawling.
The surface is remarkably thorough: memory CRUD, recall, maintenance, conflicts, triggers, sessions, temporal queries, graph operations, procedures, skills, tasks, packs, and stats are all covered. Minor gaps remain (no deletion for procedures/skills, no category member removal), but core workflows have no dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
One memory, every AI: Claude, ChatGPT, Perplexity, Gemini, Cursor, OpenClaw, Hermes, any MCP client.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yantrikos/yantrikdb-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
