Skip to content
Route Tools

Local-first tool router

POST /v1/route returns a selection, not a tool result. It requires a Route Tools bearer key and is rate-limited, but does not require or debit prepaid credits. Existing /v1/tools/*, marketplace, and /mcp execution APIs remain separate and retain their existing pricing and provider policies. This is an incremental migration, not a replacement for those APIs yet.

Request

Section titled “Request”
FieldMeaning
toolRequired capability label, e.g. browser, sandbox, search. Exact, case-sensitive matching.
queryTask description, 1–8,000 characters.
candidatesUp to 50 tools the caller can actually execute; defaults to [].
max_cost_usdMaximum estimated tool cost per execution; defaults to 0. Does not include Jev or hosting.
assessmentAdvanced override: auto (default), capability (no external assessment), or jev (always assess non-search candidates). Omit for normal use.

Each candidate needs a unique id, a description, one or more capabilities, location (local or remote), available (boolean), and cost_usd (a finite, nonnegative estimate for this task). These are caller-supplied claims, not independently verified capabilities, prices, or health checks. Do not put credentials or private data in descriptions: automatic assessment sends the task and eligible candidate metadata to TypeSafe when multiple tools qualify. Use assessment: "capability" if that data must not leave the router.

Candidates must match the capability, be available, and fit the budget. Then:

  • One eligible tool: select it without a model call. This trusts the caller’s capability claim; it does not verify task-specific suitability.
  • Multiple eligible tools: automatically assess task suitability in one batch, remove unsuitable tools, then choose the cheapest remaining tool.
  • Equal cost: prefer local execution, then tool ID for deterministic results. A higher suitability score does not override price once a tool passes the threshold.

The number of eligible tools is a simple dispatch rule, not a task-complexity detector. For a task that needs semantic validation even with one candidate, the advanced assessment: "jev" override forces a check. assessment: "capability" skips assessment entirely and trusts capability labels, including when multiple candidates qualify.

No eligible candidate returns 503 unavailable, never a surprise paid route. The caller must validate the decision against its own inventory and permissions before executing anything. No arbitrary URLs or commands are fetched or executed by this API.

Section titled “Search”

search, web_search, and you-search bypass candidate selection and Jev. They return provider: "you", tool: "you-search", and mcp_url: "https://api.you.com/mcp?profile=free" with execution: "caller".

The caller connects to that MCP server, inspects you-search for its current input schema, and invokes it with the task query. The router does not proxy search, reserve quota, check quota availability, or switch providers. Quota errors occur when the client calls You.com, not during selection.

You.com’s MCP documentation currently specifies 100 queries/day and no credentials for this profile. Live discovery has also exposed you-discover; this router selects only you-search. Limits may change. Do not assume each Route Tools API key receives a separate allowance. There is no automatic paid fallback and no quota bypass.

Internal suitability assessment

Section titled “Internal suitability assessment”

The default auto policy uses Jev when more than one candidate survives the hard filters. Callers do not choose a model. The router asks one Noul question per eligible candidate in a single POST https://api.typesafe.ai/v1/systemone call, model jev-latest. State is a JSON string containing the task, capability, and indexed candidates. Each question asks only whether that candidate can perform the task. Answers are validated and candidates with noul < 0.8 are removed; cheapest-first ordering remains application code, not a model judgment. The 0.8 threshold is a conservative initial policy, not an evaluated accuracy guarantee.

The response reports the actual path as strategy: "pinned", "capability", or "jev"; auto is a request policy, not a claim that an assessment ran.

A three-second abort signal bounds the upstream request. Missing configuration and network failures return 503; rate limits return 429; invalid or incomplete answers return 502. No retries or silent fallback to unassessed candidates.

Operator setup

Section titled “Operator setup”
Terminal window
cp apps/api/.dev.vars.example apps/api/.dev.vars
# Set TYPESAFE_API_KEY in this ignored file using your secret manager/editor.
pnpm db:migrate:local
pnpm dev

Use the example’s development bearer key only locally. For production, use pnpm --filter @route-tools/api exec wrangler secret put TYPESAFE_API_KEY and supply the key interactively. Never commit credentials. Jev requests use the deployment’s TypeSafe account; authenticated users can consume that account’s quota, so configure rate limits and monitor upstream usage. Route Tools does not currently meter or debit Jev usage. Verify your TypeSafe plan before enabling it publicly.

Performance

Section titled “Performance”

Search and single-eligible-tool selection make no model or provider calls. Selection does not load routing preferences or provider statistics. Authentication and rate limiting still apply. With at most 50 candidates, the hard filters and ordering run in memory. Multiple eligible candidates add one batched assessment request by default. These are architectural properties, not a production latency benchmark; no end-to-end performance claims have been measured yet.

Sources

Section titled “Sources”

Reviewed September 17, 2026: