feat(mcp): slim minimal-face tool descriptions, mechanics pushed to cbm skill

tools/list descriptions are per-session wire cost; the paging/continuation/
honesty fine print only matters after a tool is picked, so keeping it
resident dilutes the trigger signal and burns context. Layering contract
now enforced:

- description = trigger + interpretation contract (search_graph keeps the
  degree-column edge-family enumeration; guarded by
  mcp_tools_list_latest_metadata)
- inputSchema = parameter contract (aspect enum, path semantics, cursor
  rules appear exactly once, in the schema)
- skills/cbm/SKILL.md = mechanics + recipes + honesty boundaries (loaded
  progressively; the skill frontmatter description is the always-on
  trigger surface)

Per-tool (chars incl. punctuation): search_graph 158->125, query_graph
336->125 (drops the dead get_graph_schema pointer - that tool is not on
the minimal face), get_architecture 178->150. Registry total 672->400
(-40%). The top-level --help Tools: block renders from the same registry,
so descriptions keep a single source of truth.

tests/test_mcp.c mcp_tools_list_latest_metadata now asserts the new
trigger lines + edge enumeration are present and "absence is not proof" /
"continue safely with next_cursor" are absent (regression guard for the
fine print having left the wire).

skills/cbm/SKILL.md: fixed the stale minimal list (detect_changes ->
search_graph per fork issue #5), dropped the stale "MCP registration
removed" stance, added the MCP-face mechanics section as the
progressive-disclosure carrier plus a recipes-are-MCP-arguments note.
Installed to ~/.grok/skills/cbm/.

Verified: mcp suite 321 PASS / 0 FAIL (gcc 13.2, SANITIZE=). cli suite has
12 pre-existing failures (hook/README-surface family, identical under a
stash baseline - untouched by this change, tracked as full-run debt).

Author: daidaiJ

README.md

@@ -134,4 +134,4 @@ codebase-memory-mcp config reset tools_disabled       # 恢复默认
 | [docs/FORK_PATCHES.md](docs/FORK_PATCHES.md) | fork 补丁清单：动机、修改点、验证矩阵 |
 | [docs/UPSTREAM_README.md](docs/UPSTREAM_README.md) | 上游原版 README（架构、安装、全部工具说明） |
 | [AGENTS.md](AGENTS.md) | 智能体协作指南（目录结构、开发约定、坑位清单） |
-| [skills/cbm/SKILL.md](skills/cbm/SKILL.md) | Agent Skill：何时用/不用 cbm、安装方法、三个实测有效的命令配方与硬规则 |
+| [skills/cbm/SKILL.md](skills/cbm/SKILL.md) | Agent Skill：何时用/不用 cbm、安装方法、三个实测有效的命令配方与硬规则、MCP 最小面工具细则（描述瘦身后机制细节的渐进披露载体） |

docs/FORK_PATCHES.md

@@ -414,3 +414,43 @@ pipeline does. Verified: `test-focused TEST_SUITES="mcp watcher log
 index_policy subprocess"` → 458 PASS / 0 FAIL / 29 SKIP (gcc 13.2, SANITIZE=
 because the local MinGW gcc ships no ASan runtime; the recipe toolchain stays
 MSYS2 CLANG64).
+
+## 11. Minimal-face tool descriptions: trigger + interpretation lines, mechanics pushed to the skill (2026-09-30)
+
+**动机**：`tools/list` 的 description 是每个会话的常驻 wire 开销，而其中的
+分页/续读/诚实性细则只有工具被选中后才需要——常驻既稀释触发信号又烧上下文。
+fork 配套 skill（`skills/cbm/SKILL.md`）以渐进披露承载细则：skill description
+常驻（负责触发），body 按需加载（负责机制、配方与判读边界）。顺带修掉一个死
+建议：原 query_graph 描述里的 `get_graph_schema(diagnostics=full)` 路由指针在
+MCP 最小面不可达（该工具不在面上），这类跨工具路由只属于 skill。
+
+**新增不变量（描述分层契约）**：
+
+- description = 触发语 + 结果判读契约。search_graph 的 degree 列五族边枚举是
+  判读契约（度列只统计 CALLS/USAGE/CALL_REFERENCE/INHERITS/IMPLEMENTS），留在
+  描述里，`mcp_tools_list_latest_metadata` 断言看守。
+- inputSchema = 参数契约。aspect 枚举、path 语义、max_rows/cursor 规则等只在
+  schema 出现一次，描述不再复述。
+- `skills/cbm/SKILL.md` = 机制 + 组合配方 + 诚实性边界（next_cursor 续读规则、
+  graph=missed 缺席≠完备、auto-index 仅 ALL profile）。
+
+**逐工具修改点（`src/mcp/mcp.c` TOOLS[]，字符数含标点）**：
+
+- `search_graph` 158→125：匹配机制措辞降为触发级（BM25→keyword；query/
+  name_pattern/semantic_query 的分工 schema 已表达）；保留五族边枚举。
+- `query_graph` 336→125：下推 200 行默认/精确或下界总数/next_cursor 续读规则、
+  graph=missed 诚实性注记、get_graph_schema 路由。
+- `get_architecture` 178→150：aspect 全枚举与 path 语义与 schema 重复，删；
+  保留默认输出形态（languages/packages/entry_points）。
+
+三段合计 672→400（-40%）。顶部 `--help` 的 Tools: 块由同一注册表渲染
+（`cbm_mcp_tools_help_list`），同步变短——描述只有这一处事实源。
+
+**测试**：`tests/test_mcp.c` `mcp_tools_list_latest_metadata` 断言改写为新契约：
+三工具新触发语 + 五族边枚举必须出现；`absence is not proof` /
+`continue safely with next_cursor` 必须缺席（细则已离开 wire 的回归护栏）。
+
+**验证**：`mcp` 套件 321 PASS / 0 FAIL（gcc 13.2，SANITIZE= 本机无 ASan 运行时；
+权威配方仍见 docs/BUILD_WINDOWS.md）。`cli` 套件另有 12 个**预存**失败
+（hook/README-surface 系列，stash 基线对照确认与本节改动无关，属于全量跑批
+遗留债，不在此节修复）。

skills/cbm/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cbm
-description: 当需要架构概览/模块聚类/复杂度热点排行（codegraph 无架构视图）、commit 影响半径（diff 驱动，codegraph impact 只能符号驱动）、大型或陌生仓库整体理解时，用 codebase-memory-mcp CLI 查询预索引知识图谱。小项目或单符号查询直接用 grep/codegraph，不要动 cbm。
+description: 当需要架构概览/模块聚类/复杂度热点排行（codegraph 无架构视图）、commit 影响半径（diff 驱动，codegraph impact 只能符号驱动）、大型或陌生仓库整体理解、全仓符号/调用图查询时，用 codebase-memory-mcp 查询预索引知识图谱（CLI 全量，或 MCP 最小 3 工具 search_graph/query_graph/get_architecture）。小项目或单符号查询直接用 grep/codegraph。
 ---
 
 # cbm（codebase-memory-mcp fork）— 架构级图谱查询（低频重型工具）
 
-定位：**只做 codegraph 和 grep 做不了/不划算的事**。使用 fork 补丁版 CLI（命令名 `codebase-memory-mcp`，安装见下节）；MCP 注册保持移除，全部能力走 CLI。
+定位：**只做 codegraph 和 grep 做不了/不划算的事**。两种形态共享同一份预索引图谱：CLI（`codebase-memory-mcp`，17 工具全量，安装见下节）与 MCP 最小面（3 个只读工具，细则见「MCP 工具面细则」）。shell 可用的会话优先 CLI；受限客户端嵌 MCP 面。
 实测依据（2026-09-05，websearch-mcpserver 三场对照实验）：
 
 - **赢的场景**：架构概览（fan-in 热点/边界权重/分层/聚类，grep 需十几次调用）、全仓函数复杂度排行（cognitive 维度 LOC 给不出）、commit 级爆炸半径（唯一 diff 驱动形态）
@@ -31,6 +31,8 @@ CLI 是单文件可执行程序，从 fork release 下载放进 PATH 即可：
 
 ## 命令配方（实测可用语法）
 
+（以下 JSON 体与 MCP `tools/call` 的 arguments 同构，工具名即 CLI 子命令名；MCP 会话可直接换成对应工具调用。）
+
 ### 1. 架构概览（陌生/大型仓库第一站）
 
 ```bash
@@ -64,9 +66,21 @@ codebase-memory-mcp cli check_index_coverage '{"project":"<PROJECT名>","scopes"
 
 大范围采信图谱结果前先跑：`parse_partial` 文件的图谱可能局部失明（cbm 索引自己源码时 81 个文件解析失败）。
 
+## MCP 工具面细则（渐进披露）
+
+MCP `tools/list` 的 description 有意只保留触发语与判读契约（瘦身记录见 docs/FORK_PATCHES.md §11）：参数语义在各自 inputSchema 里，本节承接 schema 表达不了的组合方式与诚实性边界。
+
+| 工具 | 触发 | 机制与判读边界 |
+|---|---|---|
+| `search_graph` | 定位定义/调用方、按名称模式扫符号面 | `query`（BM25 关键词）与 `semantic_query`（嵌入相似）互斥；行带 qn/file/lines，degree 列只统计 CALLS/USAGE/CALL_REFERENCE/INHERITS/IMPLEMENTS 五族边 |
+| `query_graph` | 多跳/聚合/复杂度排行/跨服务分析（配方见上节） | 总数是精确值或下界并带截断标记；**用 `next_cursor` 续读**（保持 query/project/graph 不变，format/max_rows 可变）；`graph=missed` 是覆盖盲区文件树，缺席≠完备 |
+| `get_architecture` | 陌生/大型仓库第一站 | 省略 aspects = languages/packages/entry_points；`overview` = 除 file_tree 外的紧凑集；`cycles` 永远 opt-in；`path` 按目录前缀收窄 |
+
+MCP 最小面没有 get_graph_schema / index_status / detect_changes：Cypher 可用属性直接用上节配方 2 的属性表；索引新鲜度与影响半径走 CLI（或 `--tool-profile=all`）。MCP 最小面也不会自动建索引（auto-index 仅 ALL profile 生效），受限客户端场景先用 CLI 建索引。
+
 ## 硬规则
 
 1. **空结果 ≠ 真阴性**：依次排查 ① 参数非法（direction/项目名/SHA 格式）→ ② coverage 盲区 → ③ grep 复核，三关过了才准信"没有调用方/没有影响"。
 2. 图谱与代码文件冲突时，以代码文件为准，会话开头重跑 hook 或 `codebase-memory-mcp cli index_repository --repo-path . --mode fast`。
 3. 变异管理类（index_repository / delete_project / manage_adr / ingest_traces）同样走 CLI，非必要不碰。
-4. 若要恢复 MCP 形态（受限客户端嵌入场景）：fork 的 MCP 默认只暴露 **3 个工具**（get_architecture / query_graph / detect_changes），`--tool-profile=all` 恢复全量，`--tool-profile=minimal|analysis|scout` 可选；全局 `tools_disabled` 名单与项目本地 `.cbm/config.json` 可细粒度禁用（双侧生效、fail-loud）。配置键见 `codebase-memory-mcp config list`。
+4. 若要恢复 MCP 形态（受限客户端嵌入场景）：fork 的 MCP 默认只暴露 **3 个工具**（search_graph / query_graph / get_architecture；fork issue #5 将 detect_changes 换出，待可信度修复），`--tool-profile=all` 恢复全量，`--tool-profile=minimal|analysis|scout` 可选；全局 `tools_disabled` 名单与项目本地 `.cbm/config.json` 可细粒度禁用（双侧生效、fail-loud）。配置键见 `codebase-memory-mcp config list`。

src/mcp/mcp.c

@@ -483,8 +483,8 @@ static const tool_def_t TOOLS[] = {
      "},\"required\":[\"repo_path\"]}"},
 
     {"search_graph",
-     "Find symbols via BM25 query, regex name/qn filters, or semantic_query. Rows keep "
-     "qn/file/lines and in/out over CALLS/USAGE/CALL_REFERENCE/INHERITS/IMPLEMENTS.",
+     "Find symbols by keyword, regex, or semantic query. Degree columns count "
+     "CALLS/USAGE/CALL_REFERENCE/INHERITS/IMPLEMENTS edges.",
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},"
      "\"query\":{\"type\":\"string\"},"
      "\"label\":{\"type\":\"string\"},\"name_pattern\":{\"type\":\"string\"},\"qn_pattern\":{"
@@ -508,11 +508,8 @@ static const tool_def_t TOOLS[] = {
      "\"required\":[\"project\"]}"},
 
     {"query_graph",
-     "Read-only Cypher for multi-hop, aggregation, complexity, or cross-service analysis. "
-     "Default: 200 visible rows with "
-     "exact/lower-bound totals and truncation; continue safely with next_cursor. "
-     "graph=missed is a file tree of flagged coverage gaps; absence is not proof of completeness. "
-     "Use get_graph_schema(diagnostics=full) for properties.",
+     "Read-only Cypher over the code knowledge graph: multi-hop traversal, aggregation, "
+     "complexity ranking, cross-service analysis.",
      "{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\",\"description\":\"Cypher "
      "query\"},\"project\":{\"type\":\"string\"},"
      "\"graph\":{\"type\":\"string\",\"enum\":[\"code\",\"missed\"],\"default\":\"code\","
@@ -616,9 +613,8 @@ static const tool_def_t TOOLS[] = {
      "\"additionalProperties\":false}"},
 
     {"get_architecture",
-     "Compact counts, languages, packages, entry points. Request structure, dependencies, "
-     "routes, hotspots, boundaries, layers, clusters, cycles, or file_tree; path scopes a "
-     "directory.",
+     "Compact architecture overview of an indexed project: counts, languages, packages, "
+     "entry points. Aspects add structure, hotspots, boundaries, clusters.",
      /* The aspects enum mirrors VALID_ASPECTS (see aspect_is_valid) — update both together. */
      "{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"path\":{\"type\":"
      "\"string\",\"description\":\"Directory prefix (for example apps/hoa).\"},"

tests/test_mcp.c

@@ -1298,14 +1298,17 @@ TEST(mcp_tools_list_latest_metadata) {
      * relationships used for call/reference/type centrality, not every edge
      * family (for example DEFINES or CONTAINS_FILE). Keep the public contract
      * aligned with the store query. */
-    ASSERT_NOT_NULL(strstr(json, "Find symbols via BM25 query, regex name/qn filters, or "
-                                 "semantic_query"));
-    ASSERT_NOT_NULL(strstr(json, "Rows keep qn/file/lines and in/out over CALLS"));
-    ASSERT_NOT_NULL(strstr(json, "USAGE"));
-    ASSERT_NOT_NULL(strstr(json, "CALL_REFERENCE"));
-    ASSERT_NOT_NULL(strstr(json, "INHERITS"));
-    ASSERT_NOT_NULL(strstr(json, "IMPLEMENTS"));
+    ASSERT_NOT_NULL(strstr(json, "Find symbols by keyword, regex, or semantic query"));
+    ASSERT_NOT_NULL(strstr(json, "Degree columns count CALLS/USAGE/CALL_REFERENCE/"
+                                 "INHERITS/IMPLEMENTS edges"));
     ASSERT_NULL(strstr(json, "TOTAL degree across ALL edge types"));
+    /* Descriptions are trigger + interpretation lines; the paging/honesty
+     * fine print lives in the inputSchema and skills/cbm/SKILL.md, not on
+     * the wire of every discovery response. */
+    ASSERT_NOT_NULL(strstr(json, "Read-only Cypher over the code knowledge graph"));
+    ASSERT_NOT_NULL(strstr(json, "Compact architecture overview of an indexed project"));
+    ASSERT_NULL(strstr(json, "absence is not proof"));
+    ASSERT_NULL(strstr(json, "continue safely with next_cursor"));
     free(json);
     PASS();
 }