A Model Context Protocol server built with Spring Boot and Spring AI that provides help desk ticket management tools
This Spring AI MCP server has significant definition quality gaps. Both tools lack complete input schema definitions visible in source code. Tool descriptions are minimal (26-97 chars). Parameter descriptions are present for createTicket but the schema structure is incomplete, and getTicketStatusByUsername has no documented input parameters. The server uses Spring AI's @Tool annotation framework, but the MCP tool registration does not expose rich enough metadata for LLM reasoning. Naming is reasonable (verb_noun) but descriptions fall short of LLM optimization standards (ideal: 50-200 chars). Critical: getTicketStatusByUsername's input schema is empty {}, yet it clearly requires a 'username' context parameter, this is a major schema documentation gap that will confuse clients about what inputs are actually needed.
Create a Support Ticket
Fetch the status of the open tickets based on the given username
getTicketStatusByUsername declares empty input schema {} but requires username from ToolContext. This is a critical schema documentation gap, clients cannot see that 'username' is required. The tool definition does not expose its true input contract.
createTicket's input schema shows a 'ticketRequest' parameter of type object with properties (issue, username), but the actual Spring method signature receives username from ToolContext, not from the request object. This mismatch between declared schema and implementation will cause client confusion about which parameters are independent vs. nested.
Tool descriptions are too short. createTicket: 26 chars ('Create a Support Ticket'), getTicketStatusByUsername: 97 chars. Both fall well below the 50 - 200 char baseline for LLM-optimized descriptions. Descriptions should explain WHAT, WHEN, and any prerequisites.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 6 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 29 | - | v1 |
Output schemas are not documented in tool definitions. LLMs need to know what fields will be returned: createTicket returns a String, getTicketStatusByUsername returns List<HelpDeskTicket>. The structure of HelpDeskTicket (id, username, issue, status) is not exposed in the tool contract.
No error handling documentation. Neither tool describes what happens on failure (e.g., 'Username not found', 'Ticket creation failed due to validation error'). LLMs cannot determine recovery steps without actionable error guidance.
ToolContext.getContext().get('username') is a loosely-typed context lookup. If 'username' is missing or null, it will fail at runtime with no clear error. Parameter descriptions should clarify that 'username' is extracted from context, not passed as an explicit tool parameter.
createTicket's TicketRequest model has 'issue' and 'username' properties, but ToolContext also provides 'username'. The schema does not clarify whether 'username' in the request object is ignored in favor of context-based username, or if both must match. This dual source of username is confusing.
No idempotency or confirmation pattern documented. createTicket is a write operation that could create duplicate tickets if retried. The description does not state whether calling it twice with the same input will create two tickets or detect a duplicate.