Find tools by intent, not memory.

Semantic Discovery

compass(intent) finds tools by meaning. Describe what you want to do — get the right tool, not a list of all of them.

95% Token Savings

38,500 tokens → 2,000 per request. HNSW vector index, nomic-embed-text, ~15ms query latency, ~95% accuracy@3.

Progressive Disclosure

compass() → describe() → execute(). Load only the schema you need, only when you actually need it.

Graceful degradation

Ollama down? Compass falls back to keyword search over the same index, marks results degraded, and tells you exactly what to start.

Trace IDs in every response

Every MCP call gets an 8-char trace_id plumbed into logs, success envelopes, and error envelopes. Paste it into a bug report and grep the logs.

Production observability

/ready does a deep probe (index + Ollama + backends). /metrics emits Prometheus text with embed p95, orphan vectors, per-backend up/down.

HTTP / remote backends

Front remote and SaaS MCP servers over streamable-http, not just local stdio subprocesses. Optional bearer-token auth on your own gateway endpoint.

Hybrid search + exact-name boost

Semantic (HNSW) and lexical signals fused with Reciprocal Rank Fusion on the healthy path — describe what you want, or paste a tool name and it ranks #1.

Full-schema describe()

The complete inputSchema (required fields, descriptions, enums, defaults) is preserved through sync, so an agent can build a correct execute() call in one hop.

Per-tool timeouts & allow/deny

Override the 15s default per backend or per tool for slow image/video backends; expose a safe subset of a broad backend with allow/deny globs.

execute CLI

tool-compass execute <tool> '<json>' runs a proxied tool call from the terminal — smoke-test a backend without wiring up an agent.

Ops hardening

Active liveness probe surfaces hung-but-connected backends; analytics retention keeps the local DB bounded; schema-aware change detection re-syncs revised tools.

Install & Index

# Prerequisites: Ollama running locally
ollama pull nomic-embed-text

# Install the CLI + gateway
pip install tool-compass

# Build the search index from your configured backends
tool-compass sync

# Start the MCP gateway (or `tool-compass serve`)
tool-compass

One-shot CLI

# Search by intent without starting a server
tool-compass search "generate an AI image" --top 3 --json

# Inspect a tool's schema
tool-compass describe comfy:comfy_generate

# Diagnostics dump — version, config, Ollama reachability
tool-compass doctor

MCP tool call

compass(
  intent="I need to generate an AI image from text",
  top_k=3,
  min_confidence=0.3
)

# Returns (excerpt):
# {
#   "matches": [{
#     "tool": "comfy:comfy_generate",
#     "confidence": 0.912
#   }],
#   "tokens_saved": 20500,
#   "trace_id": "9f3a1c7b"
# }

Graceful Ollama-down

# Ollama stopped mid-session? compass still answers:
compass(intent="read a file")

# Returns:
# {
#   "matches": [{
#     "tool": "bridge:read_file",
#     "degraded": true
#   }],
#   "warnings": [
#     "Semantic search unavailable: Ollama at
#      http://localhost:11434 is unreachable.
#      Try: ollama serve"
#   ]
# }