aionai is a shared working-state MCP server that lets multiple AI coding tools (Claude, Cursor, etc.) read and write a common persistent notebook to stay in sync.
Core Context Management
context_pull — Fetch the current working state for a project segment (open tasks, questions, recent decisions, inbox handoffs); call this before starting any work
context_log — Append entries (decisions, changes, questions, tasks, or notes) to the shared state
context_resolve — Mark an open question or task as resolved so it no longer surfaces in context_pull
context_search — Full-text search across a project's history to recover past context
context_verify — Check change entries against git, classifying them as merged, unmerged, missing, or bare claims
context_handoff — Post a message to another tool's inbox (Cursor, Claude Code, etc.), with optional doorbell delivery for supported clients
Roadmap & Progress Tracking
roadmap_add_node — Add hierarchical nodes (project, segment, phase, epic, task) to a roadmap tree
roadmap_update — Update a node's priority, parent, or status
roadmap_block — Record dependency edges (blocked-by relationships) between nodes
roadmap_view — View the full hierarchical roadmap with done/total rollup per node
roadmap_progress — Get a progress summary (done vs. total, with percentages) per segment and overall
Planning & Cross-Project Reuse
constraints_for_task — Retrieve all decisions and open questions that may constrain a specific task before implementing it
project_lookup — Search another project's history to reuse approaches and decisions
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@aion pull context for myproject"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A shared working-state layer for your AI coding tools. Claude, Cursor, and other MCP clients read and write one small notebook, so they stay on the same page — and you stop being the copy-paste bus between them.
One-click install for Cursor (it configures
uvx aionai). After it's added, setAIONAI_SOURCE=cursorin the server's env. If Cursor can't finduvx, see Troubleshooting; or set it up manually via Connect your tools.
You use more than one AI assistant on a project. They don't know what each other did: you tell Claude a decision, switch to Cursor, and Cursor has no idea. You end up re-explaining and copy-pasting context by hand.
Related MCP server: anchor-mcp
aionai is a tiny local MCP server that keeps a shared, persistent notebook every tool can read and write. It does three jobs:
Remember — decisions, changes, questions, and notes, organized by project.
Track — a lightweight roadmap/to-do list with progress rollup.
Hand off — post a task to another tool's inbox (with an optional "doorbell").
It does not replace your repo, docs, or git — those stay the source of truth. aionai just holds the live working state and hands each tool the slice it needs.
Most portable — works on Windows, macOS, and Linux, and puts the aionai command
where GUI apps (Cursor, Claude Desktop) can find it:
pipx install aionaiAlready use uv? Skip the install entirely:
uvx aionai --helpRequires Python 3.10+. If a client later reports the launcher (aionai / uvx)
"not recognized", see Troubleshooting.
Point each client at the aionai command. Give each client a distinct AIONAI_SOURCE
(so handoffs route correctly) and set AIONAI_SEGMENT to your project name.
Claude Code
claude mcp add aionai --env AIONAI_SOURCE=claude-code --env AIONAI_SEGMENT=myproject -- aionai
# or with uv: claude mcp add aionai --env AIONAI_SOURCE=claude-code -- uvx aionaiCursor — .cursor/mcp.json:
{
"mcpServers": {
"aionai": { "command": "aionai", "env": { "AIONAI_SOURCE": "cursor", "AIONAI_SEGMENT": "myproject" } }
}
}Claude Desktop — Settings → Developer → Edit Config:
{
"mcpServers": {
"aionai": { "command": "aionai", "env": { "AIONAI_SOURCE": "claude-desktop", "AIONAI_SEGMENT": "myproject" } }
}
}Restart the client after editing its config — MCP servers are launched (and their env read) when the client connects.
Add this to each tool's rules (CLAUDE.md, Cursor rules) so they do it reflexively:
Before working, call
context_pull(segment="myproject")and treat the result as the current truth. As you work,context_log(...)your decisions/changes/questions/tasks. When something is settled,context_resolve(id).
That's the whole loop: pull first, write back. Now open Cursor and it already knows what you and Claude decided — no paste.
State is organized by a dotted segment path whose first element is the project:
myproject # the whole project
myproject/backend # a layer
myproject/backend/auth # a workstreamPulling a parent includes all descendants. That one mechanism keeps an always-on space from turning into an undifferentiated blob.
tool | purpose |
| current working state + your inbox |
| append a decision/change/question/task/note |
| close a question or task |
| full-text recall over history |
| check |
| post a handoff to another tool's inbox |
| build & manage the roadmap |
| see the tree / how far along |
| decisions + open questions that constrain a task |
| reuse an approach from another project |
They also surface as slash commands (/mcp__aionai__pull, …log, …resolve, …search,
…handoff) in clients that support MCP prompts.
Auto-ingest commits — copy hooks/post-commit into a repo's .git/hooks/
(set AIONAI_SEGMENT) and every commit logs itself as a change.
Doorbell — set AIONAI_DELIVERY=1 in a sender's env and a context_handoff to
Cursor also summons Cursor via its deeplink (you confirm before it runs). Without
it, handoffs are inbox-only. Only cursor has a verified deeplink today.
One SQLite database, one append-only table. Every decision, task, handoff, and
roadmap node is a row tagged with a segment and a type. History is free because
nothing is overwritten. Full-text search uses FTS5 with a LIKE fallback. The MCP
tools are thin wrappers over a plain-Python storage layer (src/aionai/store.py).
A client reports 'uvx' / 'aionai' is not recognized (or the server errors on start).
The client can't find the launcher on its PATH — common for GUI apps (Cursor, Claude
Desktop) on Windows and macOS, which don't always inherit your shell's PATH. Fixes,
best first:
Use pipx: pipx install aionai, then set "command": "aionai". pipx puts the
command where GUI apps usually find it.
Point at the full path of the launcher. Find it with where uvx (Windows) or
which uvx (macOS/Linux), then use it verbatim, e.g.:
"aionai": { "command": "C:/Users/you/AppData/Roaming/Python/Python3xx/Scripts/uvx.exe",
"args": ["aionai"], "env": { "AIONAI_SOURCE": "cursor" } }Skip the launcher — run via your Python directly (after pip install aionai):
"aionai": { "command": "python", "args": ["-m", "aionai.cli"] }Then restart the client so it re-reads the config.
var | default | purpose |
|
| database path (share explicitly if clients don't hit the default) |
|
| who is writing ( |
|
| default project segment |
| (unset) |
|
git clone https://github.com/imsm/aionai && cd aionai
pip install -e ".[dev]"
pytest
ruff check .Apache-2.0 © Ismail Saleh.
Before implementing a task, get every decision and open question that may CONSTRAIN it — from the task's segment, its ancestors, and its descendants (not recency-limited). Surface any conflict with your plan BEFORE coding.
| Name | Required | Description | Default |
|---|---|---|---|
| segment | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the tool's scope (segment, ancestors, descendants, not recency-limited) and that it surfaces conflicts. Without annotations, this gives a clear behavioral model. It omits potential side effects, but the description suggests it is read-only.
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?
Two sentences, both relevant and front-loaded. No extraneous information, every word earns its place.
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 minimal schema and no annotations, the description provides comprehensive context: purpose, usage, scope, and behavior. The output schema covers return format, so completeness is satisfied.
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 description adds full meaning to the single parameter 'segment' by explaining it is the starting point and that the tool expands to ancestors and descendants. This compensates for the 0% schema description coverage.
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 clearly states the tool retrieves all decisions and open questions that constrain a task, from the task's segment and its ancestors/descendants, with the purpose of surfacing conflicts before implementation. This differentiates it from sibling tools like context_pull which may provide general context.
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 advises using this tool 'before implementing a task' and 'before coding,' providing clear context for when to invoke it. It does not explicitly mention when not to use it, but the specificity implies it's for constraint discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a handoff to another tool's inbox (to = cursor | claude-code | claude-desktop). It lands in the target's inbox and stays PENDING until the receiver resolves it. If AION_DELIVERY is enabled and the target has a verified deeplink (today: cursor), a doorbell also summons that tool with a fixed nudge — the URL never carries your content. Returns the entry id and delivery outcome.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| refs | No | ||
| intent | No | notify | |
| content | Yes | ||
| segment | Yes |
| 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. It discloses that handoffs are PENDING until resolved, explains the AION_DELIVERY doorbell behavior, notes the URL never carries content, and states return values. It provides adequate behavioral context.
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 three sentences, each adding essential information: action+destination, state behavior, and delivery details. It is front-loaded with the core purpose and avoids any fluff.
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?
While the description covers the main workflow (handoff, pending, delivery, return), it omits parameter explanations for segment, refs, and intent. Given the tool has 5 parameters (3 required), this gap reduces completeness for an agent acting without further guidance.
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%, and the description only implicitly clarifies the 'to' parameter by listing targets. No explanation for 'segment', 'refs', 'intent', or 'content' parameters, leaving ambiguity for the agent.
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 clearly states the action ('Post a handoff') and the resource ('another tool's inbox'), with specific targets (cursor, claude-code, claude-desktop). This distinguishes it from sibling tools like context_log or context_search.
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 explains the behavior (pending state, delivery mechanism) but does not explicitly provide when to use this tool versus alternatives or when not to use it. The purpose is implied but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append an entry to the shared working state so other tools see it:
type = decision | change | question | task | note. refs is optional JSON
(e.g. {"files": ["..."], "commit": "abc123"}). Returns the new entry id.
Store WHAT/WHY (facts, decisions, intent), not HOW (procedure). A change is
"done" only when merged in git — include refs.commit/refs.pr; without a ref it
is recorded as a CLAIM (verify with context_verify).
| Name | Required | Description | Default |
|---|---|---|---|
| refs | No | ||
| type | Yes | ||
| content | Yes | ||
| segment | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return value (new entry id) and optional refs format. No annotations provided, but the description covers basic behavior. Lacks details on failure modes or 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?
Concise two-paragraph structure. No redundant sentences. Front-loaded with purpose and type details.
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 no annotations and 0% schema coverage, the description covers essential behavior, return value, and usage guidelines. Missing explanation for 'segment' parameter is a 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?
With 0% schema coverage, the description adds meaning for type (enum values) and refs (optional JSON with example). However, 'segment' is not explained, and 'content' is only implied.
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 clearly states 'Append an entry to the shared working state', using a specific verb and resource. It lists allowed types and distinguishes from sibling tools like context_search and context_verify.
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?
Provides explicit guidance on when to use (store WHAT/WHY, not HOW) and specific rules for the 'change' type (only mark done when merged). Does not explicitly exclude cases, but context from siblings helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull the current shared working state for a project segment (and its sub-segments). Call this FIRST, before doing anything on the project: it returns the open tasks, open questions, recent decisions/changes/notes, and your inbox of handoffs. Treat it as the current truth about where the work stands.
segment is a dotted path, e.g. "myproject" or "myproject/backend/auth"; a
parent pulls all descendants. Treat status entries ("fixed"/"done") as CLAIMS to
verify against git (see context_verify), not facts.
| Name | Required | Description | Default |
|---|---|---|---|
| segment | No | myproject |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses return content (open tasks, questions, decisions, inbox) and the segment behavior. Could be more explicit about being read-only, but the description implies no 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?
Two concise paragraphs. First covers purpose and usage, second covers parameter and caveat. Well-structured with no wasted words.
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 an output schema exists, the description appropriately summarizes return values. It provides necessary context among 11 siblings, including relationship with context_verify. Complete for the tool's complexity.
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% with no parameter descriptions, but the description fully explains 'segment' as a dotted path with examples and behavior (parent pulls descendants). This adds significant meaning 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 clearly states the tool pulls the current shared working state for a project segment, with a specific verb ('pull') and resource ('shared working state'). It distinguishes from siblings by advising to call it first and referencing context_verify.
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 'Call this FIRST, before doing anything on the project', providing clear when-to-use guidance. It also directs to use context_verify to verify status entries, giving an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an open question or task resolved so it stops surfacing in context_pull.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It mentions the effect on context_pull but does not disclose whether the entry is deleted, archived, or can be reopened. No information on permissions or idempotency.
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?
Single sentence, very concise. However, it omits necessary details, making the conciseness a trade-off with completeness.
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 one required parameter and an output schema (not shown), the description is minimally adequate for the purpose but lacks detail on parameter origin and behavioral consequences.
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 description does not explain the entry_id parameter. The agent must guess its meaning and how to obtain it. No value 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 clearly states the action (Mark resolved) and the resource (open question or task), and explains the effect (stops surfacing in context_pull). It effectively distinguishes from sibling tools like context_log or context_handoff.
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?
No guidance on when to use this tool versus alternatives like context_handoff or context_verify. No when-not or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search the project's history (decisions/changes/questions/notes) to recover past context. FTS5 does not stem — add a prefix wildcard (auth*) if a bare term seems too narrow.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| segment | No |
| 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 burden. It discloses that FTS5 does not stem and suggests adding a prefix wildcard, which is a helpful behavioral trait. It does not explicitly state that the tool is read-only or mention authorization needs, but for a search tool the read-only nature is implied and the tip adds value.
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 concise: two sentences, no redundant words. It front-loads the purpose and adds a useful usage note. Every sentence earns its place.
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?
The tool has an output schema (unknown content) and moderate complexity. The description covers the main purpose and a behavioral nuance, but fails to explain the segment parameter, which is a notable gap. It is mostly complete but missing a key detail.
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 provides a relevant tip about the query parameter (stemming/wildcards), but does not mention the segment parameter at all. For a 2-parameter tool, this is insufficient: one parameter is partially explained, the other is ignored.
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 clearly states it is a full-text search over project history (decisions/changes/questions/notes) to recover past context. The verb 'search' and resource 'project history' are specific. However, it does not explicitly differentiate from sibling tools like context_log or context_pull, though the function is distinct.
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 implies usage for recovering past context and provides a tip about FTS5 stemming and wildcards. However, it does not specify when not to use this tool or mention alternatives among siblings. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Completion integrity: list 'change' entries and classify each against GIT (the ground truth) — 'merged', 'present-unmerged', 'missing', or a bare 'CLAIM (no git ref)'. A tool logging "fixed" is NOT done; done = merged in git. Checks commits in the repo the server runs in.
| Name | Required | Description | Default |
|---|---|---|---|
| segment | No |
| 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 full burden. It discloses that the tool checks commits in the repo the server runs in and clarifies the classification scheme. The description implies a read-only operation without stating it explicitly, but no contradictions are present.
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 two sentences long, front-loaded with the main action and key details. Every sentence adds value, and no extraneous information is present.
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 the tool has one parameter that is not explained, contextual completeness is lacking. While an output schema exists (so return values need not be described), the missing parameter explanation is a gap. The description covers the main purpose and behavior but not the full parameter semantics.
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 one optional parameter 'segment' with 0% schema description coverage, meaning the schema provides no meaning. The description does not explain what 'segment' does or how it affects the listing/classification, leaving the agent without necessary context to set the parameter 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 clearly states the tool lists 'change' entries and classifies them against GIT (ground truth) using specific labels like 'merged', 'present-unmerged', 'missing', or 'CLAIM (no git ref)'. It distinguishes itself from sibling tools (e.g., context_log, context_pull) by focusing on verification/integrity checking.
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 guidance on when to use the tool, emphasizing that a tool logging 'fixed' is NOT done; done = merged in git. It implies the tool is used to verify completion status, though it doesn't explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reuse an approach from ANOTHER project: search that project's history for a topic and adapt the matching decisions/notes instead of starting from scratch. FTS5 does not stem — add a prefix wildcard (auth*) if a bare term is too narrow.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that FTS5 does not stem and advises on prefix wildcards, providing insight into search behavior. However, it does not mention read-only nature, error handling, or performance, so it is only moderately transparent.
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 two sentences: the first clearly states the purpose, and the second adds essential technical guidance. It is front-loaded, no redundant words, and every sentence adds value.
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 the tool has 2 required parameters, no annotations, and an output schema, the description covers the core purpose and a key technical detail. However, it lacks information on output expectations, error cases, or full parameter semantics, making it moderately complete but with noticeable gaps.
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%, yet the description only implicitly defines parameters: 'query' as the search topic and 'project' as the target project. It offers a hint about query format (wildcard) but lacks detail on project format (name/ID) or any constraints, insufficiently compensating for the schema gap.
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 clearly states the verb 'search' and the resource 'another project's history', and the purpose of reusing an approach. It distinguishes itself from siblings like 'context_search' by focusing on cross-project reuse, making the purpose specific and unambiguous.
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 a clear use case (reusing an approach from another project instead of starting from scratch) and a detailed technical hint about wildcard usage for FTS5. However, it does not explicitly state when not to use the tool or mention alternatives, though the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a node to the roadmap tree. kind = project | segment | phase | epic | task. parent_id nests under another node (0 = top-level); a child inherits its parent's segment unless set. priority is 1..5 (1 = highest; 0 = none). Returns the id.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| title | Yes | ||
| segment | No | ||
| priority | No | ||
| parent_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return value (the id), segment inheritance, and priority range. No annotations present so description does the job. Could mention validation (e.g., parent existence).
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?
Two concise sentences: first states purpose, second details key parameters. No unnecessary words.
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?
Covers main behavior and key parameters; return value specified. Lacks explanation of 'segment' and 'title' fields, but overall adequate for a node addition tool with no annotations.
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?
With 0% schema coverage, description compensates by explaining kind values, parent_id nesting, priority scale, and return value. Title and segment not fully described, but segment inheritance is noted.
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?
Clearly states 'Add a node to the roadmap tree' and enumerates valid kinds. Distinct from siblings like roadmap_view or roadmap_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?
Implies use for adding nodes; explains nesting with parent_id and segment inheritance. No explicit when-not or alternatives, but context from siblings is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a DEPENDENCY edge: node blocked_id is blocked by blocked_by_id. Use
this for real dependencies instead of overloading parent_id (parent_id =
decomposition). Surfaced in roadmap_view as a node's blocked_by.
| Name | Required | Description | Default |
|---|---|---|---|
| blocked_id | Yes | ||
| blocked_by_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the action and the effect in roadmap_view, but does not mention idempotency, error handling, or what happens if the dependency already exists. Minimal transparency beyond the core action.
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?
Two sentences include purpose, usage guidance, and view context. No wasted words, front-loaded with key action.
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?
Description is sufficient for a simple dependency creation tool with two required parameters. References parent_id for clarity and mentions output in roadmap_view. Does not discuss error cases or return values, but output schema likely covers that.
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 titles are minimal ('Blocked Id', 'Blocked By Id'), and description adds the relational meaning: 'node blocked_id is blocked by blocked_by_id' and clarifies it's a dependency edge. With 0% schema description coverage, this adds significant value.
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 clearly states the verb 'Record' and the resource 'DEPENDENCY edge', and distinguishes it from sibling tool behavior by explicitly saying not to overload parent_id.
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 tells when to use this tool ('for real dependencies instead of overloading parent_id') and provides context on how it surfaces in roadmap_view.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Progress summary: per top-level segment and overall, how many leaf work nodes are done vs total, with percentages.
| 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 full burden. It implies a read-only operation (no parameters, output schema) but does not explicitly state that it is non-destructive or disclose any behavioral traits like permissions or side effects. Adequate but not thorough.
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?
Single sentence, front-loaded with the key phrase 'Progress summary', and no wasteful words. Very concise.
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 no parameters and presence of output schema, the description covers the essential information: what the progress summary includes. It could specify scope (e.g., for all users), but overall sufficient.
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?
No parameters exist, so baseline is 4. The description adds no parameter info, which is acceptable since there are none.
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 clearly states the tool provides a progress summary for the roadmap, broken down per top-level segment and overall, with counts of done vs total leaf work nodes and percentages. This distinguishes it from siblings like roadmap_view or roadmap_add_node.
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?
No explicit guidance on when to use this tool versus alternatives. Sibling tools include roadmap_view, which might also show progress, but no differentiation is provided. Implicitly, it is the go-to for summary stats, but not clarified when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a roadmap node: set priority (1..5), reparent (parent_id), or set status ('open'/'resolved'). Pass only what you want to change (0/empty = leave as is). Resolving a task/epic is what makes progress roll up.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| entry_id | Yes | ||
| priority | No | ||
| parent_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that resolving triggers progress roll-up and that zero/empty values leave fields unchanged. No contradictions with annotations since none exist.
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 extremely concise with two sentences. The first sentence front-loads the main action and parameters, and the second provides critical usage guidance. Every word earns its place.
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 an output schema exists (so return values are documented elsewhere) and there are only 4 simple parameters with no nested objects, the description covers the essential behavior: what fields can be updated, how to partially update, and a key side effect (progress roll-up). It could mention error handling or validation, but overall it's sufficiently 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 0%, so the description must compensate. It adds meaningful context by specifying valid ranges for priority (1..5) and status ('open'/'resolved'), and explaining the reparenting action. However, it does not describe the default values or the required entry_id parameter explicitly.
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 clearly states the verb 'Update' and the resource 'roadmap node', and lists specific actions (set priority, reparent, set status). It distinguishes from sibling tools like roadmap_add_node (add) and roadmap_view (view), making the purpose unambiguous.
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 instructs 'Pass only what you want to change (0/empty = leave as is)', which is key usage guidance. However, it does not explicitly mention when not to use this tool or suggest alternatives, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the hierarchical roadmap (project > segment > phase > epic > task) with done/total rollup per node, sorted by priority. Optionally scope to a segment.
| Name | Required | Description | Default |
|---|---|---|---|
| segment | No |
| 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 full burden. It describes the output (rollup, sorting) but does not explicitly state the tool is read-only or disclose any side effects, prerequisites, or behavior when the optional segment parameter is omitted. Adequate but lacks some transparency.
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, well-structured sentence that front-loads the core purpose. Every part contributes essential information; no wasted words.
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 the tool's simplicity (one optional parameter, output schema exists), the description covers the main functionality and parameter. The hierarchical structure and rollup are clearly described, making the tool's purpose and usage fully understandable without needing additional context.
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 schema has 0% description coverage, so the description must compensate. It explains 'segment' as an optional scope filter, which adds meaning beyond the schema's empty description. However, it does not specify the expected format or source of segment values, leaving some ambiguity for the agent.
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 clearly states the action ('Show'), the resource ('hierarchical roadmap'), and the specific hierarchy levels and features (rollup, sorted by priority, optional scope to segment). It effectively distinguishes this tool from sibling tools like 'roadmap_add_node', which are for modification.
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 implies when to use (viewing roadmap) and mentions the optional scoping, but does not explicitly exclude cases or contrast with alternatives. Since this is a straightforward reader tool, the guidance is sufficient but could be clearer for an agent to differentiate from other roadmap tools.
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.0constraints_for_taskcontext_handoffcontext_logcontext_pullcontext_resolvecontext_searchcontext_verifyproject_lookuproadmap_add_noderoadmap_blockroadmap_progressroadmap_updateroadmap_viewScored across 13 tools
Tools are grouped into context management and roadmap management, each with distinct purposes. Minor overlap between context_search and project_lookup (both search but in different scopes) prevents a perfect score.
All 13 tools follow a consistent verb_noun snake_case pattern (e.g., constraints_for_task, context_log, roadmap_view), making tool purposes predictable.
With 13 tools covering two sub-domains (context and roadmap), the count is well-scoped. Each tool has a clear role without unnecessary redundancy.
The surface covers core CRUD operations for roadmap (add, update, view, block, progress) but lacks explicit delete for nodes. Context tools are comprehensive, including search, verify, and cross-project lookup. Minor gap in deletion.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
