Skip to main content
Glama
ctrlcakepro

Chilon Recall

Official
by ctrlcakepro
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Chilon Recall

Local-first knowledge retrieval for learning and serious knowledge work.

面向学习与严肃知识工作的本地优先知识检索。

Documentation: English (this page) · 简体中文（完整文档）

文档语言： English（当前页面，逐段双语）· 简体中文（完整文档）

Security · Contributing

安全策略 · 参与贡献

Chilon Recall turns your own text documents into a private, source-backed knowledge base that any local MCP client can use. Ask what your materials say, compare concepts, build review outlines, or recover a claim from months of notes—while keeping source paths, evidence boundaries, and index operations visible.

Chilon Recall 将你自己的文本资料转换为私有、来源可追溯的知识库，并可供任何本地 MCP 客户端调用。你可以询问资料内容、比较概念、制作复习提纲，或从长期笔记中找回论据，同时保留来源路径、证据边界和索引操作的可见性。

It is an independent retrieval companion in the Chilon Knowledge Work Harness family. The two projects remain separate: Chilon Recall owns local retrieval; the harness can orchestrate broader long-running knowledge work.

它是 Chilon Knowledge Work Harness 产品线中的独立检索组件。两个项目保持分离：Chilon Recall 负责本地检索；harness 可编排更广泛的长期知识工作。

Start here / 新手先看

New to MCP? You only need a document folder, Node.js 20+, and Python 3.10+. Follow these three steps first; client configuration and technical details come later.

第一次接触 MCP？你只需要一个资料文件夹、Node.js 20+ 和 Python 3.10+。先完成下面三步；客户端配置和技术细节在后文。

  1. Install into your document folder / 安装到资料文件夹。 Run the command below once. It creates a private configuration and a managed Python engine; it never stores API keys in the package or configuration file.

    运行一次下面的命令。 它会创建私有配置与受管 Python engine；不会把 API key 写入 package 或配置文件。

    npx -y chilon-recall@0.1.2 install C:\path\to\your\documents

  2. Set your provider key / 设置 provider key。 Open the generated chilon-recall.json to choose the provider endpoint and model, then set the key only in your environment. Run doctor to confirm the setup.

    打开生成的 chilon-recall.json 选择 provider endpoint 与 model，再只在环境变量中设置密钥。 运行 doctor 确认环境可用。

    $env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json"
$env:RAG_API_KEY = "your-provider-key"
npx -y chilon-recall@0.1.2 doctor

  3. Connect one client / 连接一个客户端。 Start with Codex or Claude Desktop. The client starts the local server for you; you do not need to keep a separate terminal open.

    从 Codex 或 Claude Desktop 开始即可。 客户端会替你启动本地 server，无需另开终端长期运行。

Related MCP server: Hoard

Why Chilon Recall? / 为什么使用 Chilon Recall？

  • Grounded learning — answer from the material you chose, not from an untraceable memory of it.

  • 基于资料学习——先回答“你选择的资料说了什么”，而不是依赖无法追溯的模型印象。

  • Source-backed answers — every hit carries a relative file path, headings, an approximate line number, and retrieval scores.

  • 答案可追溯——每条结果都包含相对文件路径、标题层级、近似行号和检索分数。

  • Local-first control — documents and FAISS indexes stay on your machine. Only the text sent to your configured embedding/reranking providers leaves it.

  • 本地优先控制——文档和 FAISS 索引保留在你的设备上；只有发送给自选 embedding/reranking provider 的文本会离开设备。

  • Safe operations — builds happen in staging; clear and restore actions use previews, short-lived confirmation tokens, and recoverable backups.

  • 安全操作——建库在 staging 目录中完成；清理和恢复使用预览、短期确认 token 与可恢复备份。

  • MCP portability — one stdio server works with Codex, Claude Desktop, and other MCP-compatible local clients.

  • MCP 可移植性——同一个 stdio server 可用于 Codex、Claude Desktop 及其他兼容的本地客户端。

Built for learning and knowledge work / 为学习与知识工作而设计

Chilon Recall supports both direct retrieval and reusable learning workflows:

Chilon Recall 同时支持直接检索和可复用的学习工作流：

Need / 需求

Tool / 工具

What it returns / 返回内容

Recover a claim from notes or reports从笔记或报告找回论据

rag_query

Ranked passages with source metadata带来源元数据的排序片段

Answer from course or reference material基于课程或参考资料回答问题

textbook_qa

Direct-answer evidence packet直接回答所需的证据包

Distinguish two ideas or methods区分两个概念或方法

concept_compare

Evidence for a comparison table适合整理比较表的证据

Turn a chapter into structured notes将章节转为结构化笔记

chapter_summary

Broad summary evidence and coverage cautions章节总结证据与覆盖提醒

Prepare for review or an exam复习或备考

review_outline

Concepts, relationships, confusions, and practice prompts概念、联系、易混点与练习提示

The bundled synthetic demo material covers retrieval practice, spaced review, evidence boundaries, and research triangulation. It is safe to redistribute and contains no private or copyrighted textbook content.

仓库附带的合成演示资料涵盖检索练习、间隔复习、证据边界和研究三角验证。它可以安全再分发，不包含个人资料或受版权保护的教材内容。

Detailed setup and configuration / 详细安装与配置

1. Install with npm / npm 安装

You need Node.js 20+ and Python 3.10+.

需要 Node.js 20+ 和 Python 3.10+。

Use the published, pinned npm release to create a private configuration and install the isolated Python engine with one command:

使用已发布且固定版本的 npm package，只需一条命令即可创建私有配置并安装独立 Python engine：

npx -y chilon-recall@0.1.2 install C:\path\to\your\documents

The managed engine lives outside the temporary npx cache. Use CHILON_RECALL_HOME to choose a different persistent location, and run setup after upgrading the package.

托管 engine 保存在临时 npx cache 之外。可用 CHILON_RECALL_HOME 指定其他持久位置；升级 package 后再次运行 setup。

The command writes chilon-recall.json in the document directory and creates a persistent managed Python engine in the operating system's user-data area (or CHILON_RECALL_HOME). These files are required for local operation; credentials remain outside both files.

该命令会在资料目录写入 chilon-recall.json，并在操作系统用户数据目录（或 CHILON_RECALL_HOME）创建持久的受管 Python engine。这些文件是本地运行所必需的；凭据不会写入其中。

Installation never writes credentials into the package or configuration file. To query or build an index, set the provider key in your own environment after installation.

安装过程不会把凭据写入 package 或配置文件。要执行查询或建库，请在安装完成后由你自己在环境变量中设置 provider key。

To validate the runtime and private configuration, set RAG_MANAGER_CONFIG and the provider credentials, then run:

设置 RAG_MANAGER_CONFIG 与 provider 凭据后，可运行以下命令检查运行环境和私有配置：

$env:RAG_MANAGER_CONFIG = "C:\path\to\your\documents\chilon-recall.json"
$env:RAG_API_KEY = "your-provider-key"
npx -y chilon-recall@0.1.2 doctor

If you installed from npm, you can now skip to Connect an MCP client. The remaining setup details are for source checkouts or custom configurations.

如果你通过 npm 安装，现在可以直接前往 连接 MCP 客户端。以下内容面向源码 checkout 或需要自定义配置的用户。

2. Manual private configuration / 手动私有配置

Copy config/chilon-recall.example.json to config/chilon-recall.json. The destination is ignored by Git.

将 config/chilon-recall.example.json 复制为 config/chilon-recall.json。目标文件已被 Git 忽略。

Set project_dir to the folder containing your documents and rag_dir to a dedicated child directory. Keep credentials out of JSON:

将 project_dir 设为资料目录，将 rag_dir 设为其中的专用子目录。不要把凭据写入 JSON：

$env:RAG_MANAGER_CONFIG = (Resolve-Path .\config\chilon-recall.json)
$env:RAG_API_KEY = "your-provider-key"
$env:CHILON_RECALL_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe)
export RAG_MANAGER_CONFIG="$PWD/config/chilon-recall.json"
export RAG_API_KEY="your-provider-key"
export CHILON_RECALL_PYTHON="$PWD/.venv/bin/python"

config/siliconflow.example.json is included as a provider example. Chilon Recall is not tied to SiliconFlow: embeddings use an OpenAI-compatible /embeddings endpoint, and reranking uses a Cohere-compatible rerank endpoint. Disable reranking if your provider does not offer it.

仓库提供 config/siliconflow.example.json 作为 provider 示例，但 Chilon Recall 并不绑定 SiliconFlow：embedding 使用 OpenAI-compatible /embeddings endpoint，reranking 使用 Cohere-compatible rerank endpoint。若 provider 不提供 reranker，可将其禁用。

3. Start the source-checkout MCP server / 启动源码 checkout 的 MCP server

npm start

The server uses stdio, so it normally runs under an MCP client rather than in a standalone interactive terminal. Connect it, call rag_status, preview rag_build, and execute the build with the returned confirmation token.

server 使用 stdio，因此通常由 MCP client 启动，而不是作为独立交互式终端运行。连接后，先调用 rag_status，预览 rag_build，再使用返回的 confirmation token 执行建库。

Connect an MCP client / 连接 MCP client

Use absolute paths in client configuration. They are more reliable than assuming a launch directory.

客户端配置应使用绝对路径，避免依赖不确定的启动目录。

Codex / Codex 配置

Current Codex clients support local stdio MCP servers and share the same config.toml. Add a server through the ChatGPT desktop app's Settings → MCP servers, with codex mcp add, or in ~/.codex/config.toml:

当前 Codex client 支持本地 stdio MCP server，并共享同一份 config.toml。可通过 ChatGPT desktop app 的 Settings → MCP servers、codex mcp add，或在 ~/.codex/config.toml 中添加：

[mcp_servers.chilon-recall]
command = "node"
args = ["/absolute/path/to/chilon-recall/scripts/server.mjs"]
env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY", "CHILON_RECALL_PYTHON"]
startup_timeout_sec = 15
tool_timeout_sec = 1800
default_tools_approval_mode = "writes"

For an npm release, use a pinned npx command instead. Run npx -y chilon-recall@0.1.2 setup first under the same OS account. A pinned version prevents an unexpected package upgrade from changing a working MCP server.

对于 npm 已发布版本，请改用固定版本的 npx 命令。先在同一操作系统账户下运行 npx -y chilon-recall@0.1.2 setup；固定版本可避免 package 意外升级改变已正常工作的 MCP server。

[mcp_servers.chilon-recall]
command = "npx"
args = ["-y", "chilon-recall@0.1.2", "mcp"]
env_vars = ["RAG_MANAGER_CONFIG", "RAG_API_KEY", "RAG_RERANK_API_KEY"]
startup_timeout_sec = 15
tool_timeout_sec = 1800
default_tools_approval_mode = "writes"

The repository is also a valid Codex plugin (.codex-plugin/plugin.json, .mcp.json, and bundled skills). For a cloned source checkout, use the direct node configuration above and set CHILON_RECALL_PYTHON to its virtual environment.

仓库也是合法的 Codex plugin，包含 .codex-plugin/plugin.json、.mcp.json 与内置 skills。源码 clone 时请使用上方直接 node 配置，并将 CHILON_RECALL_PYTHON 指向对应 virtual environment。

DeepSeek Harness / DeepSeek Harness 配置

The repository also ships a DeepSeek Harness bundle. It uses DSH's official @deepseek-ai/dsh-mcp-client bridge, so the existing MCP tools appear under stable names such as mcp__chilon-recall__rag_status; the retrieval engine is not duplicated and credentials are not sent as tool arguments.

仓库同时提供 DeepSeek Harness bundle。它使用 DSH 官方的 @deepseek-ai/dsh-mcp-client bridge，因此现有 MCP 工具会以 mcp__chilon-recall__rag_status 等稳定名称出现；不会重复运行检索引擎，也不会把凭据作为 tool 参数传给模型。

For a source checkout, set an absolute project root and the same private configuration used by the ordinary MCP client. You can apply the bundle for a one-off run without installing it:

源码 checkout 可按以下方式设置绝对项目路径和同一份私有配置。一次性运行时无需安装 bundle，直接使用 overlay：

Current DSH limitation: the bundle forwards only RAG_MANAGER_CONFIG, RAG_API_KEY, RAG_RERANK_API_KEY, CHILON_RECALL_HOME, and CHILON_RECALL_PYTHON. Use the standard RAG key variable names with DSH until arbitrary api_key_env forwarding is added.

当前 DSH 限制：bundle 只转发 RAG_MANAGER_CONFIG、RAG_API_KEY、RAG_RERANK_API_KEY、CHILON_RECALL_HOME 和 CHILON_RECALL_PYTHON。在支持任意 api_key_env 转发之前，使用 DSH 时请采用标准 RAG 密钥环境变量名。

$env:CHILON_RECALL_ROOT = (Resolve-Path .).Path
$env:RAG_MANAGER_CONFIG = (Resolve-Path .\config\chilon-recall.json).Path
$env:RAG_API_KEY = "your-provider-key"
dsh --profile web --patch .\dsh\cordis.patch.yml

For a persistent DSH profile, install the repository bundle once, then boot the profile. On Windows, current DSH/pnpm path forwarding can split a source path containing spaces; use its 8.3 short path when necessary:

如果要持久安装到 DSH profile，请先安装一次仓库 bundle，再启动 profile。Windows 当前 DSH/pnpm 的路径转发可能拆分含空格的源码路径，必要时请使用 8.3 短路径：

$bundlePathForDsh = (cmd /c "for %I in (.) do @echo %~sI").Trim()
dsh plugin --profile web add $bundlePathForDsh
dsh --profile web

The bundle runs node scripts/cli.mjs mcp from CHILON_RECALL_ROOT. Set RAG_RERANK_API_KEY, CHILON_RECALL_HOME, or CHILON_RECALL_PYTHON when your private configuration needs them. DSH is still a developer-preview product, so its bundle or plugin APIs may change independently of Chilon Recall.

bundle 会在 CHILON_RECALL_ROOT 中运行 node scripts/cli.mjs mcp。如果私有配置需要，可继续设置 RAG_RERANK_API_KEY、CHILON_RECALL_HOME 或 CHILON_RECALL_PYTHON。DSH 仍属于 developer preview，其 bundle 或 plugin API 可能独立于 Chilon Recall 发生变化。

Claude Desktop / Claude Desktop 配置

Add this to claude_desktop_config.json, replacing every example path:

将以下内容加入 claude_desktop_config.json，并替换所有示例路径：

{
  "mcpServers": {
    "chilon-recall": {
      "command": "node",
      "args": [
        "/absolute/path/to/chilon-recall/scripts/server.mjs"
      ],
      "env": {
        "RAG_MANAGER_CONFIG": "/absolute/path/to/chilon-recall/config/chilon-recall.json",
        "CHILON_RECALL_PYTHON": "/absolute/path/to/chilon-recall/.venv/bin/python"
      }
    }
  }
}

For an npm release, replace command and args with the following and omit CHILON_RECALL_PYTHON; setup manages it:

对于 npm 已发布版本，请把 command 和 args 替换为以下内容，并省略 CHILON_RECALL_PYTHON；它由 setup 管理：

"command": "npx",
"args": ["-y", "chilon-recall@0.1.2", "mcp"]

Set RAG_API_KEY in the environment inherited by Claude Desktop, or add it only to your private local client configuration when your operating system cannot provide it. Claude Desktop stores env values in a local JSON file, so restrict file permissions and never commit that file. On Windows, use the virtual environment's python.exe path.

应在 Claude Desktop 可继承的系统环境中设置 RAG_API_KEY；若操作系统无法提供，只能把它加入本机私有 client 配置。Claude Desktop 会将 env 值存入本地 JSON，因此应限制文件权限，且绝不能提交该文件。Windows 用户应指向虚拟环境中的 python.exe。

How it works / 工作原理

Private text documents
        │
        ▼
heading-aware chunking ──► OpenAI-compatible embeddings
        │
        ▼
 local FAISS index + JSON source metadata
        │
question ──► vector recall ──► optional reranking
        │
        ▼
structured MCP evidence with relative source paths
私有文本资料
        │
        ▼
标题感知分块 ──► OpenAI-compatible embeddings
        │
        ▼
本地 FAISS 索引 + JSON 来源元数据
        │
问题 ──► 向量召回 ──► 可选 reranking
        │
        ▼
带相对来源路径的结构化 MCP 证据

The Node.js MCP host owns configuration validation, source discovery, approval tokens, path safety, backups, and client-facing tools. The Python engine owns chunking, provider calls, FAISS serialization, and retrieval. Index files are read and written through Python byte I/O so non-ASCII paths work reliably on Windows.

Node.js MCP host 负责配置验证、资料发现、approval token、路径安全、备份和面向 client 的工具。Python engine 负责分块、provider 调用、FAISS 序列化与检索。索引通过 Python byte I/O 读写，以便在 Windows 的非 ASCII 路径下可靠工作。

Tool reference / 工具一览

Read-only tools:

只读工具：

  • rag_status

  • rag_list_documents

  • rag_query

  • rag_list_backups

  • textbook_qa

  • concept_compare

  • chapter_summary

  • review_outline

Configuration and index tools:

配置和索引工具：

  • rag_save_config updates only schema-approved, non-secret fields and creates a backup of the JSON file.

  • rag_save_config 仅修改 schema 允许的非敏感字段，并创建 JSON 文件备份。

  • rag_build, rag_clear_index, and rag_restore_index require action: "preview" first. The preview returns a short-lived token bound to the current configuration and source/index state. Use that token once with action: "execute".

  • rag_build、rag_clear_index 与 rag_restore_index 必须先使用 action: "preview"。预览会返回一个绑定当前配置和来源/索引状态的短期 token，再使用该 token 一次性执行 action: "execute"。

Provider configuration / Provider 配置

Embeddings / 向量化

The first release supports the openai-compatible adapter. Configure:

首版支持 openai-compatible adapter，需要配置：

  • base_url

  • model

  • api_key_env

  • optional doc_prefix and query_prefix

  • base_url

  • model

  • api_key_env

  • 可选的 doc_prefix 和 query_prefix

The key itself must exist only in the named environment variable.

key 本身只能存在于指定的环境变量中。

Reranking / 重排序

The cohere-compatible adapter sends model, query, documents, top_n, and return_documents to the configured URL. Set enabled to false to return top FAISS matches directly.

cohere-compatible adapter 会向配置的 URL 发送 model、query、documents、top_n 和 return_documents。将 enabled 设为 false 可直接返回排名靠前的 FAISS matches。

Provider compatibility is an interface claim, not a guarantee that every nominally compatible service behaves identically. Test your selected models with the synthetic demo before indexing private documents or incurring large costs.

Provider 兼容性只是接口层面的声明，并不保证每个标称兼容的服务行为完全相同。在索引私有资料或产生较大费用前，应先用合成示例测试你选择的模型。

Data safety / 数据安全

  • The server binds to one RAG_MANAGER_CONFIG; individual tool calls cannot select arbitrary configuration files.

  • server 固定绑定一个 RAG_MANAGER_CONFIG；单次 tool call 不能选择任意配置文件。

  • Secret-shaped keys are rejected in Python configuration loading. Provider credentials come from environment variables.

  • Python 配置加载会拒绝疑似 secret 的字段；provider 凭据从环境变量读取。

  • Absolute source paths are hidden unless display.expose_absolute_paths is explicitly enabled.

  • 除非显式启用 display.expose_absolute_paths，否则不会暴露绝对来源路径。

  • The active index, staging area, and backups must resolve inside rag_dir; root and out-of-bound operations are rejected.

  • active index、staging area 和 backups 必须解析到 rag_dir 内部；根目录和越界操作会被拒绝。

  • A new build never modifies the active index until all required files exist.

  • 新建库在所有必需文件就绪前绝不会修改 active index。

  • Clearing moves the active index into backups/. Restoring backs up the current index first.

  • 清理操作会把 active index 移入 backups/；恢复前会先备份当前索引。

  • Confirmation tokens expire after ten minutes, are single-use, and become invalid if source, config, or index state changes.

  • Confirmation token 十分钟后过期，且只能使用一次；来源、配置或索引状态变化时也会失效。

Before publishing changes, run:

发布修改前运行：

npm run check
npm audit --audit-level=high

The publication check rejects likely secrets, personal email addresses, and user-profile paths in tracked source files.

发布检查会拒绝 tracked source files 中疑似的 secret、个人邮箱和用户目录路径。

Limits / 已知限制

  • Version 0.1.2 indexes UTF-8 .md, .txt, .rst, and .csv text. Convert PDFs to reviewed text first; scanned PDFs need OCR.

  • v0.1.2 只索引 UTF-8 .md、.txt、.rst 和 .csv 文本。PDF 应先转换为经过核对的文本；扫描版 PDF 需要 OCR。

  • The included chunker recognizes Markdown # and ## headings. It does not yet parse tables, citations, or document-native structure semantically.

  • 内置 chunker 识别 Markdown # 和 ## headings，暂时不会从语义上解析表格、引文或原生文档结构。

  • Rebuilding is full-index, not incremental.

  • 当前建库是全量重建，不是增量索引。

  • Local embedding and reranker models are not bundled in the first release.

  • 首版不内置本地 embedding 和 reranker 模型。

  • Retrieval returns evidence candidates; it does not prove that the collection is complete, current, correct, or internally consistent.

  • 检索返回的是证据候选，不能证明资料集合完整、最新、正确或内部一致。

Roadmap / 路线图

  • Incremental indexing and content hashing

  • 基于内容哈希的增量索引

  • First-class PDF extraction/OCR adapters with coverage reports

  • 带覆盖报告的 PDF 提取/OCR adapter

  • Local embedding and reranking providers

  • 本地 embedding 与 reranking provider

  • Additional source filters and collection namespaces

  • 更多来源过滤条件和 collection namespace

  • Evaluation fixtures for retrieval quality and citation coverage

  • 用于检索质量和引用覆盖率的评估 fixtures

  • Publish the validated npm package and a separate Python engine package

  • 发布经过验证的 npm package 与独立 Python engine package

Development / 开发

Source checkout / 源码 checkout

Use this workflow only when developing Chilon Recall or when you need a source-based configuration instead of the npm installer:

仅在开发 Chilon Recall，或需要源码配置而非 npm installer 时使用以下流程：

git clone https://github.com/ctrlcakepro/chilon-recall.git
cd chilon-recall
npm install
python -m venv .venv

Activate the virtual environment, then install the Python engine:

激活 virtual environment 后安装 Python engine：

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
# macOS or Linux
source .venv/bin/activate
python -m pip install -e .
npm install
python -m pip install -e .
npm run check

Tests use synthetic documents and mock provider endpoints, so they do not need a paid API key. See CONTRIBUTING.md and SECURITY.md.

测试使用合成资料与 mock provider endpoint，因此不需要付费 API key。参阅 CONTRIBUTING.md 和 SECURITY.md。

License / 许可证

MIT © 2026 ctrlcakepro and contributors.

项目使用 MIT 许可证，© 2026 ctrlcakepro and contributors。

Available Tools

12 tools
chapter_summaryGrounded Chapter SummaryC
Read-only

Retrieve evidence for a structured chapter or topic summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
emphasisNocore claims, key concepts, structure, methods, and examples
candidatesNo
chapterOrTopicYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds only that it retrieves evidence for a structured summary, which is somewhat consistent with the read-only nature. However, it does not disclose return format, how evidence is grounded, or how parameters like 'top' and 'candidates' affect behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, grammatical sentence with no wasted words, making it very concise. It is front-loaded with the main verb. However, for a tool with four parameters and no schema descriptions, the sentence is arguably under-sized, though this is more a completeness issue than a structural flaw.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters, no output schema, and no parameter descriptions, yet the description only states 'Retrieve evidence for a structured chapter or topic summary.' It does not explain what the output looks like, how parameters modify behavior, or any prerequisites. This is insufficient for an agent to confidently invoke the tool with correct arguments.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only implies that 'chapterOrTopic' is the topic to summarize, but provides no meaning for 'top', 'emphasis', or 'candidates'. The description adds minimal value beyond the schema's bare parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Retrieve evidence for a structured chapter or topic summary,' which clearly identifies the action (retrieve evidence) and the resource (a structured summary). It distinguishes from sibling tools like rag_query by focusing on chapter/topic summaries, though it could be more explicit about whether it generates a summary or just returns evidence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as rag_query or textbook_qa. There is no mention of scenarios, exclusions, or complementary tools, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

concept_compareGrounded Concept ComparisonC
Read-only

Retrieve evidence for comparing two concepts across clear dimensions.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
conceptAYes
conceptBYes
candidatesNo
compareFocusNodefinitions, similarities, differences, relationships, and examples

TDQS

C2.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'retrieve evidence' aligns with this read-only behavior, so no contradiction. However, the description adds little beyond the annotations—no details on limitations, return format, or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is front-loaded with the core function, though brevity sacrifices necessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with five parameters, no output schema, and no parameter descriptions, this one-liner is insufficient. It gives a high-level idea but omits how to specify comparison focus, result limits, or what 'evidence' means in practice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no information about the five parameters (conceptA, conceptB, top, candidates, compareFocus). It does not compensate for the lack of schema descriptions, leaving parameter behavior entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('retrieve evidence') and identifies the resource ('comparing two concepts'). This distinguishes it from siblings like rag_query or textbook_qa, though the phrase 'across clear dimensions' is vague about what those dimensions are.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 such as rag_query or textbook_qa. There are no exclusions, prerequisites, or contextual hints beyond the basic purpose, leaving the agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_buildBuild Knowledge IndexA
Destructive

Preview or execute a staged index build. Execution requires the unexpired token returned by preview.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNopreview
confirmationTokenNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds valuable context about the staged build and the unexpired token requirement, which implies a safety gate. It doesn't detail the destructive consequences of execution, but it does add the temporal token constraint 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences, front-loaded with the core action, and every sentence adds essential information. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the two-step workflow and token requirement, which is essential. However, there is no output schema and the description does not clarify what the preview returns besides a token, nor what happens to the existing index upon execution. Given the destructive hint, more detail about side effects would make it more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description carries full responsibility for explaining parameters. It references 'Preview or execute' to map to the action enum and 'token returned by preview' to explain confirmationToken. It gives both parameters meaningful context, though it doesn't explicitly enumerate the enum values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Preview or execute a staged index build,' using a specific verb and resource, and clearly identifies the two modes of operation. This distinguishes it from siblings like rag_query or rag_list_documents by focusing on the build action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the required two-step workflow: 'Execution requires the unexpired token returned by preview.' This tells the agent to run preview first and then use the token for execute. It doesn't mention alternatives or exclusions, but the workflow guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_clear_indexClear Active Index SafelyA
Destructive

Preview or move the active index into a recoverable backup. Execution requires a matching token.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNopreview
confirmationTokenNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructive behavior, and the description adds valuable context: the action is recoverable via backup, and execution requires a token. It does not detail what happens to the current index beyond 'move' or how token matching works, but it 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise, front-loaded sentences deliver the essential purpose and a safety requirement without any filler. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is sufficient for basic invocation but leaves gaps: how to obtain the 'matching token,' what preview outputs, and how restore relates to the backup. Sibling tools imply the restore path, but the description does not explicitly connect them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the action parameter through 'preview or move' and the confirmationToken through 'execution requires a matching token.' It does not explicitly bind these to parameter names or describe token format, but it gives meaningful semantics for both.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation: moving the active index into a recoverable backup, with preview and execute modes. It is distinguishable from siblings like rag_restore_index and rag_list_backups, though it does not use the word 'clear' explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when clearing the active index and notes that execution requires a matching token, but it does not explicitly contrast with alternatives or state when not to use the tool. The preview/execute distinction provides some usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_list_backupsList Index BackupsA
Read-only

List recoverable index backups without exposing their absolute paths.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds important behavioral context beyond annotations by noting that absolute paths are hidden, which is a security/privacy-relevant trait. The readOnlyHint and destructiveHint annotations already cover safety, and the description complements them without contradicting. It does not detail return format, but for a simple list tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action, resource, and a meaningful qualifier. Every word earns its place; there is no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with no output schema, the description covers the essential purpose and a notable behavioral nuance. It could optionally mention what fields are returned (e.g., names, timestamps), but the low complexity and good annotations make the description adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so there is nothing for the description to explain beyond what the schema states. Baseline for zero parameters is 4, and the description correctly focuses on behavior rather than redundant parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('recoverable index backups'), and adds a distinguishing qualifier ('without exposing their absolute paths'), clearly differentiating it from sibling tools like rag_list_documents or rag_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for viewing available backups, but does not explicitly state when to use it (e.g., before restoration) or how it compares to alternatives. No exclusions or alternative tool names are provided, so guidance is implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_list_documentsList Knowledge SourcesA
Read-only

List text documents included by the fixed knowledge-base configuration.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context by specifying that it lists 'text documents' from the 'fixed knowledge-base configuration', clarifying that the list reflects a static configuration rather than dynamic state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It directly states the action and scope, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with strong annotations, the description adequately conveys what is listed. The return format is implied by the verb 'List', and the main gap is the unexplained 'limit' parameter, though this is minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema defines a single optional 'limit' parameter (1-2000), but the description does not mention it or explain its effect. With 0% schema description coverage, the description should compensate, but it provides no parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and identifies the resource 'text documents' with a clear scope ('fixed knowledge-base configuration'). This clearly distinguishes it from siblings like rag_list_backups (which lists backups) and rag_status (which shows status).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for inspecting the configured knowledge-base documents, but it does not explicitly state when to use this tool versus alternatives like rag_list_backups or rag_status. No exclusions or alternative tool names are mentioned, so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_queryQuery Knowledge IndexB
Read-only

Retrieve source-backed passages from the active local index.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
questionYes
candidatesNo

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that the tool returns 'source-backed passages' from a 'local index,' but does not explain behavior when the index is not active or built, so it provides some context but not deep behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no fluff. Every word contributes to stating the tool's purpose, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 3 parameters and no output schema, but the description omits parameter semantics, usage guidance, and return format details. While annotations cover read-only safety, an agent would not know how to set 'top'/'candidates' or what the response contains, making the description incomplete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the meaning or role of the 'top', 'question', or 'candidates' parameters. It implies a query is needed ('Retrieve source-backed passages') but never maps the query to the 'question' parameter or clarifies the numeric parameters, so the description fails to compensate for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Retrieve' and a precise resource 'source-backed passages from the active local index,' clearly distinguishing it from siblings like rag_list_documents or rag_status. It succinctly states what the tool does without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 instead of alternatives such as textbook_qa or other rag tools. The description lacks any contextual usage cues, leaving an agent without help in selecting between similar query tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_restore_indexRestore Index BackupA
Destructive

Preview or restore a named backup. Execution requires a matching token and backs up the current index first.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNopreview
backupIdYes
confirmationTokenNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the destructiveHint annotation by disclosing that it 'backs up the current index first' and that execution requires a matching token. This is valuable safety-related behavior that would not be known from the schema or annotations alone, enhancing the agent's ability to assess risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and front-loads the core purpose. It avoids fluff and introduces important caveats (token, backup-first) in an efficient second sentence. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a restore tool with no output schema, the description covers the key aspects: the backup identifier, the preview/execute modes, the token requirement, and the safety backup of the current index. It is complete enough for an agent to understand the tool's behavior and likely outcomes without further documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero schema description coverage, the description compensates by referencing 'named backup' (backupId), 'matching token' (confirmationToken), and 'Preview or restore' (action). These implicit mappings clarify the purpose of each parameter, though it does not explicitly enumerate the parameters or their formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Preview or restore a named backup.' The verb 'restore' with resource 'index backup' is specific, and the preview/execute distinction is immediately clear. It differentiates from sibling tools like rag_clear_index by focusing on restoring from a backup rather than clearing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on how to use the tool: a preview mode exists, execution requires a matching token, and the current index is backed up first. While it doesn't explicitly state when to use this tool versus alternatives, the destructive nature and prerequisite of a token are conveyed, giving enough guidance for most usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_save_configUpdate Knowledge ConfigurationB

Atomically update approved non-secret settings in the server's fixed configuration file.

ParametersJSON Schema
NameRequiredDescriptionDefault
ragDirNo
maxCharsNo
minCharsNo
batchSizeNo
docPrefixNo
projectDirNo
rerankTopNNo
queryPrefixNo
rerankerUrlNo
overlapCharsNo
retrieveTopKNo
rerankerModelNo
embeddingModelNo
fileExtensionsNo
rerankerEnabledNo
embeddingBaseUrlNo
rerankerApiKeyEnvNo
embeddingApiKeyEnvNo
exposeAbsolutePathsNo

TDQS

B3.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a write (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds valuable context by emphasizing atomicity and the restriction to 'approved non-secret settings', which helps the agent understand side effects and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence that avoids redundancy. It is concise and front-loaded, though it could incorporate a bit more detail without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 19 parameters, no output schema, and no explanation of the configuration file lifecycle, the description is insufficiently complete. It does not explain what happens after an update or how 'approved' settings are determined, leaving significant ambiguities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

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 name or explain any of the 19 parameters. The phrase 'approved non-secret settings' is too vague to indicate which parameters are permitted or how they relate to the function.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Atomically update') and resource ('the server's fixed configuration file'), with a scope ('approved non-secret settings'). This unambiguously differentiates it from sibling tools like rag_build or rag_query, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparative scenarios with sibling tools such as rag_restore_index or rag_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rag_statusKnowledge Base StatusA
Read-only

Inspect source coverage, provider readiness, and the active index without changing data.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'without changing data.' It adds behavioral detail by naming the three aspects it inspects (source coverage, provider readiness, active index), which is useful beyond annotation hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the verb, the scope, and the non-destructive nature. Every word contributes meaning, with no redundancy or irrelevance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter status tool, the description adequately names the key output dimensions (source coverage, provider readiness, active index) despite lacking an output schema. It does not fully describe return formatting, but the essence is clear and consistent with annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description appropriately focuses on what the tool inspects rather than parameter details, which are unnecessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Inspect' with distinct resources: 'source coverage, provider readiness, and the active index.' It clearly distinguishes this from sibling tools like rag_list_documents and rag_list_backups, and from mutating tools like rag_build and rag_clear_index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without changing data' provides clear context that this is a non-mutating status check, aligning with the read-only annotations. It does not explicitly mention alternatives or when not to use, but the sibling tool list makes the usage context obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

review_outlineEvidence-backed Review OutlineC
Read-only

Retrieve evidence and organize it for focused study or review.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
topicYes
candidatesNo
reviewModeNocomprehensive

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that it 'organizes' evidence, which is useful, but it does not describe the output structure, retrieval scope, or whether the evidence comes from a specific source. There is 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no redundancy, front-loading the core action. It is concise and to the point. However, it sacrifices informativeness, which is more a completeness concern than a conciseness one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain what the tool returns, but it only says 'organize it.' It does not mention the outline format, how `reviewMode` changes behavior, or what 'evidence' refers to. This is insufficient for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

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 mention any of the four parameters. It doesn't explain the meaning of `topic`, `top`, `candidates`, or `reviewMode`, leaving the agent to guess from names alone. The description fails to compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs 'retrieve' and 'organize' and states the purpose 'for focused study or review,' which aligns with the title 'Evidence-backed Review Outline.' It is reasonably distinct from sibling tools like rag_query or textbook_qa, though it does not explicitly say it generates an outline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for focused study or review' gives some context about when to use the tool. However, it does not mention alternatives, when not to use it, or how it differs from similar tools like chapter_summary or concept_compare. Usage is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

textbook_qaSource-backed Learning Q&AC
Read-only

Retrieve evidence for answering a learning question from the configured knowledge base.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
depthNostandard
questionYes
candidatesNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'retrieve' aligns with that. However, the description adds no additional behavioral information such as rate limits, configuration assumptions, or output characteristics beyond the annotations. With annotations covering the safety profile, the description provides minimal extra value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, directly stating the core purpose. It is front-loaded and efficiently sized, earning full marks for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters and no output schema, and the description only covers the basic purpose. It fails to explain return values, parameter semantics, or any operational context needed for correct invocation, making it incomplete for a tool of moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are absent for all four parameters (0% coverage), so the description must compensate. It implicitly references the 'question' parameter via 'learning question' but does not explain the meaning or usage of 'top', 'depth', or 'candidates'. This leaves agents without enough information to set optional parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

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 retrieve evidence for answering learning questions from a configured knowledge base. It uses a specific verb ('retrieve') and resource ('evidence'), and the title 'Source-backed Learning Q&A' reinforces the educational Q&A focus. However, it does not explicitly differentiate itself from similar siblings like rag_query, so it misses a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as rag_query or concept_compare. It only describes the action without any prerequisites, exclusions, or comparative context, making it insufficient for selecting the right tool among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation4/5

Most tools have clearly distinct purposes: admin operations (backups, status, config, build, clear/restore) are unambiguous, and retrieval tools are specialized by task (general query, QA, comparison, summary, outline). However, rag_query and textbook_qa overlap somewhat as both retrieve evidence for questions, and chapter_summary vs review_outline could be confused.

Naming Consistency3/5

Admin tools follow a consistent rag_ prefix with verb_noun pattern (list_backups, save_config, clear_index), but retrieval tools are mixed: rag_query fits, while textbook_qa, concept_compare, chapter_summary, and review_outline use noun-based names without the prefix. This creates a predictable split between admin and query tools, but the naming style is not uniform.

Tool Count5/5

12 tools is well within the ideal range, covering both index lifecycle management and a variety of retrieval modes. Each tool contributes a distinct function, and none feel redundant or unnecessary for the server's purpose.

Completeness4/5

The tool set covers the core index lifecycle (build, clear, restore, backup, status) and multiple retrieval scenarios (question answering, concept comparison, summaries, outlines). Minor gaps include no explicit backup deletion and no full-document retrieval, but these are not essential for the stated educational RAG use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • ragi

    SusuTawar
    A
    license
    A
    quality
    D
    maintenance
    Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
    3
    14
    MIT

  • OmniClip RAG MCP Server

    EllisMorrow
    A
    license
    Not graded
    quality
    A
    maintenance
    Read-only local-first MCP server enabling AI assistants to semantically search private Markdown, PDF, and Tika-backed knowledge bases without data upload.
    46
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ctrlcakepro/chilon-recall'

If you have feedback or need assistance with the MCP directory API, please join our Discord server