Heimdall exposes 3 tools with reasonable naming (kb_search, kb_insert, kb_sync) and descriptions that explain purpose and context. However, schema quality is inconsistent: kb_search and kb_insert have proper TypeBox schemas with typed parameters and descriptions, but kb_sync has an empty schema object. Parameter descriptions are present but sometimes lack actionable constraints (e.g., kb_search 'query' lacks guidance on format or length). Output schemas are not documented, LLMs cannot predict response structure. Error handling is minimal: the run() helper returns {ok, text} but provides no recovery guidance or error classification. kb_insert's keywords parameter changed from comma-separated string to array between definition and implementation, creating a mismatch. No tool declares permissions, audit requirements, or idempotency guarantees.

• Add explicit output schema documentation for each tool. kb_search should document: {results: [{title, body, keywords, trust_verdict, path}], total_count}. kb_insert should document: {success: boolean, anchor_id, message}.
• Fix kb_insert keywords parameter: either change schema to Type.String() with description 'comma-separated keywords' OR update description to match array type. Align implementation with schema.
• Enhance error responses with recovery guidance. Instead of 'ERROR: aborted', return structured errors: {error: 'timeout', message: 'Search exceeded 300s. Try a shorter query or narrower scope.', retryable: true}.
• Add parameter constraints to kb_search: query description should specify 'natural language or code snippet, 1-500 characters' and n should have min/max bounds (1-50).
• Document tool permissions and idempotency. kb_search is READ_ONLY (safe to retry); kb_insert and kb_sync are WRITE (idempotent if anchors are deduplicated by title). State this in descriptions.