MCP server for searching documents and managing folders in a RAG (Retrieval-Augmented Generation) system with permission-based access control
Three tools with complete JSON schemas and strong, detailed descriptions. Naming follows verb_noun convention (search_*, list_*). Descriptions are 50-400+ chars, well above the 10-char minimum, and include context about limitations (e.g., 'closest is not the same as relevant'). Parameters are typed with constraints (minLength, min/max for limit). However, output schemas are not documented, the code shows tool definitions but no explicit return type documentation. Error handling is minimal; no recovery guidance or actionable error messages visible. No tool annotations (readOnlyHint, etc.) despite all three being read-only operations.
List the folders this agent may read, each with its id, its name and its parent, so that a search can be narrowed to one of them. Folders the agent cannot read are left out entirely.
Search every document this agent is allowed to read and return the passages that best answer the query. Results carry the text itself, so a further fetch is not needed. Documents the owner has not granted to this agent are never searched and never mentioned. Passages may come from several collections, each indexed by a different embedding model. A score is only meaningful against other passages from the same collection: 0.44 from one model is not worse than 0.61 from another, because the two are not on the same scale. Compare rank_in_collection instead, and treat the order they arrive in as the answer to which passages are best. A search always returns its closest matches, and closest is not the same as relevant: asked about something this store knows nothing about, it answers with whatever was least unlike the question. Read the passages before trusting that they answer it.
Search only within one folder and everything below it. Use it to keep an answer to one subject area when the folder is known. A folder that does not exist and one this agent may not read both return nothing.
Output schemas not documented. Tools return structured results (e.g., {results: [...], folders: [...]}) but no schema definition visible for LLM to plan downstream calls or extract fields.
No tool annotations despite all three tools being read-only. Missing readOnlyHint annotation would signal to LLMs that these tools are safe to call without confirmation.
No error handling guidance. Code raises RpcError for invalid tool names but no recovery hints (e.g., 'Try list_readable_folders() first to get valid folder_id'). LLMs cannot self-correct.
search_documents description warns about score comparability across models but does not explain what fields the result contains (e.g., text, rank_in_collection, score, source). LLM must infer structure.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
list_readable_folders has empty inputSchema properties but no explicit documentation of output structure (id, name, parent fields). Downstream tools like search_in_folder expect folder_id but output schema is opaque.