图数据库驱动的代码架构管理系统 —— 用 Neo4j 维护「需求 / 代码模块 / 数据」三层依赖图，Agent 开发自动填充，变更影响一键查询，Hook 反应式联动多 Agent 协作。
给 AI 的一句话配置指令：「阅读本 README，按『快速开始』章节完成本项目安装与配置。」
现有工具无法回答「改一个数据结构，所有需要更新的地方是哪些」——IDE 只认代码 import，构建系统只认编译依赖，数据血缘只认数据管线。本项目把代码、数据、工具、需求放进同一张图：
AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
└──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端影响分析：任意节点变更，一条 Cypher 查出全部下游
强门禁：Agent 声明图变更（意图请求）→ git 提交触发 review 核验 → 通过才写图，失败连 commit 都进不去
反应式 Hook：图变更按订阅分发给相关 Agent，无变更则传播自然收敛
桌面端：可视化图数据 + 查看进行中的任务
设计细节见 docs/design-v1.1.md，程序结构见 docs/architecture.md。
Related MCP server: codemap
Windows 10/11（Git Bash 可用）
Python ≥ 3.11（python --version 确认）
可选：OpenAI 兼容 LLM API（review / 夜间维护 agent 用，默认指向 http://localhost:8642/v1，可在配置中修改或跳过）
对本项目克隆后的任意 AI 助手说：
「阅读 README.md，执行快速开始的安装流程，完成本项目配置。」
AI 应执行的唯一核心命令：
python setup/setup.py该脚本全自动完成以下步骤（每步失败都会给出明确的人工接管指引）：
步骤 | 动作 | 产物 |
1 | 检查 Python 版本 | 版本不符则退出并提示 |
2 | 下载并解压 JDK 21（Temurin，多镜像源） |
|
3 | 下载并解压 Neo4j Community 5.x（多镜像源） |
|
4 | 启动 Neo4j 服务并初始化密码 | 密码默认 |
5 | 创建 |
|
6 | 应用图 schema（约束 + 索引 + 示例管线种子数据） | Neo4j 中的三层图 |
7 | 注册 MCP server 到 | WorkBuddy 可直接调用 6 个 tool |
8 | Smoke test：跑一次 impact query | 应返回 8 个下游节点 |
9 | 输出后续步骤指引 | 桌面端启动 / git hooks / exe 打包 |
预计耗时：首次约 5–15 分钟（取决于 JDK + Neo4j 共 ~380MB 的下载速度）。断点续跑：脚本每步幂等，失败后修复问题重跑即可，已完成的步骤自动跳过。
# 1. 依赖
python -m venv .venv && .venv/Scripts/pip install -e .
# 2. Neo4j（手动下载 zip 解压到 runtime/neo4j/，需要 JDK 21）
runtime/neo4j/bin/neo4j.bat install-service
runtime/neo4j/bin/neo4j.bat start
# 3. 初始化密码（首次默认 neo4j/neo4j，登录后强制改）
runtime/neo4j/bin/cypher-shell.bat -u neo4j -p neo4j \
"ALTER CURRENT USER SET PASSWORD FROM 'neo4j' TO 'graph123';"
# 4. 应用 schema 与种子数据
.venv/Scripts/python -m graph_arch.setup_db
# 5. 注册 MCP（见下方「接入 Agent Harness」）
# 6. 验证
.venv/Scripts/python -c "from graph_arch.graph.queries import impact; \
print(len(impact('data:dataset_b')), '个下游节点') # 应输出 8"# 开发运行
.venv/Scripts/python desktop/main.py
# 打包为独立 exe（产物在 desktop/dist/）
.venv/Scripts/python desktop/build_exe.py功能：
图可视化：按层着色（需求/模块/数据），点击节点看详情（摘要、指针、状态、邻域）
活动面板：pending 意图请求、任务队列、最近 changelog 流、stale 节点列表
自动每 5 秒刷新
setup.py 已自动写入 ~/.workbuddy/mcp.json。重启 WorkBuddy 后，工具目录中出现：
submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks
若 Hermes 支持 MCP：同样注册本 server（python -m graph_arch.mcp_server，工作目录为仓库根）。
若仅支持 OpenAI function calling：tools 定义见 src/graph_arch/mcp_server.py 的 docstring，可直接转换为 OpenAI tools 格式。
开发工作流（必须遵守）:
1. 接到任何修改类任务，先调 query_context 加载目标节点邻域（摘要+指针+状态）
2. 若涉及已有数据结构/模块，必须调 query_impact 确认影响范围
3. 按指针从源头（git/文档/schema）加载细节后开工
4. 完成后必须 submit_graph_intent 声明图变更，再创建 git 提交
5. review 失败则按返回原因修正，重新提交graph-arch/
├── README.md # 本文件
├── pyproject.toml # 包定义与依赖
├── docs/ # 设计文档（v1.1）+ 结构文档
├── setup/setup.py # 一键安装脚本
├── config/
│ ├── settings.yaml # Neo4j/LLM/路径/超时（setup 自动生成）
│ ├── hooks.yaml # Hook 规则注册
│ └── skill_routes.yaml # skill 路由表（harness 层）
├── schema/ # Cypher：约束 + 种子数据
├── src/graph_arch/
│ ├── graph/ # client / writer / queries / merger
│ ├── hooks/ # engine / cycle_guard / actions
│ ├── review/ # 核验协议 + LLM 调用
│ ├── tasks/ # 任务队列 + 死信队列
│ ├── mcp_server.py # 入口 1: MCP server（常驻）
│ ├── git_hook.py # 入口 2: git hooks（pre-receive/post-merge）
│ ├── nightly.py # 入口 3: 夜间维护（定时）
│ └── setup_db.py # schema 初始化
├── desktop/ # 桌面端（PySide6 + vis-network）
├── git-hooks/ # 仓库钩子 + 安装脚本
├── changelog/ # append-only 变更日志（JSONL）
├── runtime/ # JDK / Neo4j（setup 下载，不入 git）
└── tests/键 | 默认 | 说明 |
|
| Neo4j 连接 |
|
| setup 初始化后写入 |
|
| OpenAI 兼容端点（review/维护用，可留空跳过） |
|
| 模型名 |
|
| 同一节点在同一 Hook 链中的触发次数上限（防环） |
|
| 任务认领超时（超时转派/死信） |
|
| 变更日志目录 |
bash git-hooks/install.sh /path/to/your/code-repo之后该仓库的 push / merge 会触发 review 核验与图合并。
症状 | 处理 |
Neo4j 下载失败（403/超时） | 手动从 neo4j.com 下载 |
| 确认 |
bolt 连接拒绝 |
|
review 步骤报 LLM 连接失败 | LLM 可留空：在 |
MCP 工具不出现 | 重启 harness；确认 |
MIT（按需修改）
认领一个 Hook 分发的任务（多 Agent 防撞车的排他锁定）。
何时必须调用:
收到任务通知、评估后确认需要响应时，开发之前先认领
认领成功才开工；返回 rejected 说明他人已认领，直接放弃
何时不需要:
评估后确认无需变更时（不认领，让任务自然超时或被他人处理）
参数:
task_id: 任务 id（来自 get_pending_tasks）
agent_id: 你的 Agent 角色 id（稳定命名，与订阅关系关联）
返回: {status: claimed|rejected, task_id, ...}
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| agent_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does so well: it discloses the exclusive-lock side effect, the claimed/rejected status outcomes, and the rule that work must start only after a successful claim. It does not cover edge cases like invalid task_id or lock expiry, so it is not a perfect 5.
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 front-loaded: purpose first, then usage conditions, parameters, and return shape. Each section is short, scannable, and contains no filler.
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?
It covers the full call path: when to call, when not to call, parameter provenance, and return statuses. Given only two string parameters and a simple claimed/rejected result, nothing essential is missing and the output schema further covers the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only gives string types, but the description compensates fully: task_id is sourced from get_pending_tasks and agent_id is the stable agent role id tied to the subscription relationship. Both parameters receive meaning and constraints that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: '认领一个 Hook 分发的任务' with the clarifying parenthetical '多 Agent 防撞车的排他锁定'. This clearly sets it apart from sibling tools like get_pending_tasks (listing) and submit_graph_intent/graph_revision (other mutations).
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?
Dedicated '何时必须调用' and '何时不需要' sections give concrete conditions: claim after evaluation and before starting work, and do not claim when no change is needed. It also tells the agent what to do on rejection ('直接放弃'), which is actionable routing behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看待核验的意图请求（review agent 专用）。
何时调用:
你是 Review Agent，git hook 触发你执行核验时
排查「为什么图没更新」时检查是否有滞留的 pending
何时不需要:
普通开发任务（你不应该消费别人的意图请求）
返回: 意图请求列表（完整 JSON）
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| 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 the behavioral disclosure burden. '查看' signals a read-only list operation, and '返回: 意图请求列表（完整 JSON）' states the expected outcome. It also discloses the role restriction. It could be more explicit about side effects, but the wording strongly implies this is a non-mutating lookup.
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 with distinct '何时调用', '何时不需要', and '返回' sections. All information is meaningful and front-loaded, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the necessary context: what it returns, who may use it, when to use it, and when not to. Nothing critical is missing for an agent to decide whether to invoke it.
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 zero parameters, so there are no parameter semantics to document. Per the calibration baseline, this scores 4; the description does not need to add parameter-level detail.
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-resource pair ('查看待核验的意图请求') and immediately scopes it to the review agent. This distinguishes it from sibling tools like get_pending_tasks and clearly identifies what resource the tool operates on.
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 lists when to call it: when acting as the Review Agent during git hook verification, and when debugging why the graph did not update. It also gives a clear negative case: normal development tasks where the agent should not consume others' intent requests. This is excellent routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
拉取任务队列（被动触达的 pull 端）。harness 执行循环中每轮调用。
何时必须调用:
Agent 执行循环的每轮迭代开始时（检查是否有 Hook 分发给你的任务）
何时不需要:
正在处理一个任务的中间（先完成当前任务）
参数:
status: pending（待认领）/ claimed（已认领）/ completed
返回: 任务列表 [{task_id, source_node, message, subscribers, status, ...}] 对订阅了你的任务: 先 query_impact 评估 → 需响应则 claim_task 后开工
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | pending |
| 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 full behavioral burden. It discloses the polling cadence, the passive pull nature, the status semantics, the return shape, and the intended workflow after retrieval. '拉取' clearly implies a read operation with no mutation side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, when to call, when not to call, parameters, return shape, and follow-up workflow. Every section earns its place and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description is complete: it explains the trigger condition, the parameter values, and the downstream interaction with sibling tools. Nothing needed for correct invocation 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?
Schema coverage is 0%, so the description must compensate. It enumerates the three possible status values ('pending（待认领）/ claimed（已认领）/ completed') and their meanings, which the schema does not provide. This fully documents the only 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 opens with a specific verb and resource: '拉取任务队列（被动触达的 pull 端）', making the tool's role clear. The reference to the harness execution loop and Hook-distributed tasks distinguishes this passive pull mechanism from sibling tools like claim_task and get_pending_intents.
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 explicitly states when to call ('每轮迭代开始时') and when not to call ('正在处理一个任务的中间'), and provides a clear downstream workflow: query_impact first, then claim_task if a response is needed. This is model guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询当前图版本号（写意图请求时填入 base_revision，用于过期检测）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It clearly indicates a read-only query and states how the value is consumed (base_revision for expiry detection). This is sufficient for a zero-parameter query 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?
A single concise sentence conveys both the operation and the reason it is needed. No filler or redundant explanation.
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 zero-parameter query tool with an output schema, the description provides the necessary context: what the tool returns, how to use the result, and why it matters. Nothing essential 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?
The tool has zero parameters, and the schema confirms this, so there is no parameter documentation burden. The description mentions base_revision, but that is a field in a downstream request, not a parameter of this tool.
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 a specific verb (查询) and resource (当前图版本号), and explains the purpose: filling base_revision in write-intent requests for staleness detection. This clearly distinguishes it from sibling tools like query_impact or query_context, which target different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: call this to obtain base_revision before submitting an intent request. It doesn't explicitly state when not to use it or name alternatives, but the intended workflow is evident from the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
图导航：查询节点的邻域导航信息，用于 Agent 诞生后构建工作上下文。
何时必须调用:
接到任何涉及已有节点（数据结构/模块/需求）的任务时，第一步调用
收到 Hook 任务通知、需要了解变更节点的宏观环境时
何时不需要:
已经持有该节点邻域信息的连续会话中（避免重复调用）
参数:
node_id: 图节点 id
返回: {id, type, layer, name, summary, path, status, skill_hint, neighborhood} 返回的是导航信息而非内容本身——按 path 指针从源头（git/文档/schema）加载细节。 skill_hint 是处理建议，实际路由由 harness 的 skill_routes.yaml 决定。
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It meaningfully discloses that the return is navigation info rather than content itself, that details must be loaded via path pointers, and that skill_hint is only a suggestion overridden by skill_routes.yaml. This goes well beyond a simple query statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized into clear sections: purpose, when to call, when not to call, parameter, and return semantics. Each section earns its place, and the core navigation purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter query tool with an output schema, the description is remarkably complete: it covers invocation triggers, non-triggers, parameter meaning, return shape, and the crucial navigation-vs-content caveat. Nothing essential for correct invocation 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?
Schema description coverage is 0%, so the description must compensate. It defines node_id as a graph node id, which adds real meaning beyond the bare string type, and also describes the return fields that help an agent understand what the parameter is used for.
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 '查询' with the resource '节点的邻域导航信息' and clearly ties it to building an Agent's work context. It clearly defines what the tool does, but does not explicitly distinguish it from the sibling query_impact.
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 the tool must be called (first step for tasks involving existing nodes, and on Hook notifications) and when it is not needed (when neighborhood info is already held in a continuous session). It provides strong when/when-not guidance, though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询一个图节点的变更影响范围（谁会被这个节点的变更波及）。
何时必须调用:
修改任何已有数据结构、模块或需求之前
收到图变更通知、评估自己负责区域是否需要更新时
规划跨模块任务、需要完整依赖上下文时
何时不需要:
纯新增且明确无下游依赖的独立模块
参数:
node_id: 图节点 id（命名规范: data:user_table / module:auth_svc / req:login）
direction: "downstream"=谁被我影响 / "upstream"=我依赖谁
返回: [{id, layer, type, status, summary, path, hops}] 按传播距离排序。 返回的 path 是指针——细节由 skill 按指针从源头加载，不要向本工具索要内容全文。
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | ||
| direction | No | downstream |
| 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 full burden and does well: it describes the read-only query nature, the exact output shape, sort order by propagation distance, and the important pointer behavior that the result path is a pointer and full content must be loaded from source. This goes well beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for when to use, when not, parameters, and return value. It is dense but every sentence adds value, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema, the description still adds crucial context: the ordering of results, the pointer semantics of the path field, the exact parameter vocabulary, and concrete usage scenarios. Nothing an agent needs to invoke correctly 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?
Since the input schema has 0% description coverage, the description fully compensates by explaining node_id naming conventions (data:user_table / module:auth_svc / req:login) and the exact meaning of direction values ('downstream'=谁被我影响 / 'upstream'=我依赖谁). This gives an agent everything needed to fill parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: '查询一个图节点的变更影响范围（谁会被这个节点的变更波及）'. It clearly defines the tool's purpose and distinguishes it from a generic context query like query_context by focusing on change propagation and upstream/downstream impact.
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 'must call' scenarios and a clear 'not needed' case, which strongly guides when to use the tool. However, it does not explicitly name alternative siblings or say 'use X instead', so the comparison against other tools is left partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
提交图变更意图请求（开发完成后的必经步骤）。缓存为 pending，git 提交后由 review 核验。
何时必须调用:
完成任何涉及图变更的开发任务后、创建 git commit 之前
变更包括: 新增/修改节点（模块/数据结构/需求）、新增/删除依赖边
何时不需要:
未产生任何结构变更的纯阅读/查询任务
参数:
intent_json: JSON 字符串，结构: {task_id, base_revision, nodes_to_create:[{id,label,props}], nodes_to_update:[{id,props}], edges_to_create:[{from,type,to,props}], edges_to_remove:[{from,type,to}], work_notes, summary, actor} work_notes 必填工作过程状态: 为什么这么改、考虑过什么备选（下一个实例靠它重建场景）
返回: {status: "pending", task_id, path} 注意: 本工具只缓存不写入——review 失败（git 提交被拒）时 pending 不会进图。
| Name | Required | Description | Default |
|---|---|---|---|
| intent_json | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden. It discloses that the request is only cached as pending, that review happens after git commit, and that a failed review means the pending intent does not enter the graph. This is unusually clear about side effects and non-write semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with headers for usage, parameters, return, and caveats. Every section adds operational value, and the key warning about cache-only behavior is front-loaded as well as repeated at the end for emphasis without being wasted.
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 a single complex parameter and no annotations, the description covers when to use it, the JSON structure, required work_notes, return shape, and failure semantics. It does not define valid values for edge 'type' or how to obtain task_id/base_revision, but sibling tools and the output schema already imply that context, so it is only slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by defining intent_json as a JSON string with a complete nested structure: task_id, base_revision, node/edge collections, work_notes, summary, and actor. It also highlights that work_notes is required and explains its purpose, which goes beyond 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 action and resource: 'submit graph change intent request' and identifies it as the mandatory step after development and before git commit. It enumerates what counts as a graph change and explicitly covers when not needed, which distinguishes it from read/query sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated 'when must call' and 'when not needed' sections give explicit selection criteria: any graph-change task before creating the git commit, versus pure read/query tasks. This lets an agent route to query_impact/query_context instead without ambiguity.
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.0claim_taskget_pending_intentsget_pending_tasksgraph_revisionquery_contextquery_impactsubmit_graph_intentScored across 7 tools
query_impact and query_context are clearly differentiated by their focus (propagation vs. navigation), and the core command/voting tools are distinct. However, get_pending_intents and get_pending_tasks share a similar prefix and both return lists, so an agent could initially confuse them; descriptions mitigate but do not fully eliminate this.
Most tools follow a snake_case verb_noun pattern (query_impact, submit_graph_intent, claim_task, get_pending_tasks, get_pending_intents). graph_revision deviates as a noun-only identifier, and there is minor verb variance (query vs. get vs. submit), but the overall pattern is readable and predictable.
Seven tools is well within the ideal range for a specialized graph/context server. Each tool serves a distinct part of the investigate-assess-claim-submit-review workflow with no obvious redundancy or bloat.
The tool surface covers the core lifecycle: context discovery, impact analysis, task retrieval/claiming, intent submission, pending-intent review, and revision tracking. Minor gaps exist—such as no explicit intent-cancellation or node-detail tool—but query_context and query_impact fill most needs and the workflow appears functional.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.