About · By Imagile
Why toil is built this way.
How it works, what it promises, what changed, and where to tell us what's wrong.
-
How it works
The big picture: one core, the envelope, configuration, credentials and safety.
-
Principles
The 11 principles every decision traces back to.
-
Changelog
Every release, from the commits that made it.
-
Feedback
Report a bug or ask for a feature, without a GitHub account.
Token-efficient by design
Less of the context window, more of the work.
Many MCP clients put every tool's schema in context before the first question. toil is a CLI the agent already knows how to call, so the context goes on answers instead.
-
Compact envelopes
Every command prints one JSON envelope: ok, data, error, meta. One shape to read, on every call.
-
Only the fields asked for
--select keeps the fields a task names. --summary-file puts a big result in a file and hands back a sample with stats; --output-format toon writes tables as one line per row.
-
Wait, don't poll
toil wait repeats a read until a condition is true and answers once, instead of the agent asking again and again.
-
A skill, read as needed
The toil skill is a short index. The agent opens one page when a task needs it, instead of every tool schema loaded up front.
toil util deps scan --include-transitive --include-dev141,580 bytes, about 40,450 tokens{"ok":true,"data":{"ecosystems":["npm"],"manifests":[…],
"packages":[{"name":"@azure-rest/core-client","version":"2.9.0",
"ecosystem":"npm","source":"functions/feedback/package-lock.json",
"type":"direct","scope":"production"}, … 1,082 more …toil util deps scan --include-transitive --include-dev --summary-file deps.json --output-format toon2,375 bytes, about 680 tokens, with all 1,083 rows in deps.jsonschema:
name: string
version: string
…
rows[10]{name,version,ecosystem,source,type,scope}:
@azure-rest/core-client,2.9.0,npm,functions/feedback/package-lock.json,direct,production
source-map-js,1.2.2,npm,functions/feedback/package-lock.json,direct,dev
…
stats[6:]{nulls,distinct,min,max}:
name: 0,791,null,null
…One envelope, every command
Answers an agent can act on.
Every command returns the same JSON shape on stdout, says where its data came from, and stays read-only until you decide otherwise.
- ok / data / error / meta on every call, CLI or MCP
- readOnly reported, not assumed
- source on every result, so nothing is a mystery
$ npx -y @imagile-dev/toil db query --connection reporting "select status, count(*) from orders group by status"
{ "ok": true, "data": { "columns": ["status", "count"], "rows": [["open", 42], ["shipped", 318]], "truncated": false }, "meta": { "source": "postgres:reporting", "readOnly": true }}
Built for the locked-down laptop
If your machine runs Node, it runs toil.
Application control blocks unsigned executables. Security reviews stall on native modules. toil is built so there is nothing for either to catch.
-
No executable
One bundled JavaScript file on the Node you already have. Nothing for application control to block.
-
No install scripts
No postinstall, no native addon, no binary download. It installs cleanly with --ignore-scripts.
-
No browser login
Paste a token you generated once. No OAuth dance, no SSO pop-up, no device code.
-
No telemetry
toil talks only to hosts in your config. Your firewall logs show exactly what you expect.
Still speaks MCP
When a client wants MCP, toil serves it.
toil mcp serves the same commands as MCP tools. Vendor servers are often blocked, need a browser login, or don't exist; scope toil to the areas you need and point your agent at it: one config entry, a small, focused tool list, and write tools that only exist if you've turned them on.
"mcpServers": "tickets-and-docs": "command": "npx", "args": [ "-y", "@imagile-dev/toil", "mcp", "--areas", "jira,confluence" ]