非官方 — 个人项目，与 Relace 无关联。
AI 构建 — 完全在 AI 辅助下开发（Antigravity、Codex、Cursor、Github Copilot、Windsurf）。
MCP 服务器，提供 AI 驱动的代码编辑和智能代码库探索工具。
无此工具 | 使用 |
手动 grep，容易遗漏相关文件 | 自然语言提问，获取精确位置 |
编辑导致其他地方导入错误 | 追踪导入和调用链 |
全量重写消耗大量 tokens | 描述变更，无需行号 |
行号错误导致代码损坏 | 10,000+ tokens/秒合并 |
快速应用 (Fast Apply) — 通过 Relace API 以 10,000+ tokens/秒的速度应用代码编辑
智能搜索 (Agentic Search) — 基于自然语言查询的智能代码库探索
智能检索 (Agentic Retrieval) — 混合语义提示 + 实时代码探索，支持陈旧提示和显式云端维护（通过 MCP_SEARCH_RETRIEVAL=1 启用；使用 MCP_RETRIEVAL_BACKEND 选择后端）
云端搜索 (Cloud Search) — 对云端同步仓库进行语义代码搜索
Related MCP server: code-context
使用 relace 后端（默认）：从 Relace 控制台 获取 API 密钥，然后添加到您的 MCP 客户端：
~/.cursor/mcp.json
{
"mcpServers": {
"relace": {
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "/absolute/path/to/your/project"
}
}
}
}claude mcp add relace \
--env RELACE_API_KEY=rlc-your-api-key \
--env MCP_BASE_DIR=/absolute/path/to/your/project \
-- uv tool run relace-mcp~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"relace": {
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "/absolute/path/to/your/project"
}
}
}
}.vscode/mcp.json
{
"mcp": {
"servers": {
"relace": {
"type": "stdio",
"command": "uv",
"args": ["tool", "run", "relace-mcp"],
"env": {
"RELACE_API_KEY": "rlc-your-api-key",
"MCP_BASE_DIR": "${workspaceFolder}"
}
}
}
}
}~/.codex/config.toml
[mcp_servers.relace]
command = "uv"
args = ["tool", "run", "relace-mcp"]
[mcp_servers.relace.env]
RELACE_API_KEY = "rlc-your-api-key"
MCP_BASE_DIR = "/absolute/path/to/your/project"变量 | 必需 | 描述 |
| ✅* | 来自 Relace 控制台 的 API 密钥；Relace 提供商和云端工具必需 |
| ❌ | 设置为 |
| ❌ | 语义检索后端： |
| ❌ | 检索提示策略： |
| ❌ | 本地索引定期刷新监控（可选）；需要固定的 |
| ❌ | 本地索引定期监控间隔（秒，默认： |
| ❌ | 首次定期本地索引检查前的初始延迟（秒，默认： |
| ❌ | 轮次状态用户消息策略： |
| ❌ | 在搜索运行期间启用 |
| ❌ | 启用 LSP 辅助搜索： |
| ❌ | 项目根目录覆盖（通过 MCP Roots → Git → 工作区存储 → CWD 自动检测） |
| ❌ | 文件日志记录： |
| ❌ | 用于集中配置的 |
* 如果满足以下两者，则可选：(1) APPLY_PROVIDER 和 SEARCH_PROVIDER 为非 Relace 提供商，且 (2) MCP_RETRIEVAL_BACKEND 为 codanna、chunkhound 或 none。
有关 .env 使用、编码设置、自定义 LLM 提供商等更多信息，请参阅 docs/advanced.md。
始终可用：fast_apply、agentic_search。agentic_retrieval 需要 MCP_SEARCH_RETRIEVAL=1。云端工具仅在 MCP_RETRIEVAL_BACKEND=relace 时可用。index_status 适用于 relace、codanna 和 chunkhound，在 MCP_RETRIEVAL_BACKEND=none 时隐藏。
使用 MCP 原生发现界面：list_tools() 获取工具，list_resources() 获取资源。
有关详细参数，请参阅 docs/tools.md。
LSP 工具使用您系统上安装的外部语言服务器。
语言 | 语言服务器 | 安装命令 |
Python | basedpyright | (已捆绑) |
TypeScript/JS | typescript-language-server |
|
Go | gopls |
|
Rust | rust-analyzer |
|
用于监控操作的实时终端 UI。
pip install relace-mcp[tools]
relogs有关详细用法，请参阅 docs/dashboard.md。
使用 Loc-Bench 代码定位数据集评估 agentic_search 性能。
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra benchmark
# Build dataset from Hugging Face
uv run --extra benchmark python -m benchmark.cli.build_locbench --output artifacts/data/raw/locbench_v1.jsonl
# Run evaluation
uv run --extra benchmark python -m benchmark.cli.run --dataset artifacts/data/raw/locbench_v1.jsonl --limit 20所有基准测试产物均写入 benchmark/.data/ 下。
有关网格搜索、分析工具和指标解读，请参阅 docs/benchmark.md。
平台 | 状态 | 备注 |
Linux | ✅ 完全支持 | 主要开发平台 |
macOS | ✅ 完全支持 | 所有功能可用 |
Windows | ⚠️ 部分支持 |
|
错误或消息 | 解决方案 |
| 使用 Relace 提供商或云端工具时设置 |
| 在目标块附近包含 1-3 个唯一的锚点行 |
| 验证路径是否存在且位于 |
| 文件超过 10MB；将更改拆分为更小的文件或编辑 |
| 为非 UTF-8 项目显式设置 |
| 验证 API 密钥和提供商配置 |
| 稍后重试或减少请求量 |
| 检查网络访问并重试 |
| 添加更具体的锚点或具体的行，以便合并能产生差异 |
| 确保占位符标记仅用作占位符，而非预期的字面输出 |
| 拆分大型删除密集型编辑或使用显式的删除指令 |
| 将更改拆分为更小、更局部的编辑 |
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra dev --extra benchmark
uv run pytest
uv run --extra dev --extra benchmark pytest benchmark/tests -qMIT
Search codebase for code locations matching a query.
Use when you know the name or structure you're looking for — function names, class names, modules, or how components connect. For conceptual/behavioral queries without known identifiers, use agentic_retrieval instead.
Returns file paths with line ranges and an explanation of findings. Keys: explanation (str), files (dict[path → {lines, snippet}]), turns_used (int).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to find. Prefer specific identifiers over vague concepts. ✅ 'UserService class' ✅ 'where is JWT validation done' ❌ 'error handling' (too vague — results will be poor) Natural language or exact symbol names both accepted. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, etc. The description adds that the tool returns file paths with line ranges and explanations, providing useful context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (5 sentences), front-loaded with purpose, then usage guidelines, then return format and keys. No wasted 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 simple tool with one parameter, the description covers purpose, usage, return format, and is supplemented by annotations. With an output schema present, return details are adequate.
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%, and the parameter 'query' already has a detailed description with examples in the schema. The tool description adds minimal additional meaning, so 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's purpose: 'Search codebase for code locations matching a query.' It uses a specific verb ('search') and resource ('codebase'), and distinguishes from the sibling tool 'agentic_retrieval' by noting that this tool is for queries with known identifiers.
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 states when to use (when you know the name or structure) and when not to (conceptual/behavioral queries), naming the alternative tool 'agentic_retrieval'. This provides clear guidance for the AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete cloud repository and local sync state. IRREVERSIBLE.
Removes all indexed data from Relace Cloud. Use cloud_list to find repo IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be True to proceed. | |
| repo_id | No | Optional repo ID to delete directly (use cloud_list to find). If not provided, deletes the repo associated with current directory. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as destructive (destructiveHint=true). The description adds detail: 'IRREVERSIBLE' and clarifies it removes both cloud data and local sync state, adding value beyond 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?
Extremely concise: two sentences plus a warning. All information is front-loaded with the core action, making it easy to parse quickly.
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 output schema exists (not shown), return values are handled. The description covers the destructive nature, local state removal, and the confirm parameter. Could mention confirmation step explicitly, but overall 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 100% with clear param descriptions. The description adds no extra meaning to params beyond hinting repo_id can come from cloud_list, but does not elaborate on confirm param or provide additional syntactic 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 deletes a cloud repository and local sync state, with the verb 'delete' and specific resource. It distinguishes from siblings like cloud_list (for listing) and implies this is for removal.
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 advises using cloud_list to find repo IDs, providing helpful context. However, it does not explicitly state when to use this tool vs alternatives (e.g., cloud_sync) 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.
[ADMIN] List all repositories in your Relace Cloud account.
Use to find repo_id for cloud_clear. Not needed for normal search/sync workflow. Returns repository IDs, names, and indexing status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint; description adds that it returns specific fields and is admin-only, complementing without contradiction.
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, front-loaded with [ADMIN], no fluff; every sentence provides 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?
Has output schema for returns; description covers purpose, usage, and relationship to siblings; fully adequate for this simple 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?
No parameters exist and schema coverage is 100%; description adds usage context (output fields) beyond schema, meeting baseline for zero-param case.
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?
Clearly states it lists all repositories, with an admin prefix and explicit use case for cloud_clear, distinguishing from normal search/sync workflow.
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 states when to use (find repo_id for cloud_clear) and when not needed (normal search/sync), providing clear differentiation from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code by meaning using AI embeddings. Requires cloud_sync first.
Use for conceptual queries where you don't know the exact file, class, or function name. Prefer agentic_search when you know the exact identifier or symbol name.
Prerequisite: cloud_sync must have been run at least once. Fails if RELACE_API_KEY is not set or no sync state exists.
Returns: {results (list), result_count (int), warnings (list[str]), query (str), branch (str), repo_id (str)}. Check warnings[] for stale index alerts (e.g., uncommitted local changes).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language description of the code to find. ✅ 'function that validates JWT and returns user ID' ✅ 'rate limiting middleware for HTTP requests' ❌ 'auth' (too vague — low-relevance results) Be specific about behavior, not just topic. | |
| branch | No | Branch to search (null = API default branch). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already define read-only, idempotent, non-destructive behavior. Description adds failure modes (RELACE_API_KEY, sync state) and return structure with warnings for stale indices.
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?
8 sentences, all value-adding: purpose, prerequisite, usage guidance, failure conditions, return type, warning tip. No redundancy.
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 search tool with 2 params, annotations, and output schema, the description covers purpose, prerequisites, usage, failures, return shape, and warnings. 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% with detailed descriptions for both parameters. The tool description does not add extra parameter information, so 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?
The description clearly states it searches for code by meaning using AI embeddings, distinguishing it from agentic_search for exact identifier searches.
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 tells when to use (conceptual queries) and when to prefer agentic_search (exact identifiers). Also mentions prerequisite cloud_sync and failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload or refresh codebase to Relace Cloud for semantic search.
Check index_status() first—skip this if cloud freshness is already 'fresh'. Syncs git-tracked files to enable cloud_search. Incremental by default.
Advanced (Relace-specific): force=True Re-upload all files; use after large refactors. force=True+mirror=True Delete cloud files absent locally; use after branch switch.
Returns: {sync_mode (str), files_created (int), files_updated (int), files_deleted (int), files_unchanged (int), warnings (list[str]), repo_id (str), repo_head (str)}. Check warnings[] for truncation or suppressed deletes. Fails if not in a git repo or RELACE_API_KEY is not set.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Ignore cache, upload all files (default: false). | |
| mirror | No | With force=True, delete cloud files not in local (default: false). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly discloses incremental default, idempotent nature (aligning with annotations), and potential destructive behavior of force+mirror, plus warnings about truncation.
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?
Structured in concise paragraphs with clear headings for advanced options, return format, and failure conditions—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?
Thoroughly covers prerequisites, usage guidance, advanced options, return structure, and failure cases, leaving no gaps given the tool's complexity and existing annotations.
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?
Adds significant value beyond schema descriptions by explaining advanced use cases for force and mirror, including when to use each option.
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 begins with a specific verb+resource ('Upload or refresh codebase to Relace Cloud for semantic search') and distinguishes from siblings by referencing index_status and cloud_search.
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 states when to use (after checking index_status), when to skip (if fresh), and provides advanced scenarios for force and mirror usage with concrete examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit or create a file using intelligent merging.
For new files: writes content directly. For existing files: merges edit_snippet with current content using anchor lines. Anchor lines are verbatim lines copied from the existing file that help locate the exact edit target. Include 1-2 unique lines adjacent to the change. Truncation markers are recommended for larger scoped edits but not required. Markdown files keep fenced code blocks verbatim; outer fence stripping is skipped for .md/.mdx targets.
On error, the response includes a code field:
NEEDS_MORE_CONTEXT: merge model could not locate the target - add 1-2 unique anchor lines from immediately around the edit location.
APPLY_NOOP: merge returned an identical file even though the snippet contained explicit remove directives or concrete new lines not present in the original.
BLAST_RADIUS_EXCEEDED: edit scope too large - split into smaller edits.
MARKER_LEAKAGE: placeholder marker text leaked into merged output (treated as literal text).
TRUNCATION_DETECTED: merged output shrank drastically and no explicit remove directive was provided.
On success: {status: "ok", diff: str | None (unified diff, None for new files or no-op)}.
Do NOT use this tool to delete files or clear file contents. Use a dedicated file management tool for those operations.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (absolute or relative to MCP_BASE_DIR; if MCP_BASE_DIR is unset, relative paths resolve against MCP Roots). | |
| edit_snippet | Yes | Code snippet representing the changes. Include only the lines being added or modified, plus placeholder comments for unchanged parts when useful for larger scoped edits: `// ... existing code ...` (JS/TS), `# ... existing code ...` (Python/shell). Anchor the edit with 1-2 verbatim lines from the existing file. | |
| instruction | No | Optional natural language hint to disambiguate the target location (e.g., 'add after imports', 'inside the if block'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, consistent with a mutating edit. The description adds far more: explains the merging behavior with anchor lines, truncation markers, markdown handling, and a full set of error codes with their meanings and remedies. It also documents the success response format. No contradiction with 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?
The description is longer than minimal but well-structured: core purpose first, then merge details, then error codes, then a do-not-use note. Each sentence adds value. A slight trim could be made (e.g., the truncation markers sentence could be part of anchor lines), but overall it's efficient and clear.
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 that an output schema exists (indicated by CONTEXT SIGNALS) and the input schema is fully described, this description is complete: it covers all behavioral aspects, error handling with codes, response format, and explicit exclusions. No gaps remain for an agent to misunderstand.
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?
Input schema has 100% description coverage for all three parameters. The description still adds substantial value: for 'path' it clarifies resolution relative to MCP_BASE_DIR or MCP Roots; for 'edit_snippet' it gives concrete examples of placeholder comments and anchor line usage; for 'instruction' it provides natural language examples. This goes well beyond the schema alone.
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 'Edit or create a file using intelligent merging,' which is a specific verb+resource pair. The sibling tools are all cloud/agentic search or index utilities, so this tool is clearly distinct as a file editing 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 states when to use the tool: for new files write directly, for existing files merge with anchors. It also provides a clear do-not-use instruction: 'Do NOT use this tool to delete files or clear file contents. Use a dedicated file management tool for those operations' – directly indicating when to avoid it and naming an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the single active indexing backend in read-only mode.
Use this before retrieval when you need to know whether the active backend is fresh and
whether semantic hints are usable. Returns active_backend, a single backend status
object with freshness and hints_usable, and background_monitor (state, reason).
This tool never refreshes indexes; if active_backend is relace and
backend.status.needs_sync is true, run cloud_sync().
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| trace_id | Yes | Trace ID for correlating logs for this tool call. |
| active_backend | Yes | The configured active indexing backend. |
| base_dir | No | Resolved repository base directory, if available. |
| base_dir_source | No | How the base directory was resolved, when resolution succeeded. |
| backend | No | Status summary for the active backend, when inspection succeeded. |
| background_monitor | No | Background monitor state summary, when inspection succeeded. |
| error | No | Error message explaining why status inspection failed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds key behavioral details: 'never refreshes indexes', conditions for needing cloud_sync, and outlines the return structure, which goes beyond the 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?
The description is three sentences, front-loaded with the primary purpose, and every sentence provides essential information without redundancy.
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 parameters and an output schema, the description sufficiently explains the return fields (active_backend, background_monitor) and the condition for using a sibling tool. It is complete for the tool's complexity.
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 no parameters (0 params, 100% coverage). The description adds no parameter info, which is appropriate as there are none. Baseline 4 is justified.
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 specifies the verb 'inspect', the resource 'single active indexing backend', and the mode 'read-only'. It clearly defines what the tool does and distinguishes it from siblings like 'cloud_sync'.
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 when to use the tool ('before retrieval when you need to know whether the active backend is fresh and whether semantic hints are usable') and when not to ('never refreshes indexes') with an alternative ('run cloud_sync()').
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.
v0.2.4agentic_searchcloud_clearcloud_listcloud_searchcloud_syncfast_apply4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / edit_snippet / descriptionAdded value: +"Code snippet representing the changes. Include only the lines being added or modified, plus placeholder comments for unchanged parts when useful for larger scoped edits: `// ... existing code ...` (JS/TS), `# ... existing code ...` (Python/shell). Anchor the edit with 1-2 verbatim lines from the existing file."Input schema / properties / instruction / descriptionAdded value: +"Optional natural language hint to disambiguate the target location (e.g., 'add after imports', 'inside the if block')."Input schema / properties / path / descriptionAdded value: +"File path (absolute or relative to MCP_BASE_DIR; if MCP_BASE_DIR is unset, relative paths resolve against MCP Roots)."fast_searchindex_statusv1.0.0cloud_clearcloud_infocloud_listcloud_searchcloud_synccloud_clearcloud_infocloud_listcloud_searchcloud_syncfast_applyfast_searchScored across 7 tools
Each tool has a clearly distinct purpose with descriptions that explicitly differentiate similar tools (e.g., agentic_search vs cloud_search based on query type). There is no functional overlap.
Cloud operations use a consistent 'cloud_' prefix, but 'agentic_search', 'fast_apply', and 'index_status' break the pattern. Mix of verb_noun and adjective_noun styles reduces predictability.
Seven tools is well-scoped for a code search and editing server. Each tool addresses a specific need without redundancy or excessive complexity.
Covers search (local and cloud) and file editing, but lacks tools for reading full file content, deleting files, or managing local files beyond edits. Users may need to rely on external tools for basic operations.
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Discover, compare, and monitor 1,400+ APIs directly from your AI coding agent.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
