本地、开源的 MCP 服务器 + agent 技能，为最新发布提供始终新鲜的官方 Zig 文档、精选的高性能轻量软件指导语料库，以及针对过时的本地 Zig 工具链的安全、先试运行的自动更新。
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 变化很快，训练记忆中的答案在次要版本之间就会过时——0.16 替换了整个 I/O 层，并将 Dir 从 std.fs 移到了 std.Io。此服务器每次调用都会获取官方文档和已发布的标准库源码（带短 TTL 重新验证），因此每个答案都引用其来源的版本。当你的本地编译器落后于文档时，服务器会明确说明，并提供受控升级。未经明确确认，它绝不会修改你的系统。
Related MCP server: Zignet
文档腐化得快。 Zig 的标准库布局在次要版本之间就会变动。提供最新发布的真实源码是 API 真相的唯一可靠来源。zig_std 通过遍历发布树中实际的再导出（re-export）来解析符号，而不是抓取的快照。
性能建议应该是机械性的。 随附的语料库解释了分配策略、数据布局、comptime、二进制大小、启动延迟、SIMD、并发和基准测试——基于硬件和运行时实际行为（缓存行、系统调用、缺页），而非感觉。
落后的编译器会悄悄使一切失效。 zig_version_status 每次检查时将你的工具链与上游索引进行比较，zig_update 则提供具体、可审查的升级计划。
一切以本地优先。 服务器通过 stdio 在你的机器上运行。没有账户、没有令牌、没有遥测。网络只流向 ziglang.org 以获取文档、发布说明和源码 tarball。
缓存的响应在超过 6 小时时会对 ziglang.org 重新验证（force=true 立即重新验证）。重新验证使用条件 GET 请求（ETag / Last-Modified），因此成本很低。
离线安全：如果网络不可用，缓存内容会以 stale 标志提供，而不是失败。（首次运行需要一次网络。）
标准库源码来自官方按版本发布的 src tarball——即使 GitHub 发布标签滞后，这也是权威内容（构建此工具时 0.16.0 在 GitHub 上尚未打标签）。tarball 每个版本只下载一次，且只解压 lib/std/**。
channel 参数选择 stable（最新发布，默认）或 master（nightly），以便预览下一版本变更。
缓存布局（~/.cache/zig-docs-mcp/，可用 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 和 uv
macOS 或 Linux（自动更新支持 Homebrew 和独立安装；Windows 会得到可用的计划输出，但尚无 tarball 策略）
需要网络访问 ziglang.org 以进行首次获取和重新验证
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不想安装？直接从克隆运行：
uv run --project ~/zig-docs-mcp zigdocs任何支持 stdio 的 MCP 客户端。将其指向 zigdocs 命令：
{
"mcpServers": {
"zig-docs": {
"command": "zigdocs"
}
}
}如果没有全局安装，直接使用克隆：
{
"mcpServers": {
"zig-docs": {
"command": "uv",
"args": ["run", "--project", "/path/to/zig-docs-mcp", "zigdocs"]
}
}
}本仓库附带两个技能。将它们符号链接并重启会话（或运行 /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-mcp然后，从 agent 内核：
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 once调用以 JSON 字符串形式返回结果（完整主题的指导读取返回原始 markdown）；当需要 version 或 docs 等字段时，用 json.loads(...) 解析。参数仅限关键字。服务器命令按顺序解析：ZIG_DOCS_MCP_CMD、PATH 上的 zigdocs，然后是对 ZIG_DOCS_MCP_REPO（默认 ~/zig-docs-mcp）执行 uv run --project。
skills/zig-docs/SKILL.md 包含 agent 遵循的操作规则：先进行版本门控，先文档后代码，引用文档版本，未经用户明确同意绝不应用更新。
zig_version_status将本地 zig version 与最新的上游发布进行比较。
{
"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
}当本地工具链较旧时，响应会添加 behind 和指向 zig_update 的 suggestion（示例）：
{
"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_update升级本地工具链。默认是试运行——它只打印确切的计划，不改变任何东西。应用需要 dry_run=false, confirm=true。参见 工具链自动更新。
zig_langref官方语言参考，为 channel 版本获取最新内容。
section="Errors" → 完整章节文本（保留代码块）：
### 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" → 按排名返回的章节命中结果：
[{"section_id": "Vectors", "title": "Vectors§"},
{"section_id": "Builtin-Functions", "title": "Builtin Functions§"}]无参数 → 所有章节 ID 的列表。
zig_std来自确切发布源码的标准库文档。符号解析遍历真实的再导出（std.zig → heap.zig → heap/ArenaAllocator.zig），跟随 @import 别名，并返回该版本中的 /// 文档以及声明文本：
{
"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. ..."
}如果名称不是遍历的命名空间中的普通顶层声明（布局在版本之间会变动），工具会回退到对整个语料库的顶层声明搜索，最佳匹配优先——例如，0.16 上的 std.fs.Dir 会正确呈现 lib/std/Io/Dir.zig。query="arena" 直接搜索标准库文档注释。
zig_changelog当前 channel 版本的发布说明摘要：每个章节的标题加简短摘要。在发布刚落地时很有用（zig_changelog(force=true)）。
perf_guidance精选的高性能轻量软件指导。无参数时列出主题；topic="allocation-strategy" 返回完整指南（原始 markdown，包含原则 / 机制 / Zig 惯用法 / 反模式 / 经验法则）；query=... 在所有指南中搜索。
zig_search跨 langref、std 文档注释和指导的统一搜索：
{"query": "vectorization", "langref": [...], "guidance": [...], "std": [...], "std_version": "0.16.0"}scope 可缩小范围：all（默认）| langref | std | guidance。
zig_update 自动选择策略：
Homebrew 管理的 zig（二进制文件解析在 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."
}独立安装（官方 tarball，任何其他位置）→ 从上游索引下载平台 tarball，解压到 ~/.local/opt/zig-<version>，并在 ~/.local/bin/zig 创建 shim：
{
"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"
}如果 ~/.local/bin 不是 PATH 中的第一位，计划会明确说明——旧编译器仍然会胜出，工具会告诉你如何修复顺序。
安全规则：
默认是试运行。不会下载、移动或链接任何东西。
应用需要同时设置 dry_run=false, confirm=true。
使用此服务器的 agent 被要求先展示计划，并在确认前获得用户的明确同意。
guidance/ 中的十二个主题，随 wheel 一起分发，由 perf_guidance 提供。原则是通用的；代码片段是 Zig 0.16 时代的；确切的 API 事实始终来自 zig_std，而非语料库。
主题 | 一句话摘要 |
| 将分配器与生命周期匹配；arena 指针成本与通用分配器记账成本；隐藏分配。 |
| 64 字节缓存行上的 SoA 与 AoS 字节计算；热/冷数据分离； |
| comptime 结果变为 rodata/立即数；运行时表产生脏页成本。 |
| 切片是 16 字节；按 token 分配会带来一次分配、一次 memcpy 和每个 token 的缓存行成本。 |
| 大小 = 可达性；剥离、panic 模式、依赖卫生；更小的文本 = 更少的启动缺页。 |
| 无 init_array、惰性文本缺页、惰性初始化、argv 之前不做任何工作。 |
| 填充计算、字段排序、打包结构体、 |
| 自动向量化障碍、逐通道累加 + 单次归约、 |
| 共享写入的 MESI 成本、futex 停放、系统调用批处理、伪共享填充。 |
| 错误是 u16 值； |
| 发布构建、预热、最小值/中位数而非平均值、用 sink 对抗 DCE、计数器。 |
| 标准库优先；依赖增加链接代码和构建脆弱性；内置小型工具。 |
变量 | 含义 | 默认值 |
| 缓存目录 |
|
| 完整服务器命令行（skill 覆盖） | — |
|
|
|
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 + check端到端测试套件首次运行需要网络（它会预热缓存）。涉及符号解析的单元测试针对预热的标准库源码缓存运行，当缓存不存在时会干净地跳过。
zigdocs server not found（Prime Agent 技能）：从克隆中执行 uv tool install . 安装，或将 ZIG_DOCS_MCP_REPO 设置为克隆路径，或将 ZIG_DOCS_MCP_CMD 设置为完整命令行。
首次运行在离线时失败：缓存初始为空；在线时获取一次。之后，过期缓存回退可让所有工具正常工作。
新发布后结果看起来过时：传递 force=true（否则适用 6 小时 TTL）。
更新后 zig version 仍较旧：需要新 shell，并且 ~/.local/bin 必须在 PATH 中位于之前的安装目录之前。试运行计划会说明你机器的确切情况。
Homebrew zig 落后于最新发布：brew 公式滞后于发布；如果你需要首发版本，请使用独立安装策略（移除 brew 公式，独立安装）。
MIT — 见 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
