This server is a passive coordination ledger for coding agents, letting them share plan revisions, task ownership, work progress, and session metadata without executing code or verifying real-world outcomes.
Join a project with an explicit session identity, optional parent session, and repository information, then receive a compact status snapshot with map recovery hints.
Publish a complete task plan using an expected revision to ensure coordinated updates.
Atomically add or update plan tasks through operations (e.g., add task) with revision checks.
Record that a session explicitly observed a particular plan revision (acknowledgment).
Read a full plan revision or compare two revisions to get differences without full maps.
Claim ownership of a task or record a delegated contribution from another session, with revision validation.
Report progress on work, release a task, or hand work off to another session, all atomically.
Fetch a compact status of all current work records, optionally including the full task map and all records.
Query work history by task, session, path, branch, or commit to find recorded efforts and their past states.
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., "@vibecheck log my current task and work location"
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.
Vibecheck is a passive MCP work ledger for coding agents. It records a shared task plan, session ancestry, claims, work locations, blockers, and commits in SQLite. Agents report changes through nine tools. The board does not run agents, schedule work, execute Git commands, or verify that reported work happened.
This repository contains the TypeScript implementation, version 1.0.1. The Python implementation is archived separately at mgd34msu/vibecheck-python.
Use a Codex or Claude Code client with native plugin support. Install Bash and either Bun 1.3.14 or later or Node.js 24 or later. The launcher supports Linux, macOS, and Windows through WSL. No Python installation is required.
For Codex, install the tagged marketplace:
codex plugin marketplace add mgd34msu/vibecheck --ref v1.0.1
codex plugin add vibecheck@vibecheckFor Claude Code:
claude plugin marketplace add mgd34msu/vibecheck@v1.0.1
claude plugin install vibecheck@vibecheckThese commands select the v1.0.1 Git tag. Enable the plugin in your client and reload the session if the tools do not appear. The plugin registers its MCP server and supplies a shared vibecheck skill. There are no startup hooks that register projects or force the skill to run on every first turn.
Ask the agent to use Vibecheck to report its current work or recover an earlier plan. Supply a stable project ID and repository identity. For a standing project policy, copy the agent instructions into your project's AGENTS.md.
Both native plugins include the same compiled runtime/vibecheck.mjs bundle and skill. The launcher selects Bun when available, then Node.js. Set VIBECHECK_RUNTIME=bun or VIBECHECK_RUNTIME=node to select one explicitly. Plugin startup does not install dependencies or write inside the plugin directory.
The bundle includes its dependency license notices in runtime/THIRD-PARTY-NOTICES.txt.
Both native plugins use the same server and skill. Their local stdio processes share the default database, so using both clients on one machine does not create separate boards.
Related MCP server: CodeLedger
From a source checkout with locked dependencies installed, run:
bun run build:release
bun run verify:releaseThe build requires Bun, zip, and tar. It refreshes the bundled runtime and writes these files in artifacts/:
vibecheck-codex-plugin-1.0.1.zip, the Codex plugin bundle.
vibecheck-claude-plugin-1.0.1.zip, the Claude plugin bundle.
vibecheck-runtime-1.0.1.tar.gz, the standalone bundled runtime.
SHA256SUMS, checksums for the release artifacts.
Verify downloaded artifacts against SHA256SUMS with your platform's SHA-256 utility. Each plugin archive extracts into a vibecheck directory with its native manifest and marketplace catalog. For an extracted Codex archive, register that directory and install:
codex plugin marketplace add /absolute/path/to/vibecheck
codex plugin add vibecheck@vibecheckFor an extracted Claude archive:
claude plugin marketplace add /absolute/path/to/vibecheck
claude plugin install vibecheck@vibecheckChoose either the GitHub marketplace or the extracted local marketplace for a client. Keep a local marketplace directory available for subsequent plugin management. See release notes for publication status.
Install Bun 1.3.14 or later, then run:
git clone https://github.com/mgd34msu/vibecheck.git
cd vibecheck
bun install --frozen-lockfile
bun src/cli.ts --version
bun src/cli.tsBun runs the TypeScript source directly. To run compiled JavaScript with Node.js 24 or later, build it first:
bun run build
node dist/cli.js --version
node dist/cli.jsThe package name is @mgd34msu/vibecheck. It is not published to the npm registry. The package declares both vibecheck and project-board commands for the same CLI.
The default transport is stdio. The process waits for an MCP client, so a quiet terminal is expected. Stop it with Ctrl-C when configuring your client.
Use an absolute path to scripts/run-server.sh as your client's MCP command. Copy examples/mcp.json and replace the example paths. Put its command, arguments, and environment into your client's supported MCP configuration format.
All local clients must use the same absolute database path to share a board. Each client may start its own stdio process. Keep SQLite on local disk; use the HTTP server below for clients on different machines. Do not put the database on a network share.
The default database is $XDG_DATA_HOME/project-board/board.sqlite3, or $HOME/.local/share/project-board/board.sqlite3 when XDG_DATA_HOME is unset. Set PROJECT_BOARD_DB or pass --database to choose another file. The existing PROJECT_BOARD_* environment variables remain unchanged.
Run the server on the machine that holds the local SQLite file:
read -rsp 'Board bearer token: ' PROJECT_BOARD_TOKEN
printf '\n'
export PROJECT_BOARD_TOKEN
export PROJECT_BOARD_DB="$HOME/.local/share/project-board/board.sqlite3"
export PROJECT_BOARD_PROJECTS='my-project'
bun src/cli.ts --transport streamable-http --host 127.0.0.1 --port 8765For compiled Node.js, replace bun src/cli.ts with node dist/cli.js after building.
Connect an MCP client to http://127.0.0.1:8765/mcp with the header Authorization: Bearer <your token>. The server requires a token even on loopback. For remote clients, provide HTTPS through your existing reverse proxy and pass --allowed-host for its public host. Keep the SQLite file on the server's local disk.
PROJECT_BOARD_PROJECTS restricts both transports to the listed comma-separated project IDs. Leave it unset to allow all projects. A configured empty list fails startup. The HTTP token grants access to the configured projects; it does not identify individual agents. Local stdio trusts its caller, and session identities are cooperative self-reports.
Keep the database outside plugin caches. The default XDG data path and any custom PROJECT_BOARD_DB path remain under your control. Plugin replacement or removal does not delete ledger data. The board does not create backups.
Pinned marketplace installations stay tied to the selected release. Select the desired release when upgrading. Remove the Claude plugin with claude plugin uninstall vibecheck@vibecheck; remove the Codex plugin with codex plugin remove vibecheck@vibecheck.
Tool | Purpose |
| Register or rejoin a project session with real identity and ancestry. |
| Publish the root's complete task inventory. |
| Atomically add or update task definitions, dependencies, and lineage. |
| Retrieve a complete plan revision or compare two revisions. |
| Record a session's review of a complete plan revision. |
| Claim ownership or contribute under a parent's work. |
| Report progress, blockers, integration, release, or handoff. |
| Read compact current state or explicit complete current state. |
| Recover work by task, session, path, branch, or commit. |
Copy the agent instructions into the project's AGENTS.md. Give every agent the same project ID and repository identity. The first project_join registers that project. Starting the server does not create projects or infer them from its working directory. The root owns and updates the shared plan. Workers claim existing tasks or contribute under their parent's work.
The following examples show MCP tools/call parameters. Replace values such as REAL_VENDOR_SESSION_ID, SESSION_ID, and WORK_ID with real runtime identities and IDs returned by the board. Model and effort strings are opaque metadata; use the actual configured values. Revisions below illustrate a fresh board. Always use returned revisions in real calls.
Join the project and retain the returned session_id and complete task_map from its snapshot. If the map is omitted for size, retrieve it with plan_read:
{
"name": "project_join",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "join-1",
"repository": "https://example.com/team/repository.git",
"vendor": "ACTUAL_VENDOR",
"runtime": "ACTUAL_RUNTIME",
"external_session_id": "REAL_VENDOR_SESSION_ID",
"model": "ACTUAL_MODEL",
"effort": "ACTUAL_EFFORT"
}
}
}Publish the root's task plan:
{
"name": "plan_publish",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "plan-1",
"session_id": "SESSION_ID",
"expected_revision": 0,
"tasks": [
{ "id": "implement", "label": "Implement the change", "depends_on": [] }
]
}
}
}Claim the task with its current task revision:
{
"name": "work_claim",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "claim-1",
"session_id": "SESSION_ID",
"task_id": "implement",
"expected_revision": 1,
"location": {
"checkout": "/absolute/path/to/checkout",
"branch": "feature/change",
"target_branch": "main",
"paths": ["src/change.ts"]
}
}
}
}Report a blocker using the work and task revisions returned by the claim:
{
"name": "work_update",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "blocked-1",
"session_id": "SESSION_ID",
"updates": [
{
"work_id": "WORK_ID",
"expected_revision": 1,
"expected_task_revision": 2,
"status": "blocked",
"blocker": "Waiting for the test fixture"
}
]
}
}
}Read the shared status with one call:
{
"name": "project_status",
"arguments": { "request": { "project_id": "my-project" } }
}Find the task's work attempts and history:
{
"name": "work_history",
"arguments": {
"request": { "project_id": "my-project", "task_id": "implement" }
}
}At natural work boundaries, read project_status with your known_plan_revision. The response contains fresh operational facts keyed by stable task, work, and session IDs. Reuse the shared definition map instead of repeating the graph on every read. Normal status needs no cursor or page assembly.
Normal status includes active, owned pending, and blocked tasks, work awaiting integration, available unowned pending tasks, and tasks with open contributions. Its complete structured JSON response has a 64 KiB UTF-8 budget. Counts disclose the scope and any omissions. If limited is true, full:true retrieves all current tasks, current owners, open contributors, all registered sessions, and the complete map. Full status includes no work history.
To recover a lost map, request include_map:true. A stale known_plan_revision sets map_changed:true and requests a replacement map automatically. Maps are all-or-omitted. If map_omitted is true, follow full_hint with full:true, or use plan_read for the complete definitions alone.
Edit part of the plan atomically without resending its inventory:
{
"name": "plan_edit",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "edit-1",
"session_id": "SESSION_ID",
"expected_revision": 1,
"operations": [
{
"op": "update",
"task_id": "implement",
"label": "Implement and verify the change"
},
{
"op": "add",
"task": {
"id": "review",
"label": "Review the change",
"depends_on": ["implement"]
}
}
]
}
}
}Read a complete definition map at a particular revision. Add compare_to to request a diff instead of the map:
{
"name": "plan_read",
"arguments": { "request": { "project_id": "my-project", "revision": 2 } }
}Only after receiving and reviewing the complete map, acknowledge that revision:
{
"name": "plan_ack",
"arguments": {
"request": {
"project_id": "my-project",
"request_id": "ack-2",
"session_id": "SESSION_ID",
"plan_revision": 2
}
}
}The root can change dependencies during work. Each edit validates the resulting graph and retains older definitions in revision history. Optional supersedes links record splits or replacements; they do not transfer work or cancel tasks. Acknowledgments record which complete revision each session has reviewed. Reads never acknowledge automatically.
For field rules, retries, handoffs, advanced cursor reads, and history selectors, see the protocol reference. Status and timestamps describe the latest report, which may be stale. A successful database claim does not prevent another process from editing or committing the same Git files.
Install the locked dependencies, then run verification:
bun install --frozen-lockfile
bun run verifyThe verification command checks formatting, strict types, forbidden assertions, and bundled runtime freshness. It runs the behavior tests under Bun and compiled JavaScript under Node.js, then builds the package. Node.js 24 or later is required for the Node tests. After changing runtime source or dependencies, run bun run build:release to refresh the committed bundle before verification.
The release passes 127 tests on Bun 1.3.14, Node.js 24.0.0, and Node.js 26.1.0. A frozen 995-case validation corpus and imported SQLite fixtures check compatibility with the Python implementation, including historical records and saved retry responses. The TypeScript compiler is version 7.0.2. A development-only TypeScript 6 compiler API parses source for the forbidden-type checks.
The implementation derives domain types from input schemas. Boundary validation rejects invalid external data before business logic runs. Authored TypeScript uses no any, type assertions, non-null assertions, or compiler suppression comments. SQLite uses the runtime's built-in bun:sqlite or node:sqlite adapter.
See release notes for the release contents and verification status.
The board retains reported metadata, not repository knowledge or conversations. It does not scan the repository to understand code. Session identities and work status are cooperative self-reports; Git commits and actual outcomes require separate verification. Dependencies and blocking_path describe the graph without scheduling work or estimating completion time.
Record the plan revision this session explicitly observed.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and readOnlyHint=false, covering the write-but-idempotent behavior. The description adds the nuance that recording is based on explicit observation, but it does not disclose side effects, duplicate handling, or what happens when the revision is already recorded.
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 sentence, front-loaded with the core verb and object, and every word carries meaning. There is no filler or redundant restatement of the tool name.
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?
With no output schema and a nested input schema at 0% description coverage, an agent only learns the general intent. It cannot confidently fill project_id/request_id or understand the acknowledgment semantics beyond what the annotations imply, making the description under-specified 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 description coverage is 0%, so the description must compensate. It maps 'session' to session_id and 'plan revision' to plan_revision, but leaves project_id and request_id entirely unaddressed. For a nested required object with four fields, this is insufficient for an agent to confidently construct the request.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and resource ('plan revision'), with the scope 'this session explicitly observed'. This distinguishes it from obvious siblings: plan_read reads, plan_edit/plan_publish modify or publish, while plan_ack records an observation. However, it doesn't explicitly name the distinction with siblings.
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 phrase 'this session explicitly observed' implies the appropriate trigger: use when the current session has actually observed a plan revision. It does not name alternative tools or state when not to use it, leaving the agent to infer based on sibling names and general context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically add or update plan tasks using the coordinator's expected revision.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that the tool is mutating, idempotent, and non-destructive. The description adds meaningful behavioral context by stating atomicity and the expected-revision concurrency control. It does not describe failure behavior on revision mismatch, but the core safety profile is already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the core operation front-loaded and no filler. It communicates atomicity, the action, the resource, and the concurrency expectation efficiently.
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 complex nested mutation tool, the description lacks explicit guidance on when to invoke it instead of plan_publish or plan_ack, and what happens if expected_revision is stale. However, the rich input schema and idempotent/non-destructive annotations cover much of the invocation detail, so the gaps are meaningful but not catastrophic.
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 carries the burden of explaining parameters, but it only clarifies expected_revision and the general add/update operation. It does not explain project_id, request_id, session_id, or the task field semantics beyond what the schema constraints already show. Most parameter meaning must be derived from names and schema structure.
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 operation (atomically add or update plan tasks) and the key constraint (coordinator's expected revision). It is specific about the resource and action, but it does not explicitly distinguish itself from sibling tools such as plan_publish or plan_ack beyond the 'edit' in the name.
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 given about when to use this tool versus alternatives like plan_publish, plan_ack, or plan_read. The description does not mention prerequisites, the role of the session, or what to do if the expected revision does not match. The agent must infer usage context from the schema and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish the coordinator's complete task plan using its expected revision.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read, idempotent, non-destructive operation. The description adds little beyond 'using its expected revision,' which hints at optimistic concurrency but does not explain what happens on a revision mismatch, whether the whole plan is replaced, or what other side effects publishing may have.
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 one short sentence with no filler and front-loads the core action. While it is terse, every word contributes meaning; it simply leaves important behavioral detail unstated.
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 nested, concurrency-sensitive publish operation with no output schema, this description is under-specified. An agent cannot determine the effect of calling it with an outdated expected_revision, whether tasks fully replace existing ones, or how the identifiers connect to a previously read plan.
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, but it only maps to two of the nested fields: 'complete task plan' hints at tasks, and 'expected revision' maps directly to expected_revision. The outer request object and fields like project_id, request_id, session_id, status, depends_on, and supersedes remain unexplained.
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 names a specific action ('publish') and a clear resource ('the coordinator's complete task plan'). It also highlights the concurrency key, 'using its expected revision,' which helps distinguish this from sibling plan tools. It could be stronger by explicitly contrasting with plan_edit or plan_read, but the purpose is clear.
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 offers no guidance on when to use plan_publish versus plan_edit, plan_ack, or plan_read. It does not state prerequisites, such as first reading the current plan to obtain expected_revision, nor does it explain the failure behavior if the revision does not match.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a complete plan revision, or use compare_to for differences without full maps.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a read-only operation, and the description confirms this with 'Read'. No additional behavioral details (e.g., side effects, rate limits) are provided, but the annotation covers the key aspect.
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, focused sentence that conveys the core functionality and a key alternative without any redundant or tangential 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 does not explain what a 'plan revision' is, what the return value looks like (no output schema), or the default behavior when 'revision' is omitted. It also leaves the 'compare_to' parameter undefined. This lack of context may cause an agent to misuse 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 a nested 'request' object with project_id, revision, and compare_to, but the description provides no explanation of these parameters. The only mention is 'compare_to' in a usage context, but its semantics (e.g., what values it accepts, what it does) are undefined. Schema coverage is 0%, and the description does not compensate.
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 reads a complete plan revision, and explicitly mentions the compare_to option for differences. It uses a specific verb and resource, making the tool's 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 provides guidance on when to use compare_to instead of reading the full plan, though it doesn't explicitly contrast with sibling tools. The guidance is implicit but useful for selecting the appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Join with explicit session identity and optional parent; return compact status with map recovery.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the description's job is to add context. It adds only that the tool returns a 'compact status with map recovery,' which is vague and does not clarify side effects, persistence, or authorization requirements. No contradiction with annotations, but the behavioral insight is minimal.
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 compact sentence with no filler. It front-loads the main action ('Join') and then mentions the return behavior. Some terms are cryptic ('map recovery'), but structurally it is efficient and avoids 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?
This tool has a complex nested request object with seven required sub-fields, yet no output schema exists and the description does not explain most of these fields or the meaning of 'map recovery.' The lack of usage context, side-effect details, and parameter semantics leaves the definition incomplete for an agent to invoke it confidently.
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 for the nested request object and its many required fields. The description only hints at two concepts: 'explicit session identity' (likely external_session_id) and 'optional parent' (likely parent_session_id). It does not explain required fields like repository, vendor, runtime, model, or request_id, nor optional fields like effort or take_over_from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Join') and a resource ('session'), which gives some direction, but the meaning is vague: 'Join' could mean joining a project, a session, or a workspace. 'return compact status with map recovery' is jargon that is not explained and does not clearly distinguish this from sibling tools like work_claim or project_status.
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?
There is no guidance on when to use this tool versus the sibling tools. The description implies a use case ('Join with explicit session identity') but does not mention alternatives, prerequisites, or exclusions. An agent cannot tell whether this is the right tool for session initialization, reconnection, or something else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read compact current work; full includes all current records and the task map.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, matching the 'Read' verb. The description adds a small behavioral detail: full mode includes all current records and the task map. However, it does not disclose behaviors like default limits, pagination, or the meaning of 'since' or 'known_plan_revision'.
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 sentence with no filler and is reasonably front-loaded. However, the phrasing 'compact current work' is slightly awkward and could be clearer, so it loses a point for structural clarity.
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 nested parameter object, abundant optional parameters, and absence of an output schema, the description is far too terse. It does not explain request construction, output shape, or the semantics of key parameters like since and known_plan_revision, leaving the agent under-informed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds some meaning for the 'full' concept and hints at 'task map' (likely include_map), but it does not explain the outer 'request' object or parameters like limit, since, task_ids, and known_plan_revision. This is insufficient for the schema's nested structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and names a resource ('current work'), and distinguishes compact vs full outputs. It is clear about the tool's fundamental purpose, though it does not explicitly differentiate it from sibling tools like plan_read or work_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It only contrasts compact and full modes within the tool itself, leaving the agent to infer the appropriate context relative to plan_read, work_history, or project_join.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim task ownership or record a delegated contribution with a revision check.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds a meaningful behavioral detail: it performs a revision check, implying the operation validates expected_revision and likely fails if the revision doesn't match. 'Record a delegated contribution' also suggests it can create a work record on behalf of someone, adding nuance beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads both core actions and the revision-check behavior. No filler, but the dual-purpose wording ('claim' or 'record delegated contribution') creates slight ambiguity that could have been unpacked in a second sentence.
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 a nested request object with seven fields, no output schema, and no per-parameter documentation; the description gives only a high-level purpose. It is adequate for an agent to guess the main intent, but missing details about location, parent_work_id, replace_work_id, and what the response returns make it incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It only clarifies expected_revision ('revision check') and hints at the request object's purpose. The nested request object and fields like location, parent_work_id, replace_work_id remain unexplained, so the description does not fully compensate 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 says 'Claim task ownership or record a delegated contribution with a revision check' — it names a verb and resource, but it's ambiguous whether this is two separate operations (claim vs. delegate) in one tool. Among siblings like work_update and work_history, it does not clearly distinguish when one would claim versus update work.
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 phrase 'with a revision check' implies expected_revision is used for optimistic concurrency, signaling when to use it versus work_update. However, it doesn't explicitly state when to use this tool over siblings like work_update or plan_ack, or what conditions make claiming appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find recorded work and its history by task, session, path, branch, or commit.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent with that. The description adds that the tool searches by identifiers, but it does not disclose return format, ordering, or pagination behavior beyond what the schema parameters imply.
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 entire description is one front-loaded sentence that states the operation, resource, and key filters without filler. It earns its place and adds value without repeating schema details verbosely.
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 read-only search tool with a nested schema, the description plus annotations and structured schema constraints are largely sufficient for an agent to select and invoke it. The absence of an output schema is partially mitigated by the phrase 'recorded work and its history,' though more explicit return-value detail would improve 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?
With 0% schema description coverage, the description partially compensates by naming task, session, path, branch, and commit as filter dimensions. However, it omits the required project_id and the after/limit pagination controls, leaving those semantics entirely to 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?
States a specific action ('Find') on a clear resource ('recorded work and its history') and enumerates the search dimensions. This differentiates it from sibling tools like work_update and work_claim, which imply mutation rather than retrieval.
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 use when historical work records are needed, but it does not explicitly name alternatives or state when not to use this tool. Usage context is present but left to inference rather than being directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically report progress, release work, or hand work to another session.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the atomicity trait, which is genuinely useful beyond the annotations. However, it does not disclose the optimistic-concurrency behavior implied by the required expected_revision field or what happens on mismatch, which is important for a mutating work-state tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word contributes to defining the tool's core behavior and scope.
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 a highly nested schema and no output schema, the description only covers the top-level purpose. It omits guidance on the update variants, required concurrency fields, failure behavior, and return value, making it insufficient for fully self-sufficient tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level meaning. It gestures at the action variants, but it does not explain request, updates, work_id, expected_revision, status, or the location object, so it leaves the schema to carry all semantic weight.
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 names a specific resource (work) and three concrete actions: report progress, release work, and hand work to another session. This clearly distinguishes it from sibling tools like work_claim, which has a different purpose.
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 clear usage context: use this tool when updating work state, releasing it, or handing it off. It does not explicitly name alternatives or exclusions, but the action verbs make the appropriate use case reasonably obvious.
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.
v1.0.0plan_ackplan_editplan_publishplan_readproject_joinproject_statuswork_claimwork_historywork_updateScored across 9 tools
Each tool targets a distinct phase of the workflow: joining a session, publishing/editing/acknowledging/reading plans, claiming/updating work, and querying status or history. Even the plan-focused tools are clearly separated by action (publish vs edit vs ack vs read), and work_claim vs work_update has no boundary ambiguity.
All tool names use snake_case with consistent resource prefixes: project_, plan_, and work_. The verb suffixes (join, publish, edit, ack, read, claim, update, status, history) are clear and follow a predictable pattern throughout.
Nine tools is well-scoped for a collaborative session and work-tracking server. Each tool earns its place, covering plan management, work claims, updates, and inspection without redundant or overlapping utilities.
The tool surface covers the core lifecycle well: join a session, publish/edit/read plans, acknowledge revisions, claim work, update work, view status, and inspect history. Minor gaps exist, such as no explicit project_leave or plan deletion, but these can be worked around using existing update/status mechanisms.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
Project management MCP for AI agents with safe task reads and writes.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
