Single tool 'query' has a clear name and reasonable description (127 chars), but critical gaps undermine quality. Input schema is present with three parameters (sql, pageNumber, pageSize), all with descriptions. However, the tool enforces restrictive constraints (WHERE clause required, SELECT * prohibited, max pageSize=50) that are documented in the description but not formalized as schema constraints or enums. Output schema is completely undocumented, the tool returns a String (likely JSON), but the LLM has no visibility into the structure of results. Error handling is basic (IllegalArgumentException for missing WHERE clause) with no recovery guidance. The tool lacks idempotency hints, read-only annotations, and pagination metadata (total count, next_cursor). Parameter descriptions are adequate but lack format/range specifications beyond the description text.

• Document the output schema explicitly. Define the structure returned by query(), e.g., {rows: [{col1: string, col2: int, ...}], total: int, pageNumber: int, pageSize: int, hasMore: bool}. Include this in the tool description or a separate schema definition.
• Formalize input constraints as schema rules. Use JSON Schema pattern for sql (e.g., must contain ' where '), minItems/maxItems for pageSize (1 - 50), and add enum or pattern validation in the schema, not just description text.
• Add pagination metadata to the response. Return total row count and a has_more flag so the LLM knows whether to fetch the next page. This prevents wasted calls and enables efficient result iteration.
• Enhance error messages with recovery guidance. Change 'SQL query must include a WHERE clause' to 'SQL query must include a WHERE clause to filter results. Example: SELECT id, name FROM users WHERE status = ?'.
• Add tool annotation hints. Use Spring AI's @Tool annotation to declare readOnlyHint=true so the MCP protocol layer and clients can see this is a safe, read-only operation without inspecting code.