knowledge-mcp has 11 tools with documented descriptions and risk classifications, but critical quality gaps undermine production readiness. Naming is clear and verb-forward (search_, get_, list_, connect_, disconnect_, personal_*, concept_search). Descriptions are present (ranging 45 - 350 chars) and explain functionality, but lack the detail required for LLM decision-making: no explicit WHEN to use each tool vs. similar alternatives, no prerequisites stated, no return value structure documented, no error recovery guidance. Input schemas are partially visible but incomplete: parameters have types (string, number) and optional null unions, but lack constraints (enums, min/max, regex patterns). Output schemas are not documented anywhere in the source, LLMs cannot plan downstream calls or understand what fields will be returned. The tools handle destructive operations (disconnect_source, personal_write) without confirmation-request patterns or explicit warnings about side effects. Three tools (search_documents, get_document, concept_search) have overlapping retrieval semantics with no clear disambiguation. The personal_write tool accepts arbitrary filenames and content without documented path-traversal validation, raising security concerns. Error handling is absent from all tool descriptions, no recovery guidance, no categorization of retryable vs. fatal errors.

• Document output schemas for every tool. For search_documents, specify: returns [{id, source, filename, content, rank, parent_id?}], total_results. For list_sources, returns [{name, type, file_count, indexed_at}]. Include all fields LLMs need for downstream tool calls.
• Add enum constraints to categorical parameters. connect_source: repo_url must match ^https://github\.com/[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+/?$. list_documents, search_documents: limit must be 1 - 100 (default 20). disconnect_source, personal_reindex_source: document that source must be a previously connected source name.
• Rewrite disconnect_source description to include a confirmation warning: 'Permanently deletes indexed content for this source and cannot be undone. Requires explicit user consent before calling.' Add a dry_run boolean parameter or implement a confirmation-request pattern.
• Rewrite personal_write description with explicit validation rules: 'filename must be a relative path within the repository (no ../, no absolute paths, max 255 chars). Only .md, .txt, .yaml files allowed. Attempting invalid paths will fail with a validation error.'
• Add explicit WHEN-to-use guidance in each tool description. Example for search_documents: 'Use for broad keyword/entity searches across all sources. If you know the exact source and filename, use get_document directly, it is faster.' Example for concept_search: 'Use to find related concepts by code, name, or definition. For document retrieval, use search_documents.'
• Document error scenarios and recovery paths. Add to search_documents: 'Returns 400 if source filter is invalid (try list_sources to get valid source names). Returns 200 with empty results if no matches found, consider trying a simpler query or removing filters.'