A Retrieval-Augmented Generation (RAG) system built with Spring Boot and LangChain4j. Provides document processing, embeddings, vector storage, and LLM inference capabilities via REST APIs and WebSocket integration.
Tool definitions not explicitly visible in Java/Spring Boot source code. Tool names and descriptions reference JavaScript service files, but source shows only Maven POM configuration.
Input schemas completely absent. No JSON Schema type definitions visible for any parameter. uploadQuiz accepts 'quizDefinition' as object with no property definitions; processResponse accepts 'responseData' as object with no properties defined.
Descriptions are severely under-specified. getAllQuizzes: 'Get all quizzes' (14 chars). uploadQuiz: 'Upload new quiz definition' (25 chars). processResponse: 'Process quiz response' (20 chars). None explain WHEN to use the tool, WHAT data structure is expected, or WHAT is returned. Per pattern:tool-description, descriptions must be 50-200 chars and include purpose, context, and expected output.
Recommendations
Register all tools in the Spring Boot MCP controller with explicit @Tool annotations or equivalent MCP server registration mechanism. Provide complete JSON Schema definitions for all input parameters with 'type', 'description', and constraints (enum, minLength, pattern, etc.).
Rewrite tool descriptions to follow the 50-200 character guideline. For each tool, include: (1) what it does in one sentence, (2) when to use it vs similar tools, (3) what input it expects, (4) what it returns. Example: 'getQuizById: Retrieve a single quiz definition by its document ID. Use this to fetch full quiz content before displaying or modifying. Returns quiz metadata, questions, and scoring rules. Requires valid documentId (UUID format).'
Document all parameter constraints explicitly. For 'documentId' in getQuizById, specify: 'UUID string format (e.g., 550e8400-e29b-41d4-a716-446655440000)' and add minLength/maxLength. For 'step' in getQuizStep, specify: 'integer, 0-indexed, must not exceed total quiz steps'. Add enums where applicable.
Define output schemas for all tools. Example for getQuizById: { 'type': 'object', 'properties': { 'quizId': {'type': 'string', 'description': 'Unique quiz identifier'}, 'title': {'type': 'string'}, 'questions': {'type': 'array', 'items': {'type': 'object', 'properties': {...}}} } }.
Add pagination to getAllQuizzes: accept 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Return 'total', 'items', and 'hasMore' in the response so the LLM can iterate through large quiz collections without exhaustion.
Parameter descriptions are generic and uninformative. 'Quiz definition object to upload' and 'Quiz response data to process' provide no actionable guidance on expected fields, format, or constraints. Per pattern:tool-description, every parameter must have a description explaining format, range, and valid values.
No output schemas documented. It is unknown what fields each tool returns, what types those fields are, or how they chain to other tools. Per pattern:response-shaper, tool responses must have documented schemas so LLMs know what to expect and can plan downstream calls.
Generic verb naming in processResponse. 'Process' is too vague, does it validate, store, score, or analyze the response? Per review:name-clarity, action verbs must be specific. Recommend: scoreQuizResponse, validateQuizResponse, or submitQuizResponse.
No error handling documented. No indication of which errors are retryable, which require user intervention, or how the LLM should respond to failures. Per pattern:recovery-guide, errors must include actionable next steps.
No indication of pagination support. getAllQuizzes has no limit or offset parameters visible. Per pattern:paginated-result, tools returning lists must support limit and offset to avoid context window exhaustion.
Destructive write operations (uploadQuiz, processResponse) lack confirmation or dry-run capability. Per pattern:confirmation-request, irreversible operations should support a preview or confirmation step to prevent agent mistakes.
uploadQuizprocessResponse
Rename 'processResponse' to a more specific verb. Examples: 'submitQuizResponse' (implies recording an answer), 'scoreQuizResponse' (implies computing a score), 'validateQuizResponse' (implies checking validity). Update description to clarify the side effect.
Add error handling guidance. Document expected error codes and recoverable paths. Example: 'If documentId not found, returns 404 with message: "Quiz not found. Try getAllQuizzes() to list available quizzes." This is retryable by searching first.'
For write operations (uploadQuiz, processResponse), add a 'dryRun' parameter (boolean, default false) to preview the operation without side effects. This allows agents to validate before committing.
Include chaining IDs in responses. If uploadQuiz returns a newly created quiz, return its quizId so the agent can immediately call getQuizById or getQuizStep without an extra lookup.
Add tool annotations (if MCP version supports) to indicate: READ_ONLY for getAllQuizzes, getQuizById, getQuizStep; DESTRUCTIVE for uploadQuiz, processResponse. This helps agent planning.
Provide a searchQuizzes tool alongside getAllQuizzes to allow filtering by title, date range, or author, reducing the need to fetch and filter large result sets in-context.