Multiple update tools (update_chunk, update_chunk_content, update_chunk_metadata) perform overlapping operations with unclear distinctions. LLMs must reason about which to select, risking misuse.
create_learning_item automatically manages topics, mixing concerns. Tool description says 'Simpler alternative to create_topic_with_chunks' but create_topic_with_chunks is not exposed. Violates single responsibility principle.
Output schemas are not documented. Tools return data structures but no schema definitions visible in source code. LLMs cannot plan downstream calls or know which fields to extract.
Document output schemas for all tools. For analytics_daily/window, specify returned KPI field names and types. For list_* tools, document whether results include IDs, timestamps, content previews. Enable LLM planning via structured responses.
Consolidate overlapping update tools: either provide update_chunk as the canonical option with optional fields, or clearly partition: update_chunk_content for content+progress, update_chunk_metadata for metadata only. Remove ambiguity via naming or merge into one robust tool.
Replace procedural warnings in get_chunk_content and get_topic_summary descriptions with constraint enforcement at the protocol level. If these tools should not be called directly, gate them behind a session check or provide a precondition in the tool annotation.
Add error handling with recovery guidance: 'If search fails with mode=semantic, ensure EMBEDDING_PROVIDER is configured. Retry with mode=keyword as fallback.'
Implement confirmation pattern for delete_chunk: require a confirmation_token parameter or add a dry_run flag. Document the cleanup behavior (which references are removed) so LLMs understand scope.
Add tool annotations for readOnlyHint, destructiveHint, and idempotentHint to all tools. Mark analytics_*, list_*, get_*, search_*, batch_fetch_* as read-only. Mark delete_chunk as destructive.
Document parameter constraints explicitly in descriptions: 'difficulty (integer, 1-10)', 'estimated_duration (integer, 1-120 minutes)', 'limit (integer, 1-100)'. Format as inline constraints, not examples.
get_chunk_content and get_topic_summary descriptions include procedural warnings ('Do NOT use this tool directly...') that should be enforced by the server, not documented to users. Long descriptions (>200 chars) with procedural guidance rather than capability statements.
delete_chunk performs automatic cleanup of prerequisite references but lacks confirmation or dry-run capability. Destructive operation with no recovery guidance in error responses.
Parameter descriptions lack validation constraints. E.g., 'difficulty' accepts 1-10 per source code but description says 'Difficulty level from 1-10' without stating these are bounds. Format constraints, regex patterns, and length limits not stated in descriptions.
search_learning_content accepts 'semantic' and 'hybrid' modes but description says 'requires configured embedding provider' without stating what happens if not configured. No error guidance for missing dependencies.
list_learning_items description recommends calling what_to_learn_today instead, but that tool is not visible in the provided interface. References to non-existent tools create dead ends for LLMs.
No evidence of tool idempotency markers or hints about retry safety. Agents cannot determine which tools are safe to retry (create operations) vs risky (delete, send).
Batch fetch tools return 'minimal' metadata but do not document what fields are included/excluded. 'Minimal' is ambiguous, LLMs need explicit field lists to plan downstream calls.
For batch_fetch_topics_minimal and batch_fetch_chunks_minimal, explicitly list which fields are returned (id, title, subject, difficulty, duration, type, timestamps) so LLMs know what's available without guessing.
Remove references to non-exposed tools (e.g., 'create_topic_with_chunks', 'what_to_learn_today'). Either expose them or remove the references.
Add pagination result guidance: specify whether offset-based or cursor-based pagination is used, and whether total_count is returned. This enables proper batch processing.
For create_learning_item, document that it auto-creates topics if topic_title is missing. If this is a convenience feature, explain when to use this vs explicitly creating a topic first.