Tools Router

Overview

An agent reasons better when it reliably knows its own tools. The tools-router gives every session a low-token, trustworthy map of the CLIs and MCP servers it can reach, which surface to prefer, and which are unauthenticated, without a human naming tools each time.

Core principle: build the index OUT of band, inject it CHEAPLY, and make every judgment AUTH-AWARE and SECRET-SAFE. Two planes:

1. A periodic recon generator that PROBES auth/health and RENDERS a compact index + flags.
2. A thin, fail-open session injector that injects the pre-rendered index and does no probing.

The split is load-bearing: probing is slow and secret-bearing, so it must never run on the session hot path; the injector relays the cached evidence states. A cached authed result is point-in-time evidence, not a guarantee of present access; recheck when stale or a call fails.

When to use

• The agent keeps being told "use the X CLI" / "check the Y MCP", it doesn't know its surface.
• Both a CLI and an MCP cover the same capability and you want one preferred (CLI is cheaper on context, often broader access) without losing the other when it's the only one that works.
• You want unauthenticated tools surfaced before the agent confidently calls a dead one.

Not for: a single known tool (just call it); a surface small enough to hold in the system prompt by hand.

The two planes

Plane 1, periodic recon generator (a timer/cron/CI job, NOT the session). Probe each CLI's read-only identity command and each MCP's health, then render. Four disciplines, each below.

Plane 2, fail-open injector (session start). Read the PRE-RENDERED compact table and inject it; do zero probing and zero subprocess spawning. If the table is missing or malformed, inject nothing and exit success; a session must never block on the index. Prepend a one-line banner when there are flags or the table is stale (older than your recon interval × a few), so a missed recon surfaces instead of silently serving stale auth.

Disciplines (the non-obvious half: get these wrong and the index lies)

Auth-aware dedup: the inversion that bites

"A CLI exists, so drop the redundant MCP" is a trap. A provider's MCP can be live while its CLI is logged out, the existence rule would remove the working provider for a broken one. Compare the working/authed state of both sides:

• working CLI + dead/unauthed MCP → recommend dropping the MCP.
• working MCP + unauthed CLI → flag the CLI; KEEP the MCP (the inversion).
• both work → a surface judgment for a human, not an auto-kill.
• Always recommend-only and human-gated: never auto-disable a provider.

Secret-safe capture: the probe output is the secret

Auth probes print secrets (a config dump can echo live API keys to stdout). If you persist raw probe output into the rendered index, you leak credentials into a file the agent reads, and in a repo with a secret-scanner pre-commit gate, you can silently block every commit. Capture only an enum (authed/unauthed/config_present/indeterminate/unknown) plus a non-secret identity (account, email, org), run a fail-closed redactor over every field, and add a test asserting no secret shape reaches any rendered string.

Per-tool auth detection: exit code alone lies

Many CLIs exit 0 while printing "not logged in"; some report auth only via a side effect; some are env-var based (auth depends on an environment variable, so a probe run without the runtime env is indeterminate, not unauthed). Two specific traps:

• config-present ≠ auth-verified. A local-config read tells you a key is stored, not that it's live, it cannot detect a revoked/expired key. Mark it config_present, not authed. A nonempty environment variable is also only config_present; an absent or empty one is indeterminate because the probe may lack the target's runtime environment. Neither is a verified-working CLI or grounds to remove an MCP.
• masked-failure. probe-command || version-command always exits 0 (the fallback fires on failure and succeeds), so RC reports "authed" even with no credential. Use an affirmative predicate ("found a logged-in marker") AND a successful exit, never "didn't see an error." A failed probe with a stale affirmative marker is unauthed; a successful probe with unknown output is indeterminate. Missing executables are not_installed and are never run.

The skeleton checks the non-JSON gh auth status success entry in the combined output streams. Its CLI contract and output implementation describe the status and marker; JSON mode has a different exit contract. The fake cloudcli and vendorcli examples assume * <account> and a JSON object with a nonempty login, respectively. Replace those contracts with your tool's documented positive signal, test unknown/version-drifted output, and never infer authentication from exit 0 alone. Scope the probe to the intended host/account before relying on its result for that destination.

Reference implementation

reference-recon.py, the generator pattern in ~150 lines (fail-soft list parse, per-tool auth spec table, secret-safe capture, auth-aware dedup, compact render). session-injector.sh, a thin, fail-open session-start injector. Both are illustrative skeletons to adapt, not drop-in code.

Common mistakes

Boundary

This skill teaches the PATTERN and its disciplines. The mechanics are your harness's:

• how a session-start hook is registered and what shape its output takes;
• how the periodic job is scheduled (systemd timer, cron, CI) and kept alive;
• where the CLI list and MCP-server list come from, and your tool runtime's PATH;
• your repo's secret-scanner config and commit gates.

Defer all of those to your environment's own contract; keep the disciplines above intact.