你的代理相互冲突。提交一份 FlightPlan。
在工作开始之前，你的每个代理都会声明其目标，并查看已经在进行中的工作。 它们围绕冲突进行协调，然后留下变更内容及其原因。
提供建议，绝不锁定。
是代理工作的副产品，而非需要维护的另一个流程。
FlightPlan 在编码代理的工作发生冲突之前对其进行协调。此仓库包含托管服务 getflightplan.com 的 CLI、MCP 服务器和安装程序。
在你的仓库根目录下：
uvx getflightplan install这将为 Claude Code 安装 FlightPlan。对于 Codex，请附加 --agent codex（或 --agent both）。该命令可以安全地重复运行。
在机器上首次运行时，接下来运行 uvx getflightplan login——它会连接你的账户并完成 MCP 设置。
托管服务处于测试阶段；使用你的 GitHub 账户登录 getflightplan.com。该包位于 PyPI 上，因此上述命令就是你所需要的全部。要固定某个分支或提交，请从源码安装：
uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install。
版本和兼容性策略：docs/versioning.md。
Related MCP server: asynkor
提交工作。 在编辑之前，代理声明其任务和预期要接触的文件。
查看进行中的工作。 FlightPlan 返回重叠的活跃工作，包括 Git 无法看到的未提交更改、编码过程中做出的决策，以及相关的近期结果。
协调。 重叠是建议性的：缩小工作范围、排序，或在了解上下文的情况下继续。
汇报。 代理记录变更内容、意外情况以及尝试过的方法，以便下一次会话不会从零开始。
.flightplan.toml——固定每个代理发布时使用的仓库名称以及注册表 URL。有意提交；不包含机密。
在 CLAUDE.md 和/或 AGENTS.md 中的托管代理片段。
/registry-digest——一个按需的“最近发生了什么”命令。
一个会话结束停止钩子（.claude/hooks/flightplan_stop_hook.py 及其设置连接），提醒代理关闭未完成的意图。
它还会检查 MCP 注册和服务可达性，并在机器拥有凭据时修复注册——无需提示。验证是建议性的，绝不会导致运行失败。
要删除安装程序写入的所有内容，请在仓库根目录下运行 getflightplan uninstall（使用 --dry-run 预览，使用 --purge-key 同时删除保存的 API 密钥）。
getflightplan login 无需复制 API 密钥即可获取凭据。它会打开你的浏览器，你在那里批准，凭据会以模式 600 保存到 ~/.config/flightplan/env。凭据永远不会被打印出来。存储凭据后，登录还会为你机器上的代理二进制文件注册 MCP 服务器——这是安装程序在机器没有凭据时必须跳过的步骤。
在没有浏览器的机器上，运行 getflightplan login --headless。该命令会显示一个短代码和一个地址。在另一台设备上打开该地址并输入代码。
getflightplan logout 会从这台机器上删除存储的凭据。要在服务上撤销它，请使用 /devices 页面。
登录后，客户端会向注册表询问此检出属于哪个仓库。它会发送你的 origin 远程地址以及最多 1000 个提交 ID，以证明你拥有一个克隆。如果你的账户有访问权限，ID 和名称会写入 .flightplan.toml。如果注册表不知道这个仓库，客户端会提供在你的浏览器中注册它的选项。如果你的账户没有访问权限，客户端会提供请求访问的选项。
getflightplan login --no-register 会跳过检查。getflightplan register 稍后单独运行它。失败的检查绝不会导致登录失败。
使用 uncommitted: true 完成的意图表示工作位于某人的工作树中，而不是其他地方。注册表无法看到你的工作树，因此它会持续警告所有接触这些路径的人，直到被告知工作已落地。
代理使用 mark_intent_landed 工具执行此操作。你也可以手动操作：
getflightplan landed <intent-id> --commit <sha> --commit <sha>提交是可选的；时间戳是修正。只有在你确定知道的情况下才传递 SHA——客户端永远不会猜测哪些提交属于某个意图。落地可以安全地重复执行，并且永远不会重写已完成记录。
FLIGHTPLAN_URL——https://api.getflightplan.com
FLIGHTPLAN_API_KEY——你的密钥（MCP 服务器的环境变量；停止钩子也会读取 ~/.config/flightplan/env）。
.flightplan.toml——每个仓库的固定配置：一个 repo 名称和 url，或者一个带有可读 name 的 target_id（一旦仓库有了固定的 ID）。
安装程序会添加以下托管契约，其中固定了你的仓库名称。
此仓库参与团队意图注册表（MCP 服务器：flightplan）。
在开始非琐碎工作之前，调用 post_intent。判断标准：该工作是否会改变其他代理可能遇到的行为、默认值或契约——或者，对于纯调查，调查结果是否能节省下一个代理一个小时？两者中任一为是 → 发布；问答和拼写级别的修复，则不需要。发送一段摘要（做什么 + 为什么）、kind（build，或用于一次性调查的 explore/spike）以及你预期要更改区域的 touches glob 模式。保留返回的 ID 以供后续使用。对于 repo，使用 git 远程 origin 的 basename（如果没有远程，则使用仓库根目录名称）——此仓库上的每个代理必须使用相同的名称，否则冲突检查会静默地互相错过。响应可能包含 context：与你的任务相关的近期已完成工作——在开始之前阅读这些结果；其中的意外和死胡同是重要的信息。
如果响应包含级别为 warn 的重叠，在暂停之前检查重叠是什么。两种情况无需确认——提及重叠并继续：重叠的意图正是你被要求处理的工作（审查它、验证它、跟进它），或者你的任务是只读的。否则，告诉你的用户谁在做什么以及哪些 glob 冲突，并在继续之前询问如何操作。fyi/nudge 级别：简要提及并继续。
如果工作范围发生变化或运行时间过长，调用 update_intent：当范围扩大时修改摘要/touches（冲突检查会针对它们运行——过时的 glob 会错过真正的冲突），或者仅使用 ID 调用以续订跨越超过一天的工作的 TTL。响应包含新的 overlaps——与发布时相同的基于 glob 的冲突检查——其中的 warn 与发布时的 warn 处理方式相同。
当工作完成或被放弃时——包括会话即将结束时——调用 complete_intent 并附上一段结果：实际发生了什么变化、任何意外情况、尝试过并被拒绝的方法、任何故意保留的内容。如果 warn 重叠改变了工作的进行方式（协调、缩小范围、无论如何继续），请说明是哪一个。附上你已经知道的 git 事实：实际更改的 files（git diff --name-only）、创建的 commits，以及如果任何工作尚未提交则 uncommitted: true——这个标志让其他代理的冲突检查大声警告而不是静默处理。完成意图结束的是片段，而不是会话：完成之后改变行为、默认值或契约的后续工作需要重新发布——“同一会话”并不豁免。
当你得知已声明未提交的工作已落地时，使用该意图的 ID（以及你知道的提交 SHA）调用 mark_intent_landed：除非有人声明，否则注册表会持续警告所有接触这些路径的人。
每当你对进行中工作的了解可能过时时，重新检查冲突——发布时检查一次，在长时间会话中会过时。需要重新检查的时刻：在你读取和编辑之间文件发生了变化，或者编辑在你刚刚读取的文本上失败——某人的工作在你下面落地了；在编辑你本次会话未创建的共享文档或工件之前；在从另一个代理交接后恢复时；以及在接触早期 warn 中命名的文件之前。最便宜的重新检查是仅使用你的意图 ID 调用 update_intent（续订 TTL，返回新的 overlaps）；当你没有开放的意图或正在规划新工作时，使用 list_intents（传递 overlaps glob，加上用于语义检查的 summary，或用于历史的 q/since）。
当在对话中做出决定时（选择了方法、拒绝了替代方案、设定了方向），在决定确定的那一刻记录它：使用 kind: "decision" 调用 post_intent，摘要为问题，结果在 outcome 中——决定了什么、拒绝了什么以及原因。一次调用；没有 touches，稍后无需完成。决定永远不会冲突，并成为可搜索的团队记忆。决定也是修正机制：已完成的结果是不可变的，因此如果后来证明是错误的，发布一个决定，引用实际成立的内容。
注册表是建议性的，绝不能阻塞工作：如果其工具缺失或出错，继续工作，并告诉你的用户一次，他们可以运行 uvx getflightplan install（参见 getflightplan.com）加入此仓库的注册表。
离开你机器的是协调记录：意图摘要和结果段落、glob 模式、更改的文件路径、分支名称和提交 ID——仅发送给 FlightPlan 服务。源代码内容永远不会上传。注册表知道的一切，都是作为你代理工作的副产品而得知的。
详细信息——什么永远不会离开，以及什么存储在哪里——在 docs/data-flow.md 中。漏洞报告：SECURITY.md。
Apache-2.0
Close out an intent when work finishes or is abandoned. The outcome summary is required for done and is the most valuable artifact this system produces: write one paragraph covering what actually changed, anything surprising, approaches tried and rejected, and anything deliberately left in place. Gather git facts as exhaust — you already have them at completion time: files = repo-relative paths actually changed (git diff --name-only over the work, committed or not); commits = SHAs created for this work; uncommitted = true if ANY of the work is not yet committed (untracked/unstaged/staged-only) — this flag is what lets other agents' collision checks warn loudly instead of quietly. Omit anything unknown. Any overlaps that come back carry excerpts, and overlaps_omitted counts the ones the server cut per level — use get_intent(id) for a full record.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id returned by post_intent. | |
| files | No | Repo-relative paths actually changed (from `git diff --name-only` over the work). Omit if unknown. | |
| status | Yes | done = landed; abandoned = stopped without landing. | |
| commits | No | Commit SHAs produced for this work. Omit if unknown. | |
| outcome | Yes | One paragraph: what actually changed, surprises, dead ends, things deliberately left alone. | |
| uncommitted | No | True if ANY of the work is not yet committed (untracked/unstaged/staged-only). This flag escalates collision warnings for other agents. False = all committed. Omit if unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers real behavioral context: the outcome is required for `done`, the `uncommitted` flag escalates collision warnings for other agents, and overlaps_omitted counts server-side cuts per level. It stops short of describing idempotency or what happens if the intent is already closed.
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?
Purpose and the required-outcome instruction are front-loaded, and most sentences (collision warning escalation, overlaps_omitted) earn their place. The git-fact paragraph is somewhat verbose and duplicates schema text.
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?
Despite no output schema, the description explains the meaningful return signals (overlap excerpts and overlaps_omitted) and the required outcome artifact. It omits error/edge behavior for an already-completed intent, so it is strong 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 100%, so the schema already documents all six parameters, and the description's git-fact explanations largely restate them. Baseline 3 applies because the description adds no syntax or format detail beyond what the structured fields provide.
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?
States a specific verb+resource ('Close out an intent') plus the triggering condition ('when work finishes or is abandoned'). It also names get_intent as the route to a full record, so an agent can place it among its siblings without opening a schema.
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?
Gives clear timing context (completion or abandonment) and points to get_intent for full records. It does not differentiate from close siblings like update_intent or mark_intent_landed, leaving a possible ambiguity about which tool ends the lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one intent's full record — the whole summary and outcome — by id or by a unique 8-char prefix. Overlap, context and list entries carry excerpts only, so call this when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting. Read-only; it records nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id, or a unique 8-char prefix of one (as shown in overlaps and the digest). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, and it does state the key trait: 'Read-only; it records nothing.' However it is silent on other relevant behavior for a lookup tool, such as what happens when an 8-char prefix is not unique or how the full record is shaped.
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?
Three short sentences, front-loaded with the core action and scope, then the routing rationale, then the safety trait. No filler, and each sentence adds information the structured fields do not provide.
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 read tool with no annotations and no output schema, the description covers what the tool does, when to reach for it, and that it is non-mutating. It stops short of covering prefix-ambiguity or lookup-failure behavior, which would fully close the gap.
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 100% and the sole parameter's description already explains the id-or-unique-8-char-prefix semantics. The description repeats the same id/prefix detail without adding format or edge-case meaning (e.g., prefix ambiguity), so this sits at the baseline for well-covered schemas.
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?
States a specific verb and resource ('Fetch one intent's full record') plus the scope of what is returned ('the whole summary and outcome'). It also differentiates itself from the excerpt-bearing surfaces ('Overlap, context and list entries carry excerpts only'), so an agent can separate it from list_intents without opening either schema.
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?
Gives concrete triggers for calling it ('when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting'). Alternatives are implied via the excerpt-only surfaces rather than named directly, and there is no explicit when-not rule, so it falls just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query in-flight and recent work across the team. Three distinct uses — pick exactly one: (1) pre-planning semantic check — pass summary (and optionally overlaps globs) to get judge-assessed semantic overlap before you post_intent; this is the strong collision check; (2) fast glob collision check — pass overlaps alone (no summary, no q) for deterministic prefix matching; (3) context search — pass q and since (add match=any for recall if a precise query returns nothing) to search summaries and outcomes including completed work. q and overlaps are AND-combined: a descriptive q alongside overlaps filters out overlapping intents whose summaries don't contain your words — for a collision check, omit q. q matches per-word (all words must appear, any order). Each returned intent carries an alert_level when overlaps is given: warn = surface loudly to your user; fyi = quiet mention; nudge = possible duplicate spike, suggest comparing notes. Rows carry outcome_excerpt by default; pass detail="full" for whole outcomes.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Plain-text search over summaries and outcomes. | |
| kind | No | Filter results by kind. | |
| repo | No | Filter to one repository. Use the basename of the git origin remote (or the repo root directory name if there is no remote) — must match the name used in post_intent, or the filter silently returns nothing. | |
| limit | No | ||
| match | No | How q terms combine: all (default) = every word must match — precise; any = recall mode, use when a context search with several descriptive words comes back empty. | all |
| since | No | ISO-8601 timestamp or shorthand like '24h', '7d'. | |
| author | No | Filter to one person's intents, e.g. 'sarah' — for questions like 'what did Sarah's agent work on last week?'. | |
| branch | No | YOUR git branch. Overlaps on the same branch are flagged `same_branch` — your own line of work, likely already in your tree, but verify (it may be uncommitted in another session). | |
| detail | No | How much of each row comes back: compact (default) = an `outcome_excerpt` per row, enough to scan; full = whole rows with full outcomes — use it for a digest, or whenever you will actually read the outcomes. | compact |
| status | No | Comma-separated of: active, done, abandoned, expired. Omit for all (history included). | |
| my_kind | No | The kind of YOUR planned work; sets alert levels. | build |
| session | No | Filter to one agent session. Pass 'current' for this session's own intents — e.g. to find your still-open intent before wrapping up. Any other value passes through verbatim. | |
| summary | No | Your planned task, one paragraph. Provide it to get semantic (judge) collision assessment instead of glob-prefix matching — use for a pre-planning check before you're ready to post_intent. | |
| overlaps | No | Globs you expect to touch; filters to overlapping intents and computes alert levels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the disclosure burden: it explains q and overlaps are AND-combined, that omitting q is required for a clean collision check, that alert_level carries warn/fyi/nudge meanings, that same-branch hits are flagged as your own line of work, and that rows default to outcome_excerpt with detail='full' returning whole outcomes.
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?
Front-loads the three-way branching before any detail, and nearly every sentence carries distinct information. It runs long with stacked clauses, but the density is earned rather than padded.
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 14-parameter read tool with no output schema and no annotations, the description covers the return shape (alert_level values, outcome_excerpt vs full detail) and all decision-relevant modes, leaving no material gap 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 coverage is already 93%, but the description adds genuine semantics beyond it: how q terms combine word-by-word and across filters, when match=any is warranted, that session='current' targets this session's own intents, and how detail trades excerpt against whole outcomes.
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?
States a specific verb and resource ('query in-flight and recent work across the team') and situates itself against a sibling by naming post_intent as the downstream action. An agent can distinguish list_intents from get_intent/post_intent without opening a schema.
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 enumerates three distinct, mutually exclusive uses ('pick exactly one') with the exact parameter combinations that select each, plus exclusions ('no summary, no q', 'for a collision check, omit q') and the alternative (post_intent after the pre-planning check). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that work an already-COMPLETED intent declared uncommitted is now in git. Call this the moment you learn it: you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed. Until someone says so, the registry keeps warning every agent who touches those paths and keeps re-telling the same story about work that is no longer at risk — a tree it cannot see is the one thing it cannot check for itself. Pass the commit SHAs if you know them; landing without them is fine and complete, the timestamp is the correction. Idempotent, and it never rewrites the completion record — the outcome, the reported files and the original uncommitted declaration all stand.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id whose work has landed. | |
| commits | No | Commit SHAs that carried the work, if you know them. Omit if you don't — do not guess. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses that the tool is idempotent, never rewrites the completion record, and that providing commit SHAs is optional ('pass the commit SHAs if you know them; landing without them is fine and complete'). It also explains behavioral nuance ('the tree it cannot see is the one thing it cannot check for itself').
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 paragraph that front-loads the core action ('Record that work... is now in git'), then adds context about when and why to call it. Every sentence contributes meaningful information — no redundancy or 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?
Given that there is no output schema and no annotations, the description covers the tool's purpose, usage cues, behavioral traits, and parameter guidance comprehensively. The tool has low complexity (2 params, 1 required), and the description provides everything needed for an agent to select and invoke 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?
Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the purpose of the `commits` parameter in context ('if you know them. Omit if you don't — do not guess'), and emphasizes that the timestamp is the correction when commits are unknown. This added guidance justifies above baseline.
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 specific verbs ('Record', 'mark', 'landed') and clearly identifies the resource ('work an already-COMPLETED intent declared uncommitted is now in git'). It distinguishes this tool from siblings like complete_intent (which marks intent completion) and post_intent (which creates a new intent) by focusing on the post-completion git state update.
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 call this ('the moment you learn it') and provides clear examples ('you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed'). It explains the consequences of not calling it ('registry keeps warning', 'keeps re-telling the same story'), which strongly implies when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register what you are about to work on so other developers' agents can avoid collisions. Call this before starting any non-trivial coding task (anything touching more than a trivial fix). Infer kind: build for work meant to land, explore/spike for throwaway investigation, decision for a resolved decision worth recording (post it the moment a debate settles: pass the resolution in outcome — what was decided, what was rejected, and why; no touches needed; it is stored complete, never collides, and needs no complete_intent). Infer touches from your plan as repo-relative glob patterns. Returns the intent id — keep it to post the outcome later. Also returns any overlapping in-flight intents — active work (alert warn/nudge/fyi) and recently-completed work that may not have landed in git yet (always fyi): overlaps are the COLLISION signal — if overlap level is warn, tell your user before proceeding; for fyi, check whether that work is already in your tree before redoing it. The response also includes context — recently-completed work relevant to THIS task: read those outcomes before you start, the surprises and dead ends in them are load-bearing (a rejected approach you might retry, a gotcha you will hit). Overlap entries carry summary_excerpt; context entries carry summary_excerpt and outcome_excerpt. overlaps_omitted counts what the server cut per alert level — a non-zero warn there means more warnings exist than are shown. Call get_intent(id) for any full record.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | build = meant to land; explore/spike = throwaway investigation; decision = a resolved decision recorded for the feed (requires `outcome`). | build |
| repo | Yes | Repository name, e.g. 'raveneye'. Use the basename of the git origin remote (or the repo root directory name if there is no remote) — every agent on the same repo must derive the same string or collision checks silently miss each other. | |
| title | No | Short headline for the work, ≤80 chars, like a commit subject line (e.g. 'FTS5 search + recall mode'). Cheap to write and the feed reads far better with one — provide it. | |
| branch | No | Git branch, if known. | |
| outcome | No | kind=decision only: the resolution — what was decided, what was rejected, and why. Other kinds write outcomes at completion instead. | |
| summary | Yes | One paragraph: what you're doing and why. | |
| touches | Yes | Repo-relative glob patterns you expect to touch, e.g. ['central/services/scorecard*']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden and largely delivers: it explains that decision-type intents are stored complete, never collide, and need no complete_intent; that it returns the intent id to keep for the later outcome post; and describes the overlap alert levels warn/nudge/fyi and what each obliges the agent to do. This is exactly the behavioral context annotations would otherwise supply.
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 core guidance is front-loaded well, but the second half becomes a dense run-on packed with field names and conditional alert logic. It is information-rich but strains readability; a few of the parentheticals could be trimmed without loss.
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 7-parameter mutation tool with a rich implied return shape and no output schema, this covers the important ground: kind inference, touch inference, the intent id, overlap warnings, context of prior outcomes, and the overlaps_omitted count. It stops short of describing the full response envelope or pagination/limits, but it is close to complete 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 coverage is 100%, so the baseline is 3. The description goes beyond by giving decision-specific semantics (outcome contents, no touches needed) and explains how touches should be inferred (repo-relative globs from the plan), adding operational meaning to the parameters rather than restating 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?
States a specific verb ('Register') and resource ('what you are about to work on') with a concrete goal ('so other developers' agents can avoid collisions'). Clearly distinguishes this write/registration tool from the read-oriented siblings list_intents and get_intent.
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 says when to call it ('before starting any non-trivial coding task (anything touching more than a trivial fix)') and gives kind-specific guidance, including that decision should be posted 'the moment a debate settles' with no touches needed. Routes the agent to get_intent for full records, effectively naming the alternative for consuming results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an in-progress intent. Call when the work changes shape (revise summary or touches — collision checks run against these fields, so stale globs silently miss real collisions) or when work runs long (a call with just the id renews the TTL heartbeat; active intents expire after ~48h without one). Calling with just the id ALSO returns fresh overlaps — the cheap mid-session collision re-check, since a post-time check goes stale over a long session. Treat a warn here exactly like a warn at post time: tell your user before proceeding. Overlaps carry excerpts, and overlaps_omitted counts any the server cut per level — use get_intent(id) for a full record. Never use this to finish work — call complete_intent for that.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id returned by post_intent. | |
| title | No | Revised short headline, ≤80 chars. | |
| branch | No | Git branch, if it has changed. | |
| summary | No | Revised one-paragraph summary: what + why. | |
| touches | No | Revised repo-relative glob patterns. Replaces the existing list — include all globs, not just new ones. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: it discloses the ~48h TTL expiry, that an id-only call renews the heartbeat, that stale globs cause silent collision misses, and that warn must be surfaced to the user. It also explains overlaps carry excerpts and that overlaps_omitted counts truncations — behavioral context well beyond the schema.
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?
Front-loaded with purpose, then conditions, then returns, then the exclusion. Dense but every clause carries distinct information; the parenthetical asides make it read long, though little is truly expendable.
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?
There is no output schema, so the description correctly compensates by explaining return values (overlaps, overlaps_omitted, excerpts) and directing to get_intent for a full record. Nothing needed to invoke the tool 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?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: an id-only call still renews TTL and returns fresh overlaps, and touches replacement semantics drive collision checks. It goes past restating the per-field descriptions.
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?
States a specific verb+resource ('Update an in-progress intent') and scopes it to in-progress work, immediately distinguishing it from complete_intent and get_intent by name. An agent can tell it apart from its siblings without opening any schema.
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?
Gives explicit triggers ('when the work changes shape', 'when work runs long'), the id-only heartbeat case, and a hard exclusion ('Never use this to finish work — call complete_intent for that'). Both when-to-use and when-not-to-use are spelled out.
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.15.0get_intentlist_intents1 field changedInput schema / properties / detailAdded value: +{
+ "default": "compact",
+ "description": "How much of each row comes back: compact (default) = an `outcome_excerpt` per row, enough to scan; full = whole rows with full outcomes — use it for a digest, or whenever you will actually read the outcomes.",
+ "enum": [
+ "compact",
+ "full"
+ ],
+ "title": "Detail",
+ "type": "string"
+}v0.1.0complete_intentlist_intentsmark_intent_landedpost_intentupdate_intentScored across 6 tools
The lifecycle roles (post, list, get, update, complete, mark_landed) are clearly distinct, but collision-check functionality is spread across three tools: post_intent returns overlaps, list_intents offers glob/semantic checks, and update_intent re-runs them mid-session. An agent could reasonably hesitate over which to use for a given check, though the descriptions do clarify the intended contexts.
All names are snake_case with a leading verb (post_intent, list_intents, get_intent, update_intent, complete_intent, mark_intent_landed). The pattern is predictable and the slightly longer mark_intent_landed still fits the verb_noun convention.
Six tools is well-scoped for a lightweight intent-coordination registry: each tool maps to a distinct lifecycle step (create, query, read, revise, close, correct-landing-status). Nothing feels padded or missing at the count level.
The surface covers the full intent lifecycle: create, list/search, get, update/heartbeat, complete (including abandonment), and post-hoc landing correction. The main minor gap is the absence of an explicit delete/retract for erroneous intents, and querying is limited to summary/glob/time rather than author or kind filters.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
Coordination for AI coding agents: declare plans, catch design conflicts early, share team memory.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
