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 "Install 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?
With no annotations, the description carries full burden. It discloses scope (ancestors, descendants, not recency-limited) and the conflict surface behavior, but lacks details on permissions, side effects, or output format.
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 short sentences, front-loaded with purpose, no redundant information. Every word 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?
Despite 1 param and output schema present, the description sufficiently explains the tool's role. Could mention the output format more explicitly, but output schema likely covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'segment' is fully explained in context via the description (task's segment, related constraints), compensating for 0% schema 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 verb 'get' and the resource 'decisions and open questions that constrain the task', and specifies the scope (segment, ancestors, descendants). It distinguishes from sibling context tools by focusing on constraints.
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 timing ('Before implementing a task', 'BEFORE coding') but does not specify when not to use or list alternatives beyond implied sibling tools.
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?
No annotations provided, so description carries full burden. Discloses that entries are appended to shared state, returns id, and that changes without refs are recorded as CLAIMs for verification. Does not describe any destructive or permission-related behavior.
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 paragraphs, relatively concise. First paragraph covers purpose and type details, second provides usage guidance. Could be more structured but no unnecessary sentences.
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 key aspects: purpose, types, refs usage, and behavioral guidance for changes. Lacks explanation of 'segment' parameter and does not detail output beyond returning id (output schema exists). Adequate for a logging tool in a context suite.
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 has 0% description coverage. Description explains 'type' (allowed values) and 'refs' (format and optionality), but 'segment' is left unexplained despite being required. Partially compensates for missing schema descriptions but not fully.
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 appends an entry to shared working state, specifies allowed types (decision, change, question, task, note), and mentions it returns the entry id. This distinguishes it from sibling tools like context_search or 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 guidance to store WHAT/WHY not HOW, and notes that a 'change' is 'done' only when merged in git. Implicitly distinguishes from siblings but lacks explicit when-to-use or when-not-to-use criteria.
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?
With no annotations provided, the description carries full burden. It only says 'mark resolved' and 'stops surfacing', but does not disclose side effects (e.g., irreversibility, permission requirements, or state changes beyond surfacing).
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 short sentence that is front-loaded and efficient. However, given the lack of parameter guidance, it could be slightly expanded without losing conciseness.
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 tool with one required parameter, no annotations, and an output schema (unknown content), the description lacks critical details: what the output looks like, whether the action is reversible, and how to interpret 'resolve'. This makes it incomplete for confident use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not mention the parameter 'entry_id' at all. The agent has no guidance on what value to provide, its format, or how to obtain it. This severely undermines correct invocation.
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 ('mark resolved'), the resource ('open question or task'), and the effect ('stops surfacing in context_pull'). It distinguishes this tool from siblings like context_search or context_log, which have different purposes.
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 (when a question/task is resolved), but does not provide explicit when-not-to-use guidance or mention alternatives like context_verify. No prerequisites are stated.
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?
The description discloses that FTS5 does not stem, which is a behavioral trait. However, without annotations, it does not explicitly confirm read-only nature, required permissions, or other side effects. The description carries the full burden but adds only basic 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 two sentences, front-loaded with the primary action, and includes a concise usage tip. No filler or redundant information.
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 description covers the main use case and provides a behavioral note, but omits explanation of the 'segment' parameter, potential errors, or output specifics. Since an output schema exists, some return information may be covered there, but the description alone is moderately incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only elaborates on the 'query' parameter with a usage tip. The 'segment' parameter is not mentioned at all, leaving its meaning unclear despite the low 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 performs full-text search on the project's history to recover past context, with specific resources (decisions/changes/questions/notes). This distinguishes it from sibling tools like context_handoff or context_resolve which handle different operations.
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 is provided on when to use this tool versus siblings. The description only offers a search tip about wildcards but does not compare to alternatives or state prerequisites.
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?
Discloses that it checks commits in the server's repo and lists classification categories ('merged', 'present-unmerged', etc.). No annotations exist, so description carries full burden; it is adequately 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?
Three sentences, front-loaded with the core action. Every sentence adds value, though the parameter gap detracts from efficiency.
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 purpose, classification, and git integration. However, missing parameter explanation for 'segment' leaves the description incomplete for a tool with one parameter.
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?
Description does not mention the 'segment' parameter at all. Schema description coverage is 0%, and the description offers no meaning beyond the schema, leaving the agent guessing about its purpose.
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?
Description clearly states 'list and classify change entries against GIT', specifying verb and resource. Differentiates from siblings by focusing on git-based completion integrity, though not explicitly contrasting with similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implicit usage context by stating that logging 'fixed' is insufficient; done means merged. However, no explicit when-to-use or alternatives are given.
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, the description adds value by revealing FTS5's stemming limitation and the need for prefix wildcards. However, it does not disclose other behavioral aspects like authentication requirements, rate limits, or behavior on missing projects.
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, efficiently conveying the core purpose and a vital usage tip. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description adequately covers the tool's purpose and a key technical detail. It could mention the output format (past decisions/notes) but is sufficient for an agent to use the tool.
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 two parameters with 0% description coverage. The description adds context about the query needing prefix wildcards and the project being a target project, but does not fully explain each parameter's format or constraints.
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 purpose: to reuse an approach from another project by searching its history. It distinguishes itself by focusing on external project reuse, unlike sibling tools like context_search which operate on current 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 when to use the tool (reusing approaches) and provides a technical tip about prefix wildcards due to FTS5 stemming behavior. However, it does not mention when not to use it or explicitly compare to sibling tools.
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?
With no annotations, the description must disclose behavioral traits. It explains that children inherit segment from parent unless set, priority range, and return value. However, it omits validation behavior (e.g., invalid kind, non-existent parent_id), side effects (e.g., tree reordering), and authorization or rate limiting. Adequate but incomplete.
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 perfectly front-loaded. First sentence states core purpose. Second sentence efficiently packs all parameter details and return value. No fluff, 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 no output schema shown, description covers return (id). Input schema is well covered except title. The tree structure context (nesting, inheritance) is explained. Missing edge cases (e.g., top-level without segment) but overall complete for typical use. Sibling tools exist but not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It explains kind (lists values), parent_id (nesting, 0=top-level, inheritance), priority (1-5, 0=none). These add significant meaning beyond the schema. However, the required 'title' parameter is not described at all, leaving a 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 'Add a node to the roadmap tree', with a specific verb and resource. It enumerates the allowed kind values (project, segment, phase, epic, task), which distinguishes it from other tools like roadmap_update or roadmap_view. No ambiguity about what the tool does.
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 (to add a new node) but does not explicitly contrast with alternatives like roadmap_update or roadmap_block. There is no guidance on prerequisites (e.g., roadmap must exist) or when not to use. The sibling tools are listed but not referenced.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the action but omits details on idempotency, side effects, error conditions, or authorization requirements. For a write operation, more transparency is needed.
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 with no redundant information. The critical action and context are front-loaded, and every word serves a purpose. Ideal conciseness.
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 low complexity (2 parameters, no annotations, output schema exists), the description covers the essential purpose and usage distinction. It omits nothing critical for selection, though behavioral details are sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds context that blocked_id is the node that gets blocked and blocked_by_id is the blocker. However, it does not specify expected formats or ranges, leaving some ambiguity.
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 records a dependency edge, specifying the two node IDs involved. It distinguishes this tool from overloading parent_id for decomposition, which is a common alternative use case. The purpose is 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 explicitly advises using this tool for real dependencies instead of misusing parent_id for dependencies. It also notes the effect is surfaced in roadmap_view as blocked_by. However, it does not explicitly state when not to use it or mention sibling tools as alternatives.
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?
The description discloses the core behavior: it calculates done vs total for leaf work nodes per segment and overall, with percentages. Since no annotations are provided, the description carries the full burden, and it adequately explains the output without contradictions.
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 concise sentence that front-loads the key information: type of summary, granularity, and metrics. Every part earns its place with no waste.
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 tool with no parameters and an output schema (existing but not shown), the description covers the essential purpose and logic. It could be improved by defining 'leaf work nodes' or 'top-level segments,' but it is still adequate.
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?
There are no parameters, so baseline is 4. The description adds context by specifying the scope (top-level segments and overall) and what is counted (leaf work nodes), which is meaningful beyond the empty 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 it provides a progress summary for top-level segments and overall, counting leaf work nodes done vs total with percentages. This is a specific verb and resource, and it distinguishes from sibling tools that focus on adding, updating, or viewing the roadmap itself.
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 obtaining progress summaries but does not provide explicit guidance on when to use this tool versus alternatives, such as roadmap_view for full details. No exclusions or when-not scenarios are mentioned.
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, the description adds valuable behavioral context: it reveals that setting status to 'resolved' triggers progress roll-up and that default values (0 or empty) leave fields unchanged. It does not cover permissions, reversibility, or error handling, which is acceptable for a simple update but could be more 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?
The description consists of two efficient sentences. The first lists updatable fields and their constraints, the second clarifies partial update behavior and the effect of resolving. Every sentence contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not detail return values. It adequately covers the three optional parameters and the behavioral effect of resolving. However, it omits validation details (e.g., out-of-range priority) and does not mention error conditions, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining the meaning and allowed values for priority (1..5), parent_id, and status ('open'/'resolved'). It clarifies that 0/empty means 'leave as is', adding meaning beyond the schema's type and title. The required entry_id is obvious and not mentioned.
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 identifies the tool as updating a roadmap node with specific fields (priority, parent_id, status). It explicitly lists the allowed values and differentiates from sibling tools like roadmap_add_node (creation) and roadmap_view (reading).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on partial updates ('Pass only what you want to change') and hints at the impact of resolving a node. However, it does not explicitly compare with alternative tools like roadmap_progress or roadmap_block, nor does it state when not to use this tool.
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 bears full burden. It mentions the tool shows a hierarchical view with rollup and optional scoping, but does not disclose any side effects, authentication needs, or rate limits. The verb 'Show' suggests read-only, but not stated explicitly.
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 with no wasted words. It front-loads the main action and structure immediately, 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 output schema exists, the description does not need to explain return values. It covers the key features: hierarchy, rollup, sorting, and optional filtering. It is complete enough for an agent to understand the tool's functionality.
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 parameter 'segment' with 0% coverage. The description adds meaning by stating 'Optionally scope to a segment,' clarifying the parameter's purpose and filling the gap left by 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 shows a hierarchical roadmap with specific levels (project > segment > phase > epic > task) and includes rollup and sorting by priority. It distinguishes itself from sibling tools like roadmap_add_node and roadmap_progress, which modify the roadmap.
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 this tool is for viewing the roadmap, not modifying it, which differentiates it from siblings like roadmap_update. However, it does not explicitly state when to use or not use this tool, but the context of siblings and the verb 'Show' provide adequate guidance.
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. Dates show when Glama detected each change.
v0.1.0constraints_for_taskcontext_handoffcontext_logcontext_pullcontext_resolvecontext_searchcontext_verifyproject_lookuproadmap_add_noderoadmap_blockroadmap_progressroadmap_updateroadmap_viewTools 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ismailelsaleh/aionai'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
