mcp-recorder defines 4 tools with basic schemas and descriptions. All tools have input schemas with type definitions and required fields. Descriptions are present but minimal (10-80 chars), below the 50-200 char LLM-optimized baseline. Parameter descriptions exist but lack detail on constraints, formats, or error recovery. No output schemas documented. Error handling is absent, tools do not guide recovery or categorize failures. Tool naming follows verb_noun convention (list_, show_, diff_, replay_) which is good, but descriptions lack context on when to use each tool vs alternatives. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles (3 READ_ONLY, 1 WRITE). Composition is reasonable, each tool has one responsibility, but chaining is not documented.

• Expand tool descriptions to 50-200 chars. Example: 'list_sessions: List all recorded MCP sessions in a directory. Use this to discover available sessions before calling show_session or diff_sessions. Returns session names and metadata.'
• Document output schemas for all tools. Example: 'show_session returns {sessions: [{name, path, entries_count, summary}], total_count}'. This enables LLMs to extract and chain results.
• Add error handling guidance to each tool description. Example: 'If session not found, returns error with available session names. Call list_sessions to discover valid names.'
• Add tool annotations: set readOnlyHint=true for list_sessions, show_session, diff_sessions; set destructiveHint=true for replay_session. This helps agents reason about side effects.
• Enhance parameter descriptions: 'dir: Directory path containing .jsonl session files. Defaults to ~/.mcp-recorder/sessions. Accepts absolute or relative paths.'