Un servidor MCP local muy ligero que proporciona a los agentes de codificación (Claude Code, GitHub Copilot, etc.) una base de conocimiento de ingeniería compartida para buscar y actualizar: convenciones internas, detalles de API, configuración de infraestructura, flujos de autenticación, configuración de desarrollo local, etc.
El conocimiento reside como archivos Markdown simples en este repositorio Git. El servidor MCP es una capa fina y sin estado de lectura/escritura sobre el sistema de archivos: nada más.
Los agentes de codificación pueden buscar en la base de conocimiento en lugar de adivinar las convenciones internas o pedir al usuario que se repita.
Los agentes pueden capturar nuevos hechos con casi ninguna fricción (una llamada de herramienta, sin necesidad de saber dónde pertenece el hecho).
Los agentes pueden crear y actualizar documentos de conocimiento estructurados de forma determinista.
Todo es Markdown en Git, por lo que es útil incluso sin el servidor MCP: búscalo con grep, léelo, edítalo, revisa los diffs, haz commit, haz PR, exactamente como código.
Related MCP server: context-book
engineering-knowledge-mcp/
├── knowledge/ # the knowledge base itself (Markdown, organized by topic area)
│ ├── api/
│ ├── cloud/
│ ├── data/
│ ├── frontend/
│ └── general/
├── inbox/
│ └── knowledge-inbox.md # low-friction capture target; triage manually into knowledge/
├── src/
│ ├── index.ts # MCP server entrypoint (stdio transport)
│ ├── paths.ts # path sanitization / traversal protection
│ ├── knowledge.ts # search, get, create, update, capture logic
│ └── tools/index.ts # MCP tool registration + input schemas
├── test/ # node:test unit tests
├── CLAUDE.md # agent instructions auto-loaded by Claude Code when working in this repo
├── package.json
└── tsconfig.jsonDecisiones de diseño, deliberadamente:
MCP solo sobre stdio. Sin servidor HTTP, sin Express: el cliente (Claude Code, Copilot, MCP Inspector) inicia este proceso y habla JSON-RPC sobre stdin/stdout.
Sin base de datos, sin embeddings, sin almacén vectorial. La búsqueda es coincidencia de tokens sin distinción de mayúsculas/minúsculas sobre secciones de Markdown, calculada bajo demanda. Esto es suficiente a la escala de decenas a cientos de documentos pequeños, y significa que no hay índice que mantener sincronizado con los archivos en disco: los archivos son la fuente de verdad, siempre.
Sin índice en memoria, sin vigilancia del sistema de archivos. Cada llamada de herramienta lee lo que necesita del disco en el momento de la llamada. Más simple y barato a esta escala.
Sin commits automáticos de Git. Las llamadas de herramienta solo tocan el árbol de trabajo. La revisión y el commit/push dependen de ti. (El diseño deja espacio para añadir auto-commit o creación de PR más adelante sin cambiar los contratos de las herramientas).
El resumen mencionaba @modelcontextprotocol/server; el paquete realmente publicado es @modelcontextprotocol/sdk (v1.30+), que es el que usa este proyecto (McpServer + StdioServerTransport).
Cada documento es un archivo Markdown bajo knowledge/<area>/<topic>.md, con frontmatter mínimo opcional:
---
title: APIM
tags:
- api
- apim
---
# APIM
## Base paths
Internal modelling APIs use ...
## Authentication
...
## Local development
...No hay esquema obligatorio más allá de eso: el frontmatter es opcional, los encabezados son solo secciones ## normales de Markdown. search_knowledge y update_knowledge usan encabezados de nivel ## (y más profundos) como unidad de "sección", por lo que estructurar los documentos con encabezados claros hace que tanto los resultados de búsqueda como las actualizaciones sean más precisos.
El conocimiento capturado pero no clasificado va a inbox/knowledge-inbox.md como entradas con marca de tiempo. Periódicamente (a mano, o pidiendo a un agente que ayude) mueve/organiza las entradas de la bandeja de entrada a los documentos adecuados en knowledge/.
Requiere Node.js 20+.
npm install
npm run build
npm startPara iteración local (se ejecuta directamente desde TypeScript mediante tsx, sin paso de compilación):
npm run devAmbos inician el servidor en stdio y esperan a que un cliente se conecte: no verás tráfico de protocolo en la terminal; solo registros de inicio/diagnóstico (escritos en stderr, nunca en stdout, ya que stdout está reservado para los mensajes del protocolo MCP).
Interfaz interactiva:
npx @modelcontextprotocol/inspector npm run devEsto abre una interfaz de navegador donde puedes llamar a search_knowledge, list_knowledge_topics, get_knowledge, capture_knowledge, create_knowledge y update_knowledge manualmente e inspeccionar sus esquemas JSON y respuestas.
No interactivo / scriptable:
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call --tool-name search_knowledge --tool-arg query="apim authentication"Claude Code / la mayoría de los clientes MCP usan un bloque de configuración como:
{
"mcpServers": {
"engineering-knowledge": {
"command": "node",
"args": ["/absolute/path/to/engineering-knowledge-mcp/dist/index.js"]
}
}
}Para el soporte MCP de GitHub Copilot, usa la entrada de servidor stdio equivalente command/args en su archivo de configuración MCP. Ejecuta npm run build primero para que exista dist/index.js, o apunta command/args a npx tsx /absolute/path/to/src/index.ts para ejecutar desde el código fuente directamente.
Este repositorio incluye un CLAUDE.md con la instrucción siguiente, que Claude Code carga automáticamente cuando trabaja dentro de este repositorio. Para otros clientes (Copilot, etc.), añade la instrucción equivalente a su prompt de sistema / archivo de instrucciones:
Antes de preguntar al usuario sobre convenciones de ingeniería internas, infraestructura, APIs, autenticación, configuración de plataforma o patrones de desarrollo establecidos, busca en el MCP de conocimiento de ingeniería. No inventes valores de configuración internos. Si el usuario pide explícitamente recordar, capturar o añadir conocimiento de ingeniería duradero, usa las herramientas de escritura del MCP de conocimiento.
Guía herramienta por herramienta:
search_knowledge(query) — primera parada para "¿cómo solemos...?", "¿cuál es nuestra convención para...?", "¿cuál es la URL base / flujo de autenticación para...?". Devuelve secciones clasificadas con rutas de archivo, no documentos completos. También busca entradas aún no clasificadas en inbox/knowledge-inbox.md, por lo que una captura reciente es localizable incluso antes de que se haya archivado bajo un tema adecuado. Entre los documentos que ya coinciden en el texto del cuerpo/encabezado, uno cuyo frontmatter tags también coincida con una palabra de la consulta se clasifica más alto: las etiquetas aumentan la clasificación, no crean una coincidencia por sí solas.
list_knowledge_topics() — sin argumentos; lista la ruta, el título y las etiquetas de cada documento sin el contenido completo. Úsalo para explorar lo que existe cuando aún no tienes un buen término de búsqueda, o para comprobar si un tema ya existe antes de llamar a create_knowledge.
get_knowledge(topicOrPath) — una vez que sabes (o search_knowledge te dijo) qué documento quieres, tráelo completo. Acepta referencias flexibles: "apim", "api/apim" o "knowledge/api/apim.md".
capture_knowledge(content, suggestedTopic?) — úsalo cuando el usuario diga "recuerda esto" / "anota eso" / afirme un hecho que vale la pena conservar, y no quieras hacerle averiguar dónde pertenece. Simplemente añade a la bandeja de entrada.
create_knowledge(topic, title, content) — úsalo al añadir un tema genuinamente nuevo que aún no existe. Falla de forma clara si el tema ya existe (usa update_knowledge en su lugar).
update_knowledge(topicOrPath, heading, content, mode) — la herramienta de escritura deliberadamente no en lenguaje natural. Consulta la nota de diseño a continuación.
update_knowledge toma heading + mode en lugar de un change de texto libreEl resumen marcó esto como algo que necesita un diseño cuidadoso: el objetivo es que el agente (que tiene un LLM) decida qué significa un cambio en lenguaje natural, no que este servidor ejecute su propia interpretación de IA de las instrucciones. Así que update_knowledge toma un objetivo estructural y determinista en su lugar:
topicOrPath — qué documento.
heading — el texto exacto del encabezado ##/###/etc. que identifica una sección. Si no existe, se añade una nueva sección ## con ese encabezado al final del documento (para que las actualizaciones nunca fallen silenciosamente contra documentos ligeramente desactualizados).
content — el Markdown literal a escribir.
mode: "append" (por defecto) añade content al final de la sección, "replace" sobrescribe todo el cuerpo de la sección.
Esto significa que se espera que el agente que llama ya haya convertido "actualiza la sección de desarrollo local para mencionar el nuevo puerto" en contenido Markdown concreto y haya elegido append/replace — exactamente el tipo de juicio que un cliente basado en LLM está posicionado para hacer, y exactamente el tipo de juicio que este servidor ligero no debería hacer a partir de una cadena cruda.
Si ya tienes notas en algún lugar (una wiki personal, una carpeta de archivos .md, una exportación de Notion, un gran documento de "conocimiento tribal", hilos de Slack que has guardado, etc.), no hay herramienta de importación ni formato especial al que convertir: esto es deliberadamente solo una carpeta de archivos Markdown. Dos formas de empezar, aproximadamente en orden de cuánto de tu estructura existente vale la pena preservar:
A. Coloca los archivos directamente (mejor cuando tus notas ya están razonablemente organizadas)
Copia tus archivos .md existentes a knowledge/, clasificándolos en las carpetas que mejor encajen de api/ cloud/ data/ frontend/ general/ (o añade nuevas carpetas de temas: nada impone las cinco iniciales).
Añade frontmatter mínimo (title, opcionalmente tags) a cada uno si no lo tiene: no es obligatorio, pero es barato y get_knowledge/los resultados de búsqueda se leen mejor con un título.
Divide documentos muy largos en secciones ## con encabezados si aún no lo están: search_knowledge y update_knowledge operan a nivel de encabezado, por lo que un muro de texto de 10,000 palabras en una sola sección se buscará/actualizará peor que el mismo contenido dividido bajo unos pocos encabezados claros.
Ejecuta npm test (verificación de que nada se rompió) y prueba algunas llamadas de search_knowledge / get_knowledge mediante el Inspector (§5) con tu contenido real.
Revisa el diff y haz commit tú mismo, igual que cualquier otro cambio en este repositorio.
B. Deja que un agente haga la migración por ti (mejor para material fuente desordenado/sin estructurar)
Apunta Claude Code (u otro agente de codificación, una vez que este MCP esté configurado para él) a tus notas existentes y pídele que las migre usando las herramientas de escritura. Por ejemplo:
Tengo notas de ingeniería en
~/notes/engineering/. Léelas y usacreate_knowledgepara convertirlas en documentos adecuados bajoknowledge/, agrupados por tema. Cuando algo no encaje limpiamente en un tema existente, usacapture_knowledgeen su lugar para que caiga en la bandeja de entrada para que yo lo revise.
Esto funciona bien porque convertir prosa desordenada en "un título, algunas etiquetas, unas pocas secciones ## claras" es exactamente el tipo de juicio en el que un agente basado en LLM es bueno: el mismo razonamiento detrás de por qué update_knowledge empuja ese juicio al llamador en lugar del servidor (ver §7). El agente aún no puede escribir fuera de knowledge//inbox/, y cada archivo resultante aparece como un archivo normal sin seguimiento/modificado para que lo revises antes de hacer commit: nada se auto-commitea.
De cualquier manera, trata el primer pase como un borrador: está bien (incluso se espera) que capture_knowledge produzca una bandeja de entrada larga que clasifiques en varias sesiones en lugar de intentar obtener una taxonomía perfecta desde el principio.
Todas las lecturas/escrituras están restringidas a knowledge/ e inbox/ bajo la raíz del repositorio. Cada ruta proporcionada por el llamador pasa por safeResolve (src/paths.ts), que rechaza rutas absolutas, traversal .., bytes nulos y cualquier cosa que resuelva fuera del directorio permitido.
create_knowledge sanitiza el topic en un segmento de nombre de archivo seguro antes de usarlo.
Ningún contenido de documento se ejecuta, evalúa o se pasa a un shell.
Ninguna herramienta ejecuta un comando de shell basado en entrada MCP.
Los errores son explícitos (por ejemplo, "no se encontró ningún documento de conocimiento que coincida con X") en lugar de recurrir a suposiciones.
Low-friction capture of a durable engineering fact or convention, e.g. 'When testing the modelling API locally, X must be set to Y.' Appends a timestamped entry to inbox/knowledge-inbox.md for later triage into knowledge/. Does not require knowing where the information belongs. Use when the user explicitly asks to remember, capture, or add durable engineering knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The knowledge to capture, in plain language | |
| suggestedTopic | No | Optional hint about where this might eventually belong |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure, and it succeeds: it states that it appends a timestamped entry to a specific file (inbox/knowledge-inbox.md) and that the entry is for later triage into knowledge/. It also clarifies that it does not require knowing where the information belongs, setting correct expectations. It could mention potential effects (e.g., file creation or append behavior) but the essential behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence followed by an example and a usage directive. It front-loads the core purpose, provides a concrete illustration, and adds the usage trigger without any filler. Every element earns its place, and the whole fits comfortably in a readable length.
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 only two parameters, one required, no output schema, and no nested structures, the description is fully sufficient. It covers what the tool does, where it writes, when to use it, and the key benefit (low friction). Nothing an agent needs to correctly invoke this tool is missing.
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?
Although the schema already documents both parameters at 100% coverage, the description adds meaningful semantic context. It explains that content is a durable engineering fact or convention, gives an example, and clarifies that suggestedTopic is optional because the tool does not require knowing the target location. This goes beyond mere schema repetition and helps an agent understand how both fields interact.
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 a specific verb ('capture'), a target resource (durable engineering knowledge appended to inbox/knowledge-inbox.md), and a clear distinction from direct knowledge creation. It includes a concrete example that helps an agent immediately recognize what counts as appropriate input, and the sibling list (create_knowledge) reinforces the uniqueness of this tool as an inbox capture.
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 on when to use the tool: 'Use when the user explicitly asks to remember, capture, or add durable engineering knowledge.' It also explains the benefit ('Does not require knowing where the information belongs'), which implicitly signals that create_knowledge is the alternative when topic placement is known. However, it does not explicitly list when-not-to-use conditions or name sibling alternatives, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Markdown knowledge document under knowledge/.md. Fails if a document already exists at that path (use update_knowledge instead). Topic paths are sanitized and cannot escape the knowledge directory.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Document title, used in frontmatter and as the H1 if content has none | |
| topic | Yes | Topic path, e.g. 'api/graphql' or 'cloud/gcp' | |
| content | Yes | Markdown body content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing the fail-if-exists behavior, path sanitization, and containment within the knowledge directory. It does not mention the success return value or authorization requirements, but those are secondary for a create operation with this level of detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the main action is front-loaded, the failure condition follows immediately, and the alternative tool is named without extra prose. Every sentence contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple create tool: it covers purpose, path behavior, failure mode, and the key alternative. The only minor gap is not describing what a successful response looks like, but the absence of an output schema makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds useful context for topic by explaining the knowledge/<topic>.md mapping and sanitization, but it does not significantly expand on title or content beyond what the schema already says.
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 names the specific action (create), the resource (Markdown knowledge document), and the exact storage location (knowledge/<topic>.md). It also explicitly contrasts itself with update_knowledge by stating the failure condition when the document already exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly says to use update_knowledge instead when a document already exists, which gives an explicit create-vs-update routing rule. It does not explicitly contrast itself with capture_knowledge, but the failure-on-existing condition makes the intended use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full content of a specific knowledge document by topic or path. Accepts loose references such as 'apim', 'api/apim', or 'knowledge/api/apim.md'.
| Name | Required | Description | Default |
|---|---|---|---|
| topicOrPath | Yes | Topic name or relative path, e.g. 'apim' or 'api/apim' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates it is a read operation ('Retrieve'), which implies no side effects. However, it does not disclose details like error handling (e.g., behavior when topic is not found), authentication requirements, or rate limits. For a simple read tool this is adequate but not comprehensive.
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 exceptionally concise, with two sentences that front-load the primary purpose and then provide illustrative examples. Every word earns its place, with no filler or redundant content. This is ideal for efficient agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers the essential aspects: what it does (retrieve full content) and what inputs it accepts. It does not specify the return format (e.g., markdown text) or any failure modes, but given the simplicity of the tool, this is not a significant gap. The description is sufficient for an agent to know how to invoke it 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?
Since schema coverage is 100%, the parameter is already well-documented in the schema with an example. The description adds value by explaining that loose references are accepted and provides additional format examples ('knowledge/api/apim.md'), which the schema does not cover. This goes beyond mere repetition and helps the agent understand the flexibility of the input.
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 verb 'Retrieve' and the resource 'full content of a specific knowledge document', making the purpose unambiguous. It also distinguishes from siblings by focusing on retrieval of a specific document by topic/path, as opposed to search or list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool - when you have a specific topic or path - and gives concrete examples of accepted loose references. It does not explicitly name sibling tools or state when not to use it, but the implication is clear that this is for known references rather than discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every knowledge document (path, title, tags) without full content. Use this to browse what topics exist before deciding what to search for, when a keyword search comes up empty, or to check whether a topic already exists before calling create_knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It implies a read-only operation (listing without side effects) and even mentions checking existence before creation, but it does not explicitly state 'read-only' or 'non-mutating'. It is clear enough, though not fully explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and tightly packed with purpose, output details, and usage guidance. No unnecessary words or redundancy; it is efficiently 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 the simplicity of the operation (no parameters, no output schema), the description provides sufficient context: what it lists, what it omits, and when to use it. It covers the essential aspects for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are no parameters to describe. The description adds no parameter-related information, but since schema coverage is 100% (empty), a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists knowledge documents with their path, title, and tags, and explicitly excludes full content. It distinguishes from sibling tools by framing it as a browsing/pre-check operation, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: browsing topics before searching, when keyword search returns empty, and before calling create_knowledge. This gives clear guidance on when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search all engineering knowledge Markdown documents (and not-yet-triaged inbox captures) with simple case-insensitive text matching, boosted by frontmatter tag matches. Returns the strongest matching sections (not full documents) ranked by relevance, with file paths. Use this before asking the user about internal conventions, infra, APIs, auth, or platform config.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search terms, e.g. 'apim authentication' or 'aws s3 bucket policy' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the matching mechanism (case-insensitive text, tag boosting), the scope (including not-yet-triaged inbox captures), and the return format (sections with file paths). It does not mention potential side effects or limitations like rate limits, but the read-only nature is strongly implied by 'Search'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, consisting of two sentences that efficiently cover the tool's functionality, output, and usage context. There is no redundant or vague wording, and every clause contributes informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description single-handedly provides sufficient context: it defines the search scope, matching behavior, return details, and a clear use-case. It also clarifies that it returns sections rather than full documents, which is crucial for an agent deciding between this and a document retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description adds meaning to the single 'query' parameter by explaining that it performs case-insensitive text matching and that tag matches boost results. This goes beyond the schema's example terms, giving the agent insight into how the query is interpreted.
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 function: searching all engineering knowledge Markdown documents, including inbox captures. It specifies the resource, the verb 'Search', and the output (sections with file paths), making it unambiguous and distinct from other potential 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?
Explicit guidance is provided: 'Use this before asking the user about internal conventions, infra, APIs, auth, or platform config.' This tells the agent exactly when to invoke this tool, and the implicit contrast with retrieving full documents (sections vs. full documents) hints at when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deterministically update an existing knowledge document by targeting a specific Markdown heading. This tool does NOT interpret natural-language change requests — the caller must decide what content to write and whether to append to the section or replace it. If the heading doesn't exist, a new section is appended at the end of the document.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'append' adds content to the end of the section; 'replace' overwrites the section body | append |
| content | Yes | Markdown content to write into the section | |
| heading | Yes | Exact heading text to target, e.g. 'Local development' | |
| topicOrPath | Yes | Topic name or relative path identifying the document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool is deterministic, does not interpret natural language, targets a specific heading, and appends a new section if the heading is missing. This covers key operational behavior, though it does not mention permissions, error handling, or reversibility—acceptable for a low-risk knowledge document update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficient and front-loaded with the core action. The key behavioral constraints (deterministic, no NL interpretation, heading behavior) are stated without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 4 parameters, no output schema, and no annotations, the description covers the main operational aspects: target document, heading behavior, append/replace semantics, and the caller's responsibility. It lacks explicit mention of edge cases like handling invalid paths or partial failures, but these are not critical for a knowledge base update.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds value beyond the schema by explaining the heading-targeting behavior (exact text, and appending a new section if not found) and by clarifying that the caller must decide between append and replace, which maps to the mode parameter but is not fully explicit in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (update), resource (existing knowledge document), and a precise mechanism (targeting a Markdown heading). It explicitly distinguishes itself from natural-language change requests and implies it is not for creation, which differentiates it from siblings like create_knowledge and capture_knowledge.
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 clearly implies use for updating existing documents and clarifies it is deterministic, but it does not explicitly name alternatives or state when not to use it (e.g., for creating new docs, use create_knowledge). The behavioral note about appending a new section when heading is missing provides some context, but sibling differentiation is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0capture_knowledgecreate_knowledgeget_knowledgelist_knowledge_topicssearch_knowledgeupdate_knowledgeScored across 6 tools
All six tools have distinct purposes: searching, listing, retrieving, capturing to inbox, creating new docs, and updating existing docs. No overlapping or ambiguous functions.
Tool names follow a consistent verb_noun pattern (search_knowledge, list_knowledge_topics, get_knowledge, capture_knowledge, create_knowledge, update_knowledge). Verbs clearly indicate actions and nouns correctly describe the target.
Six tools is a well-scoped number for a knowledge management server, covering search, browse, read, capture, create, and update without unnecessary redundancy.
The tool set covers create (capture and create), read (search, list, get), and update, but lacks a delete/remove operation. This is a minor gap since knowledge bases may need to retire outdated entries, but core workflow is supported.
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Hosted markdown project wikis your team's AI assistants read, search, and update over MCP.
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.