FlightPlan server is an advisory intent registry that lets coding agents coordinate overlapping work before it collides, record outcomes, and resolve uncommitted-work warnings.
post_intent — file an intent before non-trivial work with summary, kind (build/explore/spike/decision), repo, branch, title, and touches globs; returns intent id, overlap alerts (warn/nudge/fyi), and relevant context.
list_intents — query in-flight/recent work: semantic overlap check by summary, deterministic glob collision check by overlaps, and context search by q/since with filters (repo, author, branch, status, kind, session).
update_intent — revise an intent's summary/touches/branch, renew TTL heartbeat, and re-check collisions mid-session.
complete_intent — close work as done or abandoned with outcome, changed files, commit SHAs, and uncommitted flag to warn others.
mark_intent_landed — tell the registry that previously uncommitted completed work has landed in git, optionally with commit SHAs; idempotent and preserves the completion record.
Overall behavior is advisory only: it never blocks work; it surfaces overlaps and context so agents can coordinate.
Your agents collide. File a FlightPlan.
Before work begins, each of your agents declares where it's headed and sees what's already in flight. They coordinate around conflicts, then leave behind what changed and why.
Advisory, never locking.
A byproduct of agent work, not another process to maintain.
FlightPlan coordinates coding agents before their work collides. This repo contains the CLI, MCP server, and installer for the hosted service at getflightplan.com.
From your repo's root:
uvx getflightplan installThat installs FlightPlan for Claude Code. For Codex or Cursor, append
--agent codex or --agent cursor. --agent also takes a comma list
(--agent claude,cursor) and all, which means every agent this version
knows. The command is safe to re-run.
The first time on a machine, run uvx getflightplan login next — it
connects your account and finishes the MCP setup.
The hosted service is in beta; sign in with your GitHub account at
getflightplan.com. The package is on PyPI, so the
command above is all you need. To pin a branch or commit instead, install from
the source:
uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install.
Version and compatibility policy: docs/versioning.md.
Related MCP server: asynkor
File the work. Before editing, an agent declares its task and the files it expects to touch.
See what's in flight. FlightPlan returns overlapping active work, including uncommitted changes Git cannot see, decisions made during coding, plus relevant recent outcomes.
Coordinate. Overlaps are advisory: narrow the work, sequence it, or proceed with context.
Debrief. The agent records what changed, what surprised it, and what it tried so the next session does not start cold.
.flightplan.toml — pins the repo name every agent posts under, plus the
registry URL. Committed on purpose; no secrets.
A managed agent snippet in CLAUDE.md and/or AGENTS.md.
/registry-digest — an on-demand "what happened lately" command.
A session-end stop hook (.claude/hooks/flightplan_stop_hook.py plus its
settings wiring) that reminds the agent to close out open intents.
It also checks MCP registration and service reachability, and repairs the registration when the machine has a credential — no prompts. Verification is advisory and never fails the run.
To remove everything the installer wrote, run getflightplan uninstall from
the repo root (--dry-run to preview, --purge-key to also delete the saved
API key).
getflightplan login gets a credential without a copied API key. It opens
your browser, you approve there, and the credential goes to
~/.config/flightplan/env with mode 600. The credential is never printed.
After the credential is stored, login also registers the MCP server for
the agent binaries on your machine — the step install has to skip while
the machine has no credential.
On a machine with no browser, run getflightplan login --headless. The
command shows a short code and an address. Open that address on another
device and enter the code.
getflightplan logout removes the stored credential from this machine. To
revoke it on the service, use the /devices page.
After a login, the client asks the registry which repository this checkout is.
It sends the address of your origin remote and up to 1000 commit ids, which
prove that you have a clone. If your account has access, the id and the name
go into .flightplan.toml. If the registry does not know the repository, the
client offers to register it in your browser. If your account has no access,
the client offers to request it.
getflightplan login --no-register skips the check. getflightplan register
runs it on its own, later. A failed check never fails a login.
An intent completed with uncommitted: true says the work is in someone's
working tree and nowhere else. The registry cannot see your tree, so it keeps
warning everyone who touches those paths until it is told the work landed.
Agents do this with the mark_intent_landed tool. You can do it by hand:
getflightplan landed <intent-id> --commit <sha> --commit <sha>The commits are optional; the timestamp is the correction. Pass the SHAs only if you know them — the client never guesses which commits belong to an intent. Landing can be repeated safely and never rewrites the completed record.
The MCP server command is uvx getflightplan mcp — the mcp subcommand is
required. A bare getflightplan prints help and exits, so a registration or
directory build spec without mcp fails before the first MCP message.
FLIGHTPLAN_URL — optional; defaults to https://api.getflightplan.com
FLIGHTPLAN_API_KEY — your key (the MCP server's env; the stop hook also
reads ~/.config/flightplan/env).
.flightplan.toml — the per-repo pin: a repo name and url, or a
target_id with a readable name once the repo has an id pinned.
The installer adds the following managed contract with your repo name pinned.
This repo participates in the team intent registry (MCP server: flightplan).
Before starting non-trivial work, call post_intent. The test: will the
work change behavior, defaults, or contracts another agent would encounter —
or, for pure investigation, would the findings save the next agent an hour?
Yes to either → post; Q&A and typo-level fixes, no. Send
a one-paragraph summary (what + why), kind (build, or
explore/spike for throwaway investigation), and touches globs for the
areas you expect to change. Keep the returned id for later. For repo,
use the basename of the git origin remote (or the repo root directory name if there is no remote) — every agent on this repo must use the same name or
collision checks silently miss each other. The response may include
context: recent completed work relevant to your task — read those outcomes
before starting; the surprises and dead ends in them are load-bearing.
If the response includes overlaps at level warn, check what the overlap is
before pausing. Two cases need no confirmation — mention the overlap and keep
going: the overlapping intent is the very work you were asked to act on
(reviewing it, verifying it, following up on it), or your task is read-only.
Otherwise, tell your user who is doing what and which globs collide, and ask
how to proceed before continuing. fyi/nudge levels: mention briefly and
keep going.
If the work changes shape or runs long, call update_intent: revise the
summary/touches when scope grows (collision checks run against them — stale
globs miss real collisions), or call with just the id to renew the TTL on
work spanning more than a day. The response includes fresh overlaps — the
same collision check as posting, glob-based — and a warn there gets the
same treatment as a warn at post time.
When the work finishes or is abandoned — including when the session is
wrapping up — call complete_intent with a one-paragraph outcome: what
actually changed, anything surprising, approaches tried and rejected, anything
deliberately left in place. If a warn overlap changed how the work went
(coordinated, narrowed scope, proceeded anyway), say which. Attach the git
facts you already know: files actually changed (git diff --name-only),
commits created, and uncommitted: true if any of the work is not yet
committed — that flag is what lets other agents' collision checks warn loudly
instead of quietly. Completing an intent ends the slice, not the session:
follow-up work after a complete that changes behavior, defaults, or contracts
gets a fresh post — "same session" doesn't exempt it.
When you learn declared-uncommitted work has landed, call
mark_intent_landed with that intent's id (and the commit SHAs if you know
them): until someone says so, the registry keeps warning everyone who touches
those paths.
Re-check for collisions whenever your picture of in-flight work may be
stale — posting checks once, and it goes stale over a long session.
Re-check moments: a file changed between your read and your edit, or an Edit
fails on text you just read — someone's work landed under you; before editing
a shared doc or artifact you didn't create this session; when resuming after
a handoff from another agent; and before touching files named in an earlier
warn. The cheapest re-check is
update_intent with just your intent id (renews the TTL, returns fresh
overlaps); use list_intents (pass overlaps globs, plus summary for a
semantic check, or q/since for history) when you have no open intent or
are scoping new work.
When a decision gets resolved in conversation (an approach chosen, an
alternative rejected, a direction set), record it the moment it settles:
post_intent with kind: "decision", the question as the summary, and the
resolution in outcome — what was decided, what was rejected, and why. One
call; no touches, no completion later. Decisions never collide and become
searchable team memory. Decisions are also the correction mechanism:
completed outcomes are immutable, so if one later proves wrong, post a
decision citing what actually held.
The registry is advisory and must never block work: if its tools are missing
or error, proceed with the work, and tell your user once that they can run
uvx getflightplan install (see getflightplan.com) to join this repo's
registry.
What leaves your machine is the coordination record: intent summaries and outcome paragraphs, glob patterns, changed-file paths, branch names, and commit ids — sent only to the FlightPlan service. Source code contents are never uploaded. Everything the registry knows, it learns as a byproduct of your agents' work.
The details — what never leaves, and what is stored where — are in docs/data-flow.md. Vulnerability reporting: 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.
