CogSession defines 8 tools with complete input schemas and descriptions. Naming follows verb_noun convention (session_init, session_checkpoint, session_load, etc.), which is clear and consistent. Descriptions are substantive (100-250 chars), explaining WHAT each tool does and WHEN to use it. However, parameter descriptions are sparse or missing context. For example, session_update's 'type' enum is well-defined, but many parameters lack guidance on format/constraints. Output schemas are not documented, callers cannot predict response structure. Error handling is absent from tool definitions; no guidance on recovery paths. Security considerations (file path validation, permission checks) are not visible in tool specs. Overall: solid naming and descriptions, but incomplete schemas and no error guidance.

• Document output schemas for all tools. For session_search, specify: {results: [{session_id, timestamp, type, content, match_context}], total_count, has_more}. For session_status, specify all returned fields (active_session_id, context_pct, token_count, files_touched, decisions, dead_ends, assumptions, tasks, errors).
• Add min/max constraints to numeric parameters. session_update's context_pct should be 0-100. session_search's limit should be 1-100 (default 10). session_load's load_level enum is good; apply same rigor to other enums.
• Add error recovery guidance to tool descriptions. E.g., session_checkpoint: 'If disk is full, free space and retry. If permission denied, ensure .cogsessions/ is writable.' session_load: 'If session not found, call session_tree() to list available sessions.'
• Validate project_root parameter. Add to all tool descriptions: 'project_root must be an absolute path within the user's workspace. Relative paths and paths containing .. are rejected.' Implement path normalization and bounds checking in the server.
• Add pagination to session_search and session_status. Support offset/limit or cursor-based pagination. Return total_count and has_more flag so LLMs know when to fetch next page.