非公式 — 個人のプロジェクトであり、Relace とは提携していません。
AI で構築 — すべて AI の支援（Antigravity、Codex、Cursor、Github Copilot、Windsurf）を受けて開発されました。
AI を活用したコード編集およびインテリジェントなコードベース探索ツールを提供する MCP サーバーです。
従来の手法 |
|
手動 grep、関連ファイルを見落とす | 自然言語で質問し、正確な場所を取得 |
編集により他の場所のインポートが壊れる | インポートと呼び出しチェーンを追跡 |
全書き換えでトークンを消費 | 変更内容を記述、行番号は不要 |
行番号エラーでコードが破損 | 10,000 トークン/秒以上のマージ |
Fast Apply — Relace API を介して 10,000 トークン/秒以上の速度でコード編集を適用
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 から自動検出） |
| ❌ | ファイルログ: |
| ❌ | 設定を一元管理するための |
* APPLY_PROVIDER と SEARCH_PROVIDER の両方が Relace 以外であり、かつ 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.
