MCP server exposing BM25 search over markdown files in data/
Single tool with adequate naming and description, but missing critical schema documentation in the visible code. The tool 'doc_search' follows verb_noun convention and has a detailed, well-written description (194 chars) that explains WHAT it does, WHEN to use it, and what it returns. However, the input schema is inferred from the FastMCP decorator and function signature rather than explicitly defined in the codebase, the JSON schema for parameters ('query' and 'top_n') is not visible in the source code provided. The output schema is documented in the description text but not as a formal schema definition. No error handling guidance is present, when no results are found, the tool returns a plain message rather than structured error recovery guidance. The parameters lack detailed constraints and ranges.
Look up documentation to help answer the user's prompt. Call this whenever the user's question might be answered by the indexed markdown corpus (e.g. GitHub docs, project notes). Pass a focused search query derived from the user's prompt — keywords, an API name, an error string, or a paraphrased question all work. Use the returned `context` as reference material when composing your reply, and cite `sources` so the user can verify. Returns: context: concatenated excerpts, each prefixed with its source path and line range — drop this straight into your reasoning. sources: structured list of {path, start_line, end_line, score} for citation or follow-up reads.
Input schema not explicitly visible in source code. While FastMCP likely generates JSON Schema from the function signature (query: str, top_n: int = 5), the explicit schema definition is not shown. Per HARD SCORING RULES, if the actual tool definition cannot be verified in the source, schema score is penalized heavily.
No error handling guidance for common failure modes. When search returns no results, the tool returns a plain message ('No documentation matched the query...') rather than a structured error with recovery hints (e.g., 'No results found. Try broader keywords or check available docs via list_available_docs()'). LLMs need actionable next steps on failure.
Parameter descriptions and constraints not documented. The 'query' parameter has no format guidance (max length? special chars allowed? case-sensitive?). The 'top_n' parameter lacks a range constraint, is 1-100 valid? 1-1000? Should default=5 be changed if the corpus is small? These omissions force LLMs to guess.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 52 | <=2025-11-25 | v2 |
No output schema formally defined. The description text mentions 'context' and 'sources' fields, but the actual structure (types, required fields, nested object schemas) is not formally documented. LLMs cannot reliably parse ambiguous outputs.
STDIO transport only. The server is hardwired to STDIO by default and cannot be remotely accessed, limiting integration with hosted MCP clients and cloud-based agents. This is a fundamental architectural limitation.