Hindsight MCP has 5 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-60 chars, mostly short) and input schemas with required fields. However, descriptions lack context on WHEN to use each tool, dependencies between tools, and error recovery guidance. Parameter descriptions are minimal (e.g., 'The task identifier' for taskId). No output schemas documented. Tools lack error handling guidance. Naming is verb-based but generic (record_*, query_*, get_*). No tool annotations (readOnlyHint, destructiveHint). The semantic search tool (hindsight_query_similar) lacks pagination despite returning potentially large result sets. Write operations (record_intent, record_outcome) have no confirmation or dry-run pattern.

• Expand tool descriptions to 100-200 chars. Include WHEN to use (e.g., 'Call after attempting a task to record what you were trying to achieve'), dependencies ('Requires a valid taskId from an active task'), and error recovery ('If taskId not found, call hindsight_get_episode first to list available tasks').
• Document output schemas for all tools. E.g., hindsight_query_similar should return [{episodeId, similarity, intent, outcome}, ...]. hindsight_get_episode should return {episodeId, taskId, intent, outcome, timestamp, fileChanges}.
• Add pagination to hindsight_query_similar: include offset/cursor and total_count in response. Cap results at 20-50 per request. Document in description: 'Returns up to 20 results; use offset to fetch more.'
• Add tool annotations: mark record_intent and record_outcome with destructiveHint=true. Mark query_similar, get_episode, get_file_history with readOnlyHint=true.
• Add parameter descriptions for limit fields. E.g., 'Maximum number of results to return (1-100, default 20)' instead of just 'Maximum number of results to return'.