Core tool
Match a re-phrased goal to a skill you already have
The semantic cache: embed the intent, match it against your compiled skills for this host, replay on a hit, compile and cache on a miss — so the second phrasing of the same request is cheap.
dispatch
What it is
The job: Be the one call an agent makes, and get cheaper every time the agent asks for the same thing in different words.
An agent does not phrase a request the same way twice. “Export last month’s invoices”, “download the invoice CSV”, and “get me the billing export” are one task and three strings, and a cache keyed on the string would miss all three. dispatch embeds the intent, retrieves the nearest compiled skills for the same host, and asks the model a single cheap question: is this the same task? A yes replays the cached path.
On a miss it does the expensive thing once — a full discover and minimize, exactly as compile_skill would — and stores the verified path under the same cache key, so the next phrasing of the request lands as a hit. Between hit and miss sits adapt: a skill compiled by another tenant for the same host can seed the compile, which is cheaper than a cold one because the scaffold already exists.
The response tells you which of the three happened, in `mode`. That field is the honest one to log: it is how you find out whether your cache is actually working.
The call
Call it exactly like this.
Copied from the tool's registration and the route handler — not paraphrased.
// MCP tool call — server "twin-browser"
{
"tool": "dispatch",
"arguments": {
"url": "https://app.example.com/billing",
"prompt": "download last month's invoices as CSV",
"success": { "kind": "urlIncludes", "value": "/download" }
}
}curl -X POST https://twin-browser.com/api/v1/dispatch \
-H "Authorization: Bearer $TWIN_API_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://app.example.com/billing","prompt":"download last month's invoices as CSV","success":{"kind":"urlIncludes","value":"/download"}}'| Parameter | Type | What it does |
|---|---|---|
| url | string | Ad-hoc form: the URL to automate. Pair with prompt and success. |
| prompt | string | Ad-hoc form: the goal in natural language. This is the string the semantic cache matches on. |
| success | object | Ad-hoc form, required with url: the success condition — one of { kind:"statusText", match }, { kind:"urlIncludes", value }, { kind:"textVisible", value }, { kind:"extracted" }, { kind:"allOf", conditions }, { kind:"anyOf", conditions }. A malformed shape is a clean 400. |
| target | string | Named form: the base URL to automate. Pair with goal. |
| goal | string | Named form: a registry goal name to run against target. |
| params | object | Values to bind into the matched skill’s {{param:NAME}} tokens. |
Returns
// cache HIT — a deterministic replay of a stored path
{ "mode": "cache-hit", "skill": "…", "version": 2, "success": true, "steps": 6,
"path": [ … ], "runId": "…", "credits_charged": 2 }
// cross-tenant ADAPT — someone else's scaffold, re-verified for you
{ "mode": "cache-adapt", "skill": "…", "source": "…", "success": true,
"credits_charged": 5 }
// MISS — compiled cold, then cached for next time
{ "mode": "cache-miss-compiled", "skill": "…", "version": 1, "success": true,
"optimized": true, "stepsSaved": 3, "credits_charged": 10 }What it costs
2 / 5 / 10 credits
A cache hit is 2 credits, a cross-tenant adapt 5, and a cold miss 10 — the same as an uncached run, because that is exactly what a miss does. Each settles higher-of against the metered model cost. The worst case is therefore never worse than calling run_goal, and the steady state is roughly 5× cheaper.
See the full rate cardWhich one
When a different tool is the right call.
The honest answer is often the neighbouring tool. These are the trades.
run_goalrun_goal is the honest choice when you want to see the planner work without a cache in the way — debugging, or a genuinely one-off task. Every repeated task is better through dispatch.
run_goalrun_skillrun_skill is faster and has no matching step at all, but you have to know the skill’s name. dispatch pays one cheap model call to find it for you.
run_skillsearch_librarysearch_library only reads the cross-tenant corpus; it never runs anything. dispatch is what actually uses that corpus, via the adapt path.
search_libraryQuestions
dispatch, answered.
- What stops the cache matching two tasks that are not actually the same?
- Retrieval is scoped to the host and gated on a similarity floor, and the top candidate then goes through an explicit intent check before anything replays. A near-miss falls through to a compile rather than replaying the wrong path — the failure mode is “paid full price”, not “did the wrong thing”.
- What is a cache-adapt?
- A skill compiled by a different tenant on the same host, sanitized to a scaffold, used to seed your compile. You get a cheaper-than-cold compile and your own verified, private path at the end of it; the other tenant’s data never enters the picture. It sits between a hit and a miss on price for exactly that reason.
- Does dispatch need WEB_BASE_URL and TWIN_API_KEY?
- Yes. The semantic cache lives in the web application, not the execution engine, so the MCP tool calls the web API directly. In the hosted setup WEB_BASE_URL already defaults to twin-browser.com, so a TWIN_API_KEY is the only variable you have to set.
Keep going
The rest of the tool set.
run_goalDo one thing on one site, right now, and block until you know whether it worked.
run_skillRun a known-good flow again, as cheaply as it can possibly be run.
compile_skillTurn a flow you are going to run many times into a stored artifact that costs almost nothing to run again.
search_libraryFind out whether somebody has already solved this shape of task on this host.