MCP server for retrieving company and customer domain knowledge using BM25 algorithm
Four tools with complete input schemas and descriptions, but significant gaps in parameter documentation and output schema specification. Tool names follow verb_noun convention (search-, get-, list-). Descriptions are present (avg 95 chars) but lack actionable context for LLM selection. Parameters have types but most lack descriptions, critical for disambiguation. No documented output schemas, error handling guidance, or recovery paths. No tool annotations (readOnlyHint present in metadata but not in schema). Composition is reasonable (single responsibility per tool), but chaining support unclear due to missing output documentation.
Get specific chunk with surrounding context.
Retrieve full document by ID.
List all available domains and their document counts.
Search documents using BM25 algorithm. Takes keyword arrays and returns relevant document chunks.
Output schemas not documented. LLMs cannot plan downstream calls or extract required fields (e.g., does search-documents return document_id, chunk_id, score, text?). Breaks tool chaining.
Parameter descriptions missing or minimal. 'domain' in search-documents says '(optional, e.g., "company", "customer")' but does not explain what domain filtering does or when to use it. 'topN' lacks range constraints (min/max). LLMs cannot infer valid values.
No error handling guidance. Tools do not document failure modes (e.g., 'document not found', 'invalid chunk ID') or recovery steps. LLMs receive raw errors with no actionable next steps.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 46 | 2026-07-28+ | v2 |
Tool descriptions lack context for LLM selection. 'Retrieve full document by ID' does not explain when to use this vs search-documents, or what 'full document' means (size, format, structure). Ambiguous descriptions increase wrong tool selection.
No pagination support documented. search-documents accepts 'topN' but does not indicate if results are paginated, whether there is a next_cursor, or how to retrieve additional results. Large result sets risk context window exhaustion.