Rowbase's MCP server lets AI assistants safely explore schemas and run read-only queries against MySQL/MariaDB, PostgreSQL, and SQLite databases (writes only when enabled).
Read the built-in guide for workflow, safety rules, output format, and dialect notes.
List configured connections with driver, environment, and read-only/read-write mode.
List databases and the current database on a connection.
List tables/views with approximate row counts and optional name filtering.
Describe a table: columns, types, nullability, keys, defaults, foreign keys, indexes, and referencing tables.
Search schema for tables/columns whose names or MySQL column comments contain a keyword.
Sample rows from a table with optional WHERE filter, limit, and format.
Count rows of a table with optional WHERE filter.
Run one SQL statement (read-only unless writes enabled) with auto-LIMIT and truncation indicator.
Explain a SELECT execution plan, optionally with ANALYZE for real timings.
Return results as TOON, CSV, JSON, or Markdown; choose database per call.
Connects to MariaDB databases as a supported engine alongside MySQL, providing the same schema exploration and query tools: list databases/tables, describe and search the schema, sample rows, count, execute SQL and EXPLAIN, with optional opt-in writes.
Connects to MySQL databases to browse tables and run queries. Exposes tools for listing databases and tables, describing schemas, searching the schema, sampling and counting rows, running SQL queries, and explaining query plans — plus inline row editing (apply_changes) with SQL preview when writes are explicitly allowed. Connections are read-only by default and can be tunnelled over SSH.
Connects to PostgreSQL databases to explore schemas and query data. Provides tools for listing databases and tables, describing columns and keys, schema search, sampling and counting rows, running SQL queries, and explaining plans; read-only by default with opt-in editing and SSH tunnel support.
Connects to SQLite database files, exposing the same read-only-by-default toolset: browse tables, describe and search the schema, sample and count rows, run SQL queries, view query plans, and optionally apply changes when writes are enabled.
Safe by default. Every connection is read-only until you say otherwise — enforced at four independent layers
(driver-level single statement, SQL guard, READ ONLY transaction, timeouts). Production connections get a red accent.
Made for AI assistants too. A built-in MCP server lets Claude, Cursor, Codex & co. explore your schema and query data — read-only unless you allow writes, with a token-efficient output format (TOON) and a built-in guide so the assistant knows how to use it. One copy-paste prompt sets everything up.
One file, no installer. Download a single binary for macOS, Linux or Windows and run it — no admin rights, no Python, no drivers to install. Or use the native macOS app.
Nice to use. Foreign-key navigation, "referenced by", transpose, column picker, schema-aware autocomplete, EXPLAIN highlighting, query cancel, inline editing with SQL preview, export to CSV/JSON/Markdown/SQL, SSH tunnels.
Open source under Apache-2.0. Passwords live in your OS keychain, never in config files.
SQL editor: autocomplete, ⌘↩ runs the statement under the caret, EXPLAIN, cancel | Edit rows safely: pending changes, SQL preview, one atomic save |
Related MCP server: MySQL MCP Server
Grab the latest from Releases:
Platform | File | How to run |
macOS (native app) |
| open, drag to Applications |
macOS (one file) |
|
|
Linux x64 / arm64 |
|
|
Windows 10 / 11 |
| double-click |
Started without arguments, the one-file app opens the web UI in your browser. Builds are not code-signed yet: macOS → System Settings → Privacy & Security → Open Anyway; Windows → More info → Run anyway.
Open AI / MCP in the app, click Copy prompt, paste it into your assistant — it registers the server, reads the built-in guide and creates a reusable skill. Or register manually:
claude mcp add rowbase -- /path/to/rowbase mcp # one-file binary or app
claude mcp add rowbase -- uvx --from rowbase-db rowbase mcp # straight from PyPI, nothing to downloadListed in the official MCP Registry as io.github.djstreet11/rowbase.
Results come back as compact TOON tables (~40% fewer tokens than JSON):
rows[2]{id,customer,total}:
1,"Smith, Bob",9.50
2,ann,null
truncated: falseTools: guide, connections, databases, tables, describe, search_schema, sample, count, query, explain
(+ apply_changes only when you allow writes). Details: docs/MCP.md.
Install from PyPI (pipx install rowbase-db / uv tool install rowbase-db) or use a one-file download.
rowbase add shop 'postgres://me@db.example.com/shop?ssh=deploy@bastion' # read-only unless --rw
rowbase tables -c shop
rowbase q "SELECT * FROM orders WHERE status = 'new'" -c shop --format json
rowbase ui # web UI on http://127.0.0.1:8765
rowbase mcp # MCP server (stdio)
rowbase doctor # environment reportPython track: python3 -m venv .venv && .venv/bin/pip install -e . && .venv/bin/rowbase ui
One-file binaries: docs/BUILDING.md · Native macOS app: cd native && swift build · releases: docs/RELEASING.md
Architecture & roadmap: SPEC.md
Issues, ideas and pull requests are welcome — see CONTRIBUTING.md and the Code of Conduct. If Rowbase is useful to you, a ⭐ helps others find it.
Apache-2.0 — see NOTICE and THIRD_PARTY_LICENSES.md.
List the user's saved database connections exposed to MCP. Call this first to get the exact connection names every other tool requires. Returns a table connections[N]{name,driver,env,mode,database,tunnel} — mode is the EFFECTIVE read-only/read-write mode for MCP; env 'prod' means be extra careful — plus writes_enabled_in_mcp. No pagination: all exposed connections are returned.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: the returned 'mode' is the EFFECTIVE MCP read-only/read-write mode, 'prod' env warrants extra care, plus a writes_enabled_in_mcp flag and an explicit no-pagination guarantee. It stops short of stating auth requirements or how often the list can change, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences with no filler: purpose, usage ordering, then return shape and caveats. The inline table schema is dense but each element (mode semantics, prod warning, no pagination) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of describing returns and does so (fields, effective mode, writes_enabled_in_mcp, no pagination). An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document beyond the schema; the description correctly spends no space on parameters and instead explains the shape of what comes back.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the user's saved database connections exposed to MCP') and scopes it to what MCP exposes, which cleanly separates it from data-inspection siblings like databases/tables/query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call this first to get the exact connection names every other tool requires' gives explicit ordering guidance and the reason to prefer this tool over guessing names elsewhere. That is actionable when-to-use routing, not implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the exact number of rows in a table, optionally filtered — use it to size a result before fetching it or to answer 'how many' questions. Use query instead for grouped counts (GROUP BY) or counts over joins. Returns a single line: count: N. May be slow on very large unindexed filters (timeout from settings). On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table. | |
| where | No | Optional SQL boolean expression WITHOUT the WHERE keyword, e.g. status = 'paid' AND total > 100. | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes further by disclosing the return format ('count: N'), a performance caveat about slow large unindexed filters with possible timeouts, and the failure contract (isError with 'error: <reason>' plus example reasons). That is genuine behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core purpose front-loaded, followed by the sibling disambiguation and then behavioral caveats. No filler and nothing repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description compensates by stating the exact return shape and the error shape, plus a performance caveat. For a read-only count tool, an agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the schema, including the WHERE-without-keyword convention and schema.table notation. The description adds no per-parameter syntax or default semantics beyond what the schema supplies, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the exact number of rows in a table, optionally filtered') with an explicit scope qualifier, and names the sibling `query` as the alternative for grouped/joined counts. An agent can distinguish it from every sibling without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete use cases (sizing a result before fetching, answering 'how many' questions) and an explicit exclusion routing to `query` for GROUP BY or joins. The when-to-use and when-not-to-use are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the databases on a connection's server and which one is current. Use it when a connection has no database selected, or to work in another database (pass database to later calls); to list tables inside a database use tables instead. Returns current, databases[N] (user databases first) and system[N]. SQLite returns an empty list (one file = one database). On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral detail: the return shape (current, databases[N] user-first, system[N]), the SQLite edge case returning an empty list, and the failure contract (isError with 'error: <reason>'). That is exactly the beyond-annotations context the agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with purpose, then routing, then return shape, then error contract. Every sentence carries information an agent needs; no padding or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description supplies the return structure and error behavior itself, so an agent knows what it will get back and how failure surfaces. Combined with the explicit sibling routing, nothing material is missing for a one-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole `connection` parameter is fully documented in the schema, so the baseline is 3. The description does add a downstream usage hint ('pass `database` to later calls'), but that concerns how to use the results rather than clarifying the parameter itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ('List the databases on a connection's server') plus the extra dimension of which one is current. It explicitly separates itself from the sibling `tables` by naming what that sibling does instead, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit trigger conditions ('when a connection has no database selected, or to work in another database') and names the alternative tool (`tables`) with the condition that selects it. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the structure of one known table: columns with type, nullability, key, default, foreign-key target (fk = table.column — use it to write JOINs) and comment, plus indexes and the tables that reference it. Use it before writing SQL against a table; use search_schema if you don't know the table name yet. Returns table, sql_name (properly quoted name for SQL), columns[N]{name,type,nullable,key,default,fk,comment}, indexes[N]{name,unique,columns} and referenced_by[N]{table,column,ref_column}. On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table. | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read/idempotent profile, and the description goes further by disclosing the failure contract (isError with 'error: <reason>', e.g. refused statement, unknown table) and the meaning of the fk field for JOIN authoring — behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose, then usage, then return shape, then error semantics — every sentence carries information. It is dense and the return-shape clause is long, but nothing is redundant enough to cut.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the return-value burden itself by spelling out the payload fields, and it also covers the error path. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents table/database/connection (including the schema.table and default-connection conventions). The description only lightly reinforces this via 'one known table'; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Show the structure of one known table') and enumerates exactly what is returned (columns, indexes, referenced_by), which lets an agent distinguish it from search_schema and tables without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('Use it before writing SQL against a table') and names the alternative plus its selecting condition ('use search_schema if you don't know the table name yet'), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show how the database will execute a SELECT (its query plan) to diagnose slow queries or check index use — use it instead of query when the question is about performance, not data. With analyze=true the statement is actually executed to report real timings (can be slow on big tables). Returns the plan as rows plus a hint: MySQL type=ALL or PostgreSQL 'Seq Scan' means a full table scan (consider an index or a narrower WHERE). SQLite uses EXPLAIN QUERY PLAN. On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SELECT statement to analyze (without EXPLAIN). | |
| analyze | No | true = execute the statement to measure real timings and row counts (EXPLAIN ANALYZE); default false = estimate only, nothing is executed. | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only/idempotent, and the description adds traits they cannot convey: that analyze=true actually executes the statement with real timings and can be slow on large tables, what the output rows mean (type=ALL / Seq Scan = full table scan), DB-specific plan dialect, and the failure shape ('isError with error: <reason>'). It also resolves the tension an agent might feel between readOnlyHint and 'the statement is actually executed' by making clear the input is a SELECT.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose and the sibling alternative in the first clause, then layers the analyze caveat and error contract. Dense but every sentence carries information; the per-dialect plan-hint sentence is the only part that leans toward verbosity, though it is genuinely useful for interpretation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing the return shape (plan as rows plus a hint), how to interpret it, and the error format. Combined with 100% schema coverage and clear annotations, an agent has everything needed to call and read this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning for `analyze` beyond the schema (executes the statement, real timings vs estimate, performance cost) and explains how to read the returned plan. The other two params (connection, database) get no added detail, but the schema already documents them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Show how the database will execute a SELECT (its query plan)') plus the diagnostic purpose, and explicitly contrasts itself with the sibling `query` tool. An agent can distinguish it from `query`/`sample`/`count` without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit routing rule: 'use it instead of `query` when the question is about performance, not data.' It also states when the costly mode applies ('analyze=true ... can be slow on big tables'), covering both selection and a cost caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read this first, once per session: the Rowbase knowledge base — recommended workflow, safety rules (read-only model, one statement per call), the TOON output format and SQL dialect notes. Use it before any other tool; it needs no connection. Returns a markdown document.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered structurally. The description adds genuine operational context beyond that: the document is a markdown return, requires no connection, and it previews the platform's read-only model and one-statement-per-call rule. Return format and connection requirement are the key value-adds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence with the imperative 'Read this first' front-loaded, followed by a compact parenthetical inventory. Every clause carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description compensates by stating the return type ('Returns a markdown document'), and it discloses the guide's contents and the no-connection prerequisite. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so there is nothing to disambiguate; baseline is 4. The description correctly signals this by noting it 'needs no connection', reinforcing that the call is argument-free.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action and resource: read the Rowbase knowledge base document, with an enumerated inventory of what it contains (workflow, safety rules, TOON format, SQL dialect notes). This is unmistakably distinct from every sibling, which are all data-access tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit timing is given twice ('Read this first', 'Use it before any other tool') plus a frequency constraint ('once per session') and a prerequisite note ('needs no connection'). An agent knows exactly when to call it and that all other tools follow it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run exactly ONE SQL statement — the general tool for answering questions: specific columns, JOINs (follow fk from describe), filters, sorting, GROUP BY. Read-only connections accept only SELECT/SHOW/DESCRIBE/EXPLAIN/WITH/VALUES/TABLE (+PRAGMA on SQLite); multiple statements are refused. Prefer sample/count for simple peeks and totals, explain for performance. A LIMIT is added automatically when missing. Returns rows[N]{columns} plus rows, truncated (true = more rows exist — narrow with WHERE or raise limit) and ms; write statements (only if writes are enabled) return affected instead. On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | A single SQL statement in the connection's dialect, without a trailing ';' chain. | |
| limit | No | Max rows (default 100; capped by settings, usually 200). | |
| format | No | Result format. Default from settings: toon (compact table: rows[N]{cols}: then one line per row). | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint/idempotentHint/destructiveHint, the description still adds substantial non-obvious behavior: accepted statement whitelist, multi-statement refusal, automatic LIMIT insertion, truncation flag semantics with remediation ('narrow with WHERE or raise limit'), latency field, and the error envelope ('isError with error: <reason>'). The only blemish is the clause that write statements 'return affected' when writes are enabled, which sits in mild tension with readOnlyHint=true and destructiveHint=false as a static contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the tool's role, then layered with constraints, alternatives, return shape, and failure mode in a logical order. Every clause carries information, though the single dense block is long enough that it edges past optimal brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the return contract itself — and it does: rows[N]{columns} plus rows, the truncated flag and its meaning, ms, affected for writes, and the isError/'error: <reason>' failure format with examples. Combined with the statement whitelist and LIMIT behavior, nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already carries most parameter meaning. The description genuinely adds on top: the SQL must be 'in the connection's dialect' without a trailing ';' chain, the `limit` parameter is auto-filled when absent, and the `limit`/truncation interaction is spelled out. That is real semantic value beyond the property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run exactly ONE SQL statement') and immediately positions itself as 'the general tool for answering questions'. It names the sibling tools it should not be confused with (`sample`/`count` for peeks and totals, `explain` for performance), so an agent can route correctly without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use and when-to-use-something-else: prefer `sample`/`count` for simple peeks and totals, `explain` for performance. It also states the hard constraint (exactly one statement; multiple are refused) and what the read-only connection accepts, which is exactly the decision context an agent needs before choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Peek at a few real rows of one table (SELECT * … LIMIT n, in storage order, no sorting) to see what the data looks like before writing a query. Use query instead for specific columns, joins, sorting or aggregates, and count when you only need a number. Returns rows[N]{all columns} plus rows, truncated (true = more rows exist) and ms. Default 20 rows, capped by the server's max rows setting. On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return (default 20; capped by settings, usually 200). | |
| table | Yes | Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table. | |
| where | No | Optional SQL boolean expression WITHOUT the WHERE keyword, e.g. status = 'paid' AND total > 100. | |
| format | No | Result format. Default from settings: toon (compact table: rows[N]{cols}: then one line per row). | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: unsorted storage-order results, a default of 20 rows capped by the server's max-rows setting, truncation signalling, and the exact failure shape ('isError with error: <reason>', listing refused statement/unknown table/SQL error). It does not cover auth or permission requirements, but for a read-only peek tool that is a minor omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with purpose then alternatives, then return shape, then failure mode. Every sentence carries distinct information with no restatement of the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the return payload (rows[N]{all columns}, rows, truncated flag, ms) and the error contract. For a 6-parameter read tool, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, table, where, format, database and connection are all documented in the schema itself. The description's 'in storage order, no sorting' implicitly clarifies what `where`/`limit` do and don't control, but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource ('Peek at a few real rows of one table') and immediately pins down the exact mechanics (SELECT * ... LIMIT n, storage order, no sorting). An agent can distinguish this from query/count/describe without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes alternatives: 'Use `query` instead for specific columns, joins, sorting or aggregates, and `count` when you only need a number.' Both the when-to-use and the when-not-to-use conditions are named with the sibling that satisfies each.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find tables and columns whose name contains a keyword (case-insensitive substring; on MySQL also column comments). Use it when you know WHAT you are looking for but not WHERE it is stored; use tables instead to browse everything and describe for one known table. Returns matches[N]{table,column,type}, one row per matching column (a table-name match lists all its columns), capped at 500 rows (truncated: true when cut). On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Keyword to look for, e.g. invoice, email, price. | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial extra context: the return shape (matches[N]{table,column,type}), the row-per-column behavior including table-name matches listing all columns, the 500-row cap with a truncation flag, and the error contract ('error: <reason>'). This goes well beyond the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: purpose and routing come first, then return shape, then the error contract. Every clause carries information, and nothing is redundant with the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully specifies the return format, truncation behavior, and failure mode. Combined with complete schema coverage and annotations, an agent has everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics for `text` (case-insensitive substring match, and column comments on MySQL) that meaningfully augment the schema. It does not re-explain the `connection` or `database` parameters, which is acceptable given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (tables and columns) with precise matching semantics. It clearly distinguishes itself from siblings by noting it is for finding something when you know the name but not the location, as opposed to browsing (`tables`) or inspecting a known table (`describe`).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('when you know WHAT you are looking for but not WHERE it is stored') and names the alternatives for the adjacent cases: `tables` for browsing everything and `describe` for one known table. Routing is fully inference-free.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tables and views of a connection/database with approximate row counts — the entry point for browsing. Use search_schema instead when you look for a concept (e.g. 'invoice') across table AND column names, and describe once you know the table. Returns tables[N]{name,kind,approx_rows} (kind = table|view; approx_rows is an estimate, may be null; use count for exact numbers). Returns every match, no pagination. On failure returns isError with 'error: ' (e.g. refused statement, unknown table, SQL error).
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional case-insensitive substring of the table name, e.g. order. | |
| database | No | Optional database to use instead of the connection's default (names from `databases`). Omit to use the default. | |
| connection | Yes | Connection name exactly as returned by `connections` (e.g. "shop"). Unknown or unexposed names return an error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds real behavioral context: it returns every match with no pagination, approx_rows may be an estimate or null, and failures surface as isError with an 'error: <reason>' payload including example causes. The only omission is nothing meaningful given the listed traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and tightly packed with routing guidance, return shape, and error behavior in three sentences. The 'with approximate row counts' clause is slightly restated in the return-shape sentence, a minor redundancy, but overall every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of describing the return shape (tables[N]{name,kind,approx_rows}, kind=table|view, nullable estimates), exhaustiveness, and the error contract. Nothing an agent needs to call this correctly or interpret results is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all three parameters are already documented in the schema (filter semantics, database defaulting, connection naming). The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all tables and views of a connection/database with approximate row counts') and frames itself as 'the entry point for browsing', which immediately situates it among siblings. It explicitly contrasts itself with search_schema and describe, so an agent can distinguish it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing rules: use this for browsing, use `search_schema` when hunting a concept across table AND column names, use `describe` once the table is known, and use `count` for exact numbers. Both when-to-use and when-not-to-use are named with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.2count4 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / table / descriptionPrevious value: -"Table name"New value: +"Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table."Input schema / properties / where / descriptionPrevious value: -"SQL boolean expression without WHERE"New value: +"Optional SQL boolean expression WITHOUT the WHERE keyword, e.g. status = 'paid' AND total > 100."databases1 field changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."describe3 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / table / descriptionPrevious value: -"Table name (PostgreSQL: schema.table outside public)"New value: +"Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table."explain4 fields changedInput schema / properties / analyze / descriptionAdded value: +"true = execute the statement to measure real timings and row counts (EXPLAIN ANALYZE); default false = estimate only, nothing is executed."Input schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / sql / descriptionPrevious value: -"SELECT statement"New value: +"The SELECT statement to analyze (without EXPLAIN)."query6 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / format / descriptionPrevious value: -"Result format (default from settings: toon)"New value: +"Result format. Default from settings: toon (compact table: rows[N]{cols}: then one line per row)."Input schema / properties / limit / descriptionPrevious value: -"Max rows (default 100, capped by settings)"New value: +"Max rows (default 100; capped by settings, usually 200)."Input schema / properties / limit / minimumAdded value: +1Input schema / properties / sql / descriptionPrevious value: -"A single SQL statement"New value: +"A single SQL statement in the connection's dialect, without a trailing ';' chain."sample7 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / format / descriptionPrevious value: -"Result format (default from settings: toon)"New value: +"Result format. Default from settings: toon (compact table: rows[N]{cols}: then one line per row)."Input schema / properties / limit / descriptionPrevious value: -"Rows (default 20)"New value: +"Rows to return (default 20; capped by settings, usually 200)."Input schema / properties / limit / minimumAdded value: +1Input schema / properties / table / descriptionPrevious value: -"Table name"New value: +"Table or view name as returned by `tables`. PostgreSQL tables outside `public` are written schema.table."Input schema / properties / where / descriptionPrevious value: -"SQL boolean expression without WHERE"New value: +"Optional SQL boolean expression WITHOUT the WHERE keyword, e.g. status = 'paid' AND total > 100."search_schema3 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / text / descriptionPrevious value: -"Keyword, e.g. invoice"New value: +"Keyword to look for, e.g. invoice, email, price."tables3 fields changedInput schema / properties / connection / descriptionPrevious value: -"Connection name (from `connections`)"New value: +"Connection name exactly as returned by `connections` (e.g. \"shop\"). Unknown or unexposed names return an error."Input schema / properties / database / descriptionPrevious value: -"Database name to use instead of the connection's default (optional)"New value: +"Optional database to use instead of the connection's default (names from `databases`). Omit to use the default."Input schema / properties / filter / descriptionPrevious value: -"Case-insensitive substring of the table name"New value: +"Optional case-insensitive substring of the table name, e.g. order."v0.1.0connectionscountdatabasesdescribeexplainguidequerysamplesearch_schematablesScored across 10 tools
Each tool targets a distinct stage of database exploration or querying, and descriptions explicitly state when to use one over another (e.g., sample vs query, count vs query, explain vs query). The only overlap is that query can technically perform many tasks, but the guidance makes boundaries clear.
Names mix plural nouns (connections, databases, tables), verbs (describe, sample, count, query, explain), and one snake_case verb_noun (search_schema). While readable, there is no consistent pattern, so agents cannot rely on naming alone to infer tool type.
Ten tools is well-scoped for a database MCP, covering connection discovery, schema browsing, data sampling, counting, querying, and performance analysis. Each tool has a clear role, and no tool feels superfluous.
The surface covers the full read-only query lifecycle from connections and databases to tables, schema search, sampling, counting, querying, and explain plans. Writes are possible via query when enabled, and no major operations for the stated domain are missing.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
