What can you do with this server?

Chilon Recall is an MCP server for local-first, source-backed retrieval and learning workflows over your documents. * Inspect knowledge state – check index/provider readiness, list indexed documents, and list recoverable backups (rag_status, rag_list_documents, rag_list_backups). * Query for evidence – retrieve ranked, source-backed passages from your local index (rag_query). * Manage configuration safely – update approved non-secret settings atomically (rag_save_config). * Build and maintain indexes – preview then execute staged full builds, incremental content-hash syncs, safe clears, and restores (rag_build, rag_sync, rag_clear_index, rag_restore_index). * Run learning workflows – generate source-grounded Q&A, concept comparisons, chapter summaries, and review outlines (textbook_qa, concept_compare, chapter_summary, review_outline).

How do I use Chilon Recall?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Chilon Recall What do my notes say about retrieval practice?" 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.

Chilon Recall

Official

by ctrlcakepro

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Chilon Recall

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

version license node python

English (this page) · 简体中文

Quick start · Tools · MCP clients · 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.

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.

Related MCP server: Hoard

Quick start

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.

Using an AI coding agent instead (Claude Code, Codex CLI, Cursor, …)? Paste this to it: "Read https://raw.githubusercontent.com/ctrlcakepro/chilon-recall/main/AGENTS_INSTALL.md and follow it to install chilon-recall for me. My document folder is: <path>." It automates everything below except typing your own API key — see AGENTS_INSTALL.md for exactly what it will and won't do on its own.

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.

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

2. Set your provider key

Open the generated chilon-recall.json and replace the placeholder embedding.base_url (https://api.example.com/v1) and embedding.model (your-embedding-model) with your real provider values, then set the key only in your environment. doctor treats those placeholders as not-ready and will not report configuration.ready: true until you edit them.

$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.5 doctor

doctor is an offline check: it catches the template placeholders and a missing key, but it never contacts your provider, so a real-looking base_url with a typo, or a wrong key, still passes. Then confirm them online with the key wizard:

npx -y chilon-recall@0.1.5 key --base-url https://your-provider.example/v1

It prompts for the key once (hidden input), calls the provider's own /models endpoint — a mistyped URL fails here, and so does a key the provider rejects — suggests an embedding and reranker model, and prints ready-to-run $env:/setx/export commands with the key already filled in. chilon-recall uses the key for that one request only and never writes it to a file; the printed setx / >> ~/.bashrc commands do store it in plaintext if you run them.

Paste the key as a single line. The prompt submits at the first line break it receives, including one inside the pasted text: anything after it is discarded. If your clipboard holds more than the key (for example a copied KEY=... block), copy the key alone.

3. Connect one client

Start with Codex, Claude Desktop, or Qoder. The client starts the local server for you; you do not need to keep a separate terminal open.

Why 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.
Safe operations	Builds happen in staging; clear and restore actions use previews, short-lived confirmation tokens, and recoverable backups.
MCP portability	One `stdio` server works with Codex, Claude Desktop, Qoder, and other MCP-compatible local clients.

What you can do

Chilon Recall supports both direct retrieval and reusable learning workflows:

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
Refresh the index after documents change	`rag_sync`	Added/modified/deleted/unchanged file counts, plus reused and re-embedded vector counts

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

1. Install with npm

Requires Node.js 20+ and Python 3.10+.

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

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

This writes chilon-recall.json in the document directory and creates a persistent managed Python engine in the operating system's user-data area. Both files are required for local operation; credentials remain outside both of them.

The managed engine lives outside the temporary npx cache. Set CHILON_RECALL_HOME to choose a different persistent location.
Run setup again after upgrading the package.
Installation never writes credentials anywhere. Set the provider key in your own environment afterwards.

To validate the runtime and private configuration:

$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.5 doctor

doctor exits 0 only when Python, the managed engine, the configuration, and its credentials are all ready — otherwise 1, so it is safe to gate a script on. It also refuses to call the placeholder embedding.base_url/model from the install template "ready".

If you installed from npm, skip ahead to Connect an MCP client. The remaining subsections are for source checkouts and custom configurations.

2. Manual private configuration

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

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

# Windows PowerShell
$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)

# macOS or Linux
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.

3. Start the source-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. After documents change, refresh with rag_sync instead of rebuilding; it reuses vectors for unchanged files.

Connect an MCP client

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

Windows: prefer "command": "node" with an absolute path to cli.mjs/server.mjs over "command": "npx". Some MCP clients spawn command directly (bypassing the shell), and on Windows npx is a .cmd shim that a direct, non-shell spawn cannot resolve — the client reports the command as not found even though it works from a terminal. node <absolute path> avoids the shim entirely.

Client	Configuration entry point
Codex	`~/.codex/config.toml`, `codex mcp add`, or ChatGPT desktop Settings → MCP servers
DeepSeek Harness	`dsh --patch` overlay or an installed profile bundle
Claude Desktop	`claude_desktop_config.json`
Qoder	Qoder client Settings → MCP → My Servers plus a generated `.qoder/` directory

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.

Source checkout:

[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"

npm release — run npx -y chilon-recall@0.1.5 setup first under the same OS account. A pinned version prevents an unexpected package upgrade from changing a working MCP server.

[mcp_servers.chilon-recall]
command = "npx"
args = ["-y", "chilon-recall@0.1.5", "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.

DeepSeek Harness

The repository 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.

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.

One-off run — apply the overlay without installing the bundle:

$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

Persistent 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:

$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.

Claude Desktop

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

{
  "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:

"command": "npx",
"args": ["-y", "chilon-recall@0.1.5", "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.

Qoder

The Qoder client loads MCP servers from its own settings, and project-level skills and rules from the .qoder/ directory. Generate all three from a checkout or an npm install:

npx -y chilon-recall@0.1.5 qoder C:\path\to\your\project

This writes .qoder/mcp.json, .qoder/skills/<name>/SKILL.md for every bundled skill, and .qoder/rules/chilon-recall.md. Add --force to regenerate over existing files.

Generating from npx embeds an unstable path. npx unpacks the package into a temporary per-run cache (e.g. ...\npm-cache\_npx\<hash>\... on Windows), and the node/cli.mjs path written into .qoder/mcp.json points there. Clearing the npm cache or bumping the pinned version moves that path and the MCP server stops starting, with no error beyond Qoder failing to load it. The command detects this and prints a warning; prefer running chilon-recall qoder from a stable install (npm install -g chilon-recall@0.1.5, or a source checkout) so the generated path survives cache clears.

Qoder does not read .qoder/mcp.json automatically; it is a shareable snippet. Open Qoder client Settings → MCP → My Servers → + Add, paste its contents, and replace the RAG_MANAGER_CONFIG placeholder with your private configuration path:

{
  "mcpServers": {
    "chilon-recall": {
      "command": "node",
      "args": [
        "/absolute/path/to/chilon-recall/scripts/cli.mjs",
        "mcp"
      ],
      "env": {
        "RAG_MANAGER_CONFIG": "<absolute path to your private chilon-recall.json>"
      }
    }
  }
}

Set RAG_API_KEY (and RAG_RERANK_API_KEY when reranking is enabled) in the environment Qoder inherits. The generated files are safe to commit; credentials never belong in them. Restart the Qoder client so the generated skills and rules load, then confirm the tools under My Servers.

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

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.

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_build, rag_sync, 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.
rag_sync hashes files, reuses compatible unchanged vectors, and reconciles added, modified, and deleted files. It falls back to a full rebuild when indexing settings change or an older manifest lacks the required hashes.

Provider configuration

Embeddings

The first release supports the openai-compatible adapter. Configure base_url, model, api_key_env, and optionally doc_prefix and query_prefix.

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

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.

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.

Data safety

The server binds to one RAG_MANAGER_CONFIG; individual tool calls cannot select arbitrary configuration files.
Secret-shaped keys are rejected in Python configuration loading. Provider credentials come from environment variables.
Absolute source paths are hidden unless display.expose_absolute_paths is explicitly enabled.
The active index, staging area, and backups must resolve inside rag_dir; root and out-of-bound operations are rejected.
A new build never modifies the active index until all required files exist.
Clearing moves the active index into backups/. Restoring backs up the current index first.
Confirmation tokens expire after ten minutes, are single-use, and become invalid if source, config, or index state changes.

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.

Limits

Version 0.1.5 indexes UTF-8 .md, .txt, .rst, and .csv text. Convert PDFs to reviewed text first; scanned PDFs need OCR.
The included chunker recognizes Markdown # and ## headings. It does not yet parse tables, citations, or document-native structure semantically.
rag_build is a deliberate full rebuild. Use rag_sync for content-hash incremental synchronization; it always writes a new staged FAISS index so row IDs remain aligned with metadata.
Local embedding and reranker models are not bundled in the first release.
Retrieval returns evidence candidates; it does not prove that the collection is complete, current, correct, or internally consistent.

Roadmap

First-class PDF extraction/OCR adapters with coverage reports
Local embedding and reranking providers
Additional source filters and collection namespaces
Evaluation fixtures for retrieval quality and citation coverage
Publish the validated npm package and a separate Python engine package

Development

Use this workflow only when developing Chilon Recall, or when you need a source-based configuration instead of the 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:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

# macOS or Linux
source .venv/bin/activate
python -m pip install -e .

Then run the checks:

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.

License

Available Tools

13 tools

chapter_summaryGrounded Chapter SummaryC

Read-only

Retrieve evidence for a structured chapter or topic summary.

ParametersJSON Schema

Name	Required	Default
`top`	No
`emphasis`	No	core claims, key concepts, structure, methods, and examples
`candidates`	No
`chapterOrTopic`	Yes

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

Name	Required	Default
`top`	No
`conceptA`	Yes
`conceptB`	Yes
`candidates`	No
`compareFocus`	No	definitions, 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

Name	Required	Description	Default
`action`	No		preview
`confirmationToken`	No

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

Name	Required	Description	Default
`action`	No		preview
`confirmationToken`	No

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

Name	Required	Description	Default
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

Name	Required	Description	Default
`limit`	No

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

Name	Required	Description	Default
`top`	No
`question`	Yes
`candidates`	No

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

Name	Required	Default
`action`	No	preview
`backupId`	Yes
`confirmationToken`	No

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

Name	Required	Description	Default
`ragDir`	No
`maxChars`	No
`minChars`	No
`batchSize`	No
`docPrefix`	No
`projectDir`	No
`rerankTopN`	No
`queryPrefix`	No
`rerankerUrl`	No
`overlapChars`	No
`retrieveTopK`	No
`rerankerModel`	No
`embeddingModel`	No
`fileExtensions`	No
`rerankerEnabled`	No
`embeddingBaseUrl`	No
`rerankerApiKeyEnv`	No
`embeddingApiKeyEnv`	No
`exposeAbsolutePaths`	No

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

Name	Required	Description	Default
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.

rag_syncSynchronize Knowledge IndexA

Destructive

Preview or execute a staged content-hash sync. Unchanged files reuse existing vectors; added, modified, and deleted files are reconciled safely.

ParametersJSON Schema

Name	Required	Description	Default
`action`	No		preview
`confirmationToken`	No

TDQS

A3.8/5.0

Behavior4/5

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

Even though destructiveHint=true already signals potential destruction, the description adds useful behavioral context: the operation is staged, supports preview and execute, and reuses vectors for unchanged files while reconciling add/modify/delete changes. This gives the agent a clearer mental model of what will happen, though 'safely' is vague and no rollback or irreversibility detail is provided.

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, tightly worded sentence that front-loads the primary action and then adds only high-signal behavioral details. There is no filler or redundancy.

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?

For a destructive, two-phase sync tool with no output schema and an unexplained confirmationToken, the description is not fully complete: it does not say what a preview returns, whether execute requires confirmationToken, or how the token is obtained. Still, the core staged-sync model and destructive scope are communicated well enough for a basic agent to act cautiously.

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?

With 0% schema description coverage, the description must compensate for documenting the parameters. It partially maps to the 'action' parameter by saying 'Preview or execute,' but it adds no real meaning beyond the schema enum, and it leaves confirmationToken completely unexplained—its purpose, whether execution requires it, and how an agent would obtain it are all absent.

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 a specific verb-plus-resource pair, 'Preview or execute a staged content-hash sync,' and then explains the sync behavior with added/modified/deleted files. This makes the tool's role clear and distinguishes it from siblings like rag_build, rag_clear_index, and rag_restore_index.

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 this tool is for incrementally reconciling an index with changed source files, especially through the phrases 'staged content-hash sync' and 'unchanged files reuse existing vectors.' However, it never explicitly states when to choose rag_sync over rag_build, rag_clear_index, or rag_restore_index, nor does it describe prerequisites or sequencing.

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

Name	Required	Default
`top`	No
`topic`	Yes
`candidates`	No
`reviewMode`	No	comprehensive

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

Name	Required	Default
`top`	No
`depth`	No	standard
`question`	Yes
`candidates`	No

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev0.1.4Sep 19, 2026
- Addedrag_sync
12 tool updatesv0.1.0Aug 13, 2026
- First observedchapter_summary
- First observedconcept_compare
- First observedrag_build
- First observedrag_clear_index
- First observedrag_list_backups
- First observedrag_list_documents
- First observedrag_query
- First observedrag_restore_index
- First observedrag_save_config
- First observedrag_status
- First observedreview_outline
- First observedtextbook_qa

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-19 16:31 across 13 tools

Disambiguation4/5

The tools split into RAG lifecycle operations and study-retrieval modes, each with distinct purposes. rag_sync and rag_build are the closest pair, but their descriptions differentiate incremental reconciliation from full index build, so an agent can usually pick correctly.

Naming Consistency4/5

All names use snake_case and the rag_ prefix clearly groups administration tools, but the study helpers follow a noun-phrase style rather than the verb_noun convention. The one outlier is rag_status, which uses a noun where an action verb would be more consistent.

Tool Count5/5

Thirteen tools is within the well-scoped range, and each tool has a non-redundant role: nine cover the RAG index lifecycle and four cover retrieval/study modes. No tool feels like filler.

Completeness5/5

The RAG lifecycle is covered end-to-end: build, sync, query, status, config, clear/backup, list backups, and restore. The study side has compare, summary, outline, and Q&A retrieval, so the server supports its apparent purpose without obvious dead ends.

Maintenance

ActivityActive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

Mirror Memory MCP Server
io.github.Tr1ckyMag1ca1
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Knowledge & Memory Search Note Taking
2
saagarpatel.dev Portfolio A
io.github.saagpatel
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Search Documentation Access
82
trip2g B
io.github.trip2g
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
RAG Systems Note Taking Search
11238
docbaseOAuth
io.github.krayinc
DocBase MCP server for AI agents
Documentation Access Search Developer Tools
2

Related MCP Servers

ragi
RAG Systems Search
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.
Updated a month ago (2026-08-13 16:07 UTC)
3
6 npm
MIT
Hoard
Knowledge & Memory RAG Systems Agent Orchestration
thrr87
A
license
Not graded
quality
D
maintenance
Local MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.
Updated 8 months ago (2026-02-07 12:52 UTC)
4
MIT
Paper Memory MCP Lite
Research & Data Knowledge & Memory Search
StaryMoon
A
license
Not graded
quality
C
maintenance
Local-first MCP server for indexing and searching research materials (papers, notes, logs, READMEs) using SQLite FTS, with tools for memory management and evidence retrieval.
Updated 3 months ago (2026-07-02 05:51 UTC)
MIT
OmniClip RAG MCP Server
RAG Systems Search
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.
Updated a month ago (2026-08-08 15:38 UTC)
45
MIT

Chilon Recall

Contents

Quick start

1. Install into your document folder

2. Set your provider key

3. Connect one client

Why Chilon Recall?

What you can do

Detailed setup

1. Install with npm

2. Manual private configuration

3. Start the source-checkout MCP server

Connect an MCP client

Codex

DeepSeek Harness

Claude Desktop

Qoder

How it works

Tool reference

Provider configuration

Embeddings

Reranking

Data safety

Limits

Roadmap

Development

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers