AI document assistant: RAG service + MCP server for searching, asking questions over, and managing a user's document corpus with hybrid retrieval (keyword full-text + vector similarity) and retrieval-augmented generation
Corpus has 4 well-named tools with clear descriptions and documented input schemas. Tool names follow verb_noun convention (search_documents, ask_documents, list_documents, documentInfo). Descriptions are substantive (100 - 200 chars) and explain WHAT and WHEN. Input parameters have types and descriptions. However, output schemas are not explicitly documented in the source, responses are inferred from record definitions (SearchHit, AskAnswer, DocumentInfo). Parameter descriptions lack format constraints (e.g., topK range, query length limits). Error handling is minimal, no recovery guidance or actionable error messages visible. No tool annotations (readOnlyHint, idempotentHint) despite all tools being read-only. Missing pagination guidance for list_documents despite accepting a limit parameter.
Ask a natural-language question over the user's documents and get a citation-backed answer generated with retrieval-augmented generation.
Look up ingestion metadata (status, size in bytes, chunk count, upload time) for one of the user's documents by its exact filename
List the user's uploaded documents with ingestion status and chunk counts.
Search the user's document corpus with hybrid retrieval (keyword full-text + vector similarity, fused with Reciprocal Rank Fusion). Returns ranked chunks with source filename, chunk index, and scores. Use this to find passages; use ask_documents for a synthesized answer.
Output schemas not explicitly documented. SearchHit, AskAnswer, DocumentInfo are inferred from Java record definitions; LLMs cannot see these schemas in the MCP tool registration.
Parameter constraints missing. topK parameter lacks min/max bounds (e.g., 1 - 100); query parameter lacks length limits. LLMs may pass invalid values without guidance.
No tool annotations. All 4 tools are read-only but lack readOnlyHint annotation. Agents cannot infer safety without explicit hints.
Error handling not visible. No recovery guidance in code (e.g., 'User not found. Try search_users()' pattern). Agents receive raw errors with no next-step guidance.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | 2026-07-28+ | v2 |
list_documents accepts limit parameter but no pagination cursor/offset. Large result sets may exceed context window; no guidance on how to fetch next page.