A
licenseNot graded
qualityC
maintenanceEnables Codex to delegate bulk code reading, patching, and testing to an async worker using cheaper AI models, while receiving compact results.
94 npm
2
MIT
MCP-Bifrost
by ArnauFerma
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., "@MCP-BifrostConvert every method in src/tasks.py to early-return style."
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.
MCP-Bifrost
Rewrite 200 methods with a cheap model, without a single line of the result passing through the expensive one's context — and without writing anything to disk that does not compile.
An MCP server that takes code work already analysed and split up by an orchestrating model, extracts the exact target block with the language's own parser, delegates the rewriting to a cheaper worker model, validates the result, applies it atomically, and records the whole thing outside the orchestrator's context.
The head decides. The muscle types. Bifrost is the nerve between them — and the part that guarantees nothing reaches disk broken.
In the examples below the head is Claude and the muscle is DeepSeek, which is simply the model that was to hand. Neither is a requirement. See The worker for why a 7B model on your own machine may be the more interesting choice.
Why
A large codebase edited by an LLM has one real bottleneck, and it is not intelligence: it is context. Reading a 4,600-line file to change thirty lines of it burns the orchestrator's window on text it will never use again.
Bifrost's premise is that the mechanical half of coding — writing the replacement text — does not need the expensive model, and does not need to pass through its context at all.
Orchestrator does it all | Via Bifrost | |
202 methods × ~800 tok | ~161,000 tok — exceeds a context window | ~15,000 tok |
The honest version (see RF-4): for a single small edit the saving is real but modest, because the orchestrator usually had to read the code anyway to say what it wanted. The order-of-magnitude win is in volume — transformations across many symbols where the instruction can be written without reading anything.
That is the use case this is built for. Not "fix this bug."
And the number the log reports is a counterfactual. The test suites in this repository were written through Bifrost itself: 97,909 bytes applied from 1,608 bytes of instruction, which the formula scores at 61×. The realised saving was zero, because the blocks were composed by the orchestrator rather than by a worker, and every one of those bytes was paid before Bifrost saw them. The log records what crossed the boundary, not where it was written. The worked example is in §11, kept unflattering on purpose.
Related MCP server: ropey
When not to use it
Exploratory work. "Find why this crashes" is not an instruction Bifrost can execute. It needs to know the symbols before it starts.
Single small edits. The token arithmetic is marginal, and we say so (RF-4). Use your agent's normal edit tool.
Latency-sensitive loops. ~2.6 s per block, measured against DeepSeek.
Anything that is not PHP or Python. Adding a language means writing a parser adapter, not rewriting the core — but it is not there today.
Cross-file refactors where one edit's shape depends on another's outcome.
patch_groupgives atomicity, not sequencing.Codebases with no way of telling you something broke. Every gate here checks form; none understands meaning.
How this sits next to Aider, Serena and fast-apply models — including where
they are better — is in docs/comparison.md.
How it works
you ──▶ Claude Code ──▶ MCP-Bifrost ──▶ worker model
analyses, parses, writes one
splits work validates, isolated block
applies, logs
│
├──▶ source file (atomic splice)
└──▶ .bifrost/history.dbThe orchestrator decides what and how. The worker decides nothing. The server is the only component allowed to touch disk, and it refuses until every gate passes.
Validation gates
Gate | Checks | Default |
0 — offsets | the block on disk is byte-identical to what we sent the worker | on |
1 — syntax | the rebuilt file passes | on |
2 — one symbol | the returned block defines exactly one symbol — a class counts as one, whatever it holds | on |
3 — substance | no call, variable or control keyword vanished silently | off |
Three are on by default, not four. The substance gate is a coarse regex
check that never fired during calibration, and a gate that rejects good
patches is worse than one waiting to be armed. Enable it with
substance_gate=True before bulk work.
A "perimeter check" comparing bytes outside the target range was specified,
built, and then deleted: the server rebuilds the file as
original[:start] + block + original[end:], so the perimeter is preserved by
construction and the check can never fail. Calibration confirmed it — the
gate reported 9/9 while three files were left syntactically broken. See
RF-1.
Rollback
Git is already a content-addressed database, so it is used as one.
git hash-object -w before each patch yields a blob SHA that goes in the
log; reverting is git cat-file blob. Deduplicated and compressed for free,
works with a dirty working tree, and there is no bespoke snapshot format to
maintain.
The worker
DeepSeek is what was to hand, and every number in this repository was measured against it. It is not a requirement, and it is probably not the most interesting way to run this.
The worker's job is deliberately narrow. It receives one isolated block and one instruction, and returns one block. It does not choose files, plan changes, decide what to edit, or see anything else in the codebase. That is a task a 7B coding model can do — and the gates exist precisely so a weak worker's mistakes are caught before they reach disk rather than after.
Which makes the local case the more compelling one:
Your code never leaves the machine. For a proprietary codebase that is not a preference, it is a precondition.
Cost goes to zero on exactly the workload this is built for, where hundreds of blocks in one run is normal rather than extreme.
The context requirement is tiny. One method, not one file. An 8k window is plenty; the whole design is that the worker never sees more than it needs.
A weak worker is an acceptable worker when every output is parsed, syntax-checked and diffed before it counts for anything. A bad block costs a retry, not a corrupted file.
That last one is the real argument. Delegating code generation to a small local model is normally a bad idea because you cannot trust the output and checking it by hand costs more than writing it. Bifrost's answer is that the checking is mechanical, and the machine can do it.
Any OpenAI-compatible endpoint works — Ollama, llama.cpp's server, LM Studio, vLLM:
"env": {
"BIFROST_WORKER_BASE_URL": "http://localhost:11434/v1",
"BIFROST_WORKER_MODEL": "qwen2.5-coder:7b"
}No key is needed when the endpoint is not the default one.
Worker compatibility
No local model has been measured yet. The endpoint is configurable and the protocol is a plain OpenAI-compatible chat completion, but this repository does not publish claims it has not measured — and that includes claims in its own favour.
The instrument exists. Point it at your endpoint:
BIFROST_TARGET=/path/to/your/codebase \
BIFROST_WORKER_BASE_URL=http://localhost:11434/v1 \
BIFROST_WORKER_MODEL=your-model \
python3 calibratge/calibra.py --cases 9Worker | Valid JSON | Byte-identical (identity task) | No lines lost | Unfenced | Latency |
DeepSeek ( | 9/9 | 3/3 | 3/3 | 9/9 | 2.6 s |
your model here |
If you run it, open a PR with the row. Numbers that make a model look bad are as useful as numbers that make it look good — the table exists to say which workers this actually works with, not to advertise.
One thing to expect. DeepSeek returned zero of nine responses wrapped in markdown fences. Smaller models fence almost everything, and that is a parsing problem rather than a capability one. Bifrost already strips fences; if your model is otherwise sound but still fails on them, report it as a bug here rather than as a mark against the model.
What leaves the machine
The unit of work sent to a worker is one parsed block — a single method — and never the file it came from. That is a consequence of the design rather than a feature added to it: if the replacement code does not pass through the orchestrator's context, it does not pass through anywhere else either.
What it does not mean. The block does leave, in the clear, to whatever endpoint you configured. So does the instruction, which may itself describe internal architecture.
What already guards it. Heimdall runs before the send, not before the write. Where a secret is a self-contained token it is swapped for a placeholder, the worker transforms the code around it, and the original goes back before the file is written — every placeholder must return exactly once or nothing is written at all. What cannot be safely redacted blocks the send outright. Measured false-positive rate on a real codebase: 2 findings across 1,291 symbols, both correct refusals of code that manipulates keys rather than holding one. That count is from 0.1.0, when the symbol map held methods and functions only; classes became addressable in 0.1.4, so a rerun today counts a larger denominator.
If your constraint is that nothing may leave at all, the answer is a local worker, not a smaller payload.
Designed, not built
Two additions would close most of the remaining gap. Neither exists yet, and they are named here rather than hidden in an issue because the design is the interesting part:
Egress log. The log records the size of what was sent, not the bytes. Recording them alongside what came back is nearly free, and it turns "trust us" into "audit it".
Comment and literal redaction. Heimdall redacts things shaped like secrets. The parser already produces the tree, so comments and string literals — often the highest-risk payload and frequently irrelevant to the transformation — could be replaced with opaque markers and restored on return.
The obvious objection to the second is that quality may suffer when the
worker cannot see the names. That is a measurable question, not an argument:
nine cases with redaction, nine without, calibratge/calibra.py. Whichever
way it comes out gets published.
Quick start
Python 3.11+. No runtime dependencies — the server runs on the standard
library, and each language is parsed by its own official tooling (php as an
external binary, ast from the stdlib).
pipx install mcp-bifrost # or: uv tool install mcp-bifrostAdd it to .mcp.json in the project you want to patch:
{
"mcpServers": {
"bifrost": {
"command": "mcp-bifrost",
"env": { "BIFROST_DB": ".bifrost/history.db" }
}
}
}A tool the client only lists by name is easy to forget mid-task. MCP
clients that defer tool schemas show Bifrost's tools as bare names until
something asks for them, and nothing about repeating the same mechanical edit
five times in a row prompts that ask on its own — that is exactly how the
first six months of dogfooding went: insert_case sat unused for an entire
session while the same switch-case pattern got hand-edited over and over,
which then collided across two parallel edits in exactly the way
insert_case's anchoring exists to prevent. Close the gap once, for this
project:
mcp-bifrost init-hook # writes .claude/settings.json in this project
mcp-bifrost init-hook --global # or: ~/.claude/settings.json, for every projectThis adds a PreToolUse hook on Edit/Write that reminds the client to
check for a fitting Bifrost tool before hand-editing — additively, so any
hooks you already have stay in place. Run it again any time; it is a no-op
once the hook is there. Commit the project-level .claude/settings.json so
the nudge travels with the repo instead of living only on one machine.
A reminder alone turned out not to be enough — a full build session with the
hook installed and firing 50+ times still routed 96% of new files through a
raw Write (see docs/critical-review.md, RF-13). A later session settled
it: asked directly, the client admitted it was not using the tools, loaded
them, made one call, then hand-edited a new switch case, two new functions
and two method rewrites anyway, with the reminder firing on every one. Text
that has already been read and agreed with does not change the next
decision.
So the hook blocks two cases outright:
An
EditorWriteto an existing file this server adapts (.php,.py) inside a project whose.mcp.jsonregistersbifrost. The denial names the tool for each shape —insert_case,insert_symbol,fix_symbol,fix_symbols,fix_range,patch_group.A
Writecreating a file that does not exist yet, in a directory where three or more siblings already share its extension, naming the suggestedcreate_file(model_from=<nearest sibling>).
Everything else stays advisory. The first gate reads its scope off disk, so
--global is safe: a .php or .py file in a project that never
configured this server is never blocked. When an edit genuinely has no
symbol to address, touch .bifrost/hook-override lets the next one through
— it is consumed on use, so it buys one edit rather than a silent
session-wide opt-out.
If you develop this server, install the hook from a main worktree
The hook is enforced, global, and — installed editable from your development
checkout — it runs whatever branch that checkout happens to be on. Switching
to a feature branch then silently changes the gate for every other project on
the machine, which is exactly the class of surprise this tool exists to
remove. Keep a second worktree pinned to main and point the install at that
instead:
git worktree add ../MCP-Bifrost-main main
pipx install --force --editable ../MCP-Bifrost-mainDevelopment continues in the original checkout, on any branch, with no effect
on the live hook. After merging to main, refresh the worktree deliberately:
git -C ../MCP-Bifrost-main pull # editable install: no reinstall neededThe same applies to any .mcp.json that launches the server by path: point
its PYTHONPATH at the main worktree, not at the checkout you develop in.
Or from source, without installing:
git clone https://github.com/FixemBCN/MCP-Bifrost.git
cd MCP-Bifrost
python3 -m unittest discover tests # 308 tests, ~32s
python3 -m mcp_bifrost.server # same server, PYTHONPATH=.Without php on your PATH you will see OK (skipped=80), and that is the
expected result: those 80 tests drive the real PHP tokenizer, so on a machine
with no PHP there is nothing for them to prove. The remaining 228 — gates,
patcher, budget, Heimdall, the Python adapter — run on the standard library
alone. Install php-cli if you want the PHP half proven on your own machine;
CI runs
both environments on every push. git guards 91 tests the same way.
The key does not go in that file. Put it in .bifrost.env at your project
root, which the server reads when the environment does not carry it:
echo "DEEPSEEK_API_KEY=sk-..." > .bifrost.env
chmod 600 .bifrost.env
echo ".bifrost.env" >> .gitignoreOr skip the key entirely and point BIFROST_WORKER_BASE_URL at a local
model. Full instructions, and what to do before pointing this at anything
that matters, are in the manual.
Tools
Tool | What it does |
| one instruction across many symbols — the main one |
| rewrite one symbol, or an explicit line range — optional |
| add a function, method or class, or a branch to a switch router |
| write a new file, optionally by analogy with an existing one — optional |
| several operations as one transaction |
| changelog from the log; batch onto a reviewable branch |
| undo one patch, or the whole batch |
Calibration
Before writing a line of the server, one question had to be answered:
Given a real method from a real codebase, packed with the compact schema, does the worker return code that can be applied without breaking anything?
The harness in calibratge/ answers it. Zero dependencies — Python stdlib
plus the php binary.
export BIFROST_TARGET=/path/to/your/codebase
python3 calibratge/calibra.py --dry-run # show cases, no API calls
export DEEPSEEK_API_KEY=...
python3 calibratge/calibra.py --cases 9Result: the premise holds. 9/9 valid JSON, 3/3 byte-identical on the identity task, 3/3 with no original lines lost, 0/9 wrapped in markdown fences, 2.6 s average latency.
It also caught a byte-offset bug that had nothing to do with the worker and would have corrupted files silently in production. Full write-up: docs/calibration.md.
Repository layout
Path | What |
| the server |
what changed in each version, and why it was wrong before | |
manual, architecture, critical review, calibration, comparison, licensing | |
| 308 tests — 80 need |
the working record — how each decision was reached, including the reversed ones | |
| the measurement harness |
the workflow the badge reports: the suite with |
Behind the code
To be completely transparent: not a single line of this codebase was written by hand. It was conceptualised, challenged, implemented, tested and documented through a human-directed AI process. Here is what that actually meant, as precisely as it can be stated.
Human — problem, decisions, direction. I brought the initial specification and made every product decision: which worker model, which languages, what to cut, what to build next, the licence, the naming, when to stop. Several reversed earlier ones — the licence started as a no-resale source-available one and ended up Apache-2.0 once I decided reach mattered more than control. I also decided what the system must refuse to do, which turned out to be the more consequential half.
Claude Opus — adversarial design. Before implementation, Claude reviewed
the specification as an outsider looking for reasons it would fail, and
produced twelve findings. Two killed design elements I had approved: the
central "perimeter check" the spec relied on turned out to be incapable of
failing, and the project's stated justification — token savings — was shown
to be marginal for single edits and only decisive in bulk. Both are
preserved, unedited, in brainstorm/.
Measurement before code. Rather than trusting the design, a calibration harness was built first and run against the real worker on real code. It failed 6 of 9 cases — none of them the worker's fault. The cause was a byte-offset bug that would have silently corrupted any file containing an accented character. It also refuted two of Claude's own review findings. Those corrections sit above the original claims rather than replacing them.
Claude Opus — the core; delegated models — the periphery. Claude wrote the parsing, patching, validation gates, secret handling and engine directly. Two peripheral modules and the whole of the original test suite were delegated to smaller models (Haiku and Sonnet) running as subagents. That suite has since roughly doubled: the tests added in 0.1.2–0.1.5 were written by Opus and applied through Bifrost itself, and they exist because the original 128 never executed the MCP server, the worker's HTTP client, the VCS layer or the Python adapter at all. The split was deliberate rather than economical: a model starting cold on the patching code would very plausibly have reintroduced the byte-offset bug, because the natural way to write that code is the wrong way.
The delegated models found four real bugs in code Claude had written,
including one that detached a docblock from the method it documented and one
where nested switch statements silently dropped branches. Both passed every
validation gate. Adversarial review by a model with no stake in the code was
the only thing that caught them.
Human — review and acceptance. I directed the sequence, inspected results, challenged claims, and decided what stayed. Claude executed the validation and calibration runs; I read what came back and decided what it meant.
What this process did not provide
No human has read all ~10,700 lines of this repository — roughly 4,600 of server, 5,400 of tests and 700 of measurement harness — line by line. The confidence here comes from tests checked against deliberately broken code, from measurements against a real codebase, and from a design that refuses to write anything it cannot verify — not from manual audit.
If that is not the kind of confidence you want in a tool that edits your source files, that is a reasonable position, and the responsibility section is specific about what the gates do and do not catch.
Why this is in the README
Bifrost is a demonstration of its own premise. The valuable human contribution was not typing the code: it was defining the problem, controlling the context, challenging the output, and insisting on enough validation that generated code could be trusted at all.
The repository deliberately keeps the reasoning, the rejected ideas, the adversarial review and the measurements — including the parts where the AI was wrong and said so.
This account stops at the first release, and the work did not. What has
happened since is in CHANGELOG.md,
which records each defect as it was found and what it had been doing
unnoticed; how the design was arrived at before that is in
brainstorm/
and docs/critical-review.md.
Documentation
Document | What it is |
what it is, what it can do, how to install it, and what you are responsible for | |
what gets built and why | |
a fresh-eyes pass hunting for reasons this fails — twelve findings, two later refuted by measurement | |
what the worker actually did when asked | |
how this sits next to Aider, Serena and fast-apply — and where they win | |
what we consume, what we grant |
brainstorm/ holds the working record: the original spec, the
design journal across five revisions, the adversarial review, and the
calibration results. docs/ is the reference and wins where the two differ.
Responsibility
This tool edits your source files automatically using a language model. Apache 2.0 means it is provided as is, without warranty: you are responsible for what it does to your code. Read the diffs, run your tests, deploy on purpose. The manual is specific about what the gates do and do not catch.
Contributing
Contributions of every kind are welcome — including an argument that something here is wrong. This project has already deleted one validation gate for being tautological and refuted two of its own claims with measurement.
One convention, and it is the one that matters: every test must be able to fail. Details in the manual.
License
Built on the Model Context Protocol, MIT-licensed by Anthropic, PBC. MCP-Bifrost is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC.
Available Tools
11 toolscreate_fileB
Write a new source file. Never overwrites. Pass model_from to generate BY ANALOGY: the worker is handed an existing sibling as a structural exemplar and traces its shape, naming and error handling rather than inventing its own. Where a codebase already has many files of one kind, this is by far the most reliable way to add another — the worker does not need to know your conventions, it needs to copy them.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| verify | No | Optional shell command run after the file is written, cwd the repo root — e.g. 'pytest tests/test_foo.py -q'. Non-zero exit deletes the file and returns the command's output instead of reporting success — catches a syntactically fine file that is still wrong, which no gate before this can see. | |
| file_path | Yes | ||
| model_from | No | Path to an existing file to use as the structural exemplar. Strongly recommended. | |
| instruction | Yes | ||
| allow_secrets | No |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the non-destructive guarantee ('Never overwrites') and the analogy-generation behavior of model_from, plus the existence of verification. It does not describe required permissions, what happens to the file on failure outside the verify path, or the return shape, leaving real gaps for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly: the core action and the never-overwrites guarantee come first, then the model_from explanation. The closing clause about the worker not needing to know conventions is somewhat rhetorical padding, but the overall size is proportionate to the tool's unusual semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter write tool with no annotations and no output schema, the description covers the main creation and analogy flow well but leaves allow_secrets unexplained and says nothing about failure/side-effect behavior beyond verify. Adequate for the happy path, incomplete around safety-relevant parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 40%, so the description must compensate, and it does well for model_from — explaining the analogy mechanism far beyond the schema's one-liner. However, allow_secrets is left completely undocumented in both the schema and the description, which is a notable risk for a flag governing secret material, and instruction/file_path are unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Write a new source file') and immediately constrains it with 'Never overwrites', which separates it from the mutation-siblings like insert_symbol and fix_symbol that edit existing files. It never names those siblings explicitly, so the distinction must be inferred rather than read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives strong conditional guidance for one path ('where a codebase already has many files of one kind', use model_from), but says nothing about when to reach for create_file versus insert_symbol or fix_symbol for the same file, and gives no prerequisites or ordering advice. Usage context is implied by the never-overwrites constraint rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_docsA
Turn the patch log into readable documentation — a changelog, release notes, a summary of a batch. Every patch already recorded why it was made, at no cost to your context; this reads that back. Runs ONLY when asked: nothing generates it automatically.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | By file reads as a changelog; by session reads as a work log. | |
| since | No | ISO date, e.g. 2026-08-01. | |
| title | No | ||
| output_path | No | Write here. Omit to get the markdown back instead. | |
| session_only | No | Limit to this session's changes. |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the data source (recall of recorded patch rationale), that it is read-only on the log, and that nothing is auto-generated, but it does not state whether anything is mutated, what gets written when output_path is supplied, or whether output is truncated for large logs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action and output types. Slightly padded by the "at no cost to your context" value pitch, but the invocation constraint is well placed and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter, zero-required tool with no output schema, the description adequately conveys the two output modes (returned markdown vs. written to output_path) and the scoping constraint that it never fires automatically. It stops short of describing the markdown's structure, but nothing critical to a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already carries the parameter meaning (including the file/session enum semantics and the output_path fallback). The description adds no parameter-level detail beyond that baseline, which is adequate but not additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: turn the patch log into readable documentation, with concrete exemplars (changelog, release notes, batch summary). It is clearly distinct from sibling mutations like revert_patch or insert_symbol, though it never names a sibling or contrasts with publish_session, which is the nearest-looking alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Runs ONLY when asked: nothing generates it automatically" clarifies that this is a user-triggered read, which is useful context. However, it never says when to pick export_docs over publish_session or patch_group, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fix_rangeA
Rewrite an explicit line range. The escape hatch for code that does not live inside a symbol — module-level configuration, a branch of a switch, markup embedded in the source. Prefer fix_symbol where one applies: line numbers move when earlier patches land, and a stale range is rejected rather than applied.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| end_line | Yes | 1-based, inclusive. | |
| file_path | Yes | ||
| start_line | Yes | 1-based, inclusive. | |
| instruction | Yes | ||
| allow_secrets | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a genuine behavioral trait: a stale range is rejected rather than applied, which tells the agent the operation is validated and fails safe. It also warns that line numbers shift after patches. It does not cover permissions, reversibility of the rewrite, or what allow_secrets gates, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action, then the use case, then the alternative and its rationale. No filler; every clause adds routing or safety information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Usage and sibling routing are covered thoroughly, but for a 6-parameter mutation tool with no annotations and no output schema, the 33% parameter coverage leaves real gaps. The meaning of instruction, context, and allow_secrets is never addressed, so an agent still cannot fully invoke it from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% — start_line and end_line are documented in the schema, but context, instruction, and especially allow_secrets are undocumented in both places. The description adds no parameter-level meaning at all, and allow_secrets in particular is a security-sensitive parameter left entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Rewrite an explicit line range') and immediately scopes it to code that does not live inside a symbol. It explicitly names the sibling fix_symbol and the condition under which that one is preferable, so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('module-level configuration, a branch of a switch, markup embedded in the source') and when-not ('Prefer fix_symbol where one applies'), along with the rationale (line numbers move when earlier patches land). This is unusually complete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fix_symbolA
Rewrite one named function, method or class in place. The symbol is extracted with the language's own parser, sent to a worker model, validated, and spliced back atomically. Addressing by name is immune to line drift, so it is safe to issue many against the same file. Skip this only when the edit is too small for a symbol boundary to matter — a one-line typo, a single config value, a comment. Anything that changes what a function does should go through here even when you already read the code: unlike a manual edit, this re-resolves the symbol by name (immune to line drift from earlier edits landing in the same file), validates syntax before writing, and is rollback-able from a saved git blob. Having read the file first buys a manual edit none of that.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| verify | No | Optional shell command run after the write lands, cwd the repo root — e.g. 'pytest tests/test_foo.py -q' or 'php -l path/to/file.php'. Non-zero exit reverts the write and returns the command's output instead of reporting success. The one thing a subagent gets for free by running the suite itself. | |
| context | No | Optional. Signatures or snippets the worker needs. Bare sibling signatures are usually useless; send what actually matters, such as the shape of a parameter. | |
| file_path | Yes | Path to the source file. | |
| instruction | Yes | What to change, stated compactly. The worker sees only this symbol, so anything it needs to know that is not in the code must be said here or passed in context. | |
| symbol_name | Yes | Function or method name. Qualify as 'Class::method' when the bare name is ambiguous — ambiguity is rejected, never guessed. | |
| allow_secrets | No | Override Heimdall, the gate that refuses to send anything looking like a credential to the worker. Only after seeing what it flagged and judging it a false positive. The override is recorded. |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden and it does. It discloses the pipeline (parse → worker → validate → atomic splice), line-drift immunity, syntax validation before writing, rollback-ability from a saved git blob, and the existence of a secrets gate. These are non-obvious behavioral traits an agent must know to pick this over a manual edit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then usage, then rationale. The final two clauses ('unlike a manual edit... Having read the file first buys a manual edit none of that') re-argue the same point already made one sentence earlier, and the rhetorical closing is padding. Otherwise efficient and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, it covers safety (atomic, validated, rollback-able), addressing semantics (name-qualified, ambiguity rejected), and failure paths (verify non-zero exit reverts). An agent has enough to call it correctly and to know when not to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: the reason addressing by name is safe ('immune to line drift'), and the rationale for context ('the worker sees only this symbol'). The parameter-level docs also add substantial nuance (verify reverting on non-zero exit, allow_secrets recording the override), though that credit belongs to the schema itself. Description-level contribution above baseline is modest but real.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Rewrite one named function, method or class in place.' It explains the mechanism (parser extraction, worker model, validation, atomic splice). It does not explicitly differentiate from the closest sibling fix_symbols (plural), which is presumably batch. That is a notable gap in a family where singular vs plural matters a lot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-not: 'Skip this only when the edit is too small for a symbol boundary to matter — a one-line typo, a single config value, a comment.' And explicit when: 'Anything that changes what a function does should go through here even when you already read the code.' It also argues against the alternative (a manual edit) with concrete reasons. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fix_symbolsA
Apply ONE instruction across MANY symbols. This is the tool this server exists for. For a single target, use fix_symbol instead — the parallel worker calls here only pay off once there is more than one. The order-of-magnitude win is a transformation stated once and applied to symbols you never read: 'add a docblock to every method here', 'switch every call to the new API'. Worker calls run in parallel, writes run in series, and each symbol is re-resolved by name just before its write, so earlier patches moving later offsets is not a problem.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | Objects with 'file_path' and 'symbol_name'. An optional per-target 'instruction' overrides the shared one. | |
| instruction | No | Applied to every target that does not carry its own. | |
| max_parallel | No | Concurrent worker calls, default 6. |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and largely meets it: it discloses the execution model (worker calls run in parallel, writes run in series), and that each symbol is re-resolved by name before its write so earlier patches shifting offsets is not a problem. It does not describe failure/partial-write behavior or whether patches can be reverted, which the sibling revert_patch/revert_session imply is possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the routing rule, and the concurrency/ordering sentence is genuinely informative. The line 'This is the tool this server exists for' is promotional filler that does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param mutation tool with no output schema, the description covers execution ordering, concurrency, override semantics, and offset safety. It stops short of covering partial-failure or recovery behavior, which an agent running a bulk write would want.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the required baseline is 3. The prose adds conceptual framing ('a transformation stated once and applied to symbols you never read') but no syntax or format detail beyond what the schema already documents for targets, instruction, and max_parallel.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Apply ONE instruction across MANY symbols') and explicitly names the sibling it is not for: 'For a single target, use fix_symbol instead.' An agent can route between fix_symbols and fix_symbol without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use threshold ('the parallel worker calls here only pay off once there is more than one') and names the alternative tool for the single-target case. Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert_caseA
Add a branch to a switch. A case label is not a symbol, so no parser addresses it — but in a router-style file it is the extension point every new endpoint goes through. Anchored to a neighbouring case label, which stays stable across a batch the way line numbers do not. A label that already exists is rejected: PHP takes the first match and silently ignores the rest, so a duplicate is dead code that looks alive.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| file_path | Yes | ||
| after_case | Yes | Label of the case to insert after, without quotes. | |
| instruction | Yes | What the new branch does. Say 'output only the case block'. | |
| allow_secrets | No |
TDQS
A3.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers real behavioral detail: duplicate labels are rejected, with the PHP-semantics rationale (first match wins, duplicates become dead code), and it explains the anchoring strategy that survives a batch. It omits error/failure behavior and any mention of the allow_secrets parameter's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action and stays to four sentences, but the prose is stylized ('dead code that looks alive', 'stays stable across a batch the way line numbers do not'), which adds flavor at some cost to scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A mutation tool with no annotations and no output schema gets good rationale-level coverage, but the description leaves allow_secrets and context semantics undocumented and does not state what the caller receives. Adequate, not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40% (context, file_path, allow_secrets lack descriptions). The description usefully clarifies after_case semantics (anchor must be an existing, stable case label) and hints at instruction usage, which partially compensates, but it says nothing about context or allow_secrets.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
First sentence states a specific verb+resource ('Add a branch to a switch'), and the second sentence explicitly distinguishes it from symbol-based siblings by noting a case label is not a symbol so no parser addresses it. The purpose is clear, though the differentiation from insert_symbol is implied rather than named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied context ('in a router-style file it is the extension point every new endpoint goes through') which suggests when this tool is appropriate. However, it never names the alternative tool (insert_symbol) or states exclusions, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert_symbolB
Add a new function, method or class next to an existing one. Classes are addressable, so a class is a valid anchor and a valid thing to insert. Anchoring to a symbol rather than a line number is what makes this usable in a batch: the anchor does not move when everything above it changes. The anchor is also shown to the worker as a style reference, so the new code matches its neighbours.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| anchor | Yes | Existing symbol to position against. 'Class::method' when ambiguous. | |
| context | No | ||
| position | Yes | Anchored to a class, 'end_of_class' appends a member to that class — the direct way to add a method to it. Anchored to a member, it appends to the class the member belongs to. | |
| file_path | Yes | ||
| instruction | Yes | What the new symbol should be. Say 'output only the symbol' to avoid getting a whole class back. | |
| allow_secrets | No |
TDQS
B3.4/5.0
Behavior3/5
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 the anchor is shown to the worker as a style reference and that symbols are stable under edits above them, but it omits mutation side effects, reversibility (relevant given revert_patch/revert_session siblings), and any handling guidance for allow_secrets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core action, and each subsequent sentence adds a distinct rationale (batch stability, style matching). Slight redundancy in "a class is a valid anchor and a valid thing to insert," but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with no annotations and no output schema, the description covers purpose and the anchor rationale well but is silent on failure behavior, whether existing code is ever touched, and the undocumented context/allow_secrets parameters. Adequate, with visible gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description reinforces the anchor concept (classes addressable, 'Class::method') already stated in the schema. It adds nothing for the two undocumented parameters, context and allow_secrets, leaving their semantics unstated anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence gives a specific verb and resource: "Add a new function, method or class next to an existing one." That is enough to distinguish it from fix_symbols/fix_symbol (repair) and create_file (whole-file creation) without opening schemas, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the conceptual advantage of symbol anchoring over line numbers and frames the tool as batch-friendly, which implies when to reach for it. However, it never says when NOT to use it or points to siblings like create_file or fix_symbol as alternatives, so routing is left largely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
patch_groupA
Apply several operations as one transaction: all of them land, or none do. Use whenever a change spans more than one file — a new class plus the require_once that references it plus the method that returns it. Applying that halfway leaves the project worse than not starting. On failure everything already applied is rolled back in reverse order.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operations | Yes | Each entry is an object with 'op' set to fix_symbol | fix_range | insert_symbol | create_file, plus that tool's arguments. Order matters: they are applied in sequence. |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: all-or-nothing atomicity, the rationale (a half-applied change is worse than none), and the rollback semantics including reverse-order unwinding on failure. These are exactly the traits an agent needs before committing a multi-op mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the atomic guarantee before the usage condition and the rollback detail; nothing is padding. The example clause is slightly long but earns its place by making the multi-file trigger concrete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter batched mutation with full schema description coverage and no output schema, the essentials are present: transaction semantics, usage trigger, and failure behavior. Error-reporting detail (e.g. what is returned when an operation fails) is the only notable omission, and it is minor given no output schema exists to explain returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'operations' property already documents the op vocabulary (fix_symbol | fix_range | insert_symbol | create_file) and that order matters. The prose adds no parameter-level detail beyond that, so the baseline 3 for schema-dominated parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Apply several operations as one transaction') and immediately scopes it as the multi-file batching counterpart to the single-op siblings. An agent can tell from the 'spans more than one file' condition that this is the grouped variant of fix_symbol/insert_symbol/create_file without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('use whenever a change spans more than one file') and a concrete motivating example (new class + require_once + returning method), plus the failure consequence. It stops short of naming the alternatives (e.g. 'for a single edit use fix_symbol'), so the routing is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_sessionA
Put this session's changes on a branch as one reviewable commit, with a body listing every change and the reason recorded for it. Worth doing after any sizeable batch: a batch loose in the working tree is close to unreviewable, and where there is no test suite, review is the only safety net there is. Opening a pull request is opt-in and pushes to the remote — ask before setting it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | ||
| draft | No | Default true. | |
| branch | Yes | ||
| subject | Yes | The commit subject line. Yours to write — a machine summarising a batch produces 'Update 12 methods'. | |
| pull_request | No | Push and open a PR. Off by default: this leaves the machine. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the commit-body behavior and that opening a PR is opt-in and leaves the machine ('pushes to the remote'), which is valuable side-effect context. It omits what gets staged/committed (whole working tree?), whether the branch is created or must pre-exist, and whether anything is pushed without pull_request.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then rationale, then the side-effect warning. The motivational clause about review being 'the only safety net' is arguably padding, but each sentence contributes something and length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations and no output schema, so the description must carry the behavioral load for a mutation tool. It covers the commit and the opt-in PR push, but leaves the commit scope, branch-creation semantics, and return behavior unspecified — adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%; 'base' and 'branch' carry no schema description and receive no elucidation in the prose either. The description adds behavioral meaning around 'pull_request' (opt-in, pushes to remote), but this largely restates the schema note, and the two undocumented params remain unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Put this session's changes on a branch as one reviewable commit.' An agent can tell it commits a session to a branch, and its effect (branch + commit + optional PR) distinguishes it from sibling mutators like revert_session or patch_group. However, it never explicitly names an alternative, so differentiation relies on inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Worth doing after any sizeable batch' gives a concrete when-to-use trigger, and the closing note establishes the rule that pull_request pushes to the remote and should be confirmed first. No explicit when-not or sibling alternative is offered, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
revert_patchB
Undo one patch by id, restoring the file from the blob saved in git's object store before it was applied.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| patch_id | Yes |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the mechanism: the file is restored from a blob saved in git's object store from before the patch. That is genuinely useful behavioral context, but it omits whether the operation is destructive to later edits, permission/auth requirements, and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words; the action verb leads and the restore mechanism follows. Efficient and well-structured for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation tool with no annotations and no output schema, the description explains the core action and mechanism adequately. It leaves gaps on destructiveness to subsequent changes and error conditions that an agent performing an undo would want.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (patch_id, string) with 0% schema coverage. The phrase 'one patch by id' confirms the id identifies a single patch, adding marginal meaning, but formats, acceptable values, and where ids come from are not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (undo) and resource (one patch, by id), and the mechanism clarifies scope precisely. It implies patch-level granularity that differs from the sibling revert_session, though it never names that sibling to make the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given. The description never tells the agent when to reach for revert_patch versus the sibling revert_session, patch_group, or the various fix_* tools, and states no prerequisites for a valid revert.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
revert_sessionA
Undo every patch applied in this session, newest first. Use when a batch has gone wrong partway: you rarely want to undo one patch out of twenty, you want to undo the batch.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does disclose one real behavioral trait: patches are undone newest-first. It omits other important traits for a destructive operation — whether the undo is itself reversible, atomicity/partial-failure behavior, and permission requirements — so it is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the action and scope front-loaded, and the second sentence earns its place by justifying usage rather than restating the name. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, annotations, or parameters, the description must stand alone, and it covers scope, ordering, and intent well. It still leaves safety-relevant gaps (reversibility of the undo, partial-failure handling) that matter for a batch-mutating operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema offers nothing to interpret and the baseline is 4. The description correctly introduces no parameter discussion, which is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (undo) with an explicit resource and scope (every patch in this session), plus an ordering guarantee ('newest first'). It implicitly distinguishes itself from the sibling revert_patch by stressing batch-level scope ('you rarely want to undo one patch out of twenty'), so an agent can route correctly without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear triggering condition: 'Use when a batch has gone wrong partway.' However, it never names the alternative tool (revert_patch) or states a when-not case, so the agent must infer the boundary from the rhetorical aside rather than an explicit rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.1.8- First observed
create_file - First observed
export_docs - First observed
fix_range - First observed
fix_symbol - First observed
fix_symbols - First observed
insert_case - First observed
insert_symbol - First observed
patch_group - First observed
publish_session - First observed
revert_patch - First observed
revert_session
TDQS
A4/5.0
Scored across 11 tools
Disambiguation5/5
Tools are sharply delineated by scope: fix_symbols for batch symbol edits, fix_symbol for single symbols, fix_range for line ranges, insert_symbol/insert_case for insertions, create_file for new files. The descriptions explicitly guide when to use each, preventing misselection between overlapping editing operations.
Naming Consistency5/5
All 11 tool names use lowercase snake_case with a consistent verb_noun or verb_object pattern (fix_symbols, insert_symbol, create_file, patch_group, revert_patch). No deviations or mixed conventions.
Tool Count5/5
11 tools is well-scoped for a code transformation server. Each tool fills a distinct niche: single/multi/range edits, insertions, file creation, transactions, documentation, publishing, and reverts.
Completeness4/5
Core lifecycle is covered: create, modify, insert, batch transaction, revert, and publish. Minor gaps exist, such as no explicit delete/remove operation and no read/get tool, but agents can work around these using fix_range or fix_symbol.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.
Change-aware CI validation and affected-test guidance for coding agents.
- SinatraOAuthdev.sinatra
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables coding agents to perform safe, project-wide Python refactoring (rename, move, extract, inline, change signature, organize imports, etc.) with a dry-run safety contract and LSP-coordinate addressing.15MIT
- AlicenseNot gradedqualityDmaintenanceEnables Codex to offload expensive code reading, editing, and checking to a worker agent via Claude Code, supporting async jobs and long-running tasks.MIT
- AlicenseNot gradedqualityBmaintenanceEnables delegating coding tasks to sandboxed agents, returning changes as auditable diffs for human review before applying or discarding them.1MIT