usql-mcp provides 8 tools with explicit schemas and descriptions, which is above the baseline for community servers. However, there are consistent gaps in parameter descriptions, missing output schema documentation, and several tools lack clarity about when to use them versus similar tools. Tool naming is clear and action-oriented (execute_query, list_databases, describe_table, etc.), following the verb_noun pattern well. Descriptions are present but often generic or incomplete, e.g., 'Get the status of a background job' (39 chars) falls short of the 50-200 char LLM-optimized sweet spot. Parameter descriptions are inconsistent: some are well-detailed (e.g., 'Database connection string (optional, uses default if not provided)'), while others are minimal. No explicit output schemas are documented in the provided code, requiring LLMs to infer structure from tool behavior. Error handling is present in the factory (src/tools/tool-handler-factory.ts) with categorized error types, but recovery guidance is sparse. Security is good: connection strings are validated and sanitized, with no credentials exposed as parameters.
Cancel a running background job
Describe a table structure
Execute a SQL query against a database connection
Execute a SQL script containing multiple statements
Get the status of a background job
Get server configuration information including available database connections, default connection, and execution settings. Use this to discover what connections are available and configured. Returns background execution threshold, job TTL, query timeout, and other server settings. No parameters required - this is a read-only operation.
List all available databases
List tables in a database
Output schemas not documented. The provided code excerpt includes parameter schemas but no documented return types or response structures. LLMs cannot plan downstream tool calls or extract chaining IDs without knowing what fields to expect.
Tool descriptions too brief and generic for LLM selection. get_job_status ('Get the status of a background job', 39 chars) and cancel_job ('Cancel a running background job', 32 chars) lack context about when to call them, what they return, or how they differ from each other. Descriptions should be 50-200 chars with explicit use-case guidance.
Parameter descriptions inconsistent. Some parameters in list_tables and list_databases (e.g., 'timeout_ms') have one-liner descriptions ('Query timeout in milliseconds (optional)'), while others lack ranges or format constraints. No guidance on minimum/maximum values for numeric parameters.
Inferred effective spec: 2025-06-18+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 49 | 2025-06-18+ | v2 |
| 2026-03-09 | F | 49 | - | v1 |
No output pagination or result limits documented. Tools like list_databases and list_tables return unstructured output (RawOutput with 'content' string). No indication of pagination, result count, or limits, if a database has 10,000 tables, the response could exhaust context.
Error recovery guidance is minimal. Tool-handler-factory catches errors and categorizes them (e.g., 'InvalidConnection', 'InvalidInput'), but error messages do not suggest next steps. A user seeing 'Invalid connection string format' has no guidance on how to fix it or which tool to call next.
Job-related tools (get_job_status, cancel_job) lack documentation of job lifecycle and state model. What states can a job be in? How long does a job persist? When should an agent check status vs. wait? This guidance is essential for agents to use these tools correctly.