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.

tool-compass CLI

New subcommand shell: search, describe, sync, doctor, serve. Default (no args) still starts the MCP server — backward compatible.

Embedding cache

Persistent SQLite cache keyed by (text, provider, model). Huge speedup on re-sync when most tool descriptions haven't changed.

Per-backend concurrency

New id-keyed stdout reader replaces the blocking read lock. Concurrent calls to the same backend no longer head-of-line-block each other.

Diffing sync

Upstream tool removed? Sync now diffs the old set against the new and calls remove_tool() for disappearing names. No more index orphans.

Multi-arch Docker

GHCR image ships linux/amd64 + linux/arm64. Same tag works on x86_64 servers and Apple Silicon / ARM workstations without emulation.

Deprecated-alias handling

ToolDefinition.deprecated_aliases + get_canonical_name() mean analytics stays consistent across tool renames. UI shows a "deprecated since vX.Y.Z" badge.

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"
#   ]
# }