discord-archive provides 7 tools with generally good structure, but exhibits inconsistent parameter documentation and lacks explicit output schema definitions. Tool names follow the verb_noun pattern (semantic_search, graph_search, get_context_window, sql_query, get_message_attachments, get_message_details, get_user_profile) which is strong. Descriptions are present and reasonably detailed (150-400 chars each), explaining the semantic or functional purpose. However, parameters lack consistent type-checked constraints, notably, 'sql_query' accepts free-form strings with only a description guardrail, and several tools use default=null inconsistently. Output schemas are inferred from implementation code rather than explicitly documented in tool definitions. Error handling and recovery guidance are minimal, no actionable error messages or retry strategies visible in the tool contracts.

• Explicitly document output schemas for all tools. Add a 'returns' key to each tool definition showing the structure of results. E.g., semantic_search returns {chunk_id: int, distance: float, guild_id: string, channel_id: string, author_ids: string[], has_attachments: bool, first_message_at: ISO8601|null, last_message_at: ISO8601|null, message_ids: int[]|undefined, text: string|undefined}.
• Add input validation and sanitization guidance to sql_query. Replace free-form description with: 'Execute a read-only SQL query. Query is validated against a whitelist of allowed table/column names and a query parser to prevent injection. Examples: SELECT count(*) FROM messages WHERE guild_id = ?; SELECT * FROM channels WHERE created_at > ?. Do not parameterize with string interpolation, use bound parameters (? or $1).'
• Document how null/missing filter parameters are handled in semantic_search and graph_search. Add explicit note: 'If guild_id is null/omitted, search across all guilds. If author_id is omitted, search all authors. To filter, pass the ID as a string.'
• Add error handling guidance to all tools. E.g., semantic_search: 'On model load failure, returns {error: "Embedding model unavailable. Retry in 30s."}. On LanceDB search timeout, returns {error: "Search timeout (>30s). Try reducing limit or adding filters."}.'
• Add pagination support. Modify semantic_search and graph_search to return {results: [...], total_count: int, next_cursor: string|null}. Accept cursor parameter for continuation. Cap results at 20 by default, allow up to 100 via limit parameter.