PlyDB provides two read-only tools with clear, actionable descriptions and properly typed input schemas. Both tools follow the verb_noun naming convention and include parameter descriptions. However, output schemas are not documented in the source code, and the server lacks several production patterns (error recovery guidance, permission gates, pagination support, tool annotations). The descriptions are adequate but could be more detailed about use cases and error conditions.

• Document the output schema for both tools. Specify all returned fields, their types (string, number, array, object), and whether they are required or optional. For 'query', describe result row structure and column types. For 'get_semantic_context', describe the YAML structure and key sections (datasets, schemas, fields).
• Add error handling guidance to the 'query' description: 'If the query fails, common issues are: invalid fully-qualified table names (use catalog.schema.table), syntax errors (check SQL dialect compatibility), or missing data sources (call get_semantic_context first to verify available tables).'
• Add readOnlyHint: true to both tool definitions in the handler to signal to agents that these are safe, non-destructive operations.
• Document result limits and pagination. If 'query' can return large result sets, specify a cap (e.g., 'Limit results to first 1000 rows; use WHERE or LIMIT clauses to narrow results') and advise on chunking strategies.
• Enhance the 'sql' parameter description to include format guidance: 'A valid SQL query using DuckDB dialect. Tables must be referenced as fully-qualified 3-part names in the form catalog.schema.table. Example: SELECT * FROM main.public.users WHERE age > 18 LIMIT 10.'
• Implement error recovery patterns. When a query fails, return structured errors that guide the LLM: {"error": "Invalid table reference", "hint": "Table 'users' not found. Available tables: [list]. Use fully-qualified names like 'main.public.users'.", "retryable": false}.