Sistema de gestión de arquitectura de código impulsado por base de datos de grafos: mantiene un grafo de dependencias de tres capas de "requisitos / módulos de código / datos" con Neo4j. El desarrollo de agentes se completa automáticamente, el impacto de los cambios se consulta con un clic, y los hooks reactivos coordinan la colaboración de múltiples agentes.
Instrucción de configuración en una frase para la IA: «Lee este README y completa la instalación y configuración de este proyecto siguiendo la sección "Inicio rápido".»
Las herramientas existentes no pueden responder a la pregunta "si cambio una estructura de datos, ¿cuáles son todos los lugares que necesitan actualizarse?" — el IDE solo reconoce los imports de código, el sistema de compilación solo reconoce las dependencias de compilación, y el linaje de datos solo reconoce las canalizaciones de datos. Este proyecto coloca código, datos, herramientas y requisitos en un mismo grafo:
AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
└──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端Análisis de impacto: cualquier cambio en un nodo, una consulta Cypher revela todos los downstream
Control de acceso estricto: el agente declara el cambio en el grafo (solicitud de intención) → el commit de git activa la verificación de revisión → solo se escribe en el grafo si se aprueba; si falla, ni siquiera el commit puede entrar
Hooks reactivos: los cambios en el grafo se distribuyen a los agentes relevantes según suscripciones; si no hay cambios, la propagación converge naturalmente
Escritorio: visualización de datos del grafo + visualización de tareas en curso
Los detalles de diseño se encuentran en docs/design-v1.1.md, y la estructura del programa en docs/architecture.md.
Related MCP server: codemap
Windows 10/11 (Git Bash disponible)
Python ≥ 3.11 (confirmar con python --version)
Opcional: API LLM compatible con OpenAI (para el agente de revisión / mantenimiento nocturno; por defecto apunta a http://localhost:8642/v1, se puede modificar en la configuración u omitir)
Dile a cualquier asistente de IA después de clonar este proyecto:
"Lee README.md, ejecuta el proceso de instalación de inicio rápido y completa la configuración de este proyecto."
El único comando central que debe ejecutar la IA:
python setup/setup.pyEste script completa automáticamente los siguientes pasos (cada fallo proporciona instrucciones claras de intervención manual):
Paso | Acción | Resultado |
1 | Verificar la versión de Python | Salir y avisar si la versión no coincide |
2 | Descargar y descomprimir JDK 21 (Temurin, múltiples fuentes de espejo) |
|
3 | Descargar y descomprimir Neo4j Community 5.x (múltiples fuentes de espejo) |
|
4 | Iniciar el servicio Neo4j e inicializar la contraseña | Contraseña por defecto |
5 | Crear |
|
6 | Aplicar el esquema del grafo (restricciones + índices + datos semilla de la canalización de ejemplo) | El grafo de tres capas en Neo4j |
7 | Registrar el servidor MCP en | WorkBuddy puede llamar directamente a 6 herramientas |
8 | Prueba de humo: ejecutar una consulta de impacto | Debe devolver 8 nodos descendentes |
9 | Mostrar los siguientes pasos | Inicio del escritorio / hooks de git / empaquetado exe |
Tiempo estimado: la primera vez unos 5–15 minutos (dependiendo de la velocidad de descarga de JDK + Neo4j, ~380MB en total). Reanudación de descargas: el script es idempotente en cada paso; si falla, corrige el problema y vuelve a ejecutarlo, los pasos completados se omiten automáticamente.
# 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.pyFunciones:
Visualización del grafo: coloreado por capas (requisitos/módulos/datos), clic en un nodo para ver detalles (resumen, puntero, estado, vecindario)
Panel de actividad: solicitudes de intención pendientes, cola de tareas, flujo de changelog reciente, lista de nodos obsoletos
Actualización automática cada 5 segundos
setup.py ya escribe automáticamente en ~/.workbuddy/mcp.json. Después de reiniciar WorkBuddy, aparecen en el directorio de herramientas:
submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks
Si Hermes es compatible con MCP: registra también este servidor (python -m graph_arch.mcp_server, directorio de trabajo en la raíz del repositorio).
Si solo es compatible con OpenAI function calling: las definiciones de herramientas se encuentran en el docstring de src/graph_arch/mcp_server.py, que se pueden convertir directamente al formato de herramientas de OpenAI.
开发工作流（必须遵守）:
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/Clave | Valor por defecto | Descripción |
|
| Conexión Neo4j |
|
| Escrito después de la inicialización de setup |
|
| Endpoint compatible con OpenAI (para revisión/mantenimiento, se puede dejar vacío para omitir) |
|
| Nombre del modelo |
|
| Límite de disparos del mismo nodo en una cadena de hooks (evita bucles) |
|
| Tiempo de espera de reclamación de tareas (si se agota, se reasigna/coloca en cola de mensajes muertos) |
|
| Directorio de registros de cambios |
bash git-hooks/install.sh /path/to/your/code-repoDespués de esto, los push / merge de ese repositorio activarán la verificación de revisión y la fusión del grafo.
Síntoma | Solución |
La descarga de Neo4j falla (403/timeout) | Descarga manualmente |
| Confirma que |
La conexión bolt es rechazada | Verifica el estado del servicio con |
El paso de revisión informa fallo de conexión LLM | El LLM se puede omitir: establece |
Las herramientas MCP no aparecen | Reinicia el harness; confirma que |
MIT (modificable según sea necesario)
认领一个 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.