An autonomous LLM build orchestrator that plans goals into tasks, edits code, and verifies every change through correctness gates — all controllable via MCP tools from any compatible AI client. Your codebase never enters the client's context window.
Available Tools
list_projects — List all projects currently registered in misterdev's registry (read-only, no LLMs called).
scan — Recursively search a directory for misterdev projects and register them.
status — Inspect a registered project's tasks and their current state (pending, completed, etc.).
build — Autonomously analyze a project, decompose a plain-English goal into tasks, edit code, and verify each change through build/test/lint/typecheck gates — reverting anything that causes regressions. Supports budget capping, dry-run previews, parallel execution in isolated git worktrees, and task limits.
run — Execute an already-planned set of tasks, optionally targeting a single task by ID or previewing without making changes.
Key Behaviors
Read-only tools (list_projects, status) are safe, idempotent, and call no LLMs.
Destructive tools (build, run) edit files, make git commits, and call external LLM providers — they refuse to operate on a dirty git working tree.
Supports polyglot code understanding (Python, Rust, TypeScript/JavaScript, Go, Java, C/C++, C#, Swift, Kotlin) via a tree-sitter symbol graph.
Extensible via plugins for custom tools, gates, and targets.
Install · What it does · CLI · Extending · Configuration · Development · License
Point misterdev at a repository and a goal. It reads the codebase as a symbol graph, decomposes the goal into concrete tasks, and works each one in a try-edit-verify loop: it emits an anchored SEARCH/REPLACE edit, applies it against the file on disk, and runs the change through a sequence of correctness gates — build, tests, lint, typecheck, and any optional gates you enable. A gate that fails RED blocks the change; a gate that has nothing to check SKIPs and never blocks. When a change regresses the suite, misterdev reverts it through git. Nothing merges unless it stays green.
$ misterdev build . "add rate limiting to the public API"
planning goal → 3 tasks (model: anthropic/claude-sonnet-4-6, budget $100.00)
task 1/3 middleware: token-bucket limiter api/limiter.py
edit 1 hunk applied · syntax ok
gates build GREEN · tests GREEN (142 passed) · lint GREEN · typecheck GREEN
task 2/3 wire limiter into request pipeline api/app.py
edit 2 hunks applied
gates build GREEN · tests RED (1 failed) → rolling back, regenerating
edit 2 hunks applied (attempt 2)
gates build GREEN · tests GREEN (145 passed) · lint GREEN · typecheck GREEN
task 3/3 docs + config surface README.md, config.py
gates all GREEN
done 3/3 tasks · 145 tests green · $0.38 over 11 callsBecause misterdev only trusts its gates, the loop is honest: "the model said it's done" is never the finish line — the build, the tests, and the diff are.
pip install misterdev
# or
uv pip install misterdevPython 3.10 – 3.13. Optional extras add capability without bloating the core install:
pip install 'misterdev[local-embeddings]' # offline semantic context ranking (fastembed, no API key)
pip install 'misterdev[lsp]' # LSP semantic-diagnostics gate
pip install 'misterdev[web]' # headless-browser web verification gate (+ playwright install chromium)
pip install 'misterdev[mcp]' # Model Context Protocol tool-host substrateExtras are all opt-in and timeout-bounded. When an extra's runtime dependency is absent, the gate it powers SKIPs rather than failing.
Related MCP server: Aider MCP Server
Give misterdev a goal and it drives the whole cycle: analyze the project, plan tasks, edit, and validate — repeating until the goal is met or the budget is spent. Edits are anchored SEARCH/REPLACE hunks: the model emits only the changed regions, which are applied against the on-disk file, so a 5,000-line module is edited without reprinting it and without hitting the output-token ceiling. Matching tries exact first, then tolerates whitespace and indentation drift, always requiring a single unique anchor so a partial file is never written.
A tree-sitter symbol graph gives misterdev structural understanding of Python, Rust, TypeScript/JavaScript, Go, Java, C/C++, C#, Swift, and Kotlin. Per-file outlines plus a whole-project structural map feed planning and editing, and large files are sent as a symbol outline plus verbatim windows of the task-relevant symbols — so context and cost scale with the edit, not with the file.
Every change runs through an ordered gate sequence: build → lint → tests → typecheck, with optional gates layered on top — an adversarial critic (an independent second model that reviews each diff before it is applied), goal-check, claim-verifier, mutation scoring, runtime-smoke, web, and vision verification. A gate that fails RED blocks the change; a gate with nothing to check SKIPs and never blocks. Regressions are reverted via git, so a working tree only ever moves forward.
misterdev keeps a per-model performance ledger and pairs it with a cost-aware selector that picks for quality-per-dollar across the full breadth of OpenRouter — routing each task up a capability ladder (harvested free / cheap → a strong mid-tier → a frontier tier) and escalating to a stronger model only when a cheaper one can't clear the gates. The strongest tier is reserved for the final attempt, so frontier spend is the rare safety net, not the default; a hard task that a mid model stalls on is finished by a frontier model, while easy tasks resolve on free/cheap ones. Quality never drops because a weak model that writes bad code fails the gate and the policy climbs. It runs against OpenRouter or Anthropic with automatic failover, caches responses to avoid paying twice, and token budgeting keeps spend inside the ceiling you set.
Disjoint tasks run concurrently, each in its own isolated git worktree, so independent work doesn't contend for the tree. An integration gate re-checks each wave against the full suite and reverts any task that regresses it — parallelism without cross-contamination.
misterdev keeps a durable, fingerprinted stream of its own real failures and runs an AlphaEvolve-style keep-if-better loop over its own source: it attributes what breaks, classifies why (harness artifact vs observation gap vs capability), proposes a targeted structural self-edit, and promotes it only when it beats the champion on a held-out task set it never optimized against — with zero regressions. A reward-hacking guardrail walls off the tests and benchmark. The result is a loop that removes whole failure classes over time without overfitting to any one benchmark. See docs/path-to-100.md.
Run it with misterdev evolve --benchmark <polyglot-benchmark checkout> --workdir <scratch dir> (dry-run by default; add --live to actually apply/gate/promote, --from-failures to target the real-build failure stream instead of the benchmark's worst niche). evolution.benchmark_dir/evolution.noise_band in project.yaml set the defaults so a caller can omit the matching flags; both are opt-in and unset by default. An evolve_async MCP tool runs the same pass in the background (poll with job_status). A nightly --scheduled --live --from-failures pass also runs via .github/workflows/evolve.yml once the repo secret OPENROUTER_API_KEY is configured — gated by the same exclusive lock + circuit breaker, so an overlapping or repeatedly-failing trigger is a clean no-op.
On the correctness side, misterdev works reproduction-first: for an issue-driven task it synthesizes a failing test from the acceptance criteria, validates that the test actually fails on the clean tree (a test that reproduces nothing is discarded rather than trusted), then drives the fix to turn it green — so the model edits toward a concrete, verified target instead of a description.
Two-timescale evolution (built; opt-in via orchestrator.runtime_tooling; see docs/two-timescale-evolution.md) takes the self-improvement further than a memoryless runtime agent can. At runtime, the model may author a small task-specific helper tool that runs sandboxed (a hardened, network-less container — untrusted code never touches the host or the repo, and with no container engine the capability degrades off); its output feeds the edit. Every invented tool is then captured with the task's outcome into a tool corpus — a free byproduct of normal runs — and a deliberate promotion pass admits the tools whose success generalizes on a held-out task split (baseline drawn from the reproduction corpus) into a persistent, best-per-capability tool library that future runs start from. Fast loop invents; slow loop keeps only the winners; the same held-out gate that guards scaffold self-edits keeps the library general rather than benchmark-overfit. Capability compounds across runs instead of being reinvented each task — the memory the current top open-source scaffolds lack. Run the promotion pass with python -m misterdev.core.evolution.tool_promotion <project>.
Tools, gates, and targets self-register through Python entry points. pip install misterdev-plugin-x adds a capability with zero edits to the core — misterdev discovers the entry point at runtime and wires it in. A working example lives at examples/misterdev-plugin-hello. See Extending misterdev.
misterdev can connect to Model Context Protocol servers and let the model call their discovered tools mid-build — bounded, opt-in, and constrained by a tool allowlist. Transports include stdio and remote streamable-http with auth, so you can point it at a hosted MCP gateway like Glama and give the build access to a whole catalog of tools without running any of them locally.
Gate-verified pass@1 on Aider's polyglot benchmark (Exercism exercises with hidden test suites), anthropic/claude-sonnet-4-6:
Language | Solved | Rate |
JavaScript | 9 / 10 | 90% |
Python | 8 / 10 | 80% |
Rust | 7 / 10 | 70% |
A continuous stress run has solved 20/20 across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: docs/benchmark-results.md. Test suite: 1,941 passing — docs/TESTING.md.
Don't want to remember flags? Just describe what you want — no project setup or devplan required. misterdev routes it with zero friction:
$ misterdev "add rate limiting to the public API"
⠸ Building…Action words (add, fix, implement, write, create, …) go straight to
build — no LLM routing call, no confirmation prompt, no ceremony. Query and
management words (list, status, what, how, check, run, …) are
mapped with a model call, shown as a preview, and ask before anything mutating:
$ misterdev "check what's broken and fix it cheaply, run in parallel"
→ I'll run: misterdev build . fix broken tests --budget 5 --parallel
proceed? [Y/n]The flag-based commands below still work for scripts and power users.
The misterdev command drives everything:
Command | What it does |
| Discover projects under a directory and register them. |
| List all registered projects. |
| Show a project's tasks and their state. |
| Summarize the latest build's cost/tokens, per-model ledger performance, and the audit trail. Read-only — nothing is re-run. |
| Run pending tasks, or redirect to |
| Analyze the project, recommend work, and compose a plan interactively. |
| The autonomous build/debug/complete workflow. |
Plain misterdev with no subcommand launches interactive planning.
Flag | Effect |
| Max dollar budget for the run (default 100). |
| Commit after each completed task. |
| Execute independent tasks concurrently in isolated worktrees. |
| Plan only; show tasks without executing. |
| Wait for confirmation between tasks. |
| Skip the final validation phase. |
| Skip the suggest scan. |
| Disable auto-bisect/revert of a regressing task. |
| Restrict work to a specific area. |
| Allow building over uncommitted changes. |
| Cap the tasks this run will plan/execute (bounds cost). |
The prompt is free text or a mode word — debug, complete, review, or new <description>.
misterdev also ships as an MCP server (misterdev-mcp), so you can drive it
in plain English from Claude Desktop, Claude Code, Cursor, or any MCP client —
no flags to remember. The client just calls a tool (build, scan, status,
list_projects, run); the entire orchestration runs inside misterdev's own
process with its own model and context budget, and only a short summary
returns to the client — your codebase never enters the client's context window.
// Claude Desktop config (claude_desktop_config.json)
{
"mcpServers": {
"misterdev": {
"command": "misterdev-mcp",
"env": { "OPENROUTER_API_KEY": "sk-..." }
}
}
}Then just ask: "Have misterdev add rate limiting to the API, keep it under $5."
Mutating tools (build, run) refuse a dirty working tree and carry a
conservative default budget.
Claude Code integration. The build tool accepts a spec_text parameter.
Pass a complete spec written by Claude and misterdev skips its own analysis and
spec-generation phases, going straight to decompose → execute → verify using
your codebase's own gate suite. Claude handles the design; misterdev handles the
execution, correctness gates, and rollback:
# In Claude Code / MCP client
misterdev.build("/path/to/repo", spec_text="""
Feature: add a token-bucket rate limiter to /api/v1/*
...full spec...
""")Requires the mcp extra: pip install 'misterdev[mcp]'.
A plugin is an ordinary Python package that declares entry points in the misterdev.* groups. Install it, and misterdev picks it up — no core edits.
A tool is a class; a gate is a callable returning a GateOutcome:
# misterdev_plugin_hello.py
from misterdev.core.execution.outcomes import GateOutcome, GREEN, RED
class HelloTool:
gather_safe = True # opt into the agentic gathering loop
gather_description = "Return a friendly greeting for a name."
def __init__(self, config: dict):
self.name = config.get("name", "hello")
def execute(self, project, name: str = "world", **_ignored):
return True, f"Hello, {name}!"
def no_shouting_gate(ctx) -> GateOutcome:
build = (ctx.commands or {}).get("build_command") or ""
if build and build.isupper():
return GateOutcome(RED, "build_command is ALL CAPS; please calm down")
return GateOutcome(GREEN)# pyproject.toml — the entry points are the whole contract
[project.entry-points."misterdev.tools"]
hello = "misterdev_plugin_hello:HelloTool"
[project.entry-points."misterdev.gates"]
no_shouting = "misterdev_plugin_hello:no_shouting_gate"Targets register the same way through the misterdev.targets group. The full, runnable example — tool, gate, pyproject.toml, and notes — is at examples/misterdev-plugin-hello.
A project.yaml is created automatically when you first run misterdev in a directory — no setup required to get started. Drop a custom one in the repo root to specify build/test/lint commands, model, budget, and gates.
name: "My App"
language: "python"
build_command: "python -m compileall -q ."
test_command: "pytest -q"
lint_command: "ruff check ."
llm:
provider: "openrouter" # openrouter | anthropic
model: "anthropic/claude-sonnet-4-6"
api_key_env_var: "OPENROUTER_API_KEY"Key knobs:
Model & budget — llm.model, provider/failover, and the run's dollar ceiling (also --budget).
Gates — optional gates (adversarial critic, mutation, runtime-smoke, web, vision, goal-check) are off by default and enabled under the orchestrator.* keys.
MCP — declare servers under mcp.servers and enable tool use with orchestrator.mcp_enabled / orchestrator.mcp_tool_use; point at a remote gateway for hosted tool catalogs.
Targets — a targets: block gives a polyglot monorepo per-language build/test/lint, routed per task.
Guides: Getting started · Configuration · Plugins · MCP. project.yaml.example documents every configuration key.
Python 3.10 – 3.13
git (branch-per-task, worktrees, and rollback all run through it)
An API key for OpenRouter or Anthropic
Optional per-gate toolchains — a Playwright browser for the web gate, a language server for the LSP gate, an MCP SDK for the tool-host substrate (all installed via the matching extra)
git clone https://github.com/dcondrey/misterdev
cd misterdev
uv sync
uv run ruff check .
uv run pytest -qContributions are welcome — see CONTRIBUTING.md, and open an issue or a pull request on GitHub.
misterdev is dual-licensed:
AGPL-3.0-or-later — free for open-source use under the terms of the GNU Affero General Public License.
Commercial license — for use in a closed-source or proprietary product without AGPL obligations.
Choose the one that fits your project.
Set the approval flags on the proposed plan, then persist.
Use when: after ``propose_plan``/``get_plan`` you want to mark which items
should actually run. ``approve_all`` approves everything; otherwise
``approve_ids`` are approved and ``reject_ids`` un-approved (reject wins a
tie — the safer default). Idempotent. Then call ``execute_plan``. Related:
``propose_plan``, ``get_plan``, ``execute_plan``.
Side effects: rewrites ``.orchestrator/proposed_plan.json``; edits no code.
Returns ``{items: [...]}`` with updated flags, or ``{error}`` when no plan
exists to approve.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a project that has a proposed plan. | |
| reject_ids | No | Ids to un-approve. An id in both lists is rejected. | |
| approve_all | No | Approve every item in the plan. | |
| approve_ids | No | Ids to approve (as shown by get_plan, e.g. 'P-001'). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description confirms idempotency, details side effects (rewrites .orchestrator/proposed_plan.json, edits no code), and specifies return format (items with flags or error). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose sentence, usage paragraph with explicit flow, side effects, and return format. No redundant or unnecessary information. Every sentence adds value, and the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (return format described), annotations cover safety and idempotency, and schema covers parameters, the description completes the context by explaining side effects, the workflow position between propose_plan and execute_plan, and error conditions. It is fully self-contained for an agent to use 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 coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the tie-breaking rule ('reject wins a tie — the safer default') and the semantic relationship between approve_all, approve_ids, and reject_ids. This goes beyond the schema descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set the approval flags on the proposed plan, then persist.' It identifies the resource (proposed plan) and verb (set flags and persist). It distinguishes itself from sibling tools like propose_plan, get_plan, and execute_plan, and differentiates the approve_all parameter from the tool's core function.
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?
Explicit usage guidance: 'Use when: after propose_plan/get_plan you want to mark which items should actually run.' It contrasts with approve_all, explains conflict resolution (reject wins tie), and directs to call execute_plan afterwards. Also lists related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomously plan AND execute a goal in a project, from scratch.
Use when: you have a goal but no existing task plan — ``build`` analyzes the
project, decomposes ``goal`` into tasks, edits the code, and verifies each
change through build/test/lint/typecheck gates, reverting anything that
regresses. Do NOT use when: a task plan already exists and you just want to
execute it (use ``run``), or the working tree is dirty (commit/stash first).
Related: ``run`` (execute an existing plan), ``status`` (inspect tasks).
Pass ``reference_dir`` to port from an existing implementation: its
module/symbol map is extracted read-only and guides the plan.
Pass ``spec_text`` when you have already written the implementation spec
(e.g. in a Claude conversation) — misterdev skips its own planning phase
and executes your spec directly, making it Claude's execution backend.
DESTRUCTIVE side effects: edits files and makes git commits, and calls an
external LLM provider (open-world, non-idempotent). It refuses to run on a
dirty working tree. ``dry_run=True`` previews without changing anything;
``budget`` caps spend; ``max_tasks`` caps scope.
Returns a compact text report: what was done, per-gate results, and cost.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | Plain-English description of what to build, or a mode word: 'debug' (fix what's broken), 'complete' (finish unfinished work), or 'review'. Example: 'add rate limiting to the public API'. | |
| path | Yes | Absolute path to the project directory to build (containing project.yaml). Its git working tree must be clean. Example: '/Users/me/code/my-api'. | |
| budget | No | Maximum US dollars to spend on this run. Must be > 0; the run halts when reached. Example: 5.0. | |
| dry_run | No | When true, plan and preview the tasks without editing any code or spending beyond planning. Example: true. | |
| parallel | No | When true, run independent tasks concurrently in isolated git worktrees. Example: false. | |
| max_tasks | No | Cap how many tasks are planned/executed (bounds cost and scope). Must be >= 1; omit for no cap. Example: 5. | |
| spec_text | No | A complete implementation spec in markdown — supply this when you have already analysed the codebase and written the spec yourself (e.g. from a Claude conversation). misterdev will skip its own analysis and spec-generation phases and go straight to decompose → execute → verify using your spec. Omit to let misterdev analyse and generate the spec from ``goal``. | |
| reference_dir | No | Absolute path to a reference implementation to port from (often in another language). Its module/symbol map is extracted READ-ONLY and given to the planner so the build reproduces the reference's design idiomatically. Omit when not porting. Example: '/Users/me/code/donor-impl'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Builds on annotations (destructiveHint=true, etc.) by detailing side effects: edits files, makes git commits, calls external LLM, refuses on dirty tree, dry_run preview, budget caps, max_tasks caps. No contradiction.
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?
Well-structured: front-loaded with core purpose, then usage guidelines, then behavioral notes, then return. Every sentence is informative with no redundancies.
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 high-complexity tool (8 params, external LLM calls, destructive), the description covers purpose, guidelines, behavior, parameters, and return format. Completely adequate without 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 100%, but the description adds significant meaning beyond schema: explains mode words for goal, skips planning with spec_text, porting with reference_dir, budget halting, etc. Each parameter is enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Autonomously plan AND execute a goal in a project, from scratch.' with specific verb and resource. It distinguishes from siblings like 'run' and 'status' by stating when not to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when:' and 'Do NOT use when:', naming alternatives (run, status) and conditions (dirty working tree). Also provides guidance for spec_text and reference_dir parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an autonomous build in the BACKGROUND and return immediately.
Use when: the build may run for minutes and you want to keep working — this
returns a ``run_id`` right away instead of blocking (as the synchronous
``build`` does) until the run finishes. Poll ``job_status`` with the
``run_id`` to watch progress, ``stop_job`` to cancel, ``list_jobs`` to see
everything running. Do NOT use for a quick preview — use ``build`` with
``dry_run=True``. Related: ``build`` (synchronous), ``report`` (final outcome).
DESTRUCTIVE side effects (once running): edits files, makes git commits, and
calls an external LLM provider. Refuses to start a second job for a project
that already has one running (one writer per project).
Returns ``{run_id, status}`` on success, or ``{error}`` when a job is already
running for this project.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | What to build, or a mode word ('debug', 'complete', 'review'). Example: 'add rate limiting to the public API'. | |
| path | Yes | Absolute path to the project directory to build. Its git working tree must be clean. Example: '/Users/me/code/my-api'. | |
| budget | No | Maximum US dollars to spend; must be > 0. | |
| parallel | No | Run independent tasks concurrently in worktrees. | |
| max_tasks | No | Cap how many tasks are planned/executed; >= 1. | |
| reference_dir | No | Optional reference implementation to port from (analyzed read-only). See the synchronous ``build`` tool. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond destructiveHint=true, it details specific side effects (file edits, git commits, LLM calls) and the one-writer-per-project constraint, providing actionable knowledge for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise ~100-word paragraph front-loaded with main action, followed by usage guidance, behavioral warnings, and return value. Every sentence is necessary.
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 complexity (6 params, output schema), the description covers async behavior, destructive effects, concurrency limits, and return format. It also references sibling tools for post-invocation actions.
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 100%, so baseline is 3. The description adds little beyond cross-referencing 'reference_dir' to the synchronous build; no extra semantic enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a build in the background and returns immediately. It distinguishes from the synchronous 'build' sibling by highlighting the non-blocking behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (long builds), when not to use (quick preview, use dry_run), and directs to related tools for monitoring and control (job_status, stop_job, list_jobs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute the APPROVED items from a previously proposed plan.
Use when: ``propose_plan`` + ``approve_plan`` have selected the work and you
want it built — this composes a goal from the approved items and runs the
normal build pipeline (decompose, edit, verify, revert regressions). Do NOT
use before approving anything (it returns a no-op message). Related:
``propose_plan``, ``approve_plan``, ``build``.
DESTRUCTIVE side effects: edits files, makes git commits, and calls an
external LLM provider. Refuses a dirty working tree (like ``build``).
Returns a compact build report, or a message when nothing is approved.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a project with an approved plan. | |
| budget | No | Maximum US dollars to spend; > 0. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true), it discloses specific side effects: edits files, makes git commits, calls external LLM, refuses dirty working tree. Provides return value description.
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 paragraphs with front-loaded main action. Every sentence adds value, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists (assumed), description covers return value. Includes prerequisites, side effects, and usage context. Fully adequate for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description adds minimal extra meaning beyond the schema's parameter descriptions (path and budget). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes approved items from a previously proposed plan. It uses specific verbs like 'execute', 'build', and 'composes a goal', and distinguishes from siblings like 'propose_plan' and 'approve_plan'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: propose_plan + approve_plan have selected the work' and 'Do NOT use before approving anything'. Also lists related tools for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the persisted proposed plan and which items are approved.
Use when: you want to review the proposals from ``propose_plan`` (and see
what has been approved so far) before approving or executing. Read-only and
idempotent. Related: ``propose_plan``, ``approve_plan``, ``execute_plan``.
Returns ``{items: [...]}`` (empty ``items`` when no plan has been proposed).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a project that has a proposed plan. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds that items are empty when no plan exists, adding context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences that efficiently convey purpose, usage, and return format without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description adequately covers return values and empty case. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with a clear description for 'path'. Description does not add extra meaning beyond what schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns the proposed plan and approval state. Differentiates from siblings like propose_plan, approve_plan, execute_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when reviewing proposals before approving or executing. Mentions read-only and idempotent nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a background job's current state.
Use when: you started a job with ``build_async``/``run_async`` and want to
know whether it is still ``running`` or has ``succeeded``/``failed``/
``stopped`` — and, when finished, its report (``result``) or ``error``.
Read-only and idempotent. Related: ``list_jobs`` (all jobs), ``stop_job``.
Returns the job object (run_id, kind, project_path, status, result, error,
timestamps), or ``{error}`` when the run_id is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id returned by build_async or run_async. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: it returns result/error when finished, and returns error for unknown run_id. This goes beyond the structured fields.
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?
Four sentences covering purpose, usage, related tools, and return value. No wasted words; front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with an output schema, the description explains all necessary aspects: when to use, what it returns, error handling, and idempotency. Completely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter description already in the schema. The description reinforces the usage context (run_id comes from async methods), adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Return a background job's current state.' It distinguishes itself from sibling tools like list_jobs (all jobs) and stop_job, making its purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: after starting a job with build_async/run_async. Mentions what statuses to expect and alternative tools, providing clear guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every background job this server has started and their states.
Use when: you want an overview of all ``build_async``/``run_async`` jobs —
running and finished — e.g. to find a lost run_id. Read-only, idempotent.
Related: ``job_status`` (one job), ``stop_job``.
Returns ``{jobs: [...]}``, each entry the same object ``job_status`` returns.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds that the tool is 'Read-only, idempotent' (consistent with annotations) and describes return format as '{jobs: [...]}' matching job_status output. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all essential: purpose, usage guidelines, return format. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and output schema exists, description fully explains tool behavior, usage context, and return structure. No 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?
Zero parameters, schema coverage 100% — baseline 3. Description adds return format details (same object as job_status) which adds context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List every background job this server has started and their states' — a specific verb+resource combination. It distinguishes from siblings like job_status (one job) and stop_job.
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?
Explicit 'Use when' clause explains the scenario (overview of build_async/run_async jobs, finding lost run_id) and names alternatives (job_status, stop_job).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every project misterdev currently knows about.
Use when: you need to discover which projects are registered before calling
``status``, ``build``, or ``run`` on a specific one. Do NOT use when: the
project isn't registered yet — call ``scan`` first to register it. Related:
``scan`` (register projects), ``status`` (inspect one project). Takes no
parameters.
Side effects: none — read-only, calls no LLM, and returns the same result on
repeated calls (idempotent).
Returns a mapping of project id to an object with its registered ``path`` and
``name``; an empty mapping when nothing is registered.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond annotations: describes no side effects, read-only, no LLM calls, idempotent (same result on repeated calls). Annotations already had readOnlyHint and idempotentHint, but description expands.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured, front-loaded with purpose. Every sentence adds value: usage, side effects, return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers what the tool does, when to use, behavioral properties, and return structure. No gaps given zero parameters and simple output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, and description explicitly states 'Takes no parameters.' Schema coverage is 100% (no params), so baseline 4. Description adds no extra parameter info but correctly notes absence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every project misterdev currently knows about.' It specifies the verb 'list' and resource 'projects', and distinguishes from siblings like scan, status, build, run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('need to discover which projects are registered before calling status, build, or run') and when-not-to-use ('project isn't registered yet — call scan first'), including alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the project and return ranked, UNAPPROVED work proposals.
Use when: you want misterdev to recommend what to work on and let a human
approve a subset BEFORE any code is edited — the review gate. The proposals
are persisted, so ``get_plan`` re-reads them, ``approve_plan`` marks a
subset, and ``execute_plan`` builds the approved ones. The codebase is
analyzed in this process, so it never enters the client's context. Do NOT
use to execute immediately without review — that is ``build``. Related:
``get_plan``, ``approve_plan``, ``execute_plan``.
Side effects: spends LLM budget analyzing the project and writes the plan to
``.orchestrator/proposed_plan.json``; it edits NO source code.
Returns ``{items: [...]}`` — each item has an id, title, work_type,
rationale, and ``approved: false`` — or ``{error}`` on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the project to analyze. Example: '/Users/me/code/my-api'. | |
| budget | No | Maximum US dollars to spend on analysis; > 0. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, describes side effects: spends LLM budget, writes to .orchestrator/proposed_plan.json, edits no source code. Complements readOnlyHint=false and destructiveHint=false with concrete behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, usage, side effects, return value. Every sentence serves a function. Front-loaded with main action and outcome. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects: what it does, when to use, not to use, side effects, return format. Includes output schema info and references sibling tools. No gaps identified.
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 100% so description adds limited value. Mentions budget's purpose in side effects but doesn't detail parameter constraints beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it analyzes the project and returns ranked, unapproved work proposals. Distinguishes from siblings like build, get_plan, approve_plan, execute_plan by naming them and contrasting use cases.
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?
Explicit 'Use when' section explains the review gate purpose. Directly states 'Do NOT use to execute immediately without review — that is `build`.' Lists related tools for workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the latest build report, audit trail, and model performance.
Use when: a ``build`` or ``run`` has finished (or was stopped) and you want
the outcome — which tasks completed/failed/deferred, per-file edits, failed
commands, governance escalations, unmet-goal gaps, token/cost totals, and
per-model success rates. This is misterdev's read-only equivalent of asking
"what did the last run find and do?". Do NOT use when: nothing has been
built yet — ``latest_report`` will be null. Related: ``status`` (live task
states), ``build``/``run`` (produce a report).
Side effects: none — reads only the project's ``.orchestrator`` artifacts,
calls no LLM, and returns the same result on repeated calls (idempotent).
Returns an object with ``latest_report`` (the most recent build's structured
summary, or null), ``audit`` (command/edit/governance counts), and
``models`` (per-model attempts, success rate, and average cost). Returns an
``error`` field instead when ``path`` is not an existing directory.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a project directory that has been built at least once. Reads only misterdev's own ``.orchestrator`` artifacts under it. Example: '/Users/me/code/my-api'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds concrete behavioral details: 'reads only the project's .orchestrator artifacts, calls no LLM, and returns the same result on repeated calls (idempotent).' Also notes error handling when path is invalid. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: lead sentence, when-to-use section, side effects, and return value summary. It is appropriately sized for the tool's complexity, with every sentence contributing useful information. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and an output schema (not shown but present), the description covers all necessary aspects: prerequisites, return structure (latest_report, audit, models, error), and side effects. It is complete for an agent to use 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 coverage is 100% and the schema already describes the 'path' parameter well. The main description adds the error condition context ('Returns an error field instead when path is not an existing directory'), which provides additional meaning beyond the schema. Score 4 reflects this added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Return the latest build report, audit trail, and model performance.' It distinguishes from sibling tools like 'status' (live task states) and 'build'/'run' (produce a report), ensuring the agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Use when: a build or run has finished... Do NOT use when: nothing has been built yet...' and names related tools ('status', 'build', 'run') as alternatives. This leaves no ambiguity about when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a project's ALREADY-PLANNED pending tasks (a devplan).
Use when: tasks already exist (from a prior ``plan`` or a devplan directory)
and you want to execute them. Do NOT use when: no plan exists and you are
starting from a goal — that is ``build``'s job (it analyzes and decomposes).
Related: ``build`` (plan + execute a goal), ``status`` (see the task ids).
Pass ``task_id`` to run a single task.
DESTRUCTIVE side effects: edits files and makes git commits, and calls an
external LLM provider (open-world, non-idempotent). ``dry_run=True`` previews
without changing anything.
Returns a short text summary of what was run or previewed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a registered project's directory that already has planned tasks (a devplan). Example: '/Users/me/code/my-api'. | |
| dry_run | No | When true, preview the tasks that would run without executing or editing anything. Example: true. | |
| task_id | No | Run only this single task id (as shown by ``status``); omit to run all pending tasks in dependency order. Example: '010-add-auth'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds detail beyond annotations: specifies destructive effects (edits files, git commits, external LLM calls) and non-idempotency. Mentions dry_run to preview.
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 concise paragraphs: purpose/usage, side effects, return value. Front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use/not, side effects, return format, and parameter guidance. No gaps given schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% with clear param descriptions. Description adds context on task_id usage ('run a single task') but mostly redundant with schema. Slight value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Execute' on resource 'ALREADY-PLANNED pending tasks (a devplan)'. Differentiates from sibling tools like build and status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (tasks already exist) and when not (no plan, starting from goal, use build instead). Names related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start executing a project's planned tasks in the BACKGROUND.
Use when: a devplan exists and you want it executed without blocking — like
``run`` but returns a ``run_id`` immediately. Poll ``job_status``, cancel
with ``stop_job``. Do NOT use to plan from a goal — that is ``build_async``.
Related: ``run`` (synchronous), ``build_async``.
DESTRUCTIVE side effects (once running): edits files, makes git commits, and
calls an external LLM provider. Refuses a second job for a project that
already has one running.
Returns ``{run_id, status}``, or ``{error}`` when one is already running.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a project with planned tasks (a devplan). Example: '/Users/me/code/my-api'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes destructive side effects (edits files, git commits, calls LLM) and refusal of second job, adding context beyond the annotations which already set destructiveHint=true.
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 very concise, with the purpose stated first, followed by usage guidelines and behavioral details, all in a few sentences without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an async job with destructive effects, the description covers return values, error case (job already running), and side effects. The output schema is referenced but not detailed, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a detailed description of the 'path' parameter, including examples and requirements. The tool description adds little extra meaning, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts executing planned tasks in the background, using the verb 'Start' and resource 'project's planned tasks'. It also distinguishes from siblings like 'run' (synchronous) and 'build_async'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (devplan exists, want async) and when not to (planning from a goal, use build_async). Lists alternatives: 'run' (synchronous) and 'build_async'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover misterdev projects under a directory and add them to the registry.
Use when: you have projects on disk that misterdev does not know about yet,
before calling ``status``, ``build``, or ``run`` on them. Do NOT use when:
the projects are already registered (call ``list_projects`` to check) — a
re-scan is harmless but redundant. Related: ``list_projects`` (see what is
registered), ``status`` (inspect a registered project).
Side effects: writes only to misterdev's project registry — it never reads,
edits, or executes any project code, and re-scanning the same directory is
idempotent (no duplicates).
Returns a short confirmation string naming the directory scanned.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Absolute path to an existing, readable directory to search recursively for misterdev projects (directories containing a project.yaml). Must be a directory, not a file. Example: '/Users/me/code'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details side effects: writes only to the registry, never reads/edits/executes code, and is idempotent. Annotations already provide idempotentHint=true and destructiveHint=false, and the description adds specificity and reassurance, with no contradiction.
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 well-structured with three short paragraphs: purpose, usage guidelines, and side effects/return. It is front-loaded and every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool simplicity (1 param, output schema exists), the description covers purpose, usage, side effects, and return value. It also references siblings and provides enough context for an agent to decide when to invoke.
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 100% for the single parameter. The description adds value by mentioning recursive search and the condition 'directories containing a project.yaml', which are not in the schema. Baseline is 3, and this extra context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers and registers misterdev projects under a directory. It distinguishes itself from siblings by mentioning 'list_projects' and 'status' as related but different tools, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use (before status/build/run) and when not to use (projects already registered, with reference to list_projects), and gives related alternatives. This is comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a project's tasks and their current state.
Use when: you want to inspect what work exists and how far it has progressed,
e.g. before deciding whether to ``run`` pending tasks or ``build`` new work.
Do NOT use when: the project isn't registered — call ``scan`` first, or
``list_projects`` to find the right path. Related: ``list_projects``,
``run``, ``build``.
Side effects: none — read-only, calls no LLM, idempotent.
Returns the project's tasks, each with its id, title, and status.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a registered project's directory (the one containing its project.yaml). Must be a directory that has been registered via ``scan``. Example: '/Users/me/code/my-api'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate readOnly and idempotent, the description adds 'calls no LLM' and confirms 'no side effects', enhancing transparency beyond structured fields.
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 well-structured and concise, front-loading the purpose and efficiently covering usage, side effects, and return value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description fully covers behavior, usage constraints, and return value, leaving no 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 100%, so baseline is 3. The description does not add parameter-level details beyond what the schema provides, but the schema itself is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Show a project's tasks and their current state' with a specific verb and resource. It distinguishes from siblings by explicitly mentioning related tools and usage contexts.
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 provides explicit 'Use when' and 'Do NOT use when' conditions, including alternatives like 'scan' and 'list_projects', giving clear situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request cooperative cancellation of a running background job.
Use when: a ``build_async``/``run_async`` job should stop — it finishes any
in-flight task and starts no new work, then produces a partial report. Poll
``job_status`` afterward to confirm it reaches ``stopped``. Idempotent:
stopping a finished or already-stopped job is a harmless no-op. Related:
``job_status``, ``list_jobs``.
Returns ``{run_id, stopping: true}`` when a running job was signalled, or
``{run_id, stopping: false}`` when the id is unknown or already finished.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id of the job to stop. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds cooperative cancellation details, partial report production, and idempotency behavior beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise with structured bullet points and front-loaded purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete coverage including return value documentation, idempotency, and post-invocation steps. No gaps given the tool's simplicity and existing output schema.
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 100% for the single parameter run_id. The description does not add extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's verb (stop) and resource (running background job), and distinguishes it from sibling tools like job_status and list_jobs by mentioning build_async/run_async jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (for build_async/run_async jobs) and what to do after (poll job_status). Provides clear context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.6.0approve_planbuild2 fields changedInput schema / properties / reference_dirAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Absolute path to a reference implementation to port from (often in another language). Its module/symbol map is extracted READ-ONLY and given to the planner so the build reproduces the reference's design idiomatically. Omit when not porting. Example: '/Users/me/code/donor-impl'.",
+ "examples": [
+ "/Users/me/code/donor-impl"
+ ],
+ "title": "Reference Dir"
+}Input schema / properties / spec_textAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A complete implementation spec in markdown — supply this when you have already analysed the codebase and written the spec yourself (e.g. from a Claude conversation). misterdev will skip its own analysis and spec-generation phases and go straight to decompose → execute → verify using your spec. Omit to let misterdev analyse and generate the spec from ``goal``.",
+ "title": "Spec Text"
+}build_asyncexecute_planget_planjob_statuslist_jobspropose_planreportrun_asyncstop_jobv0.2.2build15 fields changedInput schema / properties / budget / descriptionPrevious value: -"Maximum dollars to spend on this run."New value: +"Maximum US dollars to spend on this run. Must be > 0; the run halts when reached. Example: 5.0."Input schema / properties / budget / examplesAdded value: +[
+ 5,
+ 25
+]Input schema / properties / dry_run / descriptionPrevious value: -"Plan and preview tasks without editing any code."New value: +"When true, plan and preview the tasks without editing any code or spending beyond planning. Example: true."Input schema / properties / dry_run / examplesAdded value: +[
+ false,
+ true
+]Input schema / properties / goal / descriptionPrevious value: -"Plain-English goal, or a mode word: 'debug', 'complete', or 'review'."New value: +"Plain-English description of what to build, or a mode word: 'debug' (fix what's broken), 'complete' (finish unfinished work), or 'review'. Example: 'add rate limiting to the public API'."Input schema / properties / goal / examplesAdded value: +[
+ "add rate limiting to the public API",
+ "debug",
+ "complete"
+]Input schema / properties / goal / minLengthAdded value: +1Input schema / properties / max_tasks / anyOfPrevious value: -[
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "minimum": 1,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / max_tasks / descriptionPrevious value: -"Cap how many tasks are planned/executed (bounds cost)."New value: +"Cap how many tasks are planned/executed (bounds cost and scope). Must be >= 1; omit for no cap. Example: 5."Input schema / properties / max_tasks / examplesAdded value: +[
+ 5,
+ 10
+]Input schema / properties / parallel / descriptionPrevious value: -"Run independent tasks concurrently in isolated git worktrees."New value: +"When true, run independent tasks concurrently in isolated git worktrees. Example: false."Input schema / properties / parallel / examplesAdded value: +[
+ false,
+ true
+]Input schema / properties / path / descriptionPrevious value: -"Path to the project to build (its directory)."New value: +"Absolute path to the project directory to build (containing project.yaml). Its git working tree must be clean. Example: '/Users/me/code/my-api'."Input schema / properties / path / examplesAdded value: +[
+ "/Users/me/code/my-api"
+]Input schema / properties / path / minLengthAdded value: +1run7 fields changedInput schema / properties / dry_run / descriptionPrevious value: -"Preview the tasks without executing them."New value: +"When true, preview the tasks that would run without executing or editing anything. Example: true."Input schema / properties / dry_run / examplesAdded value: +[
+ false,
+ true
+]Input schema / properties / path / descriptionPrevious value: -"Path to the project."New value: +"Absolute path to a registered project's directory that already has planned tasks (a devplan). Example: '/Users/me/code/my-api'."Input schema / properties / path / examplesAdded value: +[
+ "/Users/me/code/my-api"
+]Input schema / properties / path / minLengthAdded value: +1Input schema / properties / task_id / descriptionPrevious value: -"Run only this task id; omit to run all pending tasks."New value: +"Run only this single task id (as shown by ``status``); omit to run all pending tasks in dependency order. Example: '010-add-auth'."Input schema / properties / task_id / examplesAdded value: +[
+ "010-add-auth",
+ "T-003"
+]scan3 fields changedInput schema / properties / directory / descriptionPrevious value: -"Directory to search recursively for projects to register."New value: +"Absolute path to an existing, readable directory to search recursively for misterdev projects (directories containing a project.yaml). Must be a directory, not a file. Example: '/Users/me/code'."Input schema / properties / directory / examplesAdded value: +[
+ "/Users/me/code",
+ "/workspace/repos"
+]Input schema / properties / directory / minLengthAdded value: +1status3 fields changedInput schema / properties / path / descriptionPrevious value: -"Path to the project (its directory, containing project.yaml)."New value: +"Absolute path to a registered project's directory (the one containing its project.yaml). Must be a directory that has been registered via ``scan``. Example: '/Users/me/code/my-api'."Input schema / properties / path / examplesAdded value: +[
+ "/Users/me/code/my-api",
+ "/workspace/repos/service"
+]Input schema / properties / path / minLengthAdded value: +1v0.2.1buildlist_projectsrunscanstatusEach tool has a distinct purpose with clear guidance on when to use and when not. 'build' is for complete planning and execution, 'run' is for executing existing plans, 'status' inspects tasks, 'list_projects' lists registered projects, and 'scan' registers new projects. The descriptions explicitly differentiate overlapping tools like 'build' and 'run'.
All tool names use lowercase with snake_case for multi-word names (e.g., list_projects). They follow a consistent verb or verb_noun pattern (build, run, scan, status - 'status' is a noun but used as a command). No mixing of conventions.
Five tools cover the core workflow of project discovery, registration, status inspection, execution of plans, and full build from goal. The count is well-scoped for this domain without being too few or excessive.
The tool surface covers registration (scan), listing (list_projects), status (status), execution (run), and full build from goal (build). A minor gap is the absence of a separate plan-only tool (though build can be used with dry_run for preview). No tool for updating or removing projects from the registry, but that may be out of scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dcondrey/misterdev'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
