This server lets Claude Code route coding tasks to a fleet of local Ollama machines and remote AI providers, manage the fleet, track savings, and improve routing over time.
Delegate tasks: fleet_delegate runs a single small coding job on the best available model (by category, node, files, context, output path, JSON schema).
Parallel batches: fleet_delegate_batch applies one instruction to many files across all nodes with output patterns.
Fleet status & usage: fleet_status shows node health, routing, savings, and when benchmark/setup is due; fleet_usage reports tokens, costs, quotas, and Claude token savings.
Setup and node management: fleet_setup probes Ollama servers and writes fleet.toml; fleet_nodes adds/removes/enables/disables machines or remote providers (Gemini, Groq, OpenRouter, etc.) with limits, costs, and key env vars.
Background work & queue: fleet_job polls long tasks/batches/benchmarks; fleet_queue queues work to run while Claude is paused.
Feedback and learning: fleet_feedback records good/fixed/rejected verdicts to train the router.
Benchmarking: fleet_bench runs a self-learning benchmark (quick/full, explore, deep) that grades models and suggests configuration changes.
Model downloads: fleet_pull pulls a model onto a node via Ollama.
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., "@io.github.bdbais/routeai Write unit tests for src/utils.py and show me a preview of the changes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Claude Code plugin that routes small coding jobs to the AIs you already have — the Ollama machines on your network and the free tiers of providers like Gemini, Groq or OpenRouter — while Claude decides what to delegate and checks every result. Fewer Claude tokens, work in parallel, and free capacity used before paid.
Website, in 13 languages: https://routeai.bais.info
Claude Code ──(MCP, stdio)──► RouteAI ──► desktop with GPU complex code, functions
decides, briefs, router laptop (CPU) tests, scripts, build, docs
reviews, gives feedback learned Gemini / Groq free docs, extraction, overflow
stats + cost any paid API only when you allow itClaude is the best engineer on the team, and the most expensive. Plenty of the work in a coding session
is well defined and easy to check: unit tests for a module, a CLI script, docstrings, a CI workflow, a
pyproject.toml, working out why a build failed, or the same mechanical edit on forty files. A 7–30B model
running at home does these for free, while Claude keeps the design, the hard parts and the final review.
Related MCP server: local-agent
Priority routing by machine power. Each task category prefers a tier. complex and code go to the
fast GPU machine; tests, scripts, build and docs go to the slower machines. A task only moves to
the other tier when the preferred machines are busy.
It learns as it goes. Among suitable candidates the router ranks by measured quality² ÷ expected time. Expected time includes prompt processing, generation, model load or swap, and queue wait. Quality comes from the benchmark and from Claude's feedback on real work.
A benchmark that grades itself, meant to be run from time to time until the fleet "knows" your hardware. There are 10 tasks, each checked automatically:
code is run against hidden unit tests;
generated tests are mutation-tested against 4 buggy variants;
scripts are run with sample input and their output compared;
config files are checked by parsing the TOML;
docstrings are checked with AST comparison;
log diagnoses are checked against a strict JSON schema.
Probes also measure how much of each model sits in VRAM and how throughput scales with parallel
requests. The result is a report with concrete suggestions for fleet.toml.
Claude never pastes files. The server reads project files itself (paths or globs), can write results straight to disk, and returns only a preview.
Parallel batches. One instruction runs over many files, spread across every machine.
Claude stays in charge. The benchmark only suggests configuration changes; Claude proposes them and you approve them.
No dependencies. It needs only Python 3.11+ and Ollama. No pip install and no SDK.
Beyond local machines, RouteAI talks to any OpenAI-compatible provider — Gemini, Groq, OpenRouter, DeepSeek, Mistral, OpenAI, or your own vLLM/LM Studio endpoint:
/routeai:add-ai gemini gem1Three rules keep it safe and cheap:
The key never touches the configuration or the chat. You put it in an environment variable
(GEMINI_API_KEY, GROQ_API_KEY, …) and the node stores only that variable's name.
Your files stay home unless you say otherwise. A provider only receives project files when its node has
send_files = true; without it, it is skipped for any task that includes files.
Free first, then paid, then nothing. Set [nodes.cost] (USD per million tokens, 0 for a free tier) and a
[nodes.limits] cap: daily requests or tokens for free tiers, daily_cost_usd for paid ones. The router
prefers free nodes, stops using a node when its limit is reached, and falls back to your own machines.
/routeai:usage then shows tokens, cost and remaining quota per node.
Claude Code
Python 3.11 or newer. The launcher in bin/ finds it by itself: py -3 or python on Windows,
python3.14…python3.11, python3 or python on macOS/Linux. Set ROUTEAI_PYTHON to force one.
(The system python3 of macOS is 3.9: install a newer one, e.g. with Homebrew.)
One or more machines running Ollama. On machines other than the one running
Claude Code, set OLLAMA_HOST=0.0.0.0 so Ollama listens on the LAN.
Tested end to end on Windows 11 with two Ollama machines; the unit tests run on Windows, macOS and Linux in CI.
In Claude Code:
/plugin marketplace add bdbais/routeai
/plugin install routeai@baisTrying it out to review it? REVIEWER-GUIDE.md is a 20-minute test plan: what to run,
what to look for, the known limits, and what makes a bug report actionable.
Then, in a new session, describe your machines:
/routeai:setup gpu=http://192.168.1.13:11434 local=http://localhost:11434Setup probes each Ollama server, picks the installed models per category (models are set per machine and per
category, because the right model depends on each machine's power), lists recommended models that are missing
with their size and hardware needs — and downloads them only if you say so — then writes
~/.routeai/fleet.toml. You can also edit that file by hand; see config/fleet.example.toml.
With no config at all, the plugin uses the local Ollama only.
Let the fleet learn your hardware, then check routing and savings:
/routeai:bench
/routeai:statusEvery finished task reports how many Claude tokens it saved (this task, session and all-time), and Claude tells you in one line. It is an estimate: the tokens of the files the worker read plus the tokens it generated, minus the brief Claude wrote and the result Claude read. Tiny tasks can come out negative — delegation pays off on substantial inputs/outputs and on batches, where one brief covers many files. Measured on the test fleet: pytest tests for a ~100-line module saved ~1,200 Claude tokens (15 s on the GPU box); Markdown references for two modules, as a batch split across both machines, saved ~4,800.
You don't have to do anything special. The delegate skill teaches Claude when a sub-task is worth
delegating, how to write a self-contained brief, and how to verify the result. You can also ask directly:
"use the fleet to write tests for every module in src/parsers/".
Tool | Purpose |
| Shows node health, loaded and missing models, where each category routes, tokens saved, and whether a benchmark or setup is due |
| Probes your Ollama servers, picks models per category, suggests models to pull, writes |
| Adds, removes, enables or disables one machine, keeping the other machines' settings |
| Ollama tokens processed per machine and model, with totals, plus the Claude tokens saved |
| Queues work the fleet finishes on its own while Claude is paused; lists and clears it |
| Runs one task: |
| Runs the same instruction on many files in parallel, e.g. |
| Reports progress and results of a batch, a long task or a benchmark |
| Records |
| Runs the self-learning benchmark ( |
| Downloads a model onto a node |
The same features are available from the command line (bin/routeai is also on the PATH of Claude's
Bash tool while the plugin is enabled):
python run.py init --node gpu=http://192.168.1.13:11434 # same as /routeai:setup
python run.py status # health + routing preview + savings + bench advice
python run.py nodes add gpu2=http://192.168.1.20:11434 # also: list, remove, enable, disable
python run.py usage --days 7 # Ollama tokens per machine + savings, last week
python run.py queue work # keep working the queue while Claude is paused
python run.py bench --mode quick --deep # graded benchmark + parallel probe
python run.py bench --mode full --explore # also try installed models you haven't configuredStats, the task log and reports are kept in ~/.routeai/.
fleet_status tells you when a run is due:
While learning (a model/category pair has fewer than 5 samples, or its recent scores disagree): every 2–3 days, or after adding models.
Once stable: monthly, or after a hardware change.
Every real task also updates speed statistics, and every fleet_feedback updates quality. The benchmark is
how new models and machines earn trust quickly.
Pin num_ctx. Ollama's default context can push a model out of VRAM; on a 12 GB GPU,
qwen2.5-coder:14b went from 7 to 49 tokens/s at num_ctx = 8192. Context is fixed per model on purpose,
because changing it between requests forces a reload.
MoE models suit small GPUs. qwen3-coder:30b still produces about 28 tokens/s when half of it is
offloaded to the CPU.
CPU-only laptops still help. Give them small coder models (3–7B) for scripts, tests and docs, and
max_parallel = 1 so your own work stays responsive.
Rented or remote servers: reach them over SSH (below), not with port 11434 open. Ollama has no authentication of its own.
Ollama has no authentication, so a machine outside your LAN should never expose port 11434. RouteAI reaches it
through the SSH access you already have: Ollama keeps listening only on 127.0.0.1 over there, and each request
travels through a tunnel that RouteAI opens, keeps alive and reopens when it drops.
First time, in your own terminal (not through Claude: ssh asks for the password there):
python run.py ssh-setup linux-gpu you@your-server1/5 reaching you@your-server DNS, then the SSH port
2/5 key: created ~/.routeai/ssh/id_ed25519_linux-gpu
3/5 installing it on you@your-server ssh shows the server fingerprint and asks for the password
4/5 opening the tunnel with the key alone
5/5 saving the nodeThe password is typed into ssh itself and used once, to install a dedicated key; RouteAI never sees or stores
it. The key is installed restricted:
restrict,port-forwarding,permitopen="127.0.0.1:11434",command="/bin/false" ssh-ed25519 AAAA… routeai-linux-gpuso it can open this one tunnel and nothing else - no shell, no other ports. A stolen copy reaches your Ollama, not
your server. (--full-access installs it without restrictions; --remote-port if Ollama listens elsewhere.)
Already log in with a key? Skip all that: python run.py ssh-setup linux-gpu gpu-box --use-ssh-config, or add
it from Claude with /routeai:nodes add linux-gpu=ssh://gpu-box. Your ~/.ssh/config, agent and known_hosts
are used as they are.
In fleet.toml the node has ssh instead of url:
[[nodes]]
name = "linux-gpu"
ssh = "you@your-server" # or an ~/.ssh/config alias, or user@host:2222
ssh_key = "C:/Users/you/.routeai/ssh/id_ed25519_linux-gpu"When something breaks, python run.py ssh-check linux-gpu tests DNS, the SSH port, authentication and Ollama one
stage at a time and says what to do. The server's fingerprint is pinned at setup: if it ever changes the tunnel
refuses to open; after a legitimate reinstall, python run.py ssh-forget linux-gpu and run ssh-setup again.
Tunnels use the system ssh client (OpenSSH, built into Windows 10+, macOS and Linux) with BatchMode, so they
never wait for a prompt. They are closed when RouteAI exits; on Windows they die with it even if it is killed.
Provider keys are read from environment variables only: they are never written to fleet.toml, never
logged, and requests never follow redirects, so a key cannot be forwarded elsewhere.
A remote provider receives project files only if you set send_files = true for it.
The server only reads and writes files inside the project, plus any allowed_roots you list (explicit paths;
globs are relative to the project). Network (UNC) paths are refused before they are touched.
Worker output is written before Claude reviews it, so it is never written into .git/, .claude/,
node_modules/, virtualenvs or editor folders, where a file could run code or change tool settings.
Globs skip dotfiles and secret-looking files (.env, *.pem, *.key, credentials…); list such a file
explicitly only if you really want a local model to see it.
An answer cut off at max_output_tokens is reported as a failure and never written over a file.
Requests to nodes never follow redirects, so a node's bearer token cannot be forwarded elsewhere.
:cloud models, which run on ollama.com, are never used unless allow_cloud_models = true.
SSH nodes: the password is only ever typed into ssh in your terminal; the dedicated key can open the tunnel to
Ollama and nothing else; the host fingerprint is pinned; targets that could be read as ssh options (-o…,
spaces, quotes) are refused; the local end of a tunnel listens on 127.0.0.1 only.
Traffic to nodes bypasses system HTTP proxies, so LAN requests are not sent through a corporate proxy.
The benchmark runs code written by your local models in a temporary folder with a timeout and a minimal environment. That is enough for its small, fixed prompts, but it is not a security sandbox.
Don't delegate secrets. The delegate skill tells Claude never to send .env or credential files.
Install or refresh the plugin from a local checkout on Windows, including validation, tests, the fleet config
and a server smoke test (run it again after every change; -Uninstall removes it):
powershell -ExecutionPolicy Bypass -File scripts\install.ps1python -m unittest discover -s tests -v # no Ollama needed (live tests are skipped)
ROUTEAI_LIVE=1 python -m unittest tests.test_live -v # drives the real MCP server against your fleet
node site/build.mjs # showcase site; fails on any missing translation
claude --plugin-dir . # try the plugin from a checkoutThe live test uses your fleet.toml but a temporary home and project, so your learned statistics stay untouched.
If RouteAI saves you tokens, you can buy me a coffee on PayPal ☕ or star the repo.
Independent open-source project, not affiliated with Anthropic or Ollama. MIT licensed.
Start the self-learning benchmark in the background: graded coding tasks per category on every node/model, plus optional resource probes. Returns a job_id; the finished job contains a report with recommendations for fleet.toml.
| Name | Required | Description | Default |
|---|---|---|---|
| deep | No | Probe parallel throughput per node. | |
| mode | No | quick | |
| nodes | No | ||
| models | No | ||
| explore | No | Also try installed models that are not configured. | |
| categories | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the benchmark runs in the background, returns a job_id, and that the finished job contains a report with recommendations. This adds useful behavioral context beyond the schema. However, with no annotations, it does not address potential side effects, idempotency, or whether it modifies configuration. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core action ('Start the self-learning benchmark in the background') before adding details. It avoids redundancy and each clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, async behavior, and output (job_id/report). However, it omits prerequisites (e.g., whether fleet_setup must be run first), does not explain the 'mode' parameter, and the phrase 'every node/model' is potentially contradictory with the optional 'nodes' and 'models' parameters. Given 6 parameters and no output schema, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context for categories, nodes, models, and optional probes, but does not explain the 'mode' parameter (quick/full) or elaborate on 'explore' beyond its schema description. With only 33% schema coverage, the description partially compensates but leaves key parameters like mode ambiguous. It provides some added meaning but not complete.
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 a specific action: 'Start the self-learning benchmark in the background' with details about graded coding tasks and optional resource probes. It distinguishes from siblings by focusing on starting a benchmark, unlike fleet_status (status) or fleet_setup (configuration). The scope is 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?
No explicit guidance on when to use this tool vs alternatives. It does not mention any exclusions, prerequisites, or direct comparison to sibling tools like fleet_delegate or fleet_job. The implied use case is 'when you want to run a benchmark', but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delegate ONE small task to a local model and get the result. The server reads files itself. With output_path the answer is written to that file and only a preview comes back. Long tasks return a job_id to poll with fleet_job. complex/code → fast GPU node first; tests/scripts/build/docs → light nodes first (overflow to the other tier when busy); general → any; auto → keyword guess.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | Force a node by name (normally leave empty). | |
| files | No | Project-relative paths or globs (e.g. src/**/*.py) to include. | |
| model | No | Force a model (normally leave empty). | |
| context | No | Extra context: conventions, interfaces, examples. | |
| category | No | auto | |
| overwrite | No | ||
| instruction | Yes | Self-contained brief: what to produce, constraints, conventions, acceptance criteria. The worker sees only this, `context` and `files`. | |
| json_schema | No | JSON Schema for structured output; parsed JSON is returned in `json`. | |
| output_path | No | Project-relative file to write the result to. | |
| wait_seconds | No | Max wait before returning a job_id (default from config). | |
| max_output_tokens | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it discloses several important behaviors: the server reads files itself, output_path writes the answer to a file and returns only a preview, long tasks return a job_id, and node selection follows category-based routing with overflow. It leaves failure semantics, overwrite side effects, and the exact response envelope unspecified, but it covers the main operational behavior well.
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 dense but efficient: every sentence carries load, from the scoping sentence to the compressed category routing arrows. It is front-loaded with the core purpose and then adds behavioral detail 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 an 11-parameter tool with no output schema, the description covers the main return modes (full result, preview with output_path, job_id for long tasks) and node routing, which is enough for an agent to call it correctly. It does not describe error handling, overwrite default behavior or structured output, but the input schema handles most parameter details and the description provides the missing context.
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 73%, so the description is not wholly responsible for parameters, but it adds real value: it explains output_path's write-and-preview behavior, clarifies category routing values, and notes that the worker sees only instruction, context, and files. Node and model override semantics are left to the schema, but the schema already documents those as normally-empty overrides.
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 opens with a specific action ('Delegate ONE small task') and names the resource ('local model'). It clearly marks this as a single-task tool, distinguishing it from fleet_delegate_batch and connecting to fleet_job for long tasks. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context: use for a single small task, and if the task is long, expect a job_id to poll with fleet_job. Category routing provides guidance for node selection, and the 'ONE small task' scope strongly implies that multiple tasks belong elsewhere. It does not explicitly name fleet_delegate_batch as the alternative for multiple tasks, but the scoping makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply the same instruction to many files in parallel across all nodes (one task per file). Returns a job_id immediately; poll fleet_job. Use output_pattern with {path} {dir} {stem} {name} {ext}, e.g. 'tests/test_{stem}.py'. complex/code → fast GPU node first; tests/scripts/build/docs → light nodes first (overflow to the other tier when busy); general → any; auto → keyword guess.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Paths or globs; one task per file. | |
| context | No | ||
| category | No | auto | |
| overwrite | No | ||
| instruction | Yes | ||
| shared_files | No | Files included in every task (interfaces, style guide, conftest). | |
| output_pattern | No | ||
| max_output_tokens | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It reveals the asynchronous contract (immediate job_id + polling), parallel execution, node-tier overflow behavior, and output_pattern templating. It does not cover failure modes, permissions, or side effects, but the key runtime behavior is disclosed.
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 dense sentences, each earning its place: main behavior + async flow, output_pattern syntax, and category routing. Front-loaded with the core operation before details.
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 batch tool with no output schema and no annotations, this covers the essential call flow, polling target, scheduling, and output naming. It omits some parameter semantics (overwrite/context) and failure details, but provides enough for an agent to make a correct first invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, so the description must compensate. It adds significant meaning for output_pattern by listing placeholders and giving an example, and for category by mapping each enum value to node routing. Other parameters like overwrite and context remain undocumented, but the most complex ones are explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('apply the same instruction to many files in parallel across all nodes') and the async resource ('returns a job_id; poll fleet_job'). This clearly differentiates from sibling fleet_delegate by emphasizing many files, parallelism, and batch semantics.
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?
Gives concrete guidance on scheduling categories (complex/code → GPU, tests/scripts/build/docs → light nodes, general → any, auto → keyword guess) and tells the agent to poll fleet_job after receiving the job_id. It does not explicitly state when to prefer fleet_delegate for a single file, so no exclusion/alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell the fleet how good a delegated result was, after you reviewed it. good = used as is, fixed = needed corrections, rejected = unusable. This trains the router.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| task_id | Yes | ||
| verdict | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does reveal the main side effect ('This trains the router') and defines each verdict, but it does not mention whether repeated feedback overrides prior feedback, authorization requirements, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences contain the action, timing, verdict definitions, and system impact with no wasted words. The description is front-loaded and does not repeat schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter feedback tool, the description covers the action, when to call it, what the verdicts mean, and why it matters ('trains the router'). Return behavior and edge cases like duplicate feedback are not covered, but they are minor for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions, so the description's explanations add real value: 'good = used as is, fixed = needed corrections, rejected = unusable' fully defines the verdict enum, and 'delegated result' implies what task_id refers to. The note parameter is not explicitly described, but its role is inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action—telling the fleet how good a delegated result was—and defines the three feedback verdicts. This makes the tool's role clear and distinguishes it from siblings like fleet_status, fleet_delegate, and fleet_queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'after you reviewed it' supplies clear timing, and 'trains the router' clarifies this is post-delegation feedback rather than a status or setup tool. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Progress and results of a background job (batch, long task, benchmark or pull).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| include_outputs | No | Include output previews of each task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, so the description doesn't need to restate that. However, it adds no behavioral detail beyond that: no mention of possible errors, blocking behavior, pagination, or whether the job might be in progress and return partial data. The description is a static statement of content, not 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?
The description is a single sentence, which is concise and easy to parse. However, it is under-specified: it front-loads a general statement without critical details like the required parameter or the nature of the output. It's concise but not effectively structured for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, the tool is incomplete. It doesn't explain the return format, how progress is represented, or what happens when a job_id is invalid. Given the tool deals with background jobs, the description should cover at least the shape of results and the role of include_outputs. It is inadequate for an agent to call 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 50%: include_outputs has a description, but job_id does not. The tool description does not mention either parameter, so it adds no value beyond the schema. It fails to clarify what job_id refers to or how include_outputs affects results. The description does not compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool provides 'Progress and results of a background job' and lists job types (batch, long task, benchmark, pull). This is not a tautology and gives some specificity, but it lacks an explicit verb like 'retrieve' or 'get' and doesn't differentiate from siblings like fleet_status or fleet_pull. The purpose is clear enough but vague on what 'progress' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings. It doesn't mention alternatives or any conditions for use. The description provides no context for selecting this tool over fleet_status or fleet_pull, so an agent has to infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add, remove, enable or disable ONE machine in the fleet configuration, keeping every other machine's settings and comments. 'add' probes the new server and picks its models per category; 'list' only shows the current machines. The previous file is kept as a backup.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | for 'add': http://192.168.1.13:11434, or a provider base URL | |
| name | No | short name of the machine, e.g. gpu | |
| tier | No | for 'add' (default: auto, decided by the benchmark) | |
| action | Yes | ||
| models | No | models per category, e.g. {"docs": ["gemini-2.5-flash"]} | |
| num_ctx | No | ||
| provider | No | for 'add' of a remote AI: fills url and the usual key variable (gemini, groq, openrouter, deepseek, mistral, openai, custom) | |
| cost_input | No | USD per million input tokens (0 = free tier) | |
| send_files | No | may this project's files be sent to that provider? ask the user first | |
| api_key_env | No | name of the environment variable holding the key - never paste the key itself | |
| cost_output | No | USD per million output tokens | |
| daily_tokens | No | ||
| max_parallel | No | ||
| daily_cost_usd | No | stop using this provider after this much per day | |
| daily_requests | No | free-tier or self-imposed daily request cap |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that changes are scoped to one machine, that a backup of the previous file is kept, and that 'add' involves network probing. However, it does not specify side effects for remove/disable (e.g., whether data is deleted), potential permission requirements, or reversibility beyond the backup, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action and scope. Each sentence adds substantive detail: preservation of other machines, action-specific behavior for add/list, and backup safety. No filler or redundancy, achieving high information density per word.
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 15 parameters, no output schema, and no annotations, the description is notably incomplete. It doesn't explain the full behavior of remove/enable/disable actions, doesn't map parameters to actions, and omits details like required fields per action or error conditions. An agent would still need to infer a lot to call the tool correctly across all scenarios.
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 description adds meaningful context for 'add' (probes server, picks models) and 'list' (shows current machines), which helps interpret those parameters. But it does not clarify which parameters apply to which actions (e.g., that remove only needs name), nor does it compensate for the parameters lacking schema descriptions (num_ctx, daily_tokens, max_parallel). Schema coverage is 73%, so the description adds partial value but isn't sufficient to fully clarify conditional parameters.
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 manages ONE machine in the fleet configuration with specific actions (add, remove, enable, disable) and explicitly scopes its effect by preserving other machines' settings and comments. This distinguishes it from sibling tools that likely perform fleet-level operations, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternative fleet tools like fleet_setup or fleet_status. It mentions 'list' but doesn't contrast it with potential listing alternatives. There are no when-not-to-use conditions or references to sibling tools, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a model onto a node (ollama pull). Downloads can be many GB and take minutes: only with the user's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| model | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and handles it well by disclosing that downloads can be many GB, take minutes, and require explicit user approval. This is substantial behavioral context beyond the basic action and helps an agent avoid an expensive or unapproved call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. The main action is front-loaded and the important warning follows immediately. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema and no annotations, the description gives the essential invocation context: what it does, what it affects, and a significant caution. It could be more complete by mentioning output or return behavior, but the core information an agent needs to select and call it is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does clarify the conceptual relationship between the two parameters: a model is downloaded onto a node. However, it does not provide format, identifier conventions, valid values, or examples for 'node' or 'model', so the compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Download a model onto a node (ollama pull)'. It clearly identifies the operation and the target, and distinguishes it from sibling tools by focusing on the pull action rather than status, setup, or job management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'only with the user's approval' is an explicit condition on when the tool should be invoked, which is crucial guidance for an agent. It does not name sibling alternatives, but no sibling appears to perform the same model-download function, so the omission is not a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue work the fleet finishes on its own, so it keeps going while you are paused (usage limit reached, session closed) - slow but steady. Actions: 'add' (same fields as fleet_delegate; give an output_path so the result lands on disk), 'list' (queued, running and finished, with results to review), 'cancel' one by id, 'clear' (done | pending | all).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | for 'cancel' | |
| note | No | why this was queued, shown when reviewing | |
| what | No | done | |
| files | No | ||
| action | Yes | ||
| context | No | ||
| category | No | auto | |
| instruction | No | for 'add': the self-contained brief | |
| output_path | No | where the result is written; strongly recommended | |
| max_output_tokens | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose background execution, persistence while paused, state visibility (queued/running/finished), and the need for output_path for on-disk results. It also exposes destructive control actions like cancel and clear, though it does not spell out failure behavior or whether clear is irreversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense, front-loaded sentence: purpose first, then a compact list of actions with their relevant parameters. There is no filler and every clause contributes to selection or invocation.
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 10-parameter, four-action tool with no annotations and no output schema, the description is adequate for the main flows but not fully complete. It does not describe list return format/results structure, leaves several parameters undefined, and the reference to 'same fields as fleet_delegate' is not self-contained.
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 only 40%, so the description must compensate. It does add useful action-to-parameter mappings: cancel uses id, clear uses done/pending/all, add uses instruction and output_path, and it points to fleet_delegate for shared fields. However, it leaves context, category, files, and max_output_tokens unexplained, so the compensation is only partial.
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 opens with a specific verb and resource ('Queue work the fleet finishes on its own') and enumerates the four actions ('add', 'list', 'cancel', 'clear'). It also differentiates from fleet_delegate by emphasizing that work runs in the background while the user is paused, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear when-to-use context: when usage limit is reached or the session is closed, so the fleet keeps making progress. It does not explicitly say 'use fleet_delegate for immediate work' or list exclusions, but the pause/background framing strongly implies the alternative, so it stops just short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or replace the fleet configuration by probing the user's Ollama servers: picks installed models per category and lists recommended models that are missing (with size and hardware). Without nodes it only probes the configured machines. Never pull models without the user's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| nodes | No | ||
| overwrite | No | Replace an existing fleet.toml (the old one is kept as a backup). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a key safety constraint ('Never pull models without the user's approval') and explains the probing behavior. However, it does not detail side effects beyond 'create or replace' (e.g., backup behavior, reversibility), and the interplay between 'create or replace' and 'without nodes only probes' is slightly ambiguous. Still, it provides a reasonable behavioral sketch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and then adding a conditional nuance and a safety rule. It is concise and efficient, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two parameters and no output schema, the description covers the main purpose, the conditional behavior, and a safety constraint. It does not explain the return value or potential error conditions, but these are not critical for a setup tool with minimal inputs. The minor ambiguity about 'without nodes' prevents a perfect score.
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 50%, so the description must compensate. It adds meaning for the `nodes` parameter by explaining the behavior when it is absent ('only probes the configured machines'). It does not elaborate on `overwrite`, though the schema already describes it. Overall, it adds some value but does not fully compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary action ('Create or replace the fleet configuration') and the resource it affects, while also describing the probing and model-listing behavior. This distinguishes it from siblings like fleet_status (status check) and fleet_pull (model pulling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers some usage context, notably the conditional 'Without `nodes` it only probes the configured machines,' which clarifies a specific invocation scenario. However, it does not explicitly name alternative tools or state when this tool should be preferred over others, leaving the agent to infer based on the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nodes, health, loaded models, routing preview per category, token savings and whether a benchmark or the first setup is due.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful detail about what the status payload contains, but it does not disclose any deeper behavior such as data freshness, pagination, or what 'due' exactly triggers. It does not contradict the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler. Every item in the list adds information about what the status report contains, making it appropriately sized and front-loaded for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status tool, the description covers the main result areas adequately, including the distinguishing 'benchmark or first setup due' indicators. It does not describe the return format, but given the simple nature and the annotation coverage, the agent has enough to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already fully documents invocation with an empty object. With 100% schema coverage and no parameters to explain, the description is not required to add parameter detail; the baseline 4 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?
The description is a verbless noun phrase, but it names the resource (fleet status) and precisely enumerates its contents: nodes, health, loaded models, routing preview, token savings, and due flags. This is far from a tautology and makes the tool's scope clear, though it does not explicitly contrast it with siblings like fleet_nodes or fleet_usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to call fleet_status instead of fleet_nodes, fleet_usage, or fleet_bench. The listed contents imply an overview-style tool, but there are no explicit conditions, exclusions, or alternative routing cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How much the fleet was used and what it saved: tokens processed per node (local machines and providers) and per model, cost in USD, today's quota use, Claude tokens saved, and a breakdown per category. This project by default; scope 'all' for every project, days for a period.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | only the last N days | |
| scope | No | project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description does not need to restate safety. The description adds value by disclosing the exact metrics returned (tokens, cost, quota, saved tokens, breakdown), which is behavioral information beyond the annotation. It does not describe pagination or output structure, but for a read-only report this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the purpose ('How much the fleet was used and what it saved') and then enumerates the metrics. It is efficient with no redundant phrases, and the parameter guidance is appended cleanly. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must convey what the tool returns. It lists many metrics (tokens per node/model, cost, quota, saved tokens, category breakdown) and explains the default scope and days parameter. It does not mention sorting, pagination, or the exact format of the breakdown, but for a report tool this is reasonably complete.
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 50%: `days` has a description, but `scope` does not. The description explicitly clarifies scope ('scope ''all'' for every project') and confirms days is a period ('`days` for a period'), adding meaning beyond the schema. It effectively compensates for the undocumented scope parameter.
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's purpose: reporting fleet usage and savings, with a specific list of metrics (tokens per node/model, cost, quota, saved tokens, category breakdown). It is distinct from sibling tools like fleet_status (likely health/state) and fleet_nodes (node management) by focusing on usage metrics, so an agent can select it correctly.
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 concrete usage context: 'This project by default; scope ''all'' for every project, `days` for a period.' This explains how to use the scope and days parameters, which is helpful. It does not explicitly mention when not to use this tool versus alternatives like fleet_status, but the purpose is clear enough that an agent can infer when a usage report is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0fleet_benchfleet_delegatefleet_delegate_batchfleet_feedbackfleet_jobfleet_nodesfleet_pullfleet_queuefleet_setupfleet_statusfleet_usageScored across 11 tools
Each tool has a mostly distinct purpose, with action and resource clearly separated. The main overlaps are fleet_status vs fleet_usage on usage/savings metrics and fleet_job vs fleet_queue on background work status, but the descriptions clarify the boundaries.
All tools share the fleet_ prefix and use lowercase snake_case throughout. The verb/noun suffixes are intuitively matched to each operation, making the naming pattern highly predictable.
With 11 tools, the set is well-scoped and covers the fleet lifecycle without redundancy or bloat. Each tool has a clear role, and the count is comfortably within the ideal range.
The core workflow is well covered: set up the fleet, manage nodes, delegate single/batch tasks, queue work, monitor jobs, provide feedback, benchmark, and track usage. Minor gaps include no way to cancel a running background job or remove a pulled model.
Get dollar quotes from 200+ LLMs before any work runs; accept, execute, and verify quality.
Pay-per-call ($0.01 USDC) model-routing for AI coding agents: which LLM to call, cost vs. quality.
Build and supervise fleets of agents from Claude Code, Codex or Cursor. Connects over OAuth.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
