Servidor MCP local de código abierto + habilidades de agente que sirven documentación oficial de Zig siempre actualizada para la última versión, un corpus de guía de software ligero de alto rendimiento seleccionado, y una auto-actualización segura con simulación previa (dry-run) para una cadena de herramientas Zig local desactualizada.
zig-docs-mcp
├── zigdocs MCP server (stdio, local, no accounts)
├── guidance/ curated performance guidance (12 topics)
├── skills/zig-docs agent skill: operating rules for Zig work
└── skills/zig-docs-mcp agent skill: Python integration (`zdoc` singleton)Zig cambia rápido, y las respuestas de la memoria de entrenamiento se quedan obsoletas entre versiones menores — 0.16 reemplazó toda la capa de E/S y movió Dir de std.fs a std.Io. Este servidor obtiene documentación oficial y fuentes std publicadas en cada llamada (con revalidación TTL corta), de modo que cada respuesta cita la versión de la que proviene. Cuando tu compilador local se queda atrás respecto a la documentación, el servidor lo indica y ofrece una actualización controlada. Nunca modifica tu sistema sin confirmación explícita.
Related MCP server: Zignet
La documentación se queda obsoleta rápidamente. El diseño de la biblioteca estándar de Zig cambia entre versiones menores. Servir las fuentes reales de la última versión es la única fuente fiable de verdad de la API. zig_std resuelve símbolos recorriendo las re-exportaciones reales en el árbol publicado, no una instantánea extraída.
El consejo de rendimiento debería ser mecánico. El corpus incluido explica estrategia de asignación, diseño de datos, comptime, tamaño del binario, latencia de arranque, SIMD, concurrencia y benchmarks, basándose en cómo se comportan realmente el hardware y el runtime (líneas de caché, syscalls, fallos de página), no en sensaciones.
Un compilador desactualizado invalida silenciosamente todo. zig_version_status compara tu cadena de herramientas con el índice ascendente en cada comprobación, y zig_update ofrece un plan de actualización concreto y revisable.
Todo es local-primero. El servidor se ejecuta en tu máquina a través de stdio. Sin cuentas, sin tokens, sin telemetría. La red solo se usa para ziglang.org para documentación, notas de versión y archivos fuente.
Las respuestas en caché se revalidan contra ziglang.org cuando tienen más de 6 horas (force=true revalida inmediatamente). La revalidación usa GET condicionales (ETag / Last-Modified), por lo que es económica.
Seguro sin conexión: si la red no está disponible, el contenido en caché se sirve con una marca stale en lugar de fallar. (La primera ejecución necesita red una vez).
Las fuentes std provienen del archivo src oficial por versión, el contenido canónico incluso cuando las etiquetas de versión de GitHub se retrasan (0.16.0 no estaba etiquetado en GitHub cuando se construyó esto). El archivo se descarga una vez por versión y solo se extrae lib/std/**.
El parámetro channel selecciona stable (última versión, por defecto) o master (nocturno), para que puedas previsualizar los cambios de la próxima versión.
Diseño de caché (~/.cache/zig-docs-mcp/, se puede sobrescribir con ZIG_DOCS_MCP_CACHE):
~/.cache/zig-docs-mcp/
├── http/ upstream bodies + ETag/Last-Modified metadata
├── langref-0.16.0.json parsed reference sections (per version)
├── notes-0.16.0.json release-notes digest
├── zig-0.16.0-src.tar.xz source tarball cache
└── src/0.16.0/lib/std/ extracted std sources (550 files)Python ≥ 3.10 y uv
macOS o Linux (la auto-actualización soporta instalaciones Homebrew y autónomas; Windows obtiene un plan de impresión funcional pero aún no una estrategia de archivos)
Acceso de red a ziglang.org para las primeras descargas y revalidación
git clone https://github.com/gbrlpzz/zig-docs-mcp
cd zig-docs-mcp
uv tool install . # installs the `zigdocs` command on your PATH
zigdocs --help # verify¿Prefieres no instalarlo? Ejecútalo directamente desde el clon:
uv run --project ~/zig-docs-mcp zigdocsCualquier cliente MCP que hable stdio. Apúntalo al comando zigdocs:
{
"mcpServers": {
"zig-docs": {
"command": "zigdocs"
}
}
}Sin una instalación global, usa el clon directamente:
{
"mcpServers": {
"zig-docs": {
"command": "uv",
"args": ["run", "--project", "/path/to/zig-docs-mcp", "zigdocs"]
}
}
}Dos habilidades se incluyen en este repositorio. Crea enlaces simbólicos y reinicia la sesión (o ejecuta /reload):
ln -sfn ~/zig-docs-mcp/skills/zig-docs ~/.agents/skills/zig-docs
ln -sfn ~/zig-docs-mcp/skills/zig-docs-mcp ~/.agents/skills/zig-docs-mcpLuego, desde el kernel del agente:
from zig_docs_mcp import zdoc
await zdoc.zig_version_status() # local vs latest upstream
await zdoc.zig_update() # dry-run upgrade plan
await zdoc.zig_update(dry_run=False, confirm=True) # apply after user agrees
await zdoc.zig_langref(section="Errors") # fresh language reference
await zdoc.zig_std(symbol="std.heap.ArenaAllocator") # std docs from released source
await zdoc.zig_changelog() # what changed in the release
await zdoc.perf_guidance(topic="allocation-strategy") # curated guidance
await zdoc.zig_search(query="vectorization") # search everything at onceLas llamadas devuelven su resultado como una cadena JSON (las lecturas de guía de tema completo devuelven markdown sin procesar); analiza con json.loads(...) cuando necesites campos como version o docs. Los argumentos son solo de palabra clave. El comando del servidor se resuelve en orden: ZIG_DOCS_MCP_CMD, un zigdocs en PATH, luego uv run --project contra ZIG_DOCS_MCP_REPO (por defecto ~/zig-docs-mcp).
skills/zig-docs/SKILL.md contiene las reglas operativas que sigue el agente: comprobar versión primero, documentación antes que código, citar la versión de la documentación y nunca aplicar una actualización sin la aprobación explícita del usuario.
zig_version_statusCompara el zig version local con la última versión ascendente.
{
"local_version": "0.16.0",
"local_path": "/opt/homebrew/bin/zig",
"latest_stable": "0.16.0",
"master": "0.17.0-dev.1818+7051f8e73",
"up_to_date": true
}Cuando la cadena de herramientas local es más antigua, la respuesta añade behind y una suggestion que apunta a zig_update (ejemplo ilustrativo):
{
"local_version": "0.15.2",
"latest_stable": "0.16.0",
"up_to_date": false,
"behind": "local 0.15.2 < latest 0.16.0",
"suggestion": "Call the zig_update tool (dry-run first) to upgrade the local toolchain to the latest stable release."
}zig_updateActualiza la cadena de herramientas local. La simulación previa (dry-run) es el valor predeterminado: imprime el plan exacto y no cambia nada. Aplicar requiere dry_run=false, confirm=true. Consulta Auto-actualización de la cadena de herramientas.
zig_langrefReferencia oficial del lenguaje, obtenida recientemente para la versión del canal.
section="Errors" → texto completo de la sección (los bloques de código se conservan):
### Error Set Type
An error set is like an enum. However, each error name across the entire
compilation gets assigned an unsigned integer greater than 0. ...query="vector" → secciones clasificadas:
[{"section_id": "Vectors", "title": "Vectors§"},
{"section_id": "Builtin-Functions", "title": "Builtin Functions§"}]sin argumentos → la lista de todos los ids de sección.
zig_stdDocumentación de la biblioteca estándar de la fuente publicada exacta. La resolución de símbolos recorre las re-exportaciones reales (std.zig → heap.zig → heap/ArenaAllocator.zig), sigue los alias de @import y devuelve la documentación /// más el texto de la declaración de esa versión:
{
"symbol": "std.ArrayList",
"version_source": "0.16.0",
"file": "lib/std/std.zig",
"line": 49,
"declaration": "pub fn ArrayList(comptime T: type) type {\n return array_list.Aligned(T, null);\n}",
"docs": "A contiguous, growable list of items in memory. This is a wrapper around a\nslice of `T` values. ..."
}Si un nombre no es una declaración de nivel superior simple en el espacio de nombres recorrido (los diseños se mueven entre versiones), la herramienta recurre a una búsqueda en todo el corpus de declaraciones de nivel superior, mejor coincidencia primero, por ejemplo, std.fs.Dir en 0.16 muestra correctamente lib/std/Io/Dir.zig. query="arena" busca directamente en los comentarios de documentación de std.
zig_changelogResumen de notas de versión para la versión del canal actual: títulos de sección más un breve resumen de cada una. Útil justo después de que se publique una versión (zig_changelog(force=true)).
perf_guidanceGuía seleccionada para software ligero de alto rendimiento. Sin argumentos lista temas; topic="allocation-strategy" devuelve la guía completa (markdown sin procesar con Principio / Mecánica / Modismo de Zig / Anti-patrones / Reglas generales); query=... busca en todas las guías.
zig_searchBúsqueda unificada en langref, comentarios de documentación de std y guía:
{"query": "vectorization", "langref": [...], "guidance": [...], "std": [...], "std_version": "0.16.0"}scope lo reduce: all (predeterminado) | langref | std | guidance.
zig_update elige una estrategia automáticamente:
Zig gestionado por Homebrew (el binario se resuelve dentro del prefijo de brew) → brew upgrade zig:
{
"mode": "dry-run (nothing changed). Re-run with confirm=true to apply.",
"target_version": "0.16.0",
"current": "0.16.0",
"strategy": "homebrew",
"command": ["brew", "upgrade", "zig"],
"note": "Homebrew formula may lag the newest release slightly."
}Instalación autónoma (archivo oficial, cualquier otra ubicación) → descarga el archivo de la plataforma del índice ascendente, lo extrae en ~/.local/opt/zig-<version> y crea un enlace simbólico ~/.local/bin/zig:
{
"strategy": "standalone-tarball",
"download": "https://ziglang.org/download/0.16.0/zig-aarch64-macos-0.16.0.tar.xz",
"install_dir": "~/.local/opt/zig-0.16.0",
"steps": ["download ...", "extract ...", "symlink ~/.local/bin/zig -> .../zig/zig"],
"activation": "~/.local/bin is first on PATH; new zig takes effect immediately"
}Si ~/.local/bin no es lo primero en PATH, el plan lo dice explícitamente: el compilador antiguo seguiría ganando, y la herramienta te dice cómo arreglar el orden.
Reglas de seguridad:
El valor predeterminado es una simulación. No se descarga, mueve ni enlaza nada.
Aplicar requiere dry_run=false, confirm=true juntos.
Se instruye a los agentes que usan este servidor para que muestren el plan y obtengan la aprobación explícita del usuario antes de confirmar.
Doce temas en guidance/, incluidos en la rueda y servidos por perf_guidance. Los principios son universales; los fragmentos son de la era Zig 0.16; la verdad exacta de la API siempre proviene de zig_std, nunca del corpus.
Tema | Resumen de una línea |
| Iguala el asignador al ciclo de vida; costo de puntero de arena vs. contabilidad del asignador general; asignaciones ocultas. |
| Matemática de bytes SoA vs AoS en líneas de caché de 64 bytes; división caliente/fría; |
| Los resultados de Comptime se convierten en rodata/inmediatos; las tablas en tiempo de ejecución cuestan páginas sucias. |
| Los slices son 16 bytes; asignar por token cuesta una asignación, un memcpy y líneas de caché por token. |
| Tamaño = alcanzabilidad; strip, modos de pánico, higiene de dependencias; texto más pequeño = menos fallos de página de inicio. |
| Sin init_array, fallos de página de texto perezosos, init perezoso, sin trabajo antes de argv. |
| Matemática de relleno, orden de campos, estructuras empaquetadas, aserciones de comptime |
| Bloqueadores de auto-vectorización, acumulación por carriles + reducción única, |
| Costo MESI de escrituras compartidas, estacionamiento de futex, procesamiento por lotes de syscalls, relleno de falso uso compartido. |
| Los errores son valores u16; |
| Compilaciones de lanzamiento, calentamiento, mínimo/mediana sobre la media, sumidero para vencer a DCE, contadores. |
| Std primero; las dependencias añaden código enlazado y fragilidad de compilación; provee utilidades diminutas. |
Variable | Significado | Predeterminado |
| directorio de caché |
|
| línea de comandos completa del servidor (anulación de habilidad) | — |
| directorio del repositorio para la alternativa |
|
make sync # deps
make test # unit tests (offline; std-source tests skip without warm cache)
make e2e # spawns the real server over stdio, calls every tool
make fmt # ruff format + checkEl conjunto de pruebas e2e necesita red en la primera ejecución (calienta la caché). Las pruebas unitarias que ejercitan la resolución de símbolos se ejecutan contra la caché de fuentes std caliente y se omiten limpiamente cuando no está presente.
zigdocs server not found (habilidad de Prime Agent): instala con uv tool install . desde el clon, o establece ZIG_DOCS_MCP_REPO a la ruta del clon, o establece ZIG_DOCS_MCP_CMD a una línea de comandos completa.
La primera ejecución falla sin conexión: la caché comienza vacía; obtén una vez mientras estés en línea. Después, la alternativa de caché obsoleta mantiene todas las herramientas funcionando.
Los resultados parecen obsoletos después de una nueva versión: pasa force=true (de lo contrario, se aplica el TTL de 6 horas).
zig version sigue siendo antiguo después de una actualización: se necesita un nuevo shell, y ~/.local/bin debe preceder al directorio de instalación anterior en PATH. El plan de simulación indica la situación exacta de tu máquina.
El zig de Homebrew se retrasa con la versión más reciente: las fórmulas de brew se retrasan con las versiones; usa la estrategia autónoma (elimina la fórmula de brew, instala autónoma) si necesitas versiones del primer día.
MIT — consulta LICENSE.
Curated guidance for high-performance lightweight software (Zig-first).
topic=None lists topics. topic='allocation-strategy' returns the guide. query searches across all guides. Principles are universal; snippets are Zig 0.16-era; verify exact APIs with zig_std.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| topic | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a limitation: snippets are Zig 0.16-era and advises verifying with zig_std. It also notes principles are universal, implying portability. These are behavioral traits beyond a simple 'getter'. It does not explicitly state it is read-only, but the 'curated guidance' framing implies a non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loading purpose and then usage. No redundant content; every sentence adds value. It packs routing and caveats efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and existing output schema (which covers return format), the description covers usage modes and limitations. It does not specify whether query and topic can be combined, but that is a minor gap. Overall, sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, so the description must explain parameters. It does: topic=None lists topics, topic='allocation-strategy' returns the guide, query searches across guides. This gives actionable meaning to both params, though it doesn't enumerate all topic values—acceptable because it instructs how to discover them.
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 it provides 'Curated guidance for high-performance lightweight software (Zig-first)', a specific resource type. It distinguishes from siblings like zig_std (API reference) and zig_search (search) by focusing on performance guidance. The usage examples (topic listing, specific topic retrieval, query search) further clarify its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains how to use without params (topic=None lists topics), with a specific topic (topic='allocation-strategy' returns the guide), and with query (searches across all guides). It also points to zig_std for API verification, indicating when not to rely on this tool for exact APIs. This is clear routing to an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release-notes digest for the current channel version: what changed.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| channel | No | stable |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only states the output ('release-notes digest') but not whether the operation is read-only, whether it makes network calls, whether the 'force' parameter triggers a refresh, or if there are any side effects. This minimal disclosure leaves significant ambiguity for a fetch-style 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 a single, concise sentence that is front-loaded with the core purpose. It is efficient and easy to parse. However, it omits parameter information, making it less complete though still appropriately sized for the tool's simplicity.
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 two optional parameters and an output schema, the description should explain what both parameters do and when to set them. It does neither. The output schema exists, so return format is covered, but the parameter semantics are entirely missing. The tool is simple, yet the description fails to equip the agent to use 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?
The input schema has two parameters (force, channel) but neither has a description, and the schema coverage is 0%. The description does not mention these parameters at all, so the agent has no explanation of what 'force' or 'channel' control. This is a critical gap for a tool with optional parameters.
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: it provides a digest of release notes for the current version of a given channel. The phrase 'what changed' conveys the specific information returned. This distinguishes it from sibling tools like zig_version_status (version info), zig_update (update action), and zig_search (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention any situational context, such as 'use this to see recent changes' or 'for details on a specific version use zig_search'. No exclusions or comparisons to siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Official Zig Language Reference, fetched fresh for the channel version.
section= returns that full section. query= searches sections. Neither lists all section ids. channel: 'stable' (latest release) or 'master'.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| query | No | ||
| channel | No | stable | |
| section | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions 'fetched fresh' implying network/caching behavior, and clarifies channel versions, but it does not explain the force parameter, potential side effects, rate limits, or what happens when both section and query are provided. Significant behavioral gaps remain.
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, front-loaded with the purpose, and each sentence earns its place. It is well-structured, moving from general purpose to specific usage details. No fluff or redundancy, though it could be slightly more detailed without losing 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?
Given the tool has 4 optional params and an output schema, the description covers the main modes but leaves gaps: it does not address the interaction between section and query (mutually exclusive or combinable), the effect of force, or the output format (though schema exists). It is adequate for basic use but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains section, query, and channel, giving concrete meaning (e.g., 'stable (latest release) or master'), but it does not describe the force parameter at all. The coverage is partial—3 out of 4 params—so it adds value but is incomplete.
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 fetches the official Zig Language Reference and specifies two modes (section retrieval and query search). It uses a specific verb and resource, but does not explicitly distinguish it from sibling tools like zig_search or zig_std, though the purpose is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for usage—it's the language reference fetcher—and explains the two modes, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative guidance is given, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified search across langref, guidance, and std doc comments.
scope: 'all' | 'langref' | 'std' | 'guidance'. Results are grouped per source with short snippets; follow up with zig_langref/zig_std/perf_guidance for full text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| scope | No | all | |
| channel | No | stable |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that results are grouped per source with short snippets and that follow-up tools provide full text. However, it does not mention default behaviors (e.g., scope and channel defaults), rate limits, or any additional side effects. Basic behavior is covered but not comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the purpose front-loaded. The second sentence provides essential hints about scope and follow-up, with no redundancy. It is concise but could be slightly more structured; still, it is efficient and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with four parameters and multiple sources. The description covers the search scope and output format (snippets, grouping) but does not explain the channel parameter or how limit affects results. It also leaves ambiguity about whether changelog is searched, given the sibling tools. The output schema likely covers return format, but the description has notable 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 description coverage is 0%, so the description must compensate. It explains the scope parameter by listing valid values and clarifies the grouping of results by source. However, it does not explain the 'limit' or 'channel' parameters at all, leaving them to schema defaults. This partial compensation is helpful but incomplete.
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 unified search across langref, guidance, and std doc comments, with a specific verb and resource. It also distinguishes itself from follow-up tools by indicating it returns snippets rather than full text. However, it does not explicitly contrast with all siblings (e.g., whether changelog is included), so it slightly misses full differentiation.
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 implies usage by saying 'follow up with zig_langref/zig_std/perf_guidance for full text', which suggests using this for initial search and those for detailed content. Yet it does not specify when to use this tool instead of directly accessing those tools, nor does it mention any exclusions or scenarios where a search is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Standard-library docs from the EXACT released source of the channel.
symbol='std.fs.Dir.openFile' walks real re-exports and returns the /// docs plus the declaration text from that release. query= searches std doc comments. Prefer exact symbols; use query to discover names.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| query | No | ||
| symbol | No | ||
| channel | No | stable |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It honestly discloses how it works: walking real re-exports and returning doc comments plus declaration text from the exact release. This gives the agent a clear model of behavior and scope. It does not mention side effects, but as a lookup tool, that is expected. No contradictions with annotations (none exist).
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: the first sentence states purpose, the second explains the two modes, and the third gives a preference hint. Every sentence earns its place, and there is no verbose repetition or 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 documentation lookup tool, the description covers the core behavior and most parameters. The output schema exists, so return values need not be described. The main missing piece is the 'force' parameter's effect, which is a notable hole given the tool's simplicity. Overall, it is reasonably complete but not fully exhaustive.
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 explain parameters. It explains symbol and query with concrete examples, and channel is implied in the first sentence. However, the 'force' parameter is completely unexplained. With four parameters, leaving one entirely undefined is a notable gap, though the primary modes are well covered.
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 provides standard-library docs from a specific channel's released source. It distinguishes itself from siblings like zig_langref and zig_changelog by specifying the resource (standard library) and the operation (returns /// docs and declaration text). The two modes (symbol lookup and query search) are explicitly described.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides guidance on when to use symbol vs query ('Prefer exact symbols; use query to discover names'), which helps within the tool. However, it does not explicitly mention alternatives or when not to use this tool (e.g., versus zig_search or zig_langref). The guidance is implied by the tool's focus on std docs, but it lacks explicit exclusion or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upgrade the LOCAL zig toolchain to the latest release, safely.
dry_run=True (default): print the exact plan, change nothing. confirm=True AND dry_run=False: apply it (brew upgrade or official tarball). Never pass confirm=True without the user asking for the update.
| Name | Required | Description | Default |
|---|---|---|---|
| channel | No | stable | |
| confirm | No | ||
| dry_run | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description takes full responsibility for disclosing behavior. It states that dry_run changes nothing, that confirm=True combined with dry_run=False applies the upgrade, and warns about the danger of confirm=True without user consent. This is unusually clear for a mutation tool; it also implies a side effect (modifying the local toolchain) transparently.
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 compact and well-structured: one sentence states the purpose, the next two explain the two modes with their preconditions, and a final imperative warns about misuse. No filler or redundant information; each 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?
While the description covers the two critical operational aspects (dry-run and confirm), it omits the channel parameter entirely and does not mention what the output schema contains (e.g., what a successful upgrade returns). For a tool that mutates the local environment, the missing channel documentation is a real gap. The safety warning is strong, but the parameter coverage is incomplete, leaving the agent to guess about channel.
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 competently explains dry_run and confirm, their defaults, and their interaction. However, the channel parameter is completely ignored. The schema provides no descriptions (0% coverage) and no enums, so the agent has no idea what values channel accepts or how it affects the upgrade (e.g., does 'stable' vs 'master' change the install method or version?). This is a significant gap for a parameter that likely affects the outcome.
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 a specific action ('upgrade the LOCAL zig toolchain') and distinguishes it from siblings like zig_version_status and zig_changelog which are about checking status or docs. It even explains the two modes (dry_run and apply) and which one is safe by default, leaving no ambiguity about what the tool accomplishes.
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 and when-not-to-use guidance: dry_run is the default, confirm should never be passed without the user explicitly requesting the update. This tells the agent exactly when to apply vs. just preview, and the warning about confirm covers safety. The mention of 'brew upgrade or official tarball' gives practical method context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare local zig version with the latest upstream release.
Returns local version/path, latest stable, master, up_to_date flag and, when behind, a suggested next step. Call this before version-sensitive answers and whenever Zig code misbehaves in ways a newer compiler fixes.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It describes the return values and the underlying comparison action, and implicitly implies a read-only operation (no mutation language). However, it does not explicitly state side effects, network requirements, or error behavior, which for a status tool could be expected. It adds value beyond the name but leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose and then detailing the output and usage context. Every sentence earns its place with no redundant words, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional boolean parameter) and has an output schema, so the description needn't explain return structure. However, the lack of any explanation for the 'force' parameter and no mention of prerequisites (e.g., network access or presence of ZIG) leaves gaps. The description covers the main use case but not all context needed for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes a single boolean parameter 'force' with a default but no description, and schema coverage is 0%. The description does not mention this parameter at all, leaving the agent to guess what 'force' does (e.g., bypass cache, force network fetch). Since there is zero coverage and no explanation, the description fails to provide needed semantics for this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Compare' with a clear resource ('local `zig version` with the latest upstream release') and enumerates exactly what is returned. It also differentiates from siblings like zig_update by focusing on status rather than modification, so an agent can select it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'before version-sensitive answers' and 'whenever Zig code misbehaves in ways a newer compiler fixes.' It does not mention when not to use it or point to alternatives, which would make it a 5, but the guidance is clear and actionable.
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.0perf_guidancezig_changelogzig_langrefzig_searchzig_stdzig_updatezig_version_statusScored across 7 tools
Each tool targets a distinct purpose: version checking, updating, language reference, standard library docs, changelog, performance guidance, and a unified search that complements the others. No two tools appear to do the same thing, and descriptions clarify boundaries.
Most tools follow a 'zig_' prefix, but the second element varies in style (noun, verb_noun, abbreviation). 'perf_guidance' breaks the prefix pattern. Still, names are short, descriptive, and predictable enough for an agent to infer purpose.
Seven tools is well-scoped for a documentation and toolchain server. Each tool earns its place, covering version checks, updates, references, and search, without bloat or missing essentials.
The surface covers the core documentation lifecycle: version status, update, language reference, std docs, changelog, performance guidance, and a cross-cutting search. There are no obvious gaps for the stated purpose of providing Zig documentation and version management.
Serves your design system and coding standards to coding agents, so they stop guessing.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Search and read Rust documentation for the standard library and any crate on crates.io
