You're tired of AI agents writing code that "just works" but still misses how your team actually builds things. They search too broadly, pick generic examples, and spend tokens exploring before they understand the shape of the repo.
codebase-context changes the first step. Start with a bounded conventions map that shows the architecture, dominant patterns, and strongest local examples. Then search for the exact file, symbol, or workflow you need.
Here's what codebase-context does:
Starts with a bounded conventions map - The first call shows architecture layers, active patterns, golden files, and next calls without dumping vendored repos, fixtures, generated output, or oversized entrypoint lists into the default surface.
Finds the right local example - Search does not just return code. Each result comes back with pattern signals, file relationships, and quality indicators so the agent can move from the map to the most relevant local example instead of wandering through raw hits.
Knows what is current - Conventions are detected from your code and git history, not only from rules you wrote. The map distinguishes what is common from what is rising or declining, and points at the files that best represent the current direction.
Adds support signals when you need them - Team memory and edit-readiness checks stay available, but as supporting context after the map and search have already narrowed the work.
Map first, search second, local-first throughout. Your code never leaves your machine by default.
See the current discovery benchmark for the checked-in discovery-only proof. The gate is still pending_evidence, and claimAllowed remains false.
Real CLI output against angular-spotify, the repo used for the launch screenshots.
Lead signal: pattern drift and golden files
This is the part most tools miss: what the team is doing now, what it is moving away from, and which files are the strongest examples to follow.
Before editing: preflight and impact
When the agent searches with edit intent, it gets a compact decision card: confidence, whether it's safe to proceed, which patterns apply, the best example, and which files are likely to be affected.
More CLI examples in docs/cli.md. Full walkthrough: demo.md on GitHub.
Related MCP server: Carto MCP Server
claude mcp add codebase-context -- npx -y codebase-contextThe server runs in two modes. Use stdio unless you need multiple clients connected at once:
Mode | How it runs | When to use |
stdio (default) | Process spawned by the client | One AI client talking to one or more repos |
HTTP | Long-lived server at | Multiple clients sharing one server |
Client support at a glance:
Client | stdio | HTTP |
Claude Code | Yes | No (stdio only) |
Claude Desktop | Yes | No |
Cursor | Yes | Yes — |
Windsurf | Yes | Not yet |
Codex | Yes | Yes — |
VS Code (Copilot) | Yes | No |
OpenCode | Yes | Not documented yet |
Copy-pasteable templates: templates/mcp/stdio/.mcp.json and templates/mcp/http/.mcp.json.
Full per-client setup, HTTP server instructions, and local build testing: docs/client-setup.md.
Get a conventions map of your codebase before exploring or editing:
# See your codebase conventions — architecture layers, patterns, golden files
npx -y codebase-context map
# Then search for what you need
npx -y codebase-context search --query "auth middleware"Your AI agent uses the same map via the codebase://context MCP resource on first call.
Three commands to understand a repo before you edit it:
# What are the main conventions and best examples?
npx -y codebase-context map
# Then search for the local example you need
npx -y codebase-context search --query "auth middleware"
# What patterns is the team actually using right now?
npx -y codebase-context patternsThis is also what your AI agent consumes automatically via MCP tools; the CLI is the human-readable version of the same map-plus-search flow.
search_codebase)One call returns ranked results with file, summary, score, compact type (componentType:layer), pattern trend signals, relationship hints, related team memories, a search quality assessment, and a preflight decision card when intent="edit". The decision card shows ready (boolean), nextAction when not ready, patterns (do/avoid), bestExample, impact coverage ("3/5 callers in results"), and whatWouldHelp.
Default output is lean — if the agent wants code, it calls read_file. Add includeSnippets: true for inline code with scope headers (e.g. // AuthService.getToken()).
See docs/capabilities.md for the full field reference.
get_team_patterns)Detects what your team actually does by analyzing the codebase: adoption percentages for DI, state management, testing, and library patterns; trend direction (Rising / Stable / Declining) from git recency; golden files ranked by modern pattern density; conflicts when two approaches both exceed 20%.
remember + get_memory)Record a decision once. It surfaces automatically in search results and preflight cards from then on. Conventional commits (refactor:, migrate:, fix:, revert:) from the last 90 days auto-extract into memory during indexing — no setup required.
Memory types: convention, decision, gotcha, failure. Confidence decay: conventions never decay, decisions 180-day half-life, gotchas/failures 90-day. Stale memories get flagged instead of blindly trusted.
Tool | What it does |
| Hybrid search + decision card when |
| Pattern frequencies, golden files, conflict detection |
| Concrete references to a symbol (count + snippets) |
| Record a convention, decision, gotcha, or failure |
| Query team memory with confidence decay scoring |
| Project structure, frameworks, dependencies |
| Style guide rules for the current project |
| Import cycles between files |
| Full or incremental re-index + git memory extraction |
| Progress and stats for the current index |
One server, multiple repos. Three cases:
Case | What happens |
One project | Routing is automatic |
Multiple projects, active project already set | Routes to the active project |
Multiple projects, ambiguous | Returns |
project accepts a project root path, file path, file:// URI, or relative subproject path (e.g. apps/dashboard).
{
"name": "search_codebase",
"arguments": {
"query": "auth interceptor",
"project": "apps/dashboard"
}
}If you get selection_required, retry with one of the paths from availableProjects. Full routing details and response shapes in docs/capabilities.md.
10 languages with full symbol extraction via Tree-sitter: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust. 30+ languages with indexing and retrieval coverage, including PHP, Ruby, Swift, Scala, Shell, and config formats. Angular, React, and Next.js have dedicated analyzers; everything else uses the Generic analyzer with AST-aligned chunking when a grammar is available.
Variable | Default | Description |
|
|
|
| — | Required only if using |
| — | Bootstrap root for CLI and single-project MCP clients |
| — | Set to |
|
| Local embedding model override |
| — | Set to |
|
| HTTP server port override (same as |
|
| Override the server config file path |
First indexing: 2-5 minutes for ~30k files (embedding computation).
Subsequent queries: milliseconds from cache.
Incremental updates: refresh_index with incrementalOnly: true processes only changed files (SHA-256 manifest diffing).
.codebase-context/
memory.json # Team knowledge (should be persisted in git)
index-meta.json # Index metadata and version (generated)
intelligence.json # Pattern analysis (generated)
relationships.json # File/symbol relationships (generated)
index.json # Keyword index (generated)
index/ # Vector database (generated)Recommended .gitignore:
# Codebase Context - ignore generated files, keep memory
.codebase-context/*
!.codebase-context/memory.jsonPaste this into .cursorrules, CLAUDE.md, AGENTS.md, or wherever your AI reads project instructions:
## Codebase Context (MCP)
**Start of every task:** Call `get_memory` to load team conventions before writing any code.
**Before editing existing code:** Call `search_codebase` with `intent: "edit"`. If the preflight card says `ready: false`, read the listed files before touching anything.
**Before writing new code:** Call `get_team_patterns` to check how the team handles DI, state, testing, and library wrappers — don't introduce a new pattern if one already exists.
**When asked to "remember" or "record" something:** Call `remember` immediately, before doing anything else.
**When adding imports that cross module boundaries:** Call `detect_circular_dependencies` with the relevant scope after adding the import.These are the behaviors that make the most difference day-to-day. Copy, trim what doesn't apply to your stack, and add it once.
Benchmark — current discovery suite results and gate truth
Demo — real CLI walkthrough
Client Setup — per-client config, HTTP setup, local build testing
Capabilities Reference — tool API, retrieval pipeline, decision card schema
CLI Gallery — formatted command output examples
Motivation — research and design rationale
Contributing — dev setup and eval harness
Elastic-2.0
Routes to the active/current project automatically when known. Analyze the import graph to detect circular dependencies between files. Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. Returns all detected cycles sorted by length (shorter cycles are often more problematic).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional path prefix to limit analysis (e.g., 'src/features', 'libs/shared') | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals that results are sorted by length and notes that shorter cycles are often more problematic. However, it does not explicitly state whether the operation is read-only or has side effects, nor does it mention performance implications for large codebases.
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 three sentences, efficient but with a minor redundancy: the first sentence about routing ('Routes to the active/current project automatically') is not central to the tool's purpose. Overall, it is well-structured and front-loads the core action.
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 explains return value sorting and interpretation but lacks details on output format, data structure of cycles, or potential limitations (e.g., large graphs). Given no output schema, this is adequate but leaves ambiguity for complex filtering needs.
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 input schema covers all three parameters with descriptions, achieving 100% schema description coverage. The tool description does not add meaningful detail beyond what the schema already provides (e.g., 'scope' is described as an optional path prefix in both). Baseline score of 3 applies.
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 the tool's function: 'Analyze the import graph to detect circular dependencies between files.' It identifies a specific verb (analyze/detect) and a distinct resource (circular dependencies in imports), differentiating it from sibling tools like get_codebase_health.
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 explains why circular dependencies are problematic ('can cause initialization issues, tight coupling'), implying the tool's value. However, no explicit guidance on when to use this tool versus alternatives (e.g., get_codebase_health), nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Get actionable codebase health signals from the latest index. Returns the highest-risk files and their reasons, or a single file when requested.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Optional file path to inspect a single file-level health record. | |
| limit | No | Maximum number of files to return when no file is specified (default: 10). | |
| level | No | Optional minimum health level to return. | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions auto-routing to active project and returns risk info, but does not explicitly state read-only nature or any side effects. Incomplete for a tool with no annotations.
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?
Three sentences with no fluff. First sentence sets behavioral expectation, second states purpose, third gives filtering options. Efficient and well-structured.
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?
Adequate for a read tool with good schema coverage, but lacks detail on return format (e.g., what constitutes 'health signals' or 'highest-risk'). Output schema is absent, so more description would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds context for 'file' parameter (why to use it) but largely mirrors schema. Does not compensate for any missing schema details.
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 the tool retrieves actionable codebase health signals, returns highest-risk files with reasons, or single file when requested. It distinguishes from siblings like get_codebase_metadata and detect_circular_dependencies.
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?
Implies routing to active project automatically, so user may not need to specify project, but no explicit when-to-use or when-not-to-use compared to alternatives. Lacks exclusions for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Get codebase metadata including framework information, dependencies, architecture patterns, and project statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It reveals one behavioral trait (automatic routing), but does not address potential error states, authentication requirements, or the read-only nature of the operation. This provides moderate transparency but leaves gaps.
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 extremely concise with two sentences, front-loading the key behavioral hint. Every word adds value without redundancy or fluff.
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 lack of output schema and the moderate complexity of the tool (multiple metadata types), the description provides a reasonable overview but does not fully specify the return structure, error conditions, or behavior when no project is known. It is adequate but not comprehensive.
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 input schema has 100% description coverage for both parameters (project and project_directory). The description adds no additional meaning beyond what the schema already provides. Per the guidelines, with high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves codebase metadata including specific items like framework, dependencies, architecture patterns, and statistics. This sufficiently distinguishes it from sibling tools that have different focuses (e.g., health, style guide), though it could be more explicit about what it does not cover.
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 mentions automatic routing to the active project when known, providing some context. However, there is no explicit guidance on when to use this tool versus alternatives like get_codebase_health or get_team_patterns, nor any mention of prerequisites or 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.
Routes to the active/current project automatically when known. Get current indexing status: state, statistics, and progress. Use refresh_index to manually trigger re-indexing when needed.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions automatic routing behavior, which is useful. No destructive actions implied, but lacks details on permissions or rate limits. For a read-only status tool, it's transparent enough.
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?
Two sentences, no fluff. First sentence gives routing behavior, second gives tool purpose and sibling reference. Exceptionally concise.
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?
Covers purpose, routing, and sibling reference. No output schema, but description mentions return includes state, statistics, and progress. Missing detailed output structure, but adequate for a status check tool.
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 100% with descriptions for both parameters. Description adds that project accepts various formats and project_directory is deprecated, slightly complementing schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get current indexing status: state, statistics, and progress.' Verb and resource are specific, and it distinguishes from sibling refresh_index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Routes to the active/current project automatically' and 'Use refresh_index to manually trigger re-indexing when needed,' providing clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Retrieves team conventions, architectural decisions, and known gotchas. CALL BEFORE suggesting patterns, libraries, or architecture.
Filters: category (tooling/architecture/testing/dependencies/conventions), type (convention/decision/gotcha), query (keyword search).
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category | |
| type | No | Filter by memory type | |
| query | No | Keyword search across memory and reason | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions automatic routing to the active project. It fails to disclose behavioral traits such as read-only nature, side effects, error handling, or limitations, which is a significant gap for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a line listing filters. Every sentence provides essential information without extraneous words, making it easy to scan.
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?
With no output schema and no annotations, the description covers purpose and usage well but lacks details on return values, result count, pagination, or error conditions. It is adequate but not fully complete for a tool that influences important decisions.
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 description adds value by listing filter enums and query usage, but it omits two parameters (project and project_directory) entirely. Since schema description coverage is 100%, the baseline is 3, but missing param details reduce the added value.
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 the tool retrieves team conventions, architectural decisions, and known gotchas, with automatic routing to the active project. It distinguishes itself from siblings like get_style_guide or get_team_patterns by being a general memory retrieval tool.
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 advises 'CALL BEFORE suggesting patterns, libraries, or architecture,' providing clear context for when to use. It lacks explicit when-not-to-use or alternative tool mentions, but the usage instruction is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Query style guide rules and architectural patterns from project documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Query for specific style guide rules (e.g., "component naming", "service patterns") | |
| category | No | Filter by category (naming, structure, patterns, testing) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals the automatic project routing behavior and the query nature, suggesting a read-only operation. However, it does not explicitly state that it is non-destructive, what happens if no project is active, or any error conditions, leaving some behavioral ambiguity.
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 only two sentences, front-loading the key automatic routing feature and then the main query purpose. Every sentence is necessary and without fluff, achieving maximum conciseness.
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?
No output schema exists, so the description should explain what the tool returns. It does not describe the return format, error handling, or behavior when no results are found. The deprecated 'project_directory' parameter is not addressed. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter descriptions in schema cover 100% of parameters, already defining each parameter's purpose. The description adds value by explaining the automatic routing behavior for the optional 'project' parameter, clarifying that omitting it uses the active project, which goes beyond the schema's description.
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 the tool queries style guide rules and architectural patterns from project documentation, using the verb 'Query' and resource 'style guide rules and architectural patterns'. It distinguishes itself from siblings like search_codebase (which is broader) and get_team_patterns (which is team-specific) by focusing specifically on style guide documentation.
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 usage for querying style guide rules in the current project due to automatic routing, but does not explicitly state when to use it over alternatives (e.g., search_codebase for general search, get_team_patterns for team patterns). No when-not or explicit alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Find concrete references to a symbol in indexed chunks. Returns total usageCount and top usage snippets.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Symbol name to find references for (for example: parseConfig or UserService) | |
| limit | No | Maximum number of usage snippets to return (default: 10) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It mentions automatic routing to active project and return values, but lacks details on error cases, latency, or index prerequisites. Adequate but not thorough.
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?
Two concise sentences that front-load key information: routing and core function. No fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description mentions return values (usageCount and snippets). It covers the core function and project routing, but could elaborate on snippet ranking and error conditions.
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 100%, so baseline is 3. The description adds little beyond what the schema already provides for parameters. The routing behavior hinted at is not tied explicitly to parameters.
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 the tool's purpose: finding concrete references to a symbol in indexed chunks. It uses specific verbs and resources, and the name itself is descriptive. Though it doesn't explicitly differentiate from siblings, the function is distinct.
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 on when to use this tool versus alternatives like search_codebase or detect_circular_dependencies. The description does not mention prerequisites or 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.
Routes to the active/current project automatically when known. Get actionable team pattern recommendations based on codebase analysis. Returns consensus patterns for DI, state management, testing, library wrappers, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Pattern category to retrieve | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions automatic project routing (a behavioral trait) and returns consensus patterns. No side effects or mutability mentioned, but seems read-only.
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?
Two concise sentences, front-loaded with key purpose and automatic behavior. No unnecessary words.
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 tool with 3 params and no output schema, description is fairly complete: explains what it does, mentions project auto-routing, and lists pattern types. Could clarify return structure or 'consensus patterns' further.
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 100% with clear param descriptions. Description adds context by listing example pattern categories (DI, state, testing) which correspond to the enum values, providing meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves team pattern recommendations for specific categories (DI, state management, etc.) and mentions automatic project routing. Distinguished from siblings like get_codebase_health and get_style_guide.
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 explicit when-to-use or when-not-to-use guidance. Context signals and sibling names imply usage for pattern analysis, but no direct alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Re-index the codebase. Supports full re-index or incremental mode. Use incrementalOnly=true to only process files changed since last index.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for refreshing the index (for logging) | |
| incrementalOnly | No | If true, only re-index files changed since last full index (faster). Default: false (full re-index) | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions automatic routeing to the active project and re-indexing behavior, but does not disclose side effects, permissions, or what happens to the existing index. With no annotations, more detail would be beneficial.
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?
Three sentences conveying essential info, though the first sentence is slightly ambiguous ('Routes to...'). Still, it is concise and 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?
No output schema is provided, and the description does not explain what the tool returns or how to interpret results, leaving the agent without critical information for a re-index operation.
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?
All parameters have schema descriptions (100% coverage). The description adds minor guidance on incrementalOnly usage, but mostly restates schema info, so it provides limited added value.
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 it re-indexes the codebase and supports full or incremental modes, distinguishing it from siblings like search_codebase or get_indexing_status.
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 advises using incrementalOnly=true for faster re-indexing of changed files, but does not explicitly state when not to use the tool or mention alternative tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. CALL IMMEDIATELY when user explicitly asks to remember/record something.
USER TRIGGERS:
"Remember this: [X]"
"Record this: [Y]"
"Save this for next time: [Z]"
DO NOT call unless user explicitly requests it.
HOW TO WRITE:
ONE convention per memory (if user lists 5 things, call this 5 times)
memory: 5-10 words (the specific rule)
reason: 1 sentence (why it matters)
Skip: one-time features, code examples, essays
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type of memory being recorded. Use "failure" for things that were tried and failed - prevents repeating the same mistakes. | |
| category | Yes | Broader category for filtering | |
| memory | Yes | What to remember (concise) | |
| reason | Yes | Why this matters or what breaks otherwise | |
| scope | No | Optional scope for this memory. Use { kind: "file", file } or { kind: "symbol", file, symbol }. | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions 'Routes to the active/current project automatically' but does not disclose side effects (e.g., whether memories overwrite, persistence, permissions, or rate limits). The instructions on writing style give some behavioral expectations but leave significant gaps.
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 structured with headings (USER TRIGGERS, DO NOT, HOW TO WRITE) and front-loads the key action. While it is somewhat lengthy, every section serves a purpose. Minor redundancy in listing all triggers could be trimmed, but overall it is well-organized.
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?
With 7 parameters (4 required) and no output schema, the description provides good guidance on when and how to call, but omits post-call behavior (e.g., success confirmation, error handling). The agent must infer that memories are stored since get_memory exists. Context is adequate but not fully complete.
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 100%, so baseline is 3. The description adds value by providing guidance on how to write 'memory' (5-10 words) and 'reason' (1 sentence), and explains when to use 'failure' type. This enriches the schema descriptions and helps the agent use parameters effectively.
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 the tool's purpose: to remember/record something when the user explicitly asks. It lists specific user triggers ('Remember this', 'Record this', 'Save this for next time') and provides instructions for when to call it. This differentiates it from siblings like get_memory, which retrieves memories.
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 explicit guidelines: 'CALL IMMEDIATELY when user explicitly asks to remember/record something' and 'DO NOT call unless user explicitly requests it.' It also gives writing conventions ('ONE convention per memory', 'memory: 5-10 words', 'Skip: one-time features, code examples, essays'), making the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Routes to the active/current project automatically when known. Search the indexed codebase. Default compact mode returns at most 6 ranked results with light graph context (importedByCount, topExports, layer), a patternSummary, bestExample, nextHops, and response-budget metadata. Use mode="full" for today's richer response with full hints arrays and all memories — identical shape as before this parameter existed. IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| mode | No | Response mode. compact (default): max 6 results with light graph context, pattern summary, best example, next hops, and budget metadata. full: today's richer shape + budget metadata. | compact |
| intent | No | Optional. Use "edit", "refactor", or "migrate" to get the full preflight card before making changes. | |
| limit | No | Maximum number of results to return (default: 5) | |
| includeSnippets | No | Include code snippets in results (default: false). If you need code, prefer read_file instead. | |
| filters | No | Optional filters | |
| project | No | Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root. | |
| project_directory | No | Deprecated compatibility alias for older clients. Prefer project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral transparency. It describes default behavior (compact mode, 6 results, graph context), full mode, intent parameter effects, and hints about response metadata. It also warns about includeSnippets default and recommends read_file for code.
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, front-loading key information about routing and search function. It provides detailed mode and intent guidance but could be more concise by merging some sentences. Overall, it balances detail and readability.
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 no output schema, the description explains the compact mode return shape (graph context, pattern summary, etc.) and mentions budget metadata. It covers filters and parameters. However, it omits error handling, pagination beyond limit, and behavior for empty queries. Still fairly complete for a search tool.
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 100%, baseline is 3. The description adds value by explaining the compact mode result count (at most 6 vs schema default limit of 5), clarifying the intent parameter's role for preflight, and noting the routing behavior for project. This exceeds basic schema info.
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 it searches the indexed codebase, auto-routes to active project, and details the return format. It distinguishes from siblings like get_codebase_health or detect_circular_dependencies by being a search tool.
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 guides when to use compact vs full mode and when to pass intent for preflight. It notes that includeSnippets is false by default and to prefer read_file. However, it does not contrast with sibling tools or mention when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.6.0detect_circular_dependencies2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_codebase_healthget_codebase_metadata2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_component_usageget_indexing_status2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}get_memory3 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / properties / type / enumPrevious value: -[
- "convention",
- "decision",
- "gotcha"
-]New value: +[
+ "convention",
+ "decision",
+ "gotcha",
+ "failure"
+]get_style_guide3 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "query"
-]get_symbol_referencesget_team_patterns2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}refresh_index2 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}remember5 fields changedInput schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}Input schema / properties / scopeAdded value: +{
+ "description": "Optional scope for this memory. Use { kind: \"file\", file } or { kind: \"symbol\", file, symbol }.",
+ "properties": {
+ "file": {
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "global",
+ "file",
+ "symbol"
+ ],
+ "type": "string"
+ },
+ "symbol": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Input schema / properties / type / descriptionPrevious value: -"Type of memory being recorded"New value: +"Type of memory being recorded. Use \"failure\" for things that were tried and failed - prevents repeating the same mistakes."Input schema / properties / type / enumPrevious value: -[
- "convention",
- "decision",
- "gotcha"
-]New value: +[
+ "convention",
+ "decision",
+ "gotcha",
+ "failure"
+]search_codebase6 fields changedInput schema / properties / filters / properties / framework / descriptionPrevious value: -"Filter by framework (angular, react, vue)"New value: +"Filter by framework (angular, react, nextjs, vue)"Input schema / properties / includeSnippetsAdded value: +{
+ "default": false,
+ "description": "Include code snippets in results (default: false). If you need code, prefer read_file instead.",
+ "type": "boolean"
+}Input schema / properties / intentAdded value: +{
+ "description": "Optional. Use \"edit\", \"refactor\", or \"migrate\" to get the full preflight card before making changes.",
+ "enum": [
+ "explore",
+ "edit",
+ "refactor",
+ "migrate"
+ ],
+ "type": "string"
+}Input schema / properties / modeAdded value: +{
+ "default": "compact",
+ "description": "Response mode. compact (default): max 6 results with light graph context, pattern summary, best example, next hops, and budget metadata. full: today's richer shape + budget metadata.",
+ "enum": [
+ "compact",
+ "full"
+ ],
+ "type": "string"
+}Input schema / properties / projectAdded value: +{
+ "description": "Optional project selector for this call. Accepts a project root path, file path, file:// URI, or a relative subproject path under a configured root.",
+ "type": "string"
+}Input schema / properties / project_directoryAdded value: +{
+ "description": "Deprecated compatibility alias for older clients. Prefer project.",
+ "type": "string"
+}v1.4.1detect_circular_dependenciesget_codebase_metadataget_component_usageget_indexing_statusget_memoryget_style_guideget_team_patternsrefresh_indexremembersearch_codebaseEach tool targets a distinct aspect of codebase context: detection, health, metadata, indexing, memory, style guide, references, patterns, refresh, remember, and search. No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_codebase_health, detect_circular_dependencies). The only exception is 'remember' which is a single verb but remains clear and fits the pattern.
11 tools is well-scoped for a codebase context server. It covers indexing, querying, analysis, and memory without being overwhelming. Each tool earns its place.
The tool set covers reading and writing codebase knowledge, analysis (dependencies, health, references), and search. Minor gaps exist, such as no direct file content retrieval or code review integration, but the domain of 'context' is well-served.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Serves your design system and coding standards to coding agents, so they stop guessing.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PatrickSys/codebase-context'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
