This server routes coding prompts to locally indexed agent skills and lets you manage skill discovery, retrieval, and feedback without any LLM token cost.
route_skill: Match a natural-language prompt to the most relevant skills using hybrid BM25 + dense embeddings; optional topK, host filter, and explain scoring breakdown.
get_skill: Retrieve full markdown instructions/manifest for a skill by ID or name.
list_skills: Browse all indexed skills, optionally filtered by substring and host environment.
scan_skills: Refresh the SQLite index by scanning filesystem skill directories, optionally adding a workspace directory.
record_feedback: Log user routing corrections (query → chosen skill) to refine future scoring and prompt-to-skill synonyms.
The Universal Local Router for Agent Skills
Live Demo | Overview | Architecture | Empirical Tuning | Installation | Quick Start | Comparison | Environments | MCP & Local Models | CLI | FAQ | Star History | License
Download standalone installers directly fromGitHub Releases: RoutedSetup.exe (Windows), RoutedSetup.pkg (macOS), and RoutedSetup.deb (Linux).
Routed is a universal, local, zero-token router for Agent Skills across AI coding environments. It automatically scans, indexes, and routes coding prompts to the most relevant skill using a local hybrid search engine combining Okapi BM25, exact matching, and local dense semantic embeddings.
Zero Token Cost: Eliminates costly LLM routing calls (saving 1,000+ prompt tokens per interaction).
Sub-20ms Latency: Local CPU-evaluated hybrid search responds instantly without network roundtrips.
Empirical Hyperparameter Tuning: Zero magic numbers. Built-in parameter grid search and Stratified 5-Fold Cross-Validation (routed tune) empirically optimize scoring weights with a proven 2.6% generalization gap.
Adversarial Precision Floor: Grounded semantic gating and calibrated 0.35 confidence floor guarantee zero false activations on gibberish or non-coding prompts.
Negation Intent and Framework Penalty: Automatically isolates positive intent, suppresses negated skills, and penalizes unprompted framework specializations.
Model Context Protocol (MCP) Server: Run Routed via routed mcp to eliminate context pollution in LM Studio, Cursor, Claude Desktop, Windsurf, Continue, and Cline.
Native Multilingual Understanding: Understands German, Spanish, French, Japanese, and 100+ languages natively, automatically handling compound words without language switches.
Native Auto-Updater: Automatic version checks and seamless in-place upgrades via routed update.
Self-Healing Host Reconciliation: Unified diagnostics and adapter repair via routed doctor --fix.
Privacy First: Prompt routing is executed 100% locally; no user queries leave your machine.
Multi-Skill Dispatch: Decomposes compound prompts and activates multiple skills simultaneously.
Related MCP server: Delegation MCP
Routed evaluates queries using an empirically validated multi-tier hybrid scoring pipeline running entirely on local CPU:
flowchart LR
UserPrompt["User Prompt (/route)"] --> Engine["Routed Core Engine"]
subgraph Engine["Hybrid Scoring Pipeline (Local CPU)"]
Exact["Exact / Alias Match (10%)"]
BM25["Okapi BM25 Lexical (45%)"]
Semantic["Dense Vector Embeddings (45%)"]
Meta["Adaptive History & Decay (0-25%)"]
end
Exact --> Scorer["Composite Hybrid Scorer"]
BM25 --> Scorer
Semantic --> Scorer
Meta --> Scorer
Scorer --> Selection["Top Skill(s) Resolved (< 20ms)"]
Selection --> Agent["AI Host Agent (Antigravity / Claude / Cursor / OpenCode / Codex)"]$$\text{Composite Score} = W_{\text{sem}} \cdot \text{Semantic} + W_{\text{bm25}} \cdot \text{BM25} + W_{\text{exact}} \cdot \text{Exact} + W_{\text{history}} \cdot \text{Metadata}$$
Starting in v1.5.0, Routed eliminates arbitrary "magic numbers" by incorporating an empirical hyperparameter optimization engine:
routed tune --folds 5 --applyTo ensure scoring weights generalize robustly to unseen prompts rather than overfitting to synthetic queries, routed tune:
Precomputes Retrieval Signals: Caches lexical (BM25), exact, and dense vector signals in an in-memory matrix, allowing 1,000+ candidate parameter configurations to evaluate in milliseconds.
Stratifies 5 Folds: Splits representative benchmark cases across 9 distinct categories (exact-match, synonym, technical-jargon, abbreviation, indirect-intent, multilingual, multi-skill, domain-specific, no-skill).
Optimizes on Training Splits: Sweeps the weight simplex ($\sum W = 1.0$) with step size 0.05 and confidence thresholds to maximize composite Top-1 accuracy, Top-3 recall, and No-Skill precision.
Validates Out-of-Fold (OOF): Evaluates discovered weights against held-out validation queries, computing the Generalization Gap ($\text{Train} - \text{Val}$) and standard deviation across folds.
Metric | Factory Baseline (v1.3) | Empirically Tuned (v1.5) | Delta |
Scoring Weights | 50% Sem / 35% BM25 / 10% Exact / 5% Meta | 43% Sem / 50% BM25 / 7% Exact / 0% Meta | +15% Lexical Contrast |
Out-of-Fold Top-1 Accuracy | 40.0% | 45.6% | +5.6% |
Out-of-Fold Top-3 Recall | 55.6% | 63.3% | +7.7% |
Mean Generalization Gap | N/A | 2.6% ($\pm 17.7%$) | Proven Generalization |
No-Skill Precision | 40.0% | 40.0% (strict threshold) | Eliminates false activations |
Tuned weights are persisted directly in the local SQLite index.db. All subsequent routed route operations automatically execute with the empirical weights. You can reset to baseline at any time with routed tune --reset.
Routed evaluates router reliability using dual opposing boundary metrics across 190 evaluation cases (including 50 subtle boundary programming queries and 50 adversarial traps):
False Accept Rate (FAR): Percentage of no-skill prompts (nonsense strings, recipes, general conversation, or negated skills) that mistakenly trigger a skill. Lower is better (0.0% in v1.6.5).
False Decline Rate (FDR): Percentage of real, subtle programming requests dropped because a confidence floor was set too high. Lower is better (1.5% in v1.6.5).
Benchmark Metric | Result (v1.6.5) | Description |
Total Evaluation Cases | 190 | 130 positive coding tasks + 60 adversarial/no-skill traps |
Top-1 Accuracy | 73.2% (139/190) | Exact or primary skill match on rank 1 |
Top-3 Recall | 83.7% | Relevant skill present in top 3 suggestions |
Top-5 Recall | 87.4% | Relevant skill present in top 5 suggestions |
Mean Reciprocal Rank (MRR) | 78.8% | Position-weighted ranking effectiveness |
No-Skill Accuracy | 100.0% (60/60) | Clean decline on non-coding and adversarial prompts |
False Accept Rate (FAR) | 0.0% (0/60) | Zero false activations on noise or traps |
False Decline Rate (FDR) | 1.5% (2/130) | Valid subtle coding queries preserved |
Composite Score | 83.2 | Balanced metric weighting accuracy, recall, FAR, and FDR |
A single fixed confidence floor creates a false trade-off: raising the floor eliminates gibberish but drops real programming requests that sit near the boundary. Routed resolves this with a grounded dynamic floor:
Anchored queries (queries with lexical/BM25 overlap or exact tag/keyword match): evaluated with an anchored floor of 0.28, preserving recall and minimizing False Declines.
Unanchored queries (zero lexical overlap, relying solely on dense embedding space): evaluated with a strict floor of 0.40, suppressing noise and eliminating False Accepts.
The benchmark suite is open, deterministic, and runnable locally:
# Run full benchmark via CLI
routed benchmark
# Output machine-readable metrics JSON
routed benchmark --json
# Or clone the repository and run via npm
git clone https://github.com/BrianShea/routed.git
cd routed
npm install
npm run build
npm run benchmarkThe benchmark dataset definition is located at packages/core/src/benchmark/dataset.ts. Custom benchmark datasets can be evaluated using routed benchmark --dataset <path>.
Dimension | Routed (Local) | Traditional Cloud LLM Routing | Manual Skill Selection |
Token Cost | $0.00 (Zero tokens) | 500 to 2,000 paid tokens | $0.00 |
Latency | Under 20ms (Local CPU) | 1,200ms to 3,500ms network API | Manual human browsing |
Privacy | 100% Local (Air-gapped) | Sends user prompts to cloud | Local |
Ranking Engine | Deterministic Hybrid | Non-deterministic prompt drift | Memory or string grep |
Multi-Agent Sync | Automatic adapter synchronization | Fragmented per-tool prompting | Manual copy and paste |
npx)Test Routed immediately in any project without downloading an installer:
npx routed route "refactor auth service and add unit tests" --explainOr run the interactive setup wizard directly:
npx routed setupTo install globally via npm:
npm install -g routedFor permanent, system-level local installation across all AI coding environments:
Platform | Installer Package | Format | Quick Install |
macOS | Apple Installer / Disk Image | Run | |
Linux | Debian Package / Tarball |
| |
Windows | NSIS Executable Installer | Run |
git clone https://github.com/bshea-1/Routed.git
cd Routed
npm install
npm run build
npm run setupRun the setup wizard to detect installed AI coding tools and configure /route adapters:
routed setupScan local directories and build the hybrid index:
routed scan
routed skillsInside your AI agent chat (Antigravity, OpenCode, Claude Code, Cursor, Codex):
/route write a unit test for my authentication service using TDDOr from your terminal:
routed route "audit accessibility and fix memory leaks" --explainVerify system health, SQLite indices, and embedding models:
routed doctorEnvironment | Adapter Path / Target | Auto-Detection | Integration Method |
Model Context Protocol (MCP) |
| Supported | Universal JSON-RPC 2.0 stdio server ( |
LM Studio |
| Supported | Local MCP server for GPU-hosted local LLMs |
Ollama |
| Supported | Tool schemas ( |
Hermes Agent |
| Supported | Function calling schemas (JSON & XML) and prompt integration ( |
Antigravity |
| Supported | Native skill dispatch and background router |
Claude Code |
| Supported | Slash command integration and terminal runner |
Cursor |
| Supported | Rule-based prompt interception and MCP tools |
Codeium Windsurf |
| Supported | Cascade MCP tool server |
Continue.dev |
| Supported | Local IDE tool provider for Ollama and LM Studio |
Cline |
| Supported | Full MCP tool server and custom rule adapter |
OpenCode |
| Supported | Local skill loader and interactive prompts |
Codex |
| Supported | Universal Agentic Skill schema |
Local agent harness command protection | Supported |
Routed can be attached as a standard MCP server to any compatible host (LM Studio, Cursor, Claude Desktop, Windsurf, Continue, Cline). Instead of dumping 50+ tool schemas into your model context and exhausting VRAM, the host model only calls the route_skill tool. Routed evaluates the prompt on local CPU in sub-20ms and returns only the matched skill manifests.
Add the following snippet to your host configuration file:
{
"mcpServers": {
"routed": {
"command": "routed",
"args": ["mcp"]
}
}
}Generate Ollama tool schemas for /api/chat function calling:
routed ollama toolsRoute a prompt and generate a ready-to-run Ollama API payload:
routed ollama run --prompt "build a neural network in pytorch" --model llama3.2Generate tool schemas (OpenAI JSON or Nous Hermes XML) for Hermes agents:
# OpenAI-compatible JSON schema
routed hermes schema
# Nous Hermes XML schema
routed hermes schema --xml
# System prompt guidance snippet
routed hermes promptRoute a prompt and get ready-to-inject instructions:
routed hermes route "refactor auth service"Routed integrates directly with HOL Guard (command.routed) to ensure safe automated execution inside agent harnesses. HOL Guard intercepts and flags state-modifying operations (routed doctor --fix, routed adapters install, routed adapters uninstall, and routed update) for pre-action human review, while allowing routine routing (routed route), diagnostics (routed doctor), and update checks (routed update --check) to execute without interruption.
Command | Description | Example |
| Run interactive setup wizard |
|
| Check for updates and upgrade Routed |
|
| Start Model Context Protocol server over stdio |
|
| Ollama tool schemas, routes, and Modelfiles |
|
| Hermes schemas (JSON/XML), prompts, and routes |
|
| Find matching skill(s) for a prompt |
|
| Scan supported environments and update index |
|
| List all discovered and indexed skills |
|
| Manage |
|
| Run diagnostics and auto-reconciliation |
|
| Incrementally re-index and re-embed skills |
|
| Continuously monitor skill dirs for changes |
|
| Manage routing preferences and corrections |
|
| Run parameter grid search and K-fold CV |
|
| Display status and detected environments |
|
| Run routing accuracy and latency benchmarks |
|
| Safely remove Routed and clean adapters |
|
Usage:
routed <command> [arguments] [options]
Commands:
setup Run the interactive setup wizard
update Check for updates and automatically upgrade Routed (--check to inspect)
mcp Start Model Context Protocol (MCP) server for LM Studio, Cursor, Claude
ollama <subcommand> Ollama tool schemas, Modelfiles, and direct route integration
hermes <subcommand> Hermes agent schemas (JSON/XML), prompts, and direct route integration
route "<prompt>" Find the best matching Agent Skill(s) for a prompt
scan Scan supported AI environments and update index
skills List all discovered and indexed skills
adapters Manage /route adapters across AI coding tools
doctor Run system, database, and model diagnostics (--fix to repair)
reindex Incrementally re-index and re-embed installed skills
watch Continuously monitor skill directories for file changes
feedback Manage local routing preferences and corrections
tune Run parameter grid search and K-fold CV to optimize scoring weights
uninstall Safely uninstall Routed and remove adapters (--dry-run available)
status Display current system status and detected environments
benchmark Run routing benchmark suite and measure accuracy and latency
version Print version information
help Display help screenNo. Starting in v1.5.0, Routed incorporates a built-in hyperparameter grid search engine and Stratified K-Fold Cross-Validation framework (routed tune). Running routed tune --folds 5 systematically sweeps the scoring weight simplex and evaluates out-of-fold generalization on a representative benchmark across 9 categories. The resulting weights achieve a 2.6% generalization gap, empirically proving they generalize to unseen queries without overfitting.
Routed follows an idempotent desired-state convergence model with zero blast radius. Each host adapter runs in an isolated boundary: if Cursor installs successfully but Claude Code fails (for example, due to a file lock or directory permission), Cursor is preserved and remains fully functional. Running routed doctor --fix or routed adapters install automatically detects and reconciles any missing adapters in a single command.
Routed runs quantized ONNX dense embedding models (Snowflake Arctic Embed S / all-MiniLM-L6-v2) directly on local CPU alongside Okapi BM25. Vector similarity and text indices are cached in a local SQLite database, requiring no internet connection or cloud tokens.
When a prompt contains compound intents or conjunctions (such as "and", "with", "as well as"), Routed decomposes the prompt into sub-clauses, scores candidates across all clauses, and returns all matching skills in selectedSkills for joint agent activation.
No. Benchmark execution times average under 20 milliseconds on local CPU, making routing practically instantaneous compared to remote cloud roundtrips (1,200ms to 3,500ms).
Routed stores its index and database files in standard platform directories:
macOS: ~/Library/Application Support/Routed
Linux: ~/.local/share/routed
Windows: %LOCALAPPDATA%\Routed
MIT License. Copyright (c) 2026 bshea-1.
See LICENSE for full details.
Retrieve full markdown instructions and manifest for a skill by ID or name. Behavior: Read-only disk read; errors if not found. Usage Guidelines: Use when skill ID or name is already known (e.g. from route_skill or list_skills). Use route_skill to search by prompt intent. Parameters: id matches exact skill ID first, then falls back to case-insensitive name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The unique skill ID (e.g. "git-commit-helper") or exact skill name. Case-insensitive lookup (required). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description carries the burden. It discloses 'Read-only disk read; errors if not found' and the lookup fallback order, giving agents a clear safety profile and error expectation.
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 organized into Behavior, Usage Guidelines, and Parameters sections in four concise sentences. Every sentence adds information and the main purpose is front-loaded.
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?
Despite no annotations and no output schema, the description covers what the tool returns (full markdown instructions and manifest), its read-only behavior, failure mode, and selection criteria. For a one-parameter get tool, nothing essential is missing, though a bit more detail about the return structure could help.
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 already documents the id parameter with case-insensitive lookup semantics at 100% coverage, but the description adds the precedence rule that exact skill ID is matched first, then falls back to case-insensitive name. This is meaningful extra meaning beyond the schema.
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?
Description uses specific verb 'Retrieve' with resource 'full markdown instructions and manifest for a skill by ID or name.' It distinguishes itself from route_skill by noting that route_skill is for searching by prompt intent, so an agent can tell them apart.
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?
Explicitly states when to use: when skill ID or name is already known (e.g. from route_skill or list_skills). It also states the alternative: 'Use route_skill to search by prompt intent,' providing clear selection logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and filter all locally indexed agent skills from SQLite. Behavior: Read-only, sub-millisecond query with zero side effects. Usage Guidelines: Use to browse available skills without a prompt. Use scan_skills to refresh index after adding or editing skill files, route_skill to match prompts, or get_skill for specific skill instructions. Parameters: filter (substring search) and host (tool environment) combine as an AND filter. Returns all skills when omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Optional host environment filter to restrict results to a specific tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama). | |
| filter | No | Optional substring query matched case-insensitively across skill names, descriptions, and tags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It clearly states 'Read-only, sub-millisecond query with zero side effects,' which fully discloses behavioral characteristics with no contradictions.
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?
Organized into clear sections (Behavior, Usage Guidelines, Parameters) with no redundant wording. Every sentence adds meaningful information, achieving high density without bloat.
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 tool is simple (list/filter, no output schema needed). The description covers purpose, behavior, usage, parameter semantics, and alternatives comprehensively, leaving no relevant gaps for an agent to invoke it 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 description coverage is 100% so baseline is 3, but the description adds valuable context: 'combine as an AND filter' and 'Returns all skills when omitted,' which clarifies parameter interaction and default behavior beyond the individual schema descriptions.
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 verb ('list' and 'filter') with a clear resource ('locally indexed agent skills from SQLite'). Explicitly differentiates from siblings by naming alternative tools and their purposes (scan_skills, route_skill, get_skill).
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 explicit when-to-use guidance ('Use to browse available skills without a prompt') and explicitly names alternatives with their appropriate contexts, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record user routing corrections to refine scoring weights and learn prompt-to-skill synonyms. Behavior: Local SQLite update in <5ms. Idempotent. Usage Guidelines: Use after route_skill when a user approves or corrects a skill route. Parameters: query is the routed prompt; chosenSkillId is the correct skill identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The original natural language prompt or task query that was routed by route_skill (required, non-empty string). | |
| chosenSkillId | Yes | The unique skill ID or skill name that correctly handles the query (required, non-empty string). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a 'Local SQLite update', that it is 'Idempotent', and gives a performance expectation of '<5ms'. This goes beyond a generic 'records feedback' and provides meaningful side-effect and safety context, though it doesn't describe error/failure 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 compact, front-loaded with purpose, and logically structured with labeled Behavior, Usage Guidelines, and Parameters sections. Every sentence contributes operational value, and the key usage condition is immediately actionable.
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, no-output-schema, feedback-recording tool, the description is complete. It covers purpose, when to invoke it, side-effect characteristics (idempotent local update), and parameter meanings in context. No critical operational detail appears to be missing.
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 100%, so the baseline is 3. The description restates 'query is the routed prompt; chosenSkillId is the correct skill identifier', but this adds minimal semantic value beyond the schema. It reinforces the routing context but does not introduce new format, constraints, or examples.
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 verb and resource: 'Record user routing corrections to refine scoring weights and learn prompt-to-skill synonyms.' This clearly differentiates it from siblings like route_skill (routing), get_skill/list_skills (retrieval), and scan_skills (scanning). The resource and high-level effect are 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?
Explicitly states when to use the tool: 'Use after route_skill when a user approves or corrects a skill route.' This gives a clear trigger condition and a sequencing relationship to its primary sibling. It leaves no ambiguity about the intended invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Route natural language prompts to matching agent skills using hybrid BM25 and dense embeddings. Behavior: Read-only local CPU execution in sub-20ms with zero LLM context tokens. Usage Guidelines: Primary entry point. Use route_skill to match task prompts against skills. Use list_skills to browse skills without a prompt, get_skill for known IDs, or scan_skills to refresh index. Parameters: prompt is the required query; topK (1-10, default 3) sets result limit; host filters environment; explain enables scoring breakdown signals.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Optional host environment filter to restrict matches to a specific AI tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama). | |
| topK | No | Maximum number of top-matching skills to return. Valid integer range: 1 to 10 (default: 3). | |
| prompt | Yes | The natural language user prompt, coding task, or question to route to relevant skills (required, non-empty string). | |
| explain | No | When true, includes scoring breakdown signals (exact match score, BM25 lexical score, vector semantic similarity). Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure, and it delivers: read-only execution, local CPU operation, sub-20ms latency, and zero LLM context tokens. These are concrete, useful behavioral traits that an agent needs to decide whether to call this tool.
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 compact, uses labeled sections for behavior, usage guidelines, and parameters, and contains no filler. Every sentence contributes to either tool selection, invocation, or safety/performance understanding.
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 routing tool with no output schema, the description covers the core purpose, behavior, alternatives, and parameter semantics. An agent has enough context to decide when to use it and how to call it 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 description coverage is 100%, so the baseline is 3. The description summarizes each parameter accurately, but adds little beyond what the schema already states about prompt, topK, host, and explain.
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 a clear verb and resource: route natural language prompts to matching agent skills, with the matching mechanism specified as hybrid BM25 and dense embeddings. It also distinguishes itself from siblings by explicitly naming list_skills, get_skill, and scan_skills as alternatives with different purposes.
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 explicitly labels route_skill as the primary entry point and gives concrete conditions for using each sibling tool: list_skills for browsing without a prompt, get_skill for known IDs, and scan_skills for refreshing the index. This gives an agent clear decision criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan filesystem directories across detected AI coding tools and rebuild the local SQLite index. Behavior: Synchronizes SQLite index in-place from disk in <100ms. Read-only on source skill files. Usage Guidelines: Use to refresh index after adding or editing skill files. Use route_skill or list_skills for querying. Parameters: workspace specifies an absolute directory to include workspace-local skills; scans all global tool paths when omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Optional absolute directory path of a custom workspace to scan. If omitted, scans all standard global and workspace skill directories for detected host tools. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses the in-place SQLite index update, a <100ms performance trait, and explicitly states it is read-only on source skill files. It could add more on failure modes or permissions, but the core behavioral traits are covered.
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 compact, uses clear section labels (Behavior, Usage Guidelines, Parameters), and leads with the main purpose. Every sentence adds useful information, and there is no fluff or repetition.
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 one-parameter maintenance tool with no output schema, the description covers purpose, behavior, usage, and parameter semantics adequately. It does not describe the return value or success/failure feedback, but given the tool's simplicity and the lack of a meaningful output schema, the missing detail is minor.
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 100%, so the schema already fully documents the workspace parameter. The description adds a small reminder that workspace is an absolute directory and clarifies the omission behavior, matching what the schema already states. Baseline 3 is appropriate.
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 a specific action ('Scan filesystem directories', 'rebuild the local SQLite index') and a clear resource (skill files across detected AI coding tools). It distinguishes itself from sibling query tools like route_skill and list_skills, so an agent understands its maintenance role.
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?
Explicitly says when to use it ('after adding or editing skill files') and names alternatives for querying ('Use route_skill or list_skills'). This gives the agent clear routing criteria without inference.
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.
v1.0.2get_skill1 field changedInput schema / properties / id / descriptionPrevious value: -"The unique skill ID (e.g., \"git-commit-helper\") or exact skill name. Case-insensitive lookup (required)."New value: +"The unique skill ID (e.g. \"git-commit-helper\") or exact skill name. Case-insensitive lookup (required)."list_skills2 fields changedInput schema / properties / filter / descriptionPrevious value: -"Optional substring filter matched case-insensitively against skill names, descriptions, and tags."New value: +"Optional substring query matched case-insensitively across skill names, descriptions, and tags."Input schema / properties / host / descriptionPrevious value: -"Optional host environment filter to limit results to a specific tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama)."New value: +"Optional host environment filter to restrict results to a specific tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama)."route_skill1 field changedInput schema / properties / topK / descriptionPrevious value: -"Maximum number of top-matching skills to return. Valid range: 1 to 10 (default: 3)."New value: +"Maximum number of top-matching skills to return. Valid integer range: 1 to 10 (default: 3)."v1.0.1get_skill1 field changedInput schema / properties / id / descriptionPrevious value: -"The unique skill ID or skill name."New value: +"The unique skill ID (e.g., \"git-commit-helper\") or exact skill name. Case-insensitive lookup (required)."list_skills2 fields changedInput schema / properties / filter / descriptionPrevious value: -"Optional filter query across names, descriptions, and tags."New value: +"Optional substring filter matched case-insensitively against skill names, descriptions, and tags."Input schema / properties / host / descriptionPrevious value: -"Optional host environment filter."New value: +"Optional host environment filter to limit results to a specific tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama)."record_feedback2 fields changedInput schema / properties / chosenSkillId / descriptionPrevious value: -"The correct skill ID."New value: +"The unique skill ID or skill name that correctly handles the query (required, non-empty string)."Input schema / properties / query / descriptionPrevious value: -"The prompt query that was routed."New value: +"The original natural language prompt or task query that was routed by route_skill (required, non-empty string)."route_skill4 fields changedInput schema / properties / explain / descriptionPrevious value: -"Include scoring breakdown and matched signals."New value: +"When true, includes scoring breakdown signals (exact match score, BM25 lexical score, vector semantic similarity). Default: false."Input schema / properties / host / descriptionPrevious value: -"Optional host environment filter (e.g. antigravity, cursor, claude-code, lmstudio, ollama)."New value: +"Optional host environment filter to restrict matches to a specific AI tool (e.g. cursor, antigravity, claude-code, gemini-cli, hermes, codegate, openclaw, openmanus, lmstudio, ollama)."Input schema / properties / prompt / descriptionPrevious value: -"The user prompt or task description to route."New value: +"The natural language user prompt, coding task, or question to route to relevant skills (required, non-empty string)."Input schema / properties / topK / descriptionPrevious value: -"Maximum number of skills to return (default: 3)."New value: +"Maximum number of top-matching skills to return. Valid range: 1 to 10 (default: 3)."scan_skills1 field changedInput schema / properties / workspace / descriptionPrevious value: -"Optional workspace directory path to scan."New value: +"Optional absolute directory path of a custom workspace to scan. If omitted, scans all standard global and workspace skill directories for detected host tools."v0.1.0get_skilllist_skillsrecord_feedbackroute_skillscan_skillsScored across 5 tools
Each tool has a clearly distinct role: route_skill matches prompts, get_skill retrieves by ID, list_skills browses, scan_skills reindexes, and record_feedback captures corrections. There is no meaningful overlap or ambiguity between them.
All tools follow a consistent verb_noun snake_case pattern, with verbs accurately describing the action: route, get, list, scan, record. Singular and plural object forms are used appropriately for the resource being acted on.
Five tools is well-scoped for a skill routing and indexing server. Each tool addresses a distinct operation in the workflow—querying, retrieving, browsing, scanning, and feedback—without unnecessary bloat or missing essentials.
The tool surface fully covers the advertised domain: routing prompts, browsing the index, retrieving full skill details, refreshing the index from disk, and incorporating user corrections. Since skills are sourced from the filesystem, a create/update/delete skill tool is not needed for this server's purpose.
AI routing, memory, guardrails, and governance. Routes across Claude, GPT, Gemini.
Local-first, governed memory and session continuity for AI coding agents. No cloud, no telemetry.
Agent-first skill marketplace with USK open standard for Claude, Cursor, Gemini, Codex CLI.
Git-backed platform for skills, tools, and context for AI agents
