Single tool 'query' has a clear, action-oriented name and a detailed description (186 chars) explaining read-only constraints, row limits, table allowlisting, and ACL-based access control. Input schema is present with two parameters (sql, limit), both typed and described. However, output schema is not documented in the visible code, the tool description does not specify what fields the result contains, how rows are structured, or pagination behavior. Error handling is not visible in the provided source. The tool follows security best practices (read-only enforcement, ACL gating, table allowlisting) but lacks guidance on what to do when a query fails or returns no results.

• Document the output schema explicitly: 'Returns an object with fields: rows (array of objects), row_count (integer), query_time_ms (integer), warning (string or null). Each row is a key-value object matching the SELECT columns.'
• Add error handling examples to the description: 'If the query times out (>10s), returns error code TIMEOUT with message 'Query exceeded 10-second limit. Try adding a LIMIT clause or narrowing the WHERE condition.' If a table is not in the allowlist, returns error code FORBIDDEN with message 'Table X is not accessible. Allowed tables: [list].'
• Specify the limit ceiling in the description: 'The limit parameter is clamped to a configured ceiling (default 1000, configurable via magebit_mcp_db_tools/general/row_limit_ceiling). If you request limit=5000, it will be clamped to 1000.'
• Add a note on result truncation: 'If the result set exceeds the limit, the response includes a truncated flag and a message: 'Result set truncated to 1000 rows. Refine your query with a WHERE clause to narrow results.'
• Include ACL failure guidance: 'If you lack permission to read a table, the error message lists which ACL resource you need. Ask the administrator to grant you the required permission (e.g., Magebit_McpDbTools::read_customers).'
• Document the SQL statement timeout: 'Queries that run longer than 10 seconds (configurable) are terminated with error code TIMEOUT. This prevents runaway queries from blocking the database. Optimize your query or request a higher timeout from the administrator.'