A
licenseA
qualityA
maintenanceMCP Server for persistent code indexing. Gives AI assistants (Claude, Gemini, Copilot, Cursor) instant access to your codebase. 50x less context than grep.
22
217 npm
46
MIT
Alcove
by epicsagas
Alcove is an MCP server that gives AI coding agents on-demand access to your private project docs — without dumping everything into the context window, without leaking docs into public repos, and without per-project config for every agent you use.
Demo
Claude, Gemini, Codex — search · switch projects · global search · validate & generate. One setup.
alcove search· project switch ·--scope global·alcove validate
Related MCP server: mcp-context
The problem
You have two bad options.
Option A: Put docs in CLAUDE.md / AGENTS.md
Every file gets injected into the context window on every run.
Works for short conventions. Breaks down with real project docs.
10 architecture files = context bloat = slower, more expensive, less accurate responses.
Option B: Don't put docs in Your agent invents requirements you already documented. It ignores constraints from decisions you already made. It asks you to explain the same things every session.
Neither option scales. Now multiply it across 5 projects and 3 agents, each configured differently. Every time you switch, you lose context.
How Alcove solves this
Alcove doesn't inject your docs. Agents search for what they need, when they need it.
~/projects/my-app $ claude "how is auth implemented?"
→ Alcove detects project: my-app
→ BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
→ Agent gets the 2 most relevant docs, not all 12~/projects/my-api $ codex "review the API design"
→ Alcove detects project: my-api
→ Same doc structure, same access pattern
→ Different project, zero reconfigurationSwitch agents anytime. Switch projects anytime. The document layer stays standardized.
The right split
CLAUDE.md / AGENTS.md is for agent behavior: repeated mistakes to avoid, coding conventions, and session-specific instructions. Keep it under 200 lines.
Alcove is for project knowledge: architecture, decisions, runbooks, API docs, and anything else your agent needs to understand — but not necessarily on every run.
The pattern:
CLAUDE.md | AGENTS.md ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
ARCHITECTURE.md ← tech stack, data model, system design
DECISIONS.md ← why X was chosen over Y
DEBT.md ← known issues, workarounds
... ← agent searches here when it needs contextAgents call search_project_docs("auth flow") and get the 2 most relevant docs — not all 12. Nothing hits the context window unless it's actually needed.
Why Alcove
Why not just use
CLAUDE.md? Short conventions and agent behaviors belong there. Project documentation — architecture, decisions, runbooks, PRDs — doesn't scale in a context file. Alcove is not a replacement; it's the layerCLAUDE.mdwas never meant to be.
Without Alcove | With Alcove |
Docs in | BM25 search — agents pull only what they need |
Internal docs scattered across Notion, Google Docs, local files | One doc-repo, structured by project |
Each AI agent configured separately for doc access | One setup, all agents share the same access |
Switching projects means re-explaining context | CWD auto-detection, instant project switch |
Agent search returns random matching lines | Ranked results — best matches first, one result per file |
"Search all my notes about OAuth" — impossible | Global search across every project in one query |
Sensitive docs sitting in project repos | Private docs on your machine, never in public repos |
Doc structure differs per project and team member |
|
No way to check if docs are complete |
|
Stale docs with broken links or WIP markers go unnoticed |
|
Notes from Obsidian or other tools stay siloed |
|
Quick start
# macOS
[](https://buymeacoffee.com/epicsaga)
brew install epicsagas/tap/alcove
# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove
# Any platform — build from source
cargo install alcove
# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install
alcove setupClaude Code Plugin
If you use Claude Code, you can install Alcove as a plugin — it auto-installs the binary and registers the MCP server in one step:
claude plugin install epicsagas/alcoveThis runs a SessionStart hook that:
Installs the
alcovebinary if not found (via brew / cargo-binstall / cargo)Runs
alcove setupto register the MCP server
Optional dependencies
Tool | Purpose | Install |
| Full PDF text extraction — required for PDF search | macOS: |
Without pdftotext, Alcove falls back to a built-in PDF parser which may fail on some files. Run alcove doctor to check your setup.
Note: Pre-built binaries are available for Linux (x86_64), macOS (Apple Silicon & Intel), and Windows.
setup walks you through everything interactively:
Where your docs live
Which document categories to track
Preferred diagram format
Embedding model for hybrid search
HTTP server — host, port, auto-generated bearer token, and login item registration
Which AI agents to configure (MCP + skill files)
Re-run alcove setup anytime to change settings. It remembers your previous choices.
How it works
flowchart LR
subgraph Projects["Your projects"]
A1["my-app/\n src/ ..."]
A2["my-api/\n src/ ..."]
end
subgraph Docs["Your private docs (one repo)"]
D1["my-app/\n PRD.md\n ARCH.md"]
D2["my-api/\n PRD.md\n ..."]
P1["policy.toml"]
end
subgraph Agents["Any MCP agent"]
AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
end
subgraph MCP["Alcove MCP server"]
T["search · get_file\noverview · audit\ninit · validate"]
end
A1 -- "CWD detected" --> D1
A2 -- "CWD detected" --> D2
Agents -- "stdio (proxy → HTTP)" --> MCP
MCP -- "scoped access" --> DocsYour docs are organized in a separate directory (DOCS_ROOT), one folder per project. Alcove manages docs there and serves them to any MCP-compatible AI agent over stdio. When the background HTTP server is running (via alcove enable), the stdio process acts as a thin proxy — forwarding requests to the warm server for instant response with zero cold-start. Without the background server, it loads the full engine on each session.
What it does
On-demand doc retrieval — agents search and retrieve; nothing is pre-loaded into context
BM25 ranked search — fast full-text search powered by tantivy; most relevant docs first, auto-indexed, falls back to grep
One doc-repo, multiple projects — private docs organized by project, managed in a single place
One setup, any agent — configure once, every MCP-compatible agent gets the same access
Auto-detects your project from CWD — no per-project config needed
Scoped access — each project only sees its own docs
Cross-project search — search across all projects at once with
scope: "global"Private docs stay private — docs never touch your public repo, runs entirely on your machine
Persistent HTTP server — optional background server eliminates cold-start latency; agents connect via HTTP for instant response
Standardized doc structure —
policy.tomlenforces consistent docs across all projects and teamsCross-repo audit — finds internal docs misplaced in your project repo, suggests fixes
Document validation — checks for missing files, unfilled templates, required sections
Semantic lint — detects broken wikilinks, orphan files, stale WIP/DRAFT markers, and date claims that are 2+ years old
External vault promotion — bring a note from Obsidian (or any vault) into your alcove doc-repo with one command; auto-routes to the right project
Knowledge base vaults — create, link, and search independent knowledge bases (separate from project docs); link Obsidian vaults directly
Works with 9+ agents — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI
MCP Tools
Tool | What it does |
| List all docs with classification and sizes |
| Smart search — auto-selects BM25 ranked or grep, supports |
| Read a specific doc by path (supports |
| Show all projects in your docs repo |
| Cross-repo audit — scans doc-repo and local project repo, suggests actions |
| Scaffold docs for a new project (internal + external docs, selective file creation) |
| Validate docs against team policy ( |
| Rebuild the full-text search index (usually automatic) |
| Detect added, modified, or deleted docs since last index build |
| Semantic lint — broken links, orphan files, stale markers, stale date claims |
| Copy or move a file from an external vault into the alcove doc-repo |
| Search knowledge base vaults — separate from project docs, for research and reference |
| List all knowledge base vaults with document counts |
CLI
alcove Start MCP server (agents call this)
alcove setup Interactive setup — re-run anytime to reconfigure
alcove doctor Check the health of your alcove installation
alcove validate Validate docs against policy (--format json, --exit-code)
alcove lint Semantic lint — broken links, orphans, stale markers (--format json)
alcove promote Bring a file from an external vault into your doc-repo
alcove index Update the search index (incremental — only changed files)
alcove rebuild Rebuild the search index from scratch (use after schema changes)
alcove search Search docs from the terminal
alcove serve Start HTTP RAG server for external access
alcove enable Register as macOS login item and start background server
alcove disable Unregister from login items and stop server
alcove start Start the background server
alcove stop Stop the background server
alcove restart Restart the background server
alcove token Print the bearer token for team sharing
alcove uninstall Remove skills, config, and legacy files
alcove vault create Create a new knowledge base vault
alcove vault link Link an external directory as a vault (e.g., Obsidian)
alcove vault list List all vaults with document counts
alcove vault remove Remove a vault (symlinks: remove link only)
alcove vault add Add a document to a vault
alcove vault index Build search index for vaults
alcove vault rebuild Rebuild vault search index from scratchLint
# Lint the current project (auto-detected from CWD)
alcove lint
# Lint a specific project by name
alcove lint --project my-app
# Machine-readable output for CI
alcove lint --format jsonLint checks four things:
Check | What it catches |
|
|
| Files that no other document links to |
| WIP / TODO / FIXME / DRAFT / DEPRECATED markers |
| Year mentions that are 2+ years old (e.g. "as of 2022") |
Promote
# Copy a note from Obsidian into your doc-repo (auto-routes to matching project)
alcove promote ~/my-brain/Projects/auth-notes.md
# Route to a specific project
alcove promote ~/my-brain/Projects/auth-notes.md --project my-app
# Move instead of copy
alcove promote ~/my-brain/Projects/auth-notes.md --mvFiles with no matching project land in inbox/ for manual review.
Background Server
Alcove can run as a persistent HTTP RAG server, accessible via REST API. This is useful for external integrations, dashboards, or non-MCP clients. When enabled, the MCP stdio process automatically proxies to the warm server — eliminating cold-start latency (ONNX model load, index open) on every new session.
# Start the server in the foreground
alcove serve # default: 127.0.0.1:8080
alcove serve --port 9090 # custom port
alcove serve --host 0.0.0.0 # listen on all interfacesThe server uses a bearer token for authentication. During alcove setup, a token is auto-generated and stored in config.toml. You can also pass one explicitly with --token or the ALCOVE_TOKEN environment variable.
Token management
# Print the stored token (for sharing with teammates)
alcove token
# Teammates set it in their shell profile:
export ALCOVE_TOKEN="alcove-a3f7b2e14d5c..."Tokens are resolved with priority: --token flag > ALCOVE_TOKEN env var > config.toml.
macOS Login Item (launchd)
Register Alcove as a macOS login item so the HTTP server starts automatically on login and stays running in the background. This is the default during alcove setup — the setup wizard asks whether to enable it (default: Yes).
# Register and start (persists across reboots)
alcove enable
# Lifecycle management
alcove stop # stop the server
alcove start # start it again
alcove restart # stop + start
# Unregister (stops server and removes login item)
alcove disableThis installs a LaunchAgent at ~/Library/LaunchAgents/com.epicsagas.alcove.plist. Logs are written to ~/.alcove/logs/.
Hybrid Proxy Mode
Agents always connect to alcove via stdio (the MCP standard). When the background HTTP server is running, the stdio process acts as a thin proxy — it forwards JSON-RPC messages to the warm server over HTTP instead of loading the search engine itself. This eliminates cold-start latency (ONNX model load, index open) on every new agent session.
With background server (proxy mode):
Agent ──stdio──→ alcove (thin proxy)
│ stdin → HTTP POST /mcp
│ HTTP response → stdout
└──HTTP──→ alcove serve (always warm)
├─ BM25 index (loaded)
├─ ONNX embedding model (loaded)
├─ HNSW vector index (loaded)
└─ hybrid search ready (~5ms)
Without background server (direct mode):
Agent ──stdio──→ alcove (full engine)
├─ load ONNX embedding model (2-5s cold start)
├─ open BM25 index
├─ build HNSW vector index
└─ hybrid search ready (after warm-up)On startup, the stdio process checks GET /health on the configured host/port. If the server responds, it enters proxy mode automatically — no configuration change needed. The JSON-RPC payload is identical in both modes; only the transport changes internally.
Search
Alcove automatically picks the best search strategy. When the search index exists, it uses BM25 ranked search (powered by tantivy) for relevance-scored results. When it doesn't, it falls back to grep. You never have to think about it.
Hybrid Search (RAG)
Alcove supports Hybrid Search which combines BM25 with Vector Similarity Search (powered by fastembed).
During alcove setup, you can choose an embedding model and download it immediately. You can also manage models manually:
# Set and download an embedding model
alcove model set MultilingualE5Small
alcove model download
# Check model status
alcove model statusChoosing a model
Model | Disk | Dim | Languages | Best for |
| 15 MB | 384 | English | CI, resource-constrained environments |
| 30 MB | 384 | English | Fast English-only indexing |
| 65 MB | 384 | English | Balanced quality + size (English) |
| 130 MB | 384 | English | Good English recall |
| 235 MB | 384 | 100+ languages | Default — multilingual / mixed-language projects |
| 200 MB | 768 | English | High quality, quantized |
| 400 MB | 768 | English | Best English recall |
| 555 MB | 768 | 100+ languages | Better multilingual quality |
| 2.2 GB | 1024 | 100+ languages | Maximum multilingual quality |
| 2.3 GB | 1024 | 100+ languages | State-of-the-art multilingual |
Q (quantized) variants use int8 quantization — ~50% smaller on disk, slightly lower recall, no meaningful accuracy loss for typical document search. Use the XSQ/SQ/MQ variants when memory is a constraint.
Once a model is downloaded and ready, Alcove will automatically use Hybrid Search for both CLI search and agent-based MCP tools. This is particularly effective for multilingual projects and complex semantic queries.
# Search the current project (auto-detected from CWD)
alcove search "authentication flow"
# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grepThe index builds automatically in the background when the MCP server starts, and rebuilds when it detects file changes. No cron jobs, no manual steps.
How it works for agents: agents just call search_project_docs with a query. Alcove handles the rest — ranking, deduplication (one result per file), cross-project search, and fallback. The agent never needs to choose a search mode.
Index lifecycle
Understanding when to run alcove index vs alcove rebuild:
Command | What it does | When to use |
| Incremental update — only processes new/changed files | Default: run after adding or editing docs |
| Full rebuild — drops and recreates all index data | After changing embedding models, or after index corruption |
First-time setup:
# Step 1: BM25 search is ready immediately after setup
alcove index # builds full-text index (no model needed)
# Step 2: Enable Hybrid Search (optional but recommended)
alcove model set MultilingualE5Small
alcove model download # ~235 MB download
# Step 3: Build vector index for all existing docs
alcove rebuild # one-time full rebuild with embeddings
# ⚠ peak RAM = model size + corpus vectors (see note below)
# After this: incremental updates just work
alcove index # fast — only re-embeds changed filesSwitching models:
alcove model set SnowflakeArcticEmbedS # change model
alcove rebuild # required: vectors are model-specificMemory during rebuild:
Peak RAM = model size + all document vectors held in RAM while building the HNSW graph. For MultilingualE5Small with ~3,500 docs, expect ~700 MB peak. This is structural — after rebuild completes, steady-state drops to ~50–200 MB depending on your [memory] config. You can reduce steady-state further with lower max_hnsw_cache and shorter model_unload_secs.
Global search
Every architecture decision, every runbook, every project note — searchable across all your projects at once.
# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope globalAgents can do the same with scope: "global" in search_project_docs. One query, every project.
Project detection
By default, Alcove detects the current project from your terminal's working directory (CWD). You can override this with the MCP_PROJECT_NAME environment variable:
MCP_PROJECT_NAME=my-api alcoveThis is useful when your CWD doesn't match a project name in your docs repo.
Document policy
Define team-wide documentation standards with policy.toml in your docs repo:
[policy]
enforce = "strict" # strict | warn
[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]
[[policy.required]]
name = "ARCHITECTURE.md"
[[policy.required.sections]]
heading = "## Overview"
required = true
[[policy.required.sections]]
heading = "## Components"
required = true
min_items = 2Policy files are resolved with priority: project (<project>/.alcove/policy.toml) > team (DOCS_ROOT/.alcove/policy.toml) > built-in default (from your config.toml core files). This ensures consistent doc quality across all your projects while allowing per-project overrides.
Document classification
Alcove classifies docs into tiers:
Classification | Where it lives | Examples |
doc-repo-required | Alcove (private) | PRD, Architecture, Decisions, Conventions |
doc-repo-supplementary | Alcove (private) | Deployment, Onboarding, Testing, Runbook |
reference | Alcove | Audit reports, benchmarks, analysis |
project-repo | Your GitHub repo (public) | README, CHANGELOG, CONTRIBUTING |
The audit tool scans both your doc-repo and local project directory, then suggests actions — like generating a public README from your private PRD, or pulling misplaced reports back into Alcove.
Configuration
Config lives at ~/.config/alcove/config.toml:
docs_root = "/Users/you/documents"
[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]
[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]
[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]
[diagram]
format = "mermaid"
[server]
host = "127.0.0.1" # bind address (0.0.0.0 for all interfaces)
port = 8080 # listen port
token = "alcove-a3f7b2..." # auto-generated bearer token
[memory]
reader_ttl_secs = 300 # evict idle IndexReader after N seconds (0 = never)
max_cached_readers = 1 # max concurrent IndexReader instances in RAM
model_unload_secs = 600 # unload embedding model after N seconds of inactivity (0 = never)
max_hnsw_cache = 3 # max HNSW graphs held in memory simultaneouslyAll of this is set interactively via alcove setup. You can also edit the file directly.
Memory usage note: During initial indexing or a full rebuild, Alcove loads the embedding model (~235–500 MB) and holds all document vectors in RAM while constructing the HNSW graph — peak usage scales with corpus size and is unavoidable for that operation. The [memory] settings above control steady-state RAM after indexing is complete.
File lists are fully customizable — add any filename to any category, or move files between categories to match your team's workflow:
[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"] # added custom doc
[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"] # PRD exposed as public for this projectSupported agents
Agent | MCP | Skill |
Claude Code |
|
|
Cursor |
|
|
Claude Desktop | platform config | — |
Cline (VS Code) | VS Code globalStorage |
|
OpenCode |
|
|
Codex CLI |
|
|
Copilot CLI |
|
|
Antigravity |
| — |
Gemini CLI |
|
|
Agents with skill support activate Alcove automatically when you ask about project architecture, conventions, decisions, or status. They can also be invoked explicitly:
/alcove Summarize current project docs and status
/alcove search auth flow Search docs for a specific topic
/alcove what conventions apply? Ask a doc question directlySupported languages
The CLI automatically detects your system locale. You can also override it with the ALCOVE_LANG environment variable.
Language | Code |
English |
|
한국어 |
|
简体中文 |
|
日本語 |
|
Español |
|
हिन्दी |
|
Português (Brasil) |
|
Deutsch |
|
Français |
|
Русский |
|
# Override language
ALCOVE_LANG=ko alcove setupUpdate
# Homebrew
brew upgrade epicsagas/tap/alcove
# cargo-binstall
cargo binstall alcove
# From source
cargo install alcoveUninstall
alcove uninstall # remove skills & config
cargo uninstall alcove # remove binaryKnowledge Base Vaults
Beyond project documentation, Alcove supports independent knowledge base vaults for research notes, reference materials, and curated knowledge that LLMs can search.
# Create a vault for AI research notes
alcove vault create ai-research
# Link an existing Obsidian vault (no copying — indexes in place)
alcove vault link my-obsidian ~/Obsidian/research
# Add a document
alcove vault add ai-research ~/Downloads/transformer-survey.md
# Build the vault search index
alcove vault index
# Search from CLI
alcove search "attention mechanism" --vault ai-research
# Agents search via MCP
search_vault(query="attention mechanism", vault="ai-research")
# Search ALL vaults at once
search_vault(query="transformer", vault="*")Vaults are completely isolated from project docs — separate indexes, separate caches, separate search. Your coding agent's project doc search is never affected by vault activity.
Feature | Project docs | Vaults |
Purpose | Per-project documentation | General knowledge base |
Storage |
|
|
Index | Shared project index | Independent per-vault index |
Cache |
|
|
Search |
|
|
Symlink | No | Yes (link external dirs) |
Ecosystem
obsidian-forge
Alcove pairs naturally with obsidian-forge, an Obsidian vault generator and automation daemon. Use obsidian-forge to build and strengthen your knowledge graph in Obsidian, then promote notes into alcove with alcove promote — your AI agents get ranked, scoped search over your project knowledge base without any context bloat.
obsidian-forge (personal knowledge) → alcove promote → alcove (project docs)
vault / inbox / graph one command BM25 + vector searchContributing
Bug reports, feature requests, and pull requests are welcome. Please open an issue on GitHub to start a discussion.
License
Apache-2.0
Available Tools
15 toolsaudit_projectA
Audit documentation health across both the alcove doc-repo (private/internal) and the project repository (public-facing).
Use this tool when the user wants to know what docs are missing, outdated, or misplaced — for example: 'audit my docs', 'what docs am I missing?', 'check my documentation health'.
Scans two locations:
alcove doc-repo: checks for missing required internal docs
project repo root + docs/: checks for missing public-facing docs
Suggests actions such as generating missing public docs from internal content, or incorporating project repo materials into alcove. NEVER suggests exposing raw internal docs to the project repo.
IMPORTANT: This tool only reports findings. Always present the results to the user and ask which actions to proceed with before calling init_project or configure_project.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly explains that the tool only reports findings and scans two locations, suggesting actions but not executing them. It also includes an important caution about not exposing raw internal docs. However, without annotations, it could be more explicit about being read-only, though the description implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and bullet points, but it is slightly verbose. Every sentence adds value, and the main purpose is front-loaded. A minor trim could achieve a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully explains the tool's purpose, usage, behavior, and caveats. There is no missing information for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema provides full coverage. The description adds significant meaning by detailing the two scan locations and the tool's reporting nature, which is valuable beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits documentation health across two specific locations (alcove doc-repo and project repo). It uses a specific verb 'audit' and resource 'documentation health', and distinguishes from sibling tools like init_project and configure_project by noting it only reports findings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (when user wants to know missing/outdated/misplaced docs) with example queries. It also provides guidance on what not to do (never suggest exposing raw internal docs) and directs the agent to always ask the user before proceeding with init_project or configure_project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backup_vaultA
Create a git commit snapshot of a vault's current state.
Use this tool when the user asks to back up, sync, or save the current state of their knowledge base vault. Runs git add -A && git commit with a conventional commit message containing a timestamp.
If vault_name is provided, backs up only that vault. If omitted, backs up all vaults.
If the vault directory is not a git repository, it will be initialized automatically. If there are no changes to commit, returns a 'no_changes' status rather than an error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| vault_name | No | Name of the vault to back up. Omit to back up all vaults. |
TDQS
A4.5/5.0
Behavior4/5
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. It clearly explains the tool runs git commands, automatically initializes a git repo if missing, and returns a 'no_changes' status instead of an error when there are no changes. This adequately informs the agent of side effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, with the main purpose stated in the first sentence. Subsequent details are logically organized: use case, behavior with vs without parameter, auto-init, and no-change response. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description fully compensates by detailing return behavior (including the 'no_changes' status), git operations, and initialization logic. This covers all essential aspects a developer or AI agent would need to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as the only parameter 'vault_name' is documented. The description adds value by explaining the effect of omitting the parameter (backs up all vaults), which goes beyond the schema description that merely states 'omit to back up all vaults.' This provides actionable insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a git commit snapshot of a vault's current state,' which clearly specifies the verb ('create snapshot'), resource ('vault'), and mechanism ('git commit'). This distinguishes it from sibling tools like 'audit_project' or 'check_doc_changes' which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'when the user asks to back up, sync, or save the current state.' It also explains the behavior for vault_name provided vs omitted, guiding usage. However, it does not mention when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_doc_changesA
Check which documentation files have been added, modified, or deleted since the last index build.
Use this tool before search_project_docs when you want to ensure the index is up to date, or when the user asks whether docs have changed recently. It is safe to call at any time — without auto_rebuild it is read-only and has no side effects.
Compares current file timestamps against the stored index metadata. Returns a list of changed files grouped by status: added, modified, deleted.
Set auto_rebuild=true to automatically trigger rebuild_index if any changes are detected, avoiding a separate tool call. If no index exists yet, reports all files as new.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| auto_rebuild | No | Automatically rebuild the index if changes are detected (default: false) |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the comparison mechanism, return format (grouped by status), and the effect of auto_rebuild. Discloses that without auto_rebuild it is read-only with no side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured sentences. No wasted words; each sentence adds value. Front-loaded with purpose, followed by usage, mechanism, return, and parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely describes what the tool does, when to use, mechanism, return value, and parameter behavior. Adequate for a single-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with a clear description. The description adds usage context for the auto_rebuild parameter, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks for added, modified, or deleted documentation files since the last index build. It uses a specific verb and resource, and distinguishes from siblings like rebuild_index and search_project_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use before search_project_docs to ensure index freshness or when user asks about changes. Also states it is safe without auto_rebuild, providing clear when-to-use and safety guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
configure_projectA
Create or update per-project settings in alcove.toml. Each project can override global defaults for: diagram format, required core docs, team docs, and public docs. Only the fields you specify are changed; unmentioned settings are preserved. Run init_project first if the project does not yet exist.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| core_files | No | Required internal docs for this project (overrides global core list) | |
| diagram_format | No | Diagram syntax to use in this project's docs (e.g. "mermaid", "plantuml") | |
| project_name | Yes | Name of the project to configure | |
| public_files | No | Public-facing docs recognized for this project | |
| team_files | No | Supplementary team docs recognized for this project |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool is a create-or-update operation that only modifies specified fields, leaving others intact. However, it does not mention potential side effects like file locking, authorization requirements, or error conditions. For a configuration tool, this is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of four concise sentences, each providing essential information: what the tool does, what settings can be overridden, the partial update behavior, and the prerequisite. There is no redundant or extraneous content, and the structure front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of a configuration tool with 5 parameters and no output schema, the description covers purpose, usage, and parameter overview. However, it does not indicate what the tool returns (e.g., success/failure confirmation), which is a gap that could hinder the agent's understanding of the tool's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has high description coverage (100%) for all parameters, providing clear definitions. The description adds an overview of parameter categories but does not introduce new semantic nuances beyond what is in the schema. Therefore, the value added is minimal, and a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create or update' and the resource 'per-project settings in alcove.toml', specifying the fields that can be overridden. It distinguishes from the sibling tool 'init_project' by explicitly requiring it as a prerequisite, ensuring the agent knows when to use which.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance and a clear precondition: 'Run init_project first if the project does not yet exist.' It also explains partial updates: 'Only the fields you specify are changed; unmentioned settings are preserved.' This helps the agent decide when and how to invoke the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_doc_fileA
Read the full content of a specific documentation file by its relative path.
Use this tool when you know the exact file to read — typically after get_project_docs_overview or search_project_docs has identified the relevant file. It is read-only and has no side effects.
For large files, use offset and limit to read in chunks and avoid exceeding context limits. offset is a character (not line) position. Omit both to read the entire file.
Returns an error if the file does not exist or the path is outside the doc root.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max characters to return (default: entire file). Use together with offset to read in chunks. | |
| offset | No | Character offset to start reading from (default: 0). Use for paginating large files. | |
| relative_path | Yes | Path relative to the project doc root (e.g. "PRD.md" or "reports/weekly.md") |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully covers behavioral traits: declares read-only with 'no side effects,' explains chunking behavior, and documents error conditions (file not found or path out of bounds).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) with no filler. Purpose is front-loaded, usage guidance follows, and technical details are efficiently presented. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description covers all essential aspects: purpose, when to use, parameter semantics, chunking, and error handling. The agent has sufficient information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions, but the description adds crucial context: explains that offset is character-based, describes default behaviors, and clarifies the omit-to-read-entire-file pattern, going beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Read the full content of a specific documentation file by its relative path.' It distinguishes itself from siblings like search_project_docs and get_project_docs_overview by focusing on reading a known file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when you know the exact file to read' and provides a typical workflow after using other tools. Also addresses large file handling with offset/limit, giving clear guidance on chunking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_project_docs_overviewA
List all documentation files for the current project with file sizes and classification labels.
Call this tool first when the user asks what docs exist, wants a summary of project documentation, or before deciding which files to read. It is read-only and has no side effects.
Scans two locations: the alcove doc-repo (private/internal docs) and the project repository root + docs/ (public-facing docs).
Classification labels:
doc-repo-required: core internal docs required by policy (e.g. PRD, ARCHITECTURE)
doc-repo-supplementary: optional internal extras
project-repo: public-facing docs in the project repo (e.g. README, CHANGELOG)
reference: reports and reference materials
unrecognized: files not matching any known category
Returns an empty list if no docs exist yet. Use init_project to create initial docs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It fully discloses behavior: scans two locations, classification labels, empty list return, and read-only nature. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and concise: first sentence states purpose, then usage advice, then details about locations and classifications. Front-loaded with key information; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all needed information: purpose, when to use, where it scans, classification labels, edge case (empty list), and reference to related tool. No missing details given lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. Baseline for 0 params is 4. The description adds no parameter info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists documentation files with sizes and classification labels. The verb 'List' and resource 'documentation files for the current project' are precise, and the description distinguishes from siblings like get_doc_file and init_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call this tool first when the user asks about docs or wants a summary. It notes it is read-only with no side effects. While it does not explicitly list when not to use it, it provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
init_projectA
Initialize documentation for a new project from alcove templates. Creates internal docs (PRD, Architecture, etc.) in the alcove doc-repo. When project_path is provided, also creates external docs (README, CHANGELOG, QUICKSTART) in the project repository. Use the 'files' parameter to create only specific documents. Without 'files', creates all missing internal required docs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Specific files to create (e.g. ["PRD.md", "ARCHITECTURE.md"]). If omitted, creates all Tier 1 docs. | |
| overwrite | No | Overwrite existing files (default: false) | |
| project_name | Yes | Name of the project to initialize docs for | |
| project_path | No | Absolute path to the project repository (for creating external docs like README) |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully discloses behavior: it creates files in specific locations, handles missing docs automatically, and respects the overwrite parameter. No contradictions or hidden effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three sentences that efficiently convey the tool's purpose, customization options, and behavior. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functionality, customization via parameters, and conditional behavior. It lacks details about return values or error handling, but given the tool's complexity and lack of output schema, it is largely complete for an initialization tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context beyond the schema: it explains the dual purpose of project_path (external docs) and that omitting 'files' triggers creation of all missing internal required docs. This adds value above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initializes documentation for a new project using templates, specifying internal (PRD, Architecture) and external (README, CHANGELOG, QUICKSTART) docs. This distinguishes it from sibling tools like lint or validate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: when project_path is given, external docs are also created; the 'files' parameter selects specific documents; without 'files', all missing internal required docs are created. However, it does not explicitly mention when not to use this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lint_projectA
Lint project documentation for semantic issues: broken links, orphaned files, stale markers (WIP/TODO/FIXME/DRAFT/DEPRECATED), and stale year references.
Use this tool when the user asks to check doc quality beyond policy compliance, find broken internal links, locate TODO/WIP content, or audit doc hygiene.
Checks:
broken-link (warning): wikilinks [[target]] or markdown links text that resolve to no file
orphan (info): files not linked from any other document (index/readme/moc excluded)
stale-marker (warning): files containing WIP, TODO, FIXME, DRAFT, DEPRECATED, DO NOT USE, OUTDATED
stale-date (info): files mentioning a year that is 2+ years in the past
Optionally filter by project name. If omitted, scans all projects.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name to lint (omit for all projects) |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description clearly conveys that the tool is read-only (linting) and lists the checks performed. It does not explicitly state that it does not modify files, but the context implies analysis. It could be improved by confirming no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first sentence states purpose, followed by usage context, then a bullet list of checks, and finally the optional parameter. Every sentence adds value, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately explains what the tool returns (checks with type) and covers all necessary aspects: purpose, when to use, what it checks, and parameter usage. It is complete for a lint tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full coverage (100%) for the single parameter 'project'. The description adds value by explaining the effect of omitting the parameter (scans all projects), which goes beyond the schema's description. Hence, above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's purpose: linting project documentation for semantic issues. It lists specific check types (broken links, orphan files, stale markers, stale dates) which distinguishes it from sibling tools like audit_project or validate_docs that focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (e.g., check doc quality, find broken links, audit hygiene) and mentions the optional project filter. However, it lacks explicit when-not-to-use guidance or alternatives, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsA
List all projects that have documentation stored in the alcove doc-repo.
Use this tool when:
The user asks which projects are available or tracked in alcove
You need to verify a project exists before calling get_project_docs_overview or search_project_docs
The user wants to switch project context or compare projects
Before using scope="global" in search_project_docs to understand what will be searched
It is read-only and has no side effects. Does not require any parameters.
Returns an array of project names derived from subdirectory names in the alcove doc-repo. Returns an empty array if no projects have been initialized yet — use init_project to create one. Project names are case-sensitive and match the directory names exactly.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: read-only, no side effects, no parameters, returns array of project names, empty array if no projects, case-sensitive. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a purpose statement, bullet list of use cases, and behavioral details. Every sentence is meaningful, and it is concise with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is fully complete: it explains what is returned, the source, case sensitivity, and empty case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and the description confirms 'Does not require any parameters.' Since schema coverage is 100% trivially, the description adds value by clarifying the lack of parameters. Baseline 4 for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all projects that have documentation stored in the alcove doc-repo', providing a specific verb and resource. It distinguishes from sibling tools by focusing on listing vs. other operations like search, init, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists four explicit scenarios when to use the tool, such as verifying project existence before calling get_project_docs_overview, and mentions using it before scope='global' search. It provides clear when-to-use and alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_vaultsA
List all knowledge base vaults with their document counts.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation but does not disclose potential behaviors like authentication needs, rate limits, or pagination. For a simple list operation, the transparency is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource. It is concise and contains no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema, no annotations), the description is largely complete. It explains the scope 'all' and the inclusion of document counts. Missing details like sorting or pagination are acceptable for a basic list all operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with zero parameters. The description does not need to add parameter info. It does not provide any additional meaning beyond the schema, which is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'knowledge base vaults', and adds 'with their document counts' for extra detail. It clearly distinguishes from sibling tools like backup_vault or search_vault which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states that it lists all vaults, providing clear context for when to use. However, it does not explicitly mention when not to use or contrast with alternatives like search_vault for searching within vaults.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
promote_documentA
Promote a document from an external vault (e.g. Obsidian) into the alcove doc-repo.
Use this tool when the user wants to import, migrate, or copy a file from outside alcove into the appropriate project directory.
If 'project' is not specified, the target project is auto-detected by matching the file name and content keywords against known project directory names. Falls back to the 'inbox/' directory if no match is found.
By default, the file is copied (safe). Set copy=false to move it instead.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| copy | No | Copy the file (true, default) or move it (false) | |
| project | No | Target project name (auto-detected if omitted) | |
| source | Yes | Absolute path to the source file to promote |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses auto-detection of project, fallback to inbox, and copy vs move behavior. No annotations exist, so description carries full burden. It provides sufficient transparency beyond simple mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four succinct sentences: purpose, usage, auto-detection, copy/move default. Front-loaded with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key behaviors and parameters. Lacks output specification, but for a simple import tool this is acceptable. Could hint at return value (e.g., confirmation path).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds meaning: copy default true, project auto-detected, source absolute path. Each parameter gets extra context beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Promote a document from an external vault (e.g. Obsidian) into the alcove doc-repo.' This distinguishes it from sibling tools like get_doc_file or search_vault, which deal with internal documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this tool when the user wants to import, migrate, or copy a file from outside alcove.' Provides context but does not explicitly list when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rebuild_indexA
Trigger an incremental index update in the background. Returns immediately — the agent is not blocked while indexing runs. Run this after adding or updating documents. Search results will reflect the new documents once indexing completes.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavior: returns immediately without blocking, and search results reflect changes after completion. No annotations provided, so description carries burden; it does so well for a simple async operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each providing essential information: action, blocking behavior, usage trigger, and effect. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, and async behavior. Lacks mention of idempotency or error conditions, but given simplicity and absence of output schema, completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description adds no parameter info, which is acceptable for a tool with zero inputs. Baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Trigger an incremental index update' with a specific verb and resource. It distinguishes itself from sibling tools like search_project_docs or list_projects by focusing on background indexing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Run this after adding or updating documents,' providing clear usage context. Omits mention of when not to use or alternatives, but the sibling set does not offer a similar rebuild tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_project_docsA
Search documentation files for a keyword or phrase. Automatically uses BM25 ranked search when index is available, falls back to grep (substring match) otherwise.
scope="project" (default): current project only, based on CWD. scope="global": search across ALL projects in the doc repository.
Use global scope when the user:
does not specify a project, or says 'all projects', 'everywhere', 'across projects'
references previously saved notes, knowledge, or past decisions
wants to compare how different projects handle the same topic
uses words like 'find everywhere', 'search everything', 'all docs'
asks in Korean: '전체', '모든 프로젝트', '다른 프로젝트에서는'
Use project scope (default) when the user asks about the current project context.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 20) | |
| mode | No | Override search mode. Options: "grep" (regex-only search, skips BM25 index). Omit for default hybrid search. | |
| query | Yes | Search query | |
| scope | No | Search scope: 'project' (default, current project only) or 'global' (all projects). Omit or set to 'project' for current project. |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses automatic BM25 fallback to grep and scope behavior. However, it doesn't describe what the output looks like (e.g., file names, snippets) or mention any rate limits or auth requirements, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for scope guidance, and the main purpose is front-loaded. While every sentence adds value, it could be slightly more streamlined. Overall, it's appropriately sized and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters, the description thoroughly explains search behavior and scope usage. It does not describe the return format or what happens with no results, but for a search tool, it covers the essential aspects for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant value beyond the schema: it explains the default scope derived from CWD, provides concrete examples of when to use each scope (including Korean), and clarifies the mode parameter's effect (skipping BM25 index).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches documentation files for a keyword/phrase, specifying two search mechanisms (BM25 ranked and grep) and two scopes (project and global). It distinguishes itself from sibling tools like 'search_vault' by targeting project docs specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit and actionable guidance on when to use global vs project scope, including specific user language examples (e.g., 'all projects', 'everywhere', Korean phrases). It also implies default behavior for project scope. Though it doesn't mention alternatives like 'search_vault', the sibling list makes the differentiation clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_vaultA
Search knowledge base vaults for a query. Use this to find information in research notes, reference materials, and curated knowledge bases — separate from project documentation.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 20) | |
| query | Yes | Search query | |
| vault | No | Vault name to search. Omit or use '*' to search all vaults. |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. It does not mention any side effects, authentication needs, or rate limits. However, as a search tool, it is likely read-only and safe. A mention of read-only nature would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. The first sentence states purpose, the second adds usage context. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, all described in schema, and no output schema, the description is sufficient. It provides the key context of separation from project documentation. Could mention return format but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds context on usage but does not elaborate on parameter semantics beyond what schema already provides (limit, query, vault). Adequate but no added value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (search), resource (knowledge base vaults), and distinguishes from project documentation by explicitly saying 'separate from project documentation', which helps differentiate from sibling tool search_project_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tells when to use: for research notes, reference materials, curated knowledge bases. Implicitly says not to use for project documentation. Also mentions option to search all vaults by omitting vault parameter or using '*', providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_docsA
Validate the current project's documentation against the team policy defined in policy.toml.
Use this tool when the user asks to check doc quality, run a policy check, or verify docs before a release. It is read-only and does not modify any files.
Checks performed:
Required files exist
Template placeholders (e.g. TODO, FIXME) have been filled in
Required section headings are present
Lists meet minimum item counts defined in policy
Returns a pass/warn/fail status per file with specific details about each violation. If no policy.toml exists, returns a message indicating policy is not configured. Use configure_project or init_project to set up policy.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description discloses read-only nature, checks performed, and fallback behavior for missing policy. Only minor omission is potential scope of doc scanning, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured front-loaded with purpose and usage, then detailed checks and return. Sentences are efficient, though slightly verbose but not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, description covers key aspects: purpose, usage, checks, and return format. Slight gap in exact output structure, but sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters (0 params), so baseline is 4. Description adds context about validation without needing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'validate' and the resource 'current project's documentation against policy.toml'. It distinguishes from siblings like lint_project by emphasizing policy compliance checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'user asks to check doc quality, run a policy check, or verify docs before a release'. Also advises use of configure_project if policy missing, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.8.6- Added
backup_vault
6 tool updates
v0.7.9- Changed
get_doc_file2 fields changed- changed
Input schema / properties / limit / descriptionPrevious value: -"Max characters to return (default: all)"New value: +"Max characters to return (default: entire file). Use together with offset to read in chunks." - changed
Input schema / properties / offset / descriptionPrevious value: -"Character offset to start reading from (default: 0)"New value: +"Character offset to start reading from (default: 0). Use for paginating large files."
- Added
lint_project - Added
list_vaults - Added
promote_document - Changed
search_project_docs1 field changed- added
Input schema / properties / modeAdded value: +{ + "description": "Override search mode. Options: \"grep\" (regex-only search, skips BM25 index). Omit for default hybrid search.", + "enum": [ + "grep" + ], + "type": "string" +}
- Added
search_vault
10 tool updates
v0.7.10- First observed
audit_project - First observed
check_doc_changes - First observed
configure_project - First observed
get_doc_file - First observed
get_project_docs_overview - First observed
init_project - First observed
list_projects - First observed
rebuild_index - First observed
search_project_docs - First observed
validate_docs
TDQS
A4.3/5.0
Scored across 15 tools
Disambiguation4/5
Most tools have distinct purposes (audit vs. validate vs. lint could overlap, but descriptions clarify: audit focuses on missing/outdated, validate on policy, lint on semantic issues). Some overlap exists between search_vault and search_project_docs, but scope separation is clear.
Naming Consistency4/5
Most tools follow a verb_noun pattern (get_project_docs_overview, search_project_docs, list_projects, configure_project). Minor deviations like 'promote_document' and 'check_doc_changes' are still consistent in style. Slight inconsistency in count (some use 'docs' vs 'document').
Tool Count5/5
15 tools is well-scoped for a documentation management server, covering viewing, searching, initialization, configuration, validation, linting, indexing, and vault operations. Each tool serves a clear purpose without feeling excessive.
Completeness4/5
Covers the main lifecycle: init (init_project), read (get_doc_file, search_project_docs), update (import via promote_document, rebuild_index), and quality checks (audit, validate, lint). Minor gaps include no direct doc editing/update tool and no delete tool, but agents can use file system tools externally.
Maintenance
ActivityMaintained
ResponsivenessWithin a week
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP memory: save sessions/decisions once, search from Claude, Cursor, ChatGPT. EU-hosted FTS.
DocBase MCP server for AI agents
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceLocal MCP server that provides semantic search (RAG) over code repositories, enabling AI clients like Claude and Gemini to access project context without manual re-upload.-
- AlicenseNot gradedqualityDmaintenanceA local MCP server that gives AI coding assistants retrieval access to your personal knowledge base of books, standards, and docs, grounding their answers in sources you trust.MIT
- AlicenseAqualityDmaintenanceA local-first document retrieval MCP server that enables AI coding tools like Codex to search private local documents via semantic search and keyword boost, supporting ingestion of PDF, DOCX, TXT, Markdown, and HTML files.7MIT