epic-agent demonstrates solid tool definition quality with consistently present descriptions, well-structured schemas, and proper naming conventions. All 5 tools use action-verb naming (list_, retrieve_, search_) and have detailed descriptions explaining purpose, parameters, and return behavior. Input schemas are fully specified with type information and parameter descriptions. Key strengths: pagination support across tools, clear non-deterministic vs deterministic modes documented, output truncation handled transparently. Weaknesses: output schemas not formally documented (inferred from descriptions), no explicit error handling guidance, missing tool annotations (readOnlyHint/destructiveHint), and no confirmation patterns despite READ_ONLY categorization.

• Add formal JSON Schema definitions for all tool outputs in the tool registration. Include return type, required fields, field types, and examples. Reference this in tool descriptions (e.g., 'Returns { workshops: Array<{slug, title, exerciseCount}>, pagination: {total, cursor} }').
• Implement readOnlyHint annotation in all tool registrations since all tools are READ_ONLY. This signals to LLMs and clients that these tools have no side effects and are safe to call speculatively.
• Add explicit error handling guidance to tool descriptions. For example: 'If truncated=true, use the cursor parameter to fetch remaining content. If vectorSearchAvailable=false, results fall back to keyword search; adjust query to be more specific if needed.'
• For retrieve_learning_context, document the non-deterministic behavior of random=true: 'When random=true, results vary on each call. Agents should not retry with the same random seed; use explicit parameters (exerciseNumber, stepNumber) for deterministic retrieval.'
• Add oneOf or conditional schema constraints for search_topic_context to enforce that exerciseNumber and stepNumber require workshop to be set. Use JSON Schema dependencies if using OpenAPI/JSON Schema 2020-12.
• Consider adding a batch tool variant (e.g., retrieve_learning_contexts_batch) to allow agents to fetch multiple exercise contexts in a single call, reducing round-trips and token overhead.
• Document the 'focus' parameter in retrieve_diff_context with examples and constraints: 'Optional filename (e.g., src/App.tsx) or symbol name (e.g., handleSubmit). If omitted, returns full diff.'

Inferred effective spec: 2025-06-18+.

• Current-spec patterns present: structured tool output, Streamable HTTP