Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Vezlu Draft two launch plans on separate branches, compare them, and wait for my pick"
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.
Keep two approaches, inspect their actual text, and combine the parts you choose.
Vezlu is a small local Claude companion for text artifacts: launch plans, research notes, decision briefs or code snippets. Claude supplies the alternatives. Vezlu stores, compares and combines them through a CLI or nine MCP tools. Each project has independent named branches and immutable revision snapshots in SQLite.
Requires Python 3.12+ on macOS or Linux. From this repository's directory:
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/vezlu --helpThe runtime dependency is the official MCP Python SDK, pinned to 2.3.0. No model account or API key is needed to run the CLI. Your Claude host has its own access requirements.
Related MCP server: claude-memory
.venv/bin/vezlu --store "$PWD/.vezlu/demo" demo
.venv/bin/vezlu --store "$PWD/.vezlu/demo" call branches '{"project":"launch-demo"}'
.venv/bin/vezlu --store "$PWD/.vezlu/demo" call compare '{"project":"launch-demo","left":"community","right":"partners"}'
.venv/bin/vezlu --store "$PWD/.vezlu/demo" call read '{"project":"launch-demo","branch":"combined"}'The demo uses fixture text, not model output or a performance benchmark. From one launch plan, community changes the brief to a free neighbourhood trial with a repeat-attendance goal; partners changes distribution to library and club partnerships. The JSON output shows both complete alternatives, exact differences and a third combined result containing the community brief and partner channels. The original alternatives remain available.
The demo creates launch-demo once. Repeating it in that store returns project already exists; choose a fresh private store path for another run. The default store, when --store is omitted, is ~/.local/share/vezlu.
Add this entry to your Claude Desktop MCP configuration, replacing both paths with absolute paths on your machine:
{
"mcpServers": {
"vezlu": {
"command": "/absolute/path/to/vezlu/.venv/bin/vezlu",
"args": ["--store", "/absolute/private/data/vezlu", "serve"]
}
}
}Restart the host and enable the server. serve speaks MCP over stdio. The test suite checks the official SDK's subprocess handshake and tool calls; a live Claude Desktop session is a separate host setup check. Local MCP server configuration describes the host configuration. The adjacent SKILL.md provides a focused workflow you can give Claude.
Try: “Create two approaches to my launch. Keep the same artifact keys on both branches. Show their differences, explain the tradeoffs, and wait for my choice before combining selected artifacts.”
CLI calls use vezlu [--store DIRECTORY] call OPERATION 'JSON_OBJECT'. MCP tool names and arguments match the table. Results are JSON text; CLI errors return an error object and exit status 1. MCP input failures return tool errors. A merge conflict is a successful request with ok: false, and never changes the target.
Operation | Arguments | Result |
| none | Saved project names |
|
| Empty |
|
| Names and current heads |
|
| New branch at source head |
|
| Head, selected revision and all artifacts |
|
| New head; changes map keys to text, or |
|
| Newest reachable revision IDs, parents and merge source |
|
| Both heads and sorted changes with exact before/after text and unified diffs |
|
|
|
Read current heads before a write, fork or merge, then send those exact tokens. A stale token refuses the operation: reread the branch, inspect the new content and reconsider the choice. Multiple artifact changes commit atomically.
Combination works on whole artifacts, without line-level merging. For each selected key, Vezlu finds the unique closest common ancestor of the branch heads, then:
Adopts source changes if the target still matches the base, including additions and deletions.
Retains target-only changes and accepts identical edits.
Returns base, source and target values when both branches changed an artifact differently. All selected changes are withheld if any conflict occurs.
Choose conflicting text manually and save it with write; there is no automatic winner. Unrelated or ambiguous ancestry is refused. A partial combination records its source reference but only records the source as a second ancestry parent when all its changes are present in the result. This keeps unselected source changes available later. Repeated edits after a partial combination can conservatively conflict and need manual choice.
Branching, version history, unified diffs and three-way merging are established version-control techniques. Vezlu applies them to a small local text workflow. It does not measure which alternative is better.
Artifacts are logical keys, never imported files or filesystem paths. Project and branch names use 1–64 ASCII letters, digits, dots, underscores or hyphens and start with a letter or digit. Artifact keys allow similarly named slash-separated segments, up to 200 characters. Text must be valid UTF-8, at most 64 KiB per artifact, 128 artifacts and 1 MiB of text per snapshot. History accumulates on disk; there is no pruning in this version.
The store contains plaintext. Use a private directory on a local filesystem. Vezlu creates it with mode 0700 and the database with 0600; unsafe existing permissions, symlink path components, symlink database sidecars and hardlinked databases are refused. On macOS, /tmp is a symlink: use a real absolute directory, such as one under your home. These checks protect against accidental redirection; they are not a boundary against another process acting as your own user.
There is no cloud sync, model invocation, HTTP listener, shell-command tool, filesystem import/export, hook or telemetry. Outputs appear only in CLI/MCP responses. Keep secrets out of artifacts. Back up the store only while all Vezlu processes are stopped. Windows and network filesystems are not supported in this release.
From the checkout, with Python 3.12+ available as python:
python scripts/verify_distribution.pyThe helper creates temporary build and install environments, builds one wheel and installs it with its declared dependencies. It verifies the installed module's location and runs all 25 tests from a copied test file outside the checkout, with Python path overrides and user site packages disabled. It also checks the installed vezlu --help and fixture demo commands. Temporary environments, build files and stores are removed when the helper exits.
CI is configured to run this command on ubuntu-latest and macos-latest, each with Python 3.12 and 3.14. The workflow's job results report which combinations have passed. A live Claude Desktop session remains a separate host setup check.
The tests cover isolated branches, immutable history, restarts, independent and conflicting combinations, deletion, partial ancestry, concurrent stale writers, malformed input, private paths, real SDK stdio negotiation and the CLI fixture demo. MIT licensed; see LICENSE.
Fork source into a new branch, guarded by the source's expected_head.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | ||
| source | Yes | ||
| project | Yes | ||
| expected_head | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It does add meaningful context by stating the operation is 'guarded by the source's expected_head,' implying optimistic concurrency, but it omits what happens on mismatch, permission requirements, whether the branch creation is atomic, and other mutation 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?
The description is a single front-loaded sentence with no wasted words. The fork action and guard condition are both stated immediately.
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 is a mutation-style tool with no annotations, no output schema, and 0% schema description coverage. The one-sentence description provides only a high-level action and guard, which is insufficient for an agent to confidently invoke a four-parameter branch-creation operation.
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 for four undocumented required parameters. It clarifies the relationship between source and expected_head and implies branch is the new branch name, but it says nothing about project or parameter formats, leaving significant gaps.
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 states a specific verb and resource: 'Fork source into a new branch,' which is clearer than a generic create. However, it does not distinguish this tool from siblings such as create, branches, or merge, and 'source' remains ambiguous without schema descriptions.
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 explicit guidance on when to use this tool versus alternatives like create, branches, or merge. The only usage signal is the implied action of forking a source branch, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's branch names and current head tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'List' implies a read, but the description does not confirm read-only/non-destructive behavior, say what happens for an unknown project, or mention ordering or pagination of branches.
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 short sentence with the resource and scope front-loaded; nothing is wasted. Its brevity is efficient, though part of the gap is under-specification rather than concision.
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 one-parameter read tool with no output schema, the sentence does convey roughly what is returned (branch names plus head tokens). However, project identifier format and failure behavior are missing, leaving meaningful gaps 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% for the single 'project' parameter, and the description only says 'a project's' — it never clarifies whether this is a project ID, slug, or name, nor the required format. It adds almost no meaning beyond the bare schema title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (branch names and head tokens) scoped to a project, so the agent knows the payload shape. It does not differentiate from the sibling 'branch' tool, so an agent must guess whether 'branch' creates/reads a single branch versus this listing call.
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 when-to-use guidance and no mention of alternatives such as 'branch' (single branch) or 'history' (commits on a branch). The agent must infer selection purely from the one-word name contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show exact before/after text and unified differences between two branch heads.
| Name | Required | Description | Default |
|---|---|---|---|
| left | Yes | ||
| right | Yes | ||
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the return content (exact before/after text and a unified diff), but never states that the operation is non-mutating, whether it needs any access permissions, or whether large diffs are truncated.
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?
A single front-loaded sentence that names the operation, the inputs, and the output format with zero padding. Nothing in it is redundant given there is no title to restate.
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?
A three-required-parameter tool with no annotations, no output schema, and zero schema description coverage needs more than this. The description leaves the project parameter and the left/right orientation undocumented, which is exactly the information an agent must guess to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it largely does not. "Two branch heads" hints that left and right are branch identifiers, but it never says which side is the base versus the target, and the required 'project' parameter is not mentioned at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Show") and resource ("differences between two branch heads") with the output shape (before/after text plus unified diff). It reads as a read-only diff operation, which implicitly separates it from merge or write, but it never names a sibling to route against.
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 "between two branch heads" implies the precondition that both endpoints are branch heads, giving some context for use. There is no explicit when-to-use versus branches/history/merge, and no note about what happens if a branch or project does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a project with an empty main branch. Returns its head token.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it does disclose the key side effect (project initialized with an empty main branch) and the return value, which matters since there is no output schema. It omits permissions required, name-uniqueness/failure behavior if the project already exists, and idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and its result, with no filler. Every clause (empty main branch, head token) adds 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?
Given a single-parameter mutation tool with no annotations and no output schema, the description covers the creation effect and return value but leaves error conditions, permissions, and parameter format unaddressed. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — the single 'project' string parameter has no description at all. The description hints it identifies the project but does not say whether it is a name, slug, ID, or path, nor any format or length constraints, so the gap is not compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (create a project), plus the resulting state (empty main branch) and return value (head token). The word 'project' distinguishes it from branch/merge/compare siblings, though it never names them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to create versus using the 'projects' listing or other siblings, and no prerequisites or preconditions stated. Usage is only inferable from the tool name and verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List newest reachable revisions with ancestry and merge source references.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| branch | Yes | ||
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that results are ordered newest-first and include ancestry and merge source references, but it does not mention pagination, default limit behavior, permissions, or what is excluded.
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 wasted words. It is appropriately sized for a concise tool definition.
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 lack of annotations, output schema, and parameter descriptions, the definition is incomplete. It should explain parameter meanings, pagination behavior, and what the tool returns beyond the brief mention of ancestry and merge references.
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 does not explain any of the three parameters (project, branch, limit). The meaning of 'project', 'branch', and especially the limit default and acceptable range is left entirely to the bare schema titles.
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 states a specific verb ('List') and resource ('newest reachable revisions'), and it adds distinguishing content about ancestry and merge source references. It does not explicitly differentiate itself from siblings like compare or read, so it falls short of a 5.
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 such as read, compare, or merge. It implies a listing use case but provides no conditions, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine selected artifact paths using common ancestry. Requires both current heads. Conflicts leave target unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | ||
| source | Yes | ||
| target | Yes | ||
| project | Yes | ||
| expected_source | Yes | ||
| expected_target | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two important traits: both current heads are required, and conflicts leave the target unchanged. However, it omits permissions, reversibility, success behavior, and how conflicts are surfaced, leaving substantial gaps for a mutation 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?
Three short sentences are front-loaded with the core operation, followed by precondition and failure semantics. There is little waste, though the second and third sentences could be slightly more integrated.
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 six-required-parameter mutation tool with no annotations and no output schema, the description is quite sparse. It covers the precondition and conflict behavior but omits return values, permissions, source/target semantics, and conflict resolution details that an agent would need 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 description coverage is 0% and there are six required parameters, so the description must compensate. It maps loosely to 'paths' ('selected artifact paths'), 'expected_source'/'expected_target' ('both current heads'), and 'target' ('target unchanged'), but it says nothing about 'project' or the source/target distinction, leaving most parameter meanings 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 states a specific verb and resource: 'Combine selected artifact paths using common ancestry.' This distinguishes a merge operation from siblings like 'compare' or 'write', though it does not explicitly name an alternative. The purpose is clear enough to select the tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Requires both current heads' gives a precondition for using the tool, but it does not explain when to choose merge over 'compare', 'branch', or 'write'. Usage is implied rather than explicitly contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved project names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden: 'List' implies a read-only, non-mutating operation and 'names' indicates the return is a set of name strings, which is useful. It does not address ordering, pagination, or whether projects with no branches are included, so the disclosure is partial.
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?
A single front-loaded sentence with no filler; the verb and the returned resource appear immediately. Nothing could be cut without losing meaning.
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 zero-argument, no-output-schema listing tool, stating that it returns saved project names is nearly sufficient to call it correctly. Only minor operational details, such as result ordering or what to do with the names next, are absent.
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 tool takes zero parameters, so the baseline is 4; the schema is trivially complete and the description correctly implies no filtering or scoping inputs. Nothing about parameters is misrepresented.
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 pairs the verb 'List' with the resource 'saved project names', which is specific enough that an agent can distinguish it from create/read/write/merge siblings. It stops short of explicitly naming a sibling or stating the relationship to the branch-oriented tools, so it earns a 4 rather than a 5.
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 statement of when to call this versus alternatives, no prerequisites, and no mention of how project names relate to the branch/branches tools. An agent must infer that this is a discovery step before read/write operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all artifacts and head, or an immutable revision in this branch's ancestry.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | ||
| project | Yes | ||
| revision | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It implies a read operation and mentions immutable revisions, but gives no information about permissions, errors, pagination, return shape, or what “all artifacts and head” actually means operationally.
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 obvious waste. Its brevity is appropriate, though “all artifacts and head” is slightly compressed and ambiguous.
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 annotations, no output schema, and zero schema descriptions, the definition is not complete enough for reliable invocation. It leaves key parameter semantics, return behavior, and usage boundaries unexplained.
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 needs to explain all parameters. It gives some meaning for branch ancestry and revision immutability, but does not explain the required project parameter or clarify that revision defaults to null to read head.
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 states a specific verb and resource: reading artifacts and head, or an immutable revision in the branch ancestry. It is clearer than the bare tool name, but it does not distinguish this operation from siblings such as history or compare.
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?
It does not explain when to use this tool instead of history, compare, branch, or write. The only usage signal is the optional revision wording, which is indirect and insufficient for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically replace whole text artifacts; null deletes. Requires the current expected_head.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | ||
| changes | Yes | ||
| project | Yes | ||
| expected_head | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does disclose real behavior beyond the schema: the write is atomic, it replaces whole artifacts (destructive to prior content), null performs a delete, and expected_head is a required optimistic-concurrency token. It omits what happens on a head mismatch (error vs. overwrite), whether missing artifacts are created, and any permission requirements.
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 clauses, zero padding, and the core mutation behavior is front-loaded before the precondition. The terseness costs some clarity ('text artifacts' and the changes-map key semantics are never pinned down).
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 destructive, atomic, nested-object mutation tool with no annotations and no output schema, the essentials are present but incomplete: failure/conflict behavior on head mismatch, create-vs-replace semantics for new keys, and the return value are all unaddressed.
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 for four required parameters. It explains expected_head's role as the current head precondition and gives the semantics of the changes map values ('null deletes'), but leaves the keys of that nested map, plus project and branch, completely undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: atomically replacing whole text artifacts, with null meaning deletion. It distinguishes itself implicitly from read/create/merge siblings by being a whole-artifact replace, though it never names an alternative and the term 'artifacts' is left undefined (files? documents? keys in the changes map?).
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?
Usage is implied rather than stated: 'whole text artifacts' signals full-document replacement instead of incremental edits, and 'null deletes' signals a deletion path. There is no explicit when-to-use/when-not guidance versus create, merge, or branch, and no stated prerequisites such as the branch existing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0branchbranchescomparecreatehistorymergeprojectsreadwriteScored across 9 tools
Each tool maps to a distinct resource and action: project listing/creation, branch listing/forking, artifact reading/writing, revision history, head comparison, and merging. No two tools overlap in purpose, and guards like expected_head further clarify use.
Names are all lowercase and readable, but they mix resource nouns (projects, branches, history) with bare verbs (create, read, branch, write, compare, merge). The pattern is understandable but not a consistent verb_noun convention.
Nine tools is well-scoped for a lightweight versioned artifact store. Every tool covers a needed facet—projects, branches, revisions, reads/writes, diffs, and merges—without redundancy.
Core workflows for creating projects, branching, reading/writing artifacts, inspecting history, comparing heads, and merging are covered. Minor lifecycle gaps remain, such as deleting or renaming projects and branches, but agents can work around them.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Versioned artifact review for people and AI agents, with contextual comments and human control.
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
