mcp-hydrolix demonstrates good definition quality with clear naming, solid descriptions, and complete input schemas. All 4 tools follow verb_noun naming convention (list_*, describe_*, run_*). Descriptions are substantive (80-200 chars typically) and explain WHAT and WHEN to use each tool. Input schemas are well-formed JSON Schema with type definitions and parameter descriptions. However, output schemas are not explicitly documented in the visible code, and error handling guidance is minimal. Tools are read-only with low risk, which simplifies security but limits the need for complex permission checks. The server uses FastMCP framework which abstracts away some boilerplate, making the code cleaner but harder to verify exact schema registration details.

• Document output schemas for all tools. Add to each tool's docstring: 'Returns: {field1: type, field2: type, ...}' with sample structure or link to a schema definition file.
• Enhance error responses with recovery guidance. Wrap tool implementations to catch and enrich errors: 'SQL parse error at line 5: invalid column reference. Call describe_table(database=X, table=Y) to list available columns.'
• Add pagination details to list_* tools. Update descriptions: 'Lists all databases (up to 1000 results per request). If more results exist, use offset/limit parameters to paginate.'
• Constrain 'parameters' input in run_select_query. If parameter values must be strings, numbers, or booleans, update schema to specify: 'type: object, additionalProperties: {oneOf: [{type: string}, {type: number}, {type: boolean}]}'
• Consider adding tool annotations (readOnlyHint, destructiveHint) for MCP spec alignment. All tools are read-only and idempotent, annotate them with readOnlyHint=true for client-side UI hints.
• Add composition guidance in descriptions. E.g., 'Typically used after list_tables() to inspect column structure before writing queries.'

Inferred effective spec: 2026-07-28+.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry