Lightweight offline document search for Claude Code using BM25 keyword search
Two tools with basic schemas and descriptions, but significant gaps in parameter documentation and output schema clarity. doc_search has a reasonable description (145 chars) and three parameters with types, but 'category' lacks description detail and enum constraints. doc_search_status has minimal description (75 chars) and no parameters. Neither tool documents output structure, making it hard for LLMs to plan downstream actions. No error handling guidance. Naming follows verb_noun convention (search_, status) which is good, but descriptions lack WHEN/WHY context and recovery hints.
Search indexed documents. Use proactively when user asks about EDA tools (Innovus, ICC, etc.), company procedures, technical documentation, bug reports, or any specialized topic that might be in indexed documents. ALWAYS search BEFORE answering technical questions.
Check indexed documents status. Use when user wants to know what documents are available.
Output schemas not documented. LLMs cannot infer what fields to expect from search results or status responses, forcing them to guess at downstream field names and risk broken chains.
Parameter 'category' in doc_search lacks description and enum constraint. Free-form string invites hallucinated values like 'documentation' or 'technical' instead of the valid set (eda, company, bugs, default).
doc_search_status description is too brief (75 chars) and lacks context. Does not explain when to call it, what structure it reveals, or how to use the output to guide indexing decisions.
No error handling guidance. If search returns no results or indexing fails, LLM receives a bare message with no recovery path. Should suggest 'Run doc-search index' or 'Try a different query'.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 49 | 2026-07-28+ | v2 |
doc_search description includes imperative instruction ('ALWAYS search BEFORE answering') which is prompt-engineering leakage, not tool documentation. Descriptions should state WHAT the tool does, not HOW the LLM should use it.