Tool descriptions lack actionable context. 'Index markdown files for BM25 full-text search and vector search' does not explain when to call this vs other tools, what prerequisites exist, or what the output contains. Descriptions should be 50-200 chars and answer: What does it do? When to use it? What does it return?

Output schemas are not documented. The source code provided shows only input schemas. LLMs need to know what fields to expect (e.g., does qmd_search return [{ file: string, score: number, content: string }]? Does it support pagination?). Without documented output, agents cannot plan downstream calls.

Parameter descriptions lack format/constraint guidance. 'Array of file paths or glob patterns to index' in qmd_index does not specify: What glob syntax is supported? Are absolute and relative paths both valid? What happens if a path doesn't exist? 'Output SQLite database path' does not describe expected format or error handling if the directory doesn't exist.

No error handling guidance. If qmd_search returns results but the database is corrupted, or a query is malformed, or no results match, tools should return actionable error messages. 'Query too broad' should suggest: refine the query or lower the limit. Currently, error responses are not documented.

Missing pagination/limit guidance for search tools. qmd_search and qmd_vsearch accept a 'limit' parameter but do not document: What is the default? Is there a maximum? Do they return a total count or next_cursor for large result sets? Without pagination info, agents may fetch too many results and exhaust context.

Tool composition risk: qmd_expand and qmd_rerank have unclear dependencies. qmd_rerank accepts 'results' (array) and expects to rerank them, presumably output from qmd_search or qmd_vsearch. But this dependency is not documented. If an agent calls qmd_rerank with malformed results, what happens? Does the tool guide them to call search first?

Parameter 'results' in qmd_rerank lacks a schema. It's described as 'Array of search results to rerank' but the source shows no type definition for the array elements. What fields does each result need? Can an LLM pass arbitrary JSON, or is there a strict schema? This ambiguity violates the 'no ambiguous parameters' rule.

qmd_vector and qmd_expand are vaguely named and described. 'Generate vector embeddings for text using local LLM' does not clarify: What embedding model is used? What is the output dimensionality? Is it deterministic? Can it handle large texts? 'Expand search query into lex (lexical), vec (vector), and hyde (hypothetical document) formats' uses acronyms (hyde) that are not explained for LLM context.