Loading ToolBench
Turn any SQL database into a secure REST API + MCP server. One binary. One command.
Faucet Database API demonstrates solid tool design with consistently well-written descriptions, clear naming conventions, and comprehensive input schemas. All 8 tools follow verb_noun naming (faucet_list_*, faucet_describe_*, faucet_query, faucet_*), and descriptions consistently explain WHAT each tool does, WHEN to use it, and what permissions are required. Input schemas are present and typed for all tools. However, output schemas are not documented in the source code provided, only input schemas are visible. Error handling guidance is minimal, and the schema documentation lacks detail about response structures that would help LLMs plan downstream calls. Tool composition is generally good (e.g., list_services → list_tables → describe_table → query is a clear discovery chain), but some tools combine multiple concerns (faucet_query handles filtering, aggregation, grouping, ordering, and pagination in one call, a valid choice for SQL, but makes parameter relationships complex). Risk annotations (READ_ONLY, WRITE, DESTRUCTIVE, IRREVERSIBLE) are present and properly applied.
Delete records from a database table that match a filter expression. A filter is required to prevent accidental full-table deletes. Returns the number of deleted records. Requires DELETE permission on the table.
Get the detailed schema for a specific table, including all columns with their types, nullability, defaults, primary keys, foreign keys, and indexes. Use this to understand table structure before writing queries. Requires GET permission on the table's schema (_schema/{table}).
Insert one or more records into a database table. Each record is a JSON object mapping column names to values. Returns the inserted records (with auto-generated fields like IDs) if the database supports RETURNING. Requires POST permission on the table.
List all database services configured in Faucet. Returns each service's name, driver type, active status, and access mode. Use this first to discover available databases before querying. Only services your role has access to are listed.
List all tables in a database service, including approximate row counts and column summaries. Use this to explore what data is available before querying specific tables. Requires GET permission on _table.
Output schemas not documented. No visibility into what fields are returned by any of the 8 tools. LLMs cannot plan downstream tool calls or extract needed IDs (e.g., does list_services return service_id, or only name? Does query return column names for result mapping?) without trial-and-error.
faucet_query combines filtering, aggregation, grouping, ordering, limit, and offset into one complex tool. Parameter relationships (e.g., 'fields' can contain aggregate functions like SUM(amount), which affects how 'group' is interpreted) are documented in description text, not as formal constraints. This creates cognitive load and risks LLM misuse when multiple options interact.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | B | 79 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 54 | - | v1 |
Query records from a database table with optional filtering, field selection, ordering, and pagination. Returns results as JSON. Requires GET permission on the table. Filter syntax (DreamFactory-compatible): - Simple: name = 'John' - Comparison: age > 21, price <= 100 - Logical: status = 'active' AND role = 'admin' - IN: status IN ('active', 'pending') - LIKE: name LIKE 'J%' - NULL: email IS NOT NULL - BETWEEN: age BETWEEN 18 AND 65 - CONTAINS: name CONTAINS 'smith' Order syntax: 'column ASC, other_column DESC'
Execute a raw SQL query against a database service. Only available for services with raw_sql_allowed enabled. Use faucet_list_services to check which services allow raw SQL. Because arbitrary SQL can touch any object, it requires a role rule granting all verbs (GET, POST, PUT, PATCH, DELETE) on the _sql component of the service. The statement is executed as-is and may modify data; it is refused on services flagged read_only. Parameters should be passed as an array and referenced with positional placeholders ($1, $2 for PostgreSQL; ?, ? for MySQL).
Update records in a database table that match a filter expression. The record object contains the column values to set. A filter is required to prevent accidental full-table updates. Requires PATCH permission on the table.
No error recovery guidance. Tools return errors (e.g., permission denied, invalid SQL syntax, record not found) but descriptions do not provide 'what to try next' guidance. For example, faucet_raw_sql says 'it is refused on services flagged read_only' but offers no alternative (query the non-raw_sql tools instead).
faucet_query description includes detailed filter and order syntax examples (LIKE, BETWEEN, IN, CONTAINS, LOGICAL operators) inline. This is helpful for documentation but risks LLMs treating the examples as a complete syntax guide and failing on edge cases (e.g., case sensitivity, quote escaping). Should reference external docs or be more prescriptive.
Parameters accept wide ranges without documented constraints. faucet_query's 'limit' defaults to 25, max 1000, but no minimum is stated. faucet_raw_sql's 'limit' defaults to 100, max 10000, but whether 0 or negative are valid is unclear. Undocumented bounds invite boundary-condition errors.