Episteme has 16 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-100 chars, mostly 50-80), and input schemas are present with type definitions. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool or HOW to chain them. Output schemas are not documented. Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors. Parameter descriptions exist but are minimal (e.g., 'Entity identifier' for graph_entity.id). No tool annotations (readOnlyHint/destructiveHint). The 'sniff' tool accepts both 'files' array and 'staged' boolean without documenting mutual exclusivity. Most tools are READ_ONLY (15/16), but insight_add is WRITE with no confirmation pattern. Naming is verb-forward (analyze, infer, search, refactor, audit, ground) which is good, but tools like 'graph_entity', 'graph_neighbors', 'graph_path' could be more action-oriented (get_entity, list_neighbors, find_path). No pagination support visible despite tools returning lists (search, insight_list, graph_subgraph). Average tool description ~70 chars (below 194-char baseline); average params ~2.5 (below 4-param baseline).

• Document output schemas for all tools. Example: search returns {results: [{id, title, type, score}], total_count, next_cursor}. This enables LLMs to chain tools and extract IDs for follow-up calls.
• Add pagination to list/search tools: accept limit (1-100, default 20) and offset/cursor parameters; return total_count and next_cursor. Cap results at 50 items per call.
• Expand parameter descriptions to 50-100 chars with format hints. E.g., graph_entity.id: 'Entity identifier (UUID or string key from search results)'. Include constraints: 'limit: 1-100, default 20'.
• Add error recovery hints to tool descriptions. E.g., search: 'Returns empty if no matches. Try broader queries or use graph_entity with a known ID.' graph_entity: 'If entity not found, call search() first to discover available IDs.'
• Implement confirmation pattern for insight_add: add a 'dry_run' boolean parameter (default false) that returns the insight without persisting, or require explicit 'confirm: true' parameter to commit.