Integrates with Google's Gemini API for generating embeddings used in semantic search and context packing within code repositories.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@scythe-context-mcp find where auth token validation is handled"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Scythe Context MCP 是給 Codex App / Codex CLI 使用的本機程式碼上下文引擎。它在 repo 內建立 SQLite/sqlite-vec 索引，結合語義搜尋、關鍵字搜尋、符號/依賴關係與 context packing，讓 Codex 更快拿到可操作的檔案、行號、片段與相關路徑。
本機優先：metadata、FTS 與向量索引都存在 repo 內的 .scythe-context/。
混合搜尋：結合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠單一召回方式。
Codex 友善輸出：回傳 line ranges、snippets、match reasons、grep keywords、related files 與 suggested paths。
Gemini-compatible：支援官方 Gemini API，也支援第三方 v1beta proxy。
可診斷：內建 provider probe、index freshness、embedding coverage 與可修復建議。
隱私提醒：只有在執行 embedding 相關功能時，query 或 chunk text 才會送到你設定的 Gemini-compatible endpoint。第三方 proxy 應視為可看到這些文字。
Related MCP server: Graft
Codex MCP 設定可以直接用 npx -y scythe-context-mcp，不一定要先全域安裝。全域安裝主要適合先確認 CLI 可執行，或在 Codex 設定中使用短命令。
npm install -g scythe-context-mcp
scythe-context-mcp --versionRuntime 目標是 Node.js 24 LTS。Node 26 可能可用，但在進入 LTS 前不作為主要驗收基準。
從原始碼執行：
git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
cd scythe-context-mcp
npm install
cp .env.example .env
npm run build舊專案名 repo-beacon-mcp 已改為 scythe-context-mcp。舊的 REPO_BEACON_* 環境變數仍作為 fallback 相容，但新設定應改用 SCYTHE_CONTEXT_*。
Codex MCP 設定使用 command、args、cwd、env 與 env_vars 等欄位；可參考官方文件：Model Context Protocol 與 Configuration Reference。
情境 | 建議 |
Codex 和 MCP 都在 Windows | 用 Windows |
Codex CLI 在 WSL/Linux/macOS | 用同一個環境內的 |
Codex App on Windows 開 WSL repo | 建議用 Windows |
請先用 where node 和 npm root -g 確認你自己的 Windows Node/npm 路徑；下面是 nvm4w 安裝位置的範例。
最小設定：
[mcp_servers.scythe_context]
command = 'C:\nvm4w\nodejs\node.exe'
args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', '-y', 'scythe-context-mcp']
env_vars = ["GEMINI_API_KEY"]如果 scythe-context-mcp 已全域安裝且 Codex 啟動時的 PATH 能找到它，可以更短：
[mcp_servers.scythe_context]
command = "scythe-context-mcp"
env_vars = ["GEMINI_API_KEY"]Codex 和 MCP server 都在同一個 Unix-like 環境中執行時，最小設定是：
[mcp_servers.scythe_context]
command = "npx"
args = ["-y", "scythe-context-mcp"]
env_vars = ["GEMINI_API_KEY"]從原始碼執行時：
[mcp_servers.scythe_context]
command = "node"
args = ["/path/to/scythe-context-mcp/dist/index.js"]
env_vars = ["GEMINI_API_KEY"]這裡 args 指向 Scythe Context MCP 的 build 入口；全域設定不要把 cwd 固定到某個 repo。Scythe 會優先使用工具呼叫的 project_path，再使用 Codex 啟動 MCP 時的 workspace PWD / process cwd。只有在專案 scoped .codex/config.toml、或你真的想 pin 某個 repo 時，才需要設定 cwd 或 SCYTHE_CONTEXT_DEFAULT_PROJECT。
目前 Codex App on Windows 的 WSL agent mode 可能無法可靠直接啟動 WSL-side stdio MCP server。實測較穩的做法是讓 Codex 執行 Windows wsl.exe，再由 wsl.exe 在 WSL 內啟動 WSL Node 與 WSL npm package。
先在 WSL 內安裝：
npm install -g scythe-context-mcp
command -v scythe-context-mcp
scythe-context-mcp --version然後在 Codex config 使用：
[mcp_servers.scythe_context]
command = "/mnt/c/Windows/System32/wsl.exe"
args = ["-d", "Ubuntu", "--", "bash", "-lc", "PATH=/home/you/.nvm/current/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin exec /home/you/.nvm/current/bin/scythe-context-mcp"]
startup_timeout_sec = 40
tool_timeout_sec = 120
env_vars = ["PWD", "GEMINI_API_KEY"]
[mcp_servers.scythe_context.env]
WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"注意：
Ubuntu 要換成你的 WSL distribution 名稱；可用 wsl.exe -l -v 查看。
/home/you/.nvm/current/bin 要換成你的 WSL Node/npm 路徑；可在 WSL 內用 which node、which scythe-context-mcp 確認。
不要在全域 config 固定 cwd 或 SCYTHE_CONTEXT_DEFAULT_PROJECT。這個設定會跟著 Codex 目前 workspace 走，不需要每換 repo 就改一次。
WSLENV 這裡列的是要跨 WSL/Windows interop 保留的變數名，不是 key 內容。建議把 GEMINI_API_KEY 放在 Codex 啟動環境或系統環境，並用 env_vars 轉發；本機臨時測試才考慮直接寫在 [mcp_servers.scythe_context.env]。
不建議用 Windows Node 直接索引 WSL repo 內的 .scythe-context/。SQLite 在 UNC / WSL filesystem 邊界可能出現 database is locked，而且 native modules 也容易混到 Windows/WSL 不同平台的 binary。
以下設定不是最小啟動必需，但在大型 repo、首次 npx 下載或想固定工具面時有用：
[mcp_servers.scythe_context]
startup_timeout_sec = 40
tool_timeout_sec = 120
enabled_tools = [
"repo_index_status",
"repo_reindex",
"repo_context_pack",
"repo_semantic_search",
"repo_related_files",
"gemini_embedding_probe",
"repo_doctor"
]enabled = true 和 required = false 通常是預設行為，不需要特別寫。
如果你真的想固定某一個預設專案，可以在 [mcp_servers.scythe_context.env] 設 SCYTHE_CONTEXT_DEFAULT_PROJECT。一般多 repo 使用不需要這樣做；Scythe 會優先使用工具呼叫的 project_path，再使用 PWD，最後才使用 MCP process 的 cwd。
SCYTHE_CONTEXT_RERANK_MODE 可設為 auto 或 off。預設 auto 會啟用 local code-aware reranker；排查 ranking 問題時可暫時設為 off，回到 semantic/keyword merge 的原始排序。
Scythe 會在 repo-local .scythe-context/provider-capabilities.json 記錄目前 Gemini-compatible provider 的能力觀察結果，例如 batch embedding 是否可用、output dimensionality 是否符合預期，以及最近一次 probe / success / failure。這個檔案不提交；repo_reindex(index_embeddings=true) 會使用它避免反覆嘗試已知不支援的 batch endpoint。
如果不填 URL/model/auth，預設會使用官方 Gemini 相容設定：
GEMINI_BASE_URL: https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL: gemini-embedding-2
GEMINI_AUTH_MODE: x-goog-api-key
GEMINI_OUTPUT_DIMENSIONALITY: 1536
因此官方 Gemini 使用者通常只需要提供 GEMINI_API_KEY。第三方中轉站或自訂模型才需要覆蓋下面這些非秘密設定：
模型與 REST endpoint 可對照 Google 官方 Gemini embeddings 文件。
[mcp_servers.scythe_context.env]
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"GEMINI_API_KEY 建議放在 Codex 啟動環境或系統環境變數，並用 env_vars = ["GEMINI_API_KEY"] 轉發給 MCP server。除非只做本機臨時測試，否則不要把 key 寫進可同步或可提交的 config。
支援的 auth mode：
x-goog-api-key
bearer
query
官方 Gemini 通常使用 x-goog-api-key；很多第三方中轉站使用 bearer。如果中轉站要求 query string key，可以使用 query，必要時再設定 GEMINI_API_KEY_QUERY_PARAM。
WSLENV 是 WSL interop 規則，不是 Codex 專用欄位。只有在 Windows Codex App + WSL repo 並透過 wsl.exe wrapper 或 Windows Node 跨環境啟動時才需要。若使用上面的 wsl.exe wrapper，通常使用無 suffix 形式：
[mcp_servers.scythe_context.env]
WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
GEMINI_MODEL = "gemini-embedding-2"
GEMINI_AUTH_MODE = "bearer"
GEMINI_OUTPUT_DIMENSIONALITY = "1536"若你刻意採用 Windows Node 方案，才需要 PWD/p 把 WSL path 轉成 Windows 可讀 UNC path；但目前不建議用它直接讀寫 WSL repo 內的 SQLite index。
先檢查索引狀態：
repo_index_status如果 metadata 不存在或 freshness 顯示 stale：
repo_reindex({ "dry_run": false })第一次安裝或環境異常時，先跑本機診斷：
repo_doctor需要語義搜尋或 context pack 時，再建立 embeddings：
repo_reindex({ "dry_run": false, "index_embeddings": true })讓 Codex 針對任務拿上下文：
repo_context_pack({ "query": "where is auth token validation handled?" })對某個命中檔案展開 imports / reverse imports：
repo_related_files({ "path": "src/server/auth.ts" })Tool | 用途 |
| 查看 index path、metadata/embedding coverage、freshness diagnostics 與建議動作。 |
| 掃描專案並寫入 metadata；設定 |
| 針對任務查詢打包 primary snippets、match reasons、related files 與 suggested paths。 |
| 對已索引 chunks 做 hybrid 或 semantic search，主要用於排查 raw ranking；一般查找優先用 |
| 查看單一檔案的 symbols、imports、importedBy。 |
| 測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。 |
| 不呼叫外部 API，檢查 Node runtime、native modules、Gemini env、provider capability cache、WSL interop 與 index health。 |
repo_context_pack(mode="hybrid") 和 repo_semantic_search(mode="hybrid") 在 query embedding 不可用時會降級成 keyword-only 結果，並回傳 effectiveMode: "keyword" 與 fallback.reason: "embedding_unavailable"。mode="semantic" 不會降級，會回傳 status: "embedding_unavailable"，因為純 semantic search 必須有 query embedding。精確字串、已知路徑或小範圍檢查仍建議直接用 rg / 直接讀檔。
為了控制 Codex token 消耗，repo_index_status、repo_related_files、repo_reindex、repo_doctor 與 gemini_embedding_probe 預設回傳 compact 摘要，包含決策必要資訊與估算輸出 token；需要完整診斷資料、完整 skipped file list、vector sample 或 provider capability raw details 時，才使用 response_mode="full"。
repo_context_pack 與 repo_semantic_search 也支援 response_mode：
compact：預設模式，回傳短 snippets、決策導向 related metadata、suggested paths 與估算輸出 token。
paths_only：第一輪探索用，只回傳路徑、行號、match reason 與精簡關聯路徑摘要，適合先找要讀的檔案。
snippets：需要更多上下文或 ranking 診斷時使用，保留較完整 snippets、分數與 metadata。
建議先用 repo_context_pack(response_mode="paths_only") 找到候選檔案，再用 Codex 直接讀特定檔案或小範圍片段；如果短片段能直接幫助修改，再使用預設 compact。需要排名分數或較完整片段來排查 ranking 時，再使用 repo_semantic_search(response_mode="snippets")。
已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、embedding 失敗時的 keyword-only fallback、local code-aware reranker、輕量 symbol/dependency graph、experimental opt-in tree-sitter extractor、related-file lookup、repo_context_pack、provider diagnostics、provider capability cache、index freshness diagnostics、repo_doctor。
下一步：持續整理真實 dogfood 使用回饋，優先處理會影響 Codex 找檔效率或 token 消耗的 ranking / output 問題；tree-sitter 維持 experimental opt-in，等 benchmark 或使用者回饋證明有明確收益再提高投入。
.scythe-context/: 預設索引目錄，不提交。
.repo-beacon/: 舊索引目錄名稱，仍被 ignore。
local/: 私密 API 測試檔、參考 HTML、截圖等本機資料，不提交。
.env: 本機設定，不提交。
不要把 API key、proxy token、私有程式碼片段或 index database 放進 issue、PR 或公開 logs。
npm test
npm run build
npm audit --omit=dev
npm pack --dry-run確認 package 不包含 .env、.scythe-context/, .repo-beacon/, local/, API key 或私密參考檔。
Send one embedding request and return diagnostics for official Gemini or proxy compatibility.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| project_path | No | ||
| response_mode | No | compact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose side effects, auth requirements, rate limits, or the nature of the diagnostics. The tool is likely read-only, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, which is concise but under-informative. It lacks important details about parameters and output, making it less helpful than it could be.
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 absence of an output schema and annotations, the description should explain what diagnostics contain. It does not. The three parameters are ignored, leaving the agent with insufficient context for correct usage.
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 no meaning beyond the input schema. With 0% schema coverage, it fails to explain the role of project_path or how response_mode affects output. The enum for response_mode is in the schema but not elaborated.
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 verb (Send), resource (one embedding request), and purpose (return diagnostics for compatibility). It distinguishes from sibling tools that deal with repository management.
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?
While the purpose implies testing compatibility, there is no explicit guidance on when to use this tool versus alternatives, or when not to use it. The sibling tools are unrelated, so context is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preferred task-oriented code lookup for unknown file locations. Use response_mode=paths_only for first-pass scouting, compact for short snippets, and snippets for ranking/debug detail.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | hybrid | |
| query | Yes | ||
| max_results | No | ||
| project_path | No | ||
| related_depth | No | ||
| response_mode | No | compact | |
| max_seed_files | No | ||
| max_context_chars | No | ||
| max_related_files | No | ||
| max_related_items | No | ||
| max_snippet_chars | No | ||
| include_related_snippets | No | ||
| max_related_context_chars | No | ||
| max_related_snippet_chars | No | ||
| max_related_snippets_per_file | No |
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 lacks any mention of side effects (e.g., modifying files), permissions, performance, or output characteristics. The only behavioral hint is the purpose, but it does not disclose what the tool does beyond 'lookup', leaving significant transparency 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 concise with two well-structured sentences. The first sentence establishes purpose, and the second provides actionable guidance on response_mode. It is front-loaded and avoids 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 the complexity (15 parameters, no output schema, and a suite of sibling tools), the description is incomplete. It does not explain the overall search mechanism, parameter interactions, return format, or how this tool compares to siblings like repo_semantic_search. Important context is missing for effective agent usage.
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?
With 0% schema description coverage and 15 parameters, the description only addresses the 'response_mode' parameter, providing usage guidance for its three values. All other parameters (mode, query, max_results, etc.) are left undocumented, offering minimal added value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'task-oriented code lookup for unknown file locations', specifying a verb (lookup) and resource (code in repo). It distinguishes from siblings by emphasizing 'unknown file locations' and providing response_mode options, though it does not explicitly differentiate from similar tools like repo_semantic_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?
The description provides explicit guidance on when to use (for unknown file locations) and how to choose response_mode: 'paths_only for first-pass scouting', 'compact for short snippets', 'snippets for ranking/debug detail'. However, it does not mention when not to use or alternatives beyond these modes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run local diagnostics for runtime, native modules, config, WSL interop, and index health without calling embedding APIs.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | No | ||
| response_mode | No | compact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It lists diagnostic areas but does not mention potential side effects, permissions required, whether it is destructive, or the format of the output, leaving significant gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose, but it could be better structured by listing diagnostic areas or including parameter context.
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 and no annotations, the description should explain return values and behavior. It only lists diagnostic categories without details on output format, making it incomplete for an AI agent to anticipate the tool's response.
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 schema has 0% description coverage, and the description does not mention or explain the two parameters (project_path, response_mode), failing to add any meaning beyond the schema's type and enum definitions.
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 runs local diagnostics for specific areas (runtime, native modules, config, WSL interop, index health) and distinguishes it from sibling tools by emphasizing it does not call embedding APIs.
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 indicates when to use this tool (local diagnostics without embedding APIs) by contrasting with alternatives like gemini_embedding_probe, but does not explicitly state when not to use it or mention other sibling tools like repo_index_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show Scythe Context configuration and current index status.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | No | ||
| response_mode | No | compact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'Show' implying read-only, but does not disclose permissions, rate limits, or side effects. Minimal transparency beyond the verb.
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?
Single sentence is concise but under-specified. It sacrifices necessary detail for brevity, not earning its place.
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 and description does not explain return values. For a status tool, it is incomplete—missing what 'index status' entails or what information is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description does not mention parameters. It fails to explain project_path or response_mode enum values, leaving parameters completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Show Scythe Context configuration and current index status,' clearly indicating a read-only status tool. It distinguishes from siblings like repo_reindex (reindexing) and repo_semantic_search (searching), though 'Scythe Context' is not explained.
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 sibling tools like repo_doctor or repo_reindex. The description implies a status check but lacks explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a project, write metadata, and optionally index embeddings.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| project_path | No | ||
| response_mode | No | compact | |
| max_file_bytes | No | ||
| index_embeddings | No | ||
| target_chunk_chars | No | ||
| chunk_overlap_chars | No | ||
| max_chunks_per_file | No | ||
| embedding_batch_size | No | ||
| max_embedding_chunks | No |
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 scanning and writing metadata but does not disclose if the operation is destructive, overwrites existing data, or requires specific permissions. Side effects and state changes are not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it sacrifices necessary detail. It is front-loaded but lacks structure for a tool with many parameters.
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 10 parameters, no annotations, no output schema, and sibling tools requiring differentiation, the description is severely incomplete. It fails to explain the reindexing process, parameter semantics, or return value behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 10 parameters. Terms like dry_run, response_mode, and index_embeddings are left undefined, so the agent gains no insight beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Scan a project, write metadata, and optionally index embeddings'), which specifies the verb and resource. It distinguishes from siblings like repo_doctor (diagnose) and repo_semantic_search (search) by focusing on reindexing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like repo_index_status or repo_doctor. There is no mention of prerequisites or scenarios where reindexing is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Debug raw semantic or hybrid ranking over indexed chunks. Prefer repo_context_pack for normal lookup; use paths_only to scout cheaply and snippets only when scores or fuller snippets are needed.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | hybrid | |
| query | Yes | ||
| max_results | No | ||
| project_path | No | ||
| response_mode | No | compact | |
| max_context_chars | No | ||
| max_snippet_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should cover behavioral traits. It mentions response modes but does not detail output format, side effects, or auth needs. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Front-loaded with purpose and guidance. Every word earns its place.
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 complexity (7 params, no output schema, no annotations), description omits details on most parameters and output structure. Incomplete for confident agent use.
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 has 7 parameters with 0% description coverage. Description only explains response_mode usage partially, leaving max_results, max_context_chars, max_snippet_chars, and project_path unexplained.
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 debugs raw semantic or hybrid ranking over indexed chunks, and distinguishes from sibling repo_context_pack.
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 advises when to use this tool vs alternatives: prefer repo_context_pack for normal lookup, use paths_only to scout cheaply, snippets when detailed content needed.
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.1.14gemini_embedding_proberepo_context_packrepo_doctorrepo_index_statusrepo_reindexrepo_related_filesrepo_semantic_searchScored across 7 tools
Most tools have distinct purposes, but repo_semantic_search and repo_context_pack overlap in functionality, potentially causing confusion. repo_doctor and repo_index_status both address diagnostics but at different granularities, adding mild ambiguity.
The majority of tools follow a 'repo_' prefix, but one tool (gemini_embedding_probe) breaks this pattern. Additionally, verb-based names (doctor, reindex) mix with noun-based names (index_status, related_files, context_pack, semantic_search), creating inconsistency.
With 7 tools, the server covers the core operations for context management without being overwhelming. Each tool addresses a specific need, making the count well-scoped for the domain.
The tool set covers diagnostics, indexing, related file exploration, and search, which are the primary tasks. Missing a tool for configuration management or indexing reset is a minor gap, but the core workflow is supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Project memory, semantic code search, and grounded agent context.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
