Allows using Google Gemini embeddings for code search via the gemini-embedding-exp-03-07 model.
Allows using OpenAI embeddings for code search, providing higher-quality semantic search via the text-embedding-3-small model.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VecGrep Search for how authentication is handled in my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cursor-style semantic code search as an MCP plugin for Claude Code.
Instead of grepping 50 files and sending 30,000 tokens to Claude, VecGrep returns the top 8 semantically relevant code chunks (~1,600 tokens). That's a ~95% token reduction for codebase queries.
Measured on the VecGrep codebase itself (5 source files, ~26k tokens raw).
Mode | Avg tokens returned | vs raw read | Savings |
Raw file read (baseline) | 26,009 | — | — |
| ~3,007 | 11.6% | 88% |
| ~3,324 | 12.8% | 87% |
| ~47 | 0.2% | >99% |
search_graph returns structured node metadata only (name, kind, file, line range) — no source code — so it's ultra-cheap for structural questions ("where is X defined?", "what calls Y?").
Mode | Latency |
| ~3ms |
| ~76ms |
| ~83ms |
search_graph is ~30× faster than vector search — pure in-memory graph traversal, no embedding model call.
For name-based structural queries, pure vector search can rank documentation (CHANGELOG, README) above source code. The graph index fixes this:
Query |
|
|
"VectorStore search method" | [WRONG] CHANGELOG.md | [OK] store.py |
"GraphStore build" | [WRONG] CHANGELOG.md | [OK] server.py |
"embedding provider factory" | [OK] embedder.py | [OK] embedder.py |
"AST chunking tree-sitter" | [OK] chunker.py | [OK] chunker.py |
The graph score (graph_score: 1.00) overrides a misleading vector match whenever the query directly names a known symbol.
Rule of thumb: use
search_codefor semantic/behaviour queries,search_graphfor structural/navigation queries,hybrid_searchwhen you need both.
Related MCP server: mcplens
Chunk — Parses source files with tree-sitter to extract semantic units (functions, classes, methods)
Embed — Encodes each chunk using the configured embedding provider:
Local (default) — all-MiniLM-L6-v2-code-search-512 via fastembed ONNX (~100ms startup, no API key) or PyTorch, with auto device detection (Apple Silicon, CUDA, CPU)
Cloud (BYOK) — OpenAI, Voyage AI, or Google Gemini via your own API key (higher-quality embeddings, optional)
Store — Saves embeddings + metadata in LanceDB under ~/.vecgrep/<project_hash>/; vector dimensions adapt automatically to the chosen provider
Search — ANN index (IVF-PQ) for fast approximate search on large codebases
Incremental re-indexing via mtime/size checks skips unchanged files.
Requires Python 3.12 and uv.
Note: Python 3.12 is required —
tree-sitter-languagesdoes not yet have wheels for Python 3.13+.
pip install vecgrep # standard pip
uv tool install --python 3.12 vecgrep # uv tool (recommended)Run once — works for every project:
claude mcp add --scope user vecgrep -- vecgrepThis installs VecGrep as a persistent binary and registers it in your user config (~/.claude.json) so it's available globally across all projects. Starts instantly — no download delay on Claude Code launch.
You don't trigger VecGrep manually - Claude decides when to call the tools based on what you ask.
What you say to Claude | Tool invoked |
"Index my project at /Users/me/myapp" |
|
"How does authentication work in this codebase?" |
|
"Find where database connections are set up" |
|
"How many files are indexed?" |
|
"Build a knowledge graph of my project" |
|
"What calls the VectorStore.search method?" |
|
"Find code structurally related to authentication" |
|
Typical first-time flow:
You: "Search for how payments are handled in /Users/me/myapp"
Claude: [calls index_codebase automatically since no index exists]
Claude: [calls search_code with your query]
Claude: "Here's how payments work — in src/payments.py:42..."After the first index, subsequent searches skip unchanged files automatically — no re-indexing needed unless your code changes.
index_codebase(path, force=False, watch=False, provider=None)Index a project directory. Skips unchanged files on subsequent calls.
index_codebase("/path/to/myproject")
# → "Indexed 142 file(s), 1847 chunk(s) added (0 file(s) skipped, unchanged)"
# Use OpenAI embeddings instead of local
index_codebase("/path/to/myproject", provider="openai")Provider lock: once a project is indexed with a provider, re-indexing with a different provider requires force=True (this rebuilds the vector table with the new embedding dimensions).
Note: watch=True is only supported with the local provider — live sync with cloud providers would incur unbounded API costs.
search_code(query, path, top_k=8)Semantic search. Auto-indexes if no index exists.
search_code("how does user authentication work", "/path/to/myproject")Returns formatted snippets with file paths, line numbers, and similarity scores:
[1] src/auth.py:45-72 (score: 0.87)
def authenticate_user(token: str) -> User:
...
[2] src/middleware.py:12-28 (score: 0.81)
...get_index_status(path)Check index statistics, including the embedding provider used.
Index status for: /path/to/myproject
Files indexed: 142
Total chunks: 1847
Last indexed: 2026-02-22T07:20:31+00:00
Index size: 28.4 MB
Provider: local
Model: isuruwijesiri/all-MiniLM-L6-v2-code-search-512
Dimensions: 384index_graph(path, force=False)Build a structural knowledge graph from the codebase using tree-sitter AST extraction. No LLM required — extracts files, functions, classes, and methods as nodes; contains, calls, imports, and inherits as directed edges. Independent of the vector index.
index_graph("/path/to/myproject")
# → "Graph built: 496 nodes, 1251 edges, 35 files processed."search_graph(query, path, limit=20)Keyword search over node labels (function names, class names, file names). Returns structural nodes with source location and connectivity degree. Ultra-cheap: ~47 tokens average, ~3ms latency.
search_graph("VectorStore", "/path/to/myproject")
# → [1] CLASS VectorStore (score: 1.00, degree: 39)
# src/vecgrep/store.py:49-352graph_neighbors(node_id, path, depth=1)Return the structural neighbourhood of any node — callers, callees, imports, contained methods, and inheritance edges. Use search_graph first to find the node ID.
graph_neighbors("VectorStore", "/path/to/myproject", depth=1)
# → Callers (18): _get_store, migrate_project, test fixtures...
# Contains (18): search, add_chunks, replace_file_chunks...hybrid_search(query, path, top_k=8, alpha=0.6, min_score=0.0)Vector similarity search re-ranked by graph proximity. Final score = alpha * vector_score + (1 - alpha) * graph_score. Fixes cases where documentation ranks above source code on pure embedding similarity.
hybrid_search("VectorStore search method", "/path/to/myproject", alpha=0.6)
# → [1] src/vecgrep/store.py:292-320 (blended: 0.70, vec: 0.49, graph: 1.00)Requires both index_codebase and index_graph to have been run. Degrades gracefully to pure vector search if the graph index is absent.
VecGrep can be tuned via environment variables:
Variable | Default | Description |
|
| Local backend: |
|
| HuggingFace model ID (local provider only) |
Backend comparison:
Backend | Startup | PyTorch required | Custom HF models |
| ~100ms | No | ONNX-exported models only |
| ~2–3s | Yes | Any HuggingFace model |
VecGrep supports three cloud embedding providers. Each requires an API key environment variable and the corresponding optional dependency.
Provider | Env var | Model | Dims | Install extra |
|
|
| 1536 |
|
|
|
| 1024 |
|
|
|
| 3072 |
|
Install cloud extras:
# Single provider
uv tool install --python 3.12 'vecgrep[openai]'
pip install 'vecgrep[openai]'
# All cloud providers at once
pip install 'vecgrep[cloud]'Use a cloud provider:
# Set your API key
export VECGREP_OPENAI_KEY=sk-...
# Index with OpenAI embeddings
index_codebase("/path/to/myproject", provider="openai")
# Or tell Claude to use it:
# "Index my project at /path/to/myproject using openai embeddings"Switch providers (requires force re-index to rebuild the vector table):
index_codebase("/path/to/myproject", provider="voyage", force=True)Local backend examples:
# Use a different model with the torch backend
VECGREP_BACKEND=torch VECGREP_MODEL=sentence-transformers/all-MiniLM-L6-v2 vecgrep
# Use a custom ONNX model
VECGREP_MODEL=my-org/my-onnx-model vecgrepPython, JavaScript/TypeScript, Rust, Go, Java, C/C++, Ruby, Swift, Kotlin, C#
All other text files fall back to sliding-window line chunks.
~/.vecgrep/<sha256-of-project-path>/index.db
Each project gets its own isolated index. Delete the directory to wipe the index.
The embedding model used by VecGrep is all-MiniLM-L6-v2-code-search-512, a model fine-tuned specifically for semantic code search by @isuruwijesiri.
@misc{all_MiniLM_L6_v2_code_search_512,
author = {isuruwijesiri},
title = {all-MiniLM-L6-v2-code-search-512},
year = {2026},
publisher = {Hugging Face},
url = {https://huggingface.co/isuruwijesiri/all-MiniLM-L6-v2-code-search-512}
}? Questions | |
+ Ideas | |
> Show & Tell | |
! Bugs |
Get the status of the vector index for a codebase.
Args:
path: Absolute path to the codebase root directory.
Returns:
Index statistics: file count, chunk count, last indexed time, disk usage.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden; it does so by specifying the exact outputs (file count, chunk count, last indexed time, disk usage). The verb 'Get' and 'status' imply a non-mutating read, which is credible. However, it does not explicitly state side-effect-freeness or error behavior (e.g., if path is not indexed), so it reaches but does not exceed a strong baseline.
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 and front-loaded: a one-sentence purpose followed by clearly labeled Args and Returns blocks. No filler or redundant repetition of the schema exists.
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 single-parameter read-only status tool with an output schema, the description covers the essential call information: what the tool does, how to specify the path, and which statistics are returned. It omits deeper details such as failure modes and when to prefer this over siblings, which are minor for this simple tool but prevent a perfect completeness score.
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 only parameter, path, is fully explained as 'Absolute path to the codebase root directory', adding crucial meaning that the schema itself lacks (the schema only names it 'path' with no description). This is exactly the compensation needed given 0% schema description coverage.
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 verb ('Get') and resource ('the status of the vector index for a codebase'), making its read-only purpose obvious. This clearly distinguishes it from sibling tools like index_codebase, search_code, and hybrid_search, which perform writing or searching operations.
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 implies the tool is for inspecting index state, but it provides no explicit guidance on when to choose it over alternatives, nor any exclusion criteria. For example, it does not say 'check this before indexing' or 'use this to determine if search is stale.' Thus usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return structural neighbors of a graph node.
Shows which functions call this node, which it calls, what it imports,
what it contains, and what it inherits from — up to *depth* hops away.
Use search_graph first to find the exact node ID.
Args:
node_id: Node ID or label substring (e.g. "vectorstore_search" or "search").
path: Absolute path to the codebase root directory.
depth: Number of hops to traverse (1 = direct edges only, default 1).
Returns:
Categorised list of neighboring nodes with their source locations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| depth | No | ||
| node_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description needs to carry the behavioral disclosure burden. It does so by stating the operation is read-only ('Return', 'Shows') and by explaining depth semantics ('1 = direct edges only'). It does not explicitly mention failure modes or prerequisites like needing an already-indexed graph, which is a minor gap.
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 concise, front-loaded with the core action, and well-organized into summary, usage hint, args, and returns. Every section adds value and there is no filler or repetition beyond negligible redundancy between 'Return structural neighbors' and 'Shows which...'.
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 description covers the operation, argument semantics, depth behavior, and return shape ('Categorised list of neighboring nodes with their source locations'), and an output schema exists to handle return details. A true completeness gap is the implicit requirement that the codebase graph must already be indexed, given the sibling index_graph tool; mentioning that would make it fully self-sufficient.
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 coverage is 0%, but the description fully compensates: node_id is explained as 'Node ID or label substring' with examples, path is specified as 'Absolute path to the codebase root directory', and depth is defined as 'Number of hops to traverse' with direct-edge meaning and default. This adds substantial meaning beyond the bare 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?
The description clearly states a specific verb ('Return') and resource ('structural neighbors of a graph node'), then details exactly what kinds of relationships are included: calls, imports, containment, and inheritance. This makes it easy to distinguish from sibling tools like search_graph or search_code.
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?
It gives explicit sequential guidance: 'Use search_graph first to find the exact node ID.' This tells the agent how to prepare before calling, which is practically useful. It could go further and explicitly contrast when to use search_code or hybrid_search instead, but the neighbor-specific language makes the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic vector search re-ranked by knowledge graph proximity.
Combines vector similarity (cosine) with structural graph proximity
(BFS distance from query-matched graph nodes). The final score is:
score = alpha * vector_score + (1 - alpha) * graph_score
Both vector and graph scores are normalised to [0, 1] before blending.
Requires both index_codebase and index_graph to have been run.
Args:
query: Natural language description of what you're looking for.
path: Absolute path to the codebase root directory.
top_k: Number of results to return (default 8, max 20).
alpha: Weight of vector score vs graph score (0.0 = graph only,
1.0 = vector only, default 0.6).
min_score: Minimum blended score threshold (default 0.0).
Returns:
Formatted list of code chunks ranked by blended score.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| alpha | No | ||
| query | Yes | ||
| top_k | No | ||
| min_score | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it provides substantial behavioral detail: the scoring formula, normalization of both scores, the alpha blending semantics, and the dependency on prior indexing. It does not mention side effects, error conditions, or read-only guarantees, but for a search tool the disclosed mechanics are strong.
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 well-structured: a one-line summary, a compact formula, a prerequisites line, an Args section, and a Returns section. Every sentence contributes, with no filler or redundant restatement of the tool name.
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?
Given the tool's moderate complexity, five parameters, and an output schema, the description provides complete invocation guidance: prerequisites, parameter semantics, and return type. It could add explicit behavior when indexes are missing or stale, but nothing essential is missing for a competent agent.
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 0%, so the description must fully compensate, and it does: every parameter gets meaningful semantics, ranges, defaults, and behavioral effect. This is rare and genuinely helpful for an agent selecting and filling arguments.
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 opens with a specific verb-resource phrase, 'Semantic vector search re-ranked by knowledge graph proximity,' which clearly identifies what the tool does. It further distinguishes itself by detailing the hybrid combination of vector similarity and graph proximity, though it does not explicitly name sibling tools like search_code or search_graph.
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 clearly implies when to use the tool: when a hybrid of vector search and graph proximity is desired, and it states the precondition that both index_codebase and index_graph must have been run. However, it does not explicitly contrast this with pure alternative tools or say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a codebase directory for semantic search.
Walks the directory, extracts semantic code chunks using AST analysis,
embeds them locally with sentence-transformers, and stores in a vector index.
Subsequent calls skip unchanged files (incremental updates).
Args:
path: Absolute path to the codebase root directory.
force: If True, re-index all files even if unchanged.
watch: If True, start a background watcher for live sync on file changes.
Not supported with cloud providers (openai, voyage, gemini).
provider: Embedding provider to use. One of: 'local' (default), 'openai',
'voyage', 'gemini'. Cloud providers require the corresponding
env var (VECGREP_OPENAI_KEY, VECGREP_VOYAGE_KEY, VECGREP_GEMINI_KEY)
and optional dependency (pip install 'vecgrep[openai]' etc.).
Once set, switching providers requires force=True to rebuild the index.
Returns:
Summary: files indexed, chunks added, files skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| force | No | ||
| watch | No | ||
| provider | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it reveals directory walking, AST-based chunking, local embedding, vector storage, incremental updates, background watching, and provider-specific requirements. It is not exhaustive about index location or destructive replacement, but it clearly discloses the main behaviors and 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the Args/Returns sections are structured and scannable. The description is moderately long but each sentence contributes relevant behavioral or parameter information; only minor redundancy exists between the opening summary and later details.
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?
All parameters are explained, the return summary is identified, and important constraints such as incremental updates, provider switching, and watch limitations are covered. It could further clarify prerequisites or the relationship to sibling tools, but the output schema reduces the need to document return values in detail.
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 0%, and the Args section fully compensates for all four parameters. It adds path format (absolute), force semantics (re-index unchanged files), watch behavior and cloud-provider incompatibility, and provider enum values plus environment-variable and dependency requirements.
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 opening sentence clearly states the action ('Index'), the resource ('a codebase directory'), and the purpose ('for semantic search'). The description goes on to describe the core workflow, distinguishing it from sibling search and status tools by focusing on ingestion and vector index construction.
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 provides clear context for when indexing is relevant and explains incremental behavior and provider constraints. However, it never explicitly tells an agent when to choose this tool over siblings like index_graph, search_code, or get_index_status; the guidance is parameter-level rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build (or rebuild) a knowledge graph for a codebase.
Walks the directory using the same skip rules as index_codebase, extracts
structural nodes (files, functions, classes) and edges (contains, calls,
imports, inherits) using tree-sitter, and persists the graph to disk.
This is independent of the vector index — you can run index_graph before
or after index_codebase.
Args:
path: Absolute path to the codebase root directory.
force: If True, rebuild the graph even if one already exists.
Returns:
Summary: node count, edge count, files processed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| force | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses that the tool walks the directory, extracts nodes/edges, persists the graph to disk, and supports a force rebuild if a graph already exists. Core side effects are visible, even if performance costs and error behavior are not detailed.
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 tightly organized: a one-line summary, a brief mechanism paragraph, and clear Args/Returns sections. No sentence is wasted, and key concepts like independence from the vector index and force behavior are front-loaded appropriately.
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 description covers the essential invocation context: path requirements, force behavior, return summary (node count, edge count, files processed), and relationship to index_codebase. With the output schema already available, no additional return-structure detail is needed.
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 0%, but the description fully compensates by explaining both parameters: path is 'the absolute path to the codebase root directory' and force means 'rebuild the graph even if one already exists.' This provides complete, actionable meaning beyond the bare schema types.
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 opens with a specific verb and resource: 'Build (or rebuild) a knowledge graph for a codebase.' It further names the extraction outputs (structural nodes and edges) and explicitly mentions tree-sitter, which distinguishes it from vector-index siblings like index_codebase. The agent can confidently identify what this tool does without guessing.
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 gives clear context for how this tool relates to index_codebase ('same skip rules', 'independent of the vector index', 'run before or after'), which helps the agent understand ordering and sequencing. It does not explicitly say when to prefer this tool over graph query tools like search_graph or graph_neighbors, but it implies the build step clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantically search an indexed codebase for code relevant to a query.
Embeds the query and performs cosine similarity search against indexed
code chunks, returning the most semantically relevant snippets with
file paths and line numbers.
If the codebase is not yet indexed, it will be indexed automatically first.
Args:
query: Natural language description of what you're looking for.
E.g. "how does authentication work", "database connection setup"
path: Absolute path to the codebase root directory.
top_k: Number of results to return (default 8, max 20).
min_score: Minimum cosine similarity score to include a result (default 0.35).
Results below this threshold are filtered out as noise. Set to 0.0
to disable filtering.
Returns:
Formatted list of matching code chunks with file:line references and
similarity scores.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| query | Yes | ||
| top_k | No | ||
| min_score | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It reveals the internal mechanism (embedding + cosine similarity), the auto-indexing side effect, and the min_score filtering behavior. This goes well beyond a simple verb phrase and gives the agent confidence about what happens when called.
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 well-structured with a purpose statement, a short mechanism note, a clear args list, and a returns line. Every sentence contributes necessary information, and the most important scoping detail (semantic vs. other search) 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?
Given the tool's complexity, the description covers what it does, how it behaves when the index is missing, all parameter details, and the return format. An output schema exists for the return shape, so listing field details is unnecessary. No essential information for calling it correctly is 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 0%, so the description must compensate, and it does thoroughly. Each of the four parameters is explained with type, default, and relevant examples or constraints (e.g., min_score semantics, max for top_k), adding significant meaning beyond the bare schema titles.
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 opens with a specific verb and resource: 'Semantically search an indexed codebase for code relevant to a query.' It clearly differentiates from sibling tools like search_graph or hybrid_search by explaining the embedding/cosine similarity mechanism, so an agent can tell what this tool uniquely does without opening a schema.
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 gives clear context: use it for natural-language semantic search over code, and it even notes that auto-indexing happens if needed. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the knowledge graph for nodes matching a query.
Performs keyword matching over node labels (function names, class names,
file names) and returns the most relevant structural nodes with their
source locations and relationship degree.
The codebase graph must be built first with index_graph.
Args:
query: Keywords to search for (e.g. "VectorStore", "auth login").
path: Absolute path to the codebase root directory.
limit: Maximum number of results to return (default 20).
Returns:
Matching nodes with kind, source location, and connectivity degree.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses ranking behavior ('most relevant'), scope over structural node labels, return contents (kind, source location, connectivity degree), and a hard dependency on index_graph. It does not mention error behavior if the graph is missing, but for a search tool this is reasonably transparent.
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 key behavior and prerequisite are front-loaded, followed by a compact Args/Returns breakdown. Every sentence adds information; the only minor redundancy is restating the default limit already present in the schema.
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 description is sufficient for a simple 3-parameter search tool: prerequisite, query semantics, limit, and return summary are covered, and an output schema exists for details. It could be more complete by stating behavior when index_graph has not been run and how results are ordered, but nothing critical is 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 0%, so the Args section must carry the semantic weight, and it does. It explains query with concrete examples, path as the codebase root, and limit as maximum results with default. This is exactly the guidance an agent needs beyond the property titles.
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 opening line names a specific verb ('search'), a specific resource ('knowledge graph'), and a query criterion, and the next sentence narrows the target to node labels (function/class/file names), which distinguishes it from sibling search_code and graph_neighbors. This is enough for an agent to know what the tool matches and returns without opening the schema.
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 states the prerequisite ('codebase graph must be built first with index_graph') and gives query style examples. It does not name when-not-to-use alternatives, but it provides clear context about keyword-inside-labels vs code search, so an agent can infer the right situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop watching a codebase for file changes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It names the action but does not disclose side effects, idempotency, error behavior if no watch is active, or whether any associated state is removed.
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 a single sentence with no filler. The core verb and object are front-loaded, and every word contributes to the meaning.
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 state-changing tool with no annotations, the description omits important operational context: when to call it, what path should reference, what happens if nothing is being watched, and what the expected effect is. The one-parameter schema is simple, but the description still does not make the tool confidently callable.
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 0% and the description does not explain the 'path' parameter at all. The agent is left to infer that 'a codebase' refers to the path, but the description adds no meaning beyond the schema's bare 'Path' label.
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: 'Stop watching a codebase for file changes.' This is unambiguous and effectively distinguishes the tool from the indexing/search siblings by operation type, though it does not explicitly compare itself to any sibling.
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?
No guidance is given about when to use this tool versus alternatives, such as when an active watch exists or whether this should be called before re-indexing. The intended use is implied by the operation name, but not explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clear, distinct purposes: indexing vs searching, vector vs graph vs hybrid. The main ambiguity is between search_code and hybrid_search, since hybrid_search with alpha=1.0 is effectively the same as vector semantic search.
Several tools follow a verb_noun pattern (index_graph, index_codebase, search_graph, search_code), but graph_neighbors and hybrid_search deviate by using noun/adjective phrases, and stop_watching uses a gerund instead of a plain verb. The mixed style is readable but not fully consistent.
8 tools is well-scoped for a code search and indexing server. Each tool covers a distinct capability without unnecessary duplication or bloat.
Core lifecycle coverage is solid: indexing, searching, graph traversal, hybrid search, status, and watching. Minor gaps exist, such as no explicit delete/remove index tool and no graph-specific status endpoint, but agents can work around these using force reindexing.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/VecGrep/vecgrep'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
