SmartAssist exposes 9 tools with reasonable naming (verb-prefixed) and basic descriptions. However, critical gaps undermine production readiness: parameter descriptions are sparse or missing entirely (e.g., rag_search 'limit' lacks guidance on valid range; boost_lesson 'amount' has no bounds), output schemas are not documented anywhere in the visible code, and error handling is absent. Tool names are clear (rag_search, create_lesson, merge_lessons) but descriptions average ~80 chars, below the 194-char baseline for A+ tools. No tool declares what it returns or how to chain results. The codebase shows sophisticated internal logic (Thompson sampling, similarity profiles, auto-merge heuristics) but none of this is surfaced to the LLM via structured output documentation.

• Document output schemas for all tools. Example: rag_search should return [{lesson_id, text, similarity_score, category, created_at}, ...] with total_count and next_cursor for pagination.
• Add bounds to numeric parameters: rag_search limit (1 - 100, default 10), boost_lesson amount (0.1 - 10.0), demote_lesson amount (0.1 - 10.0). State these in parameter descriptions.
• Expand tool descriptions to 150 - 250 chars. Explain WHEN to use each tool: 'Use rag_search to find past lessons by keyword. Use rag_feedback to rate a lesson's usefulness. Use apply_feedback_protocol to bulk-import feedback from external sources.'
• Add enum constraints to category parameters. rag_search and create_lesson accept category but do not list valid values. Declare: category must be one of [testing, code_edit, git, architecture, pr_review, security, debugging].
• Implement error handling with recovery hints. E.g., if merge_lessons fails because survivor_id is invalid, return 'Lesson not found. Valid lesson IDs: [id1, id2, ...]. Did you mean one of these?'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry