dbecho gives AI agents read-only access to PostgreSQL databases, enabling natural language analytics and data exploration. Key capabilities include:
List & Discover Databases: View all configured databases with descriptions, table counts, total rows, largest tables, and sizes.
Health Check: Verify connectivity, PostgreSQL version, and database size for all configured databases.
Schema Exploration: Retrieve full schemas (tables, columns, types, primary keys, row counts, sizes), deep-dive into a single table, or generate text-based entity-relationship diagrams (ERDs).
Read-Only SQL Execution: Run SELECT, WITH, EXPLAIN, and SHOW queries with offset paging and JSON output — writes are blocked at the database level.
Query Planning: Get execution plans with estimated cost and row counts before running a query.
Table Profiling: Analyze null rates, cardinality, value distributions, min/max/avg for numeric columns, and top values for low-cardinality columns.
Time-Series Trending: Group data by day, week, month, quarter, or year to analyze counts, averages, and totals over time.
Data Quality Auditing: Detect high null rates, single-value columns, numeric outliers, future dates, and potential duplicates.
Cross-Database Comparison: Run the same SQL query across multiple databases simultaneously and view results side by side.
Row Sampling: Preview rows from any table to understand data format.
MCP Resources & Prompts: Expose schema and summary as MCP resources, plus guided prompts for database exploration, cross-database comparison, and data quality audits.
It operates as a lightweight Python package with no containers or web UI required, and ensures safety via query whitelisting, SQL injection prevention, query timeouts, row limits, and sensitive column redaction.
Provides read-only access to PostgreSQL databases, enabling AI agents to explore schemas, run SQL queries, analyze tables, detect anomalies, and generate insights across multiple databases.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@dbecho How are sales trending this quarter?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Talk to your PostgreSQL databases through AI. No dashboards, no BI tools, just questions and answers.
dbecho is an MCP server that gives AI agents (Claude Code, Cursor, Windsurf, or any MCP client) direct read-only access to your PostgreSQL databases. Point it at your databases, ask questions in plain language, get instant analytics.
You: What are my most popular blog posts and why?
Claude: [runs schema → query → analyze → trend across 29 tables]
Here's what the data shows...14 tools that cover the full analytics workflow:
Tool | Purpose |
| Show all connected databases |
| Check connectivity, PostgreSQL version, database size |
| Full schema: tables, columns, types, PKs, row counts, sizes |
| One table in depth: columns, PK, indexes, size — cheaper than |
| Locate tables and columns by name substring, across all databases at once |
| Run read-only SQL (SELECT, WITH, EXPLAIN, SHOW), with offset paging and JSON output |
| Query plan with estimated cost/rows — judge a query before running it |
| Profile a table: nulls, cardinality, distributions, top values |
| Same query across multiple databases, side by side |
| Overview: table counts, total rows, largest tables |
| Time-series: counts/averages grouped by day/week/month/year, with JSON output |
| Data quality: high nulls, outliers, duplicates, future dates |
| Preview rows from any table |
| Entity-relationship diagram: PKs and foreign keys |
Plus 3 MCP Resources (schema/summary per database) and 3 MCP Prompts (guided exploration, cross-database comparison, data quality audit).
Partitioned tables are reported as the parent, not as a pile of children:
schema, find, summary and erd hide partition children and mark the parent
[partitioned], with row estimates and size summed across the whole partition
tree (a parent stores nothing itself, so the raw catalog would show the biggest
table in the database as empty). Query the parent and let PostgreSQL prune;
describe <child> still works if you name a partition explicitly.
Related MCP server: MCP PostgreSQL
The problem: You have PostgreSQL databases across projects. Getting answers means context-switching to psql, pgAdmin, or a BI tool, writing SQL, formatting results, then bringing insights back to your conversation.
The fix: dbecho stays inside your AI agent's workflow. The agent explores schema, writes SQL, cross-references tables, and builds analysis without you leaving the conversation. One config file, zero context switches.
What makes it different from just giving an agent a connection string:
Multi-database. Connect 1 or 20 databases. Compare across them with one tool call.
Safe by default. Read-only connections, query timeouts, row limits, SQL injection prevention. You can't accidentally DROP TABLE.
Agent-optimized output. Schema, stats, and query results are formatted so LLMs parse them efficiently, not as raw psql dumps.
Zero infrastructure. No containers, no web UI, no background processes. A Python package that speaks MCP over stdio.
You: Show me what's in the database
Claude: [calls list_databases → schema → summary]
Database: ecommerce (12 tables, 847 MB)
Largest: orders (2.1M rows), products (45K rows), users (128K rows)
You: How are sales trending this quarter?
Claude: [calls trend on orders table, grouped by week]
Week | orders | total_revenue
2026-01-06 | 3,241 | $482,100
2026-01-13 | 3,892 | $571,340
2026-01-20 | 2,107 | $298,500 ← 46% drop
...
Significant drop in week of Jan 20. Let me check what happened.
[calls query to investigate, then anomalies on orders table]
Found: 89% of orders that week have status='cancelled'.
The cancellation spike correlates with a payment gateway outage
(payments table shows 0 successful transactions Jan 19-21).
You: Any data quality issues I should worry about?
Claude: [calls anomalies on each table]
Found 4 issues:
- users.email: 342 possible duplicates
- orders.shipped_at: 127 dates in the future
- products.price: 23 outliers (IQR: $5..$89, found items at $0 and $9,999)
- events.user_id: 94.2% NULL (missing user attribution)One conversation, zero context switches. The agent picks the right tools automatically.
pip install dbechoOr from source:
git clone https://github.com/ginkida/dbecho.git
cd dbecho
pip install .Requires Python 3.10+ and PostgreSQL 12 or newer.
Create dbecho.toml in your project directory:
[databases.myapp]
url = "postgres://user:pass@localhost:5432/myapp"
description = "Main application"
[databases.analytics]
url = "postgres://user:pass@localhost:5432/analytics"
description = "Analytics warehouse"
[settings]
row_limit = 500 # max rows returned per query (default: 500)
query_timeout = 30 # seconds before query is killed (default: 30)
max_profile_rows = 5000000 # refuse analyze/anomalies above this row count
redact_sensitive = true # redact password/token/secret-like columns in outputEnvironment variables work with ${VAR} syntax:
[databases.production]
url = "${DATABASE_URL}"
description = "Production (read replica)"If an app keeps its tables outside public, set schema (default "public",
lowercase identifier). All metadata tools (schema, describe, analyze, ...)
target it, and it leads search_path so raw queries can use unqualified table
names:
[databases.events]
url = "${EVENTS_DATABASE_URL}"
schema = "analytics"Verify the config and connectivity before wiring up your MCP client:
dbecho --check # validate config + ping every database
dbecho --version # print "dbecho <version>"
dbecho --help # usage and flags--check prints a [OK]/[FAIL] <name>: … line per database and exits 0 only
when every database responds (non-zero otherwise), so it drops straight into a
CI or healthcheck script.
Exit codes: 0 success, 1 config or startup failure (also a failed --check),
2 usage error. Unrecognised arguments are rejected rather than ignored, so a
typo like --verison never starts a server that quietly did nothing.
Claude Code (project-level, recommended):
Create .mcp.json in your project root:
{
"mcpServers": {
"dbecho": {
"command": "dbecho",
"args": ["--config", "/path/to/dbecho.toml"]
}
}
}Claude Code (global):
Add to ~/.claude.json:
{
"mcpServers": {
"dbecho": {
"command": "dbecho"
}
}
}When no --config is passed, dbecho searches for config in:
./dbecho.toml (current directory)
~/.config/dbecho/config.toml
~/.dbecho.toml
Other MCP clients (Cursor, Windsurf, etc.): use the same command/args in your client's MCP server configuration.
Show me a summary of all my databases
How many users signed up each month this year?
Compare order counts between staging and production
Find data quality issues in the events table
What's the relationship between users, orders, and products?
Which columns have the most nulls?
Show me the trend of daily revenue for the last 90 daysThe agent picks the right tools automatically. You don't need to know the tool names.
dbecho is designed to be safe to point at any database, including production:
Read-only connections. Every connection sets default_transaction_read_only=on at the PostgreSQL level. Even if someone crafts malicious SQL, the database rejects writes.
Query whitelist. Only SELECT, WITH, EXPLAIN, and SHOW statements are allowed — and the validator independently rejects data-modifying CTEs (WITH x AS (DELETE ...) SELECT ...), SELECT INTO, and EXPLAIN ANALYZE over write statements, so it doesn't rely on the read-only connection alone.
Blocked functions. Filesystem, large-object, dblink, and set_config functions are rejected even though the transaction is read-only — they are exfiltration/escape vectors.
SQL injection prevention. All table/column identifiers use psycopg.sql.Identifier() parameterization. User input is validated against ^[a-zA-Z_][a-zA-Z0-9_]*\Z (\Z, not $, so a trailing newline can't sneak past). The one identifier-shaped value placed outside Identifier() is the per-database schema config option — it is embedded in the connection's search_path — and it is validated against the same shape (lowercase-only) at config load, before any connection exists.
Query timeout. Default 30 seconds, enforced as one shared budget across multi-query tools via statement_timeout, with session-level timeout backstops on every connection.
Row limit. Default 500 rows per query. Prevents the agent from pulling entire tables into context. Full-table profiling (analyze/anomalies) additionally refuses tables above max_profile_rows — exact stats over 50M rows cannot be made cheap, so that one is a refusal, and the message names the setting that raises it.
Column cap. analyze/anomalies probe at most 80 columns (each costs its own queries). A wider table is profiled partially rather than refused, and the result always states how many columns were skipped and names them — a partial profile that looks complete would be worse than an error.
Sensitive-column redaction. Values of columns that look like secrets (password, token, api_key, secret, ...) are replaced with <redacted> in query/sample/analyze output (default on; redact_sensitive = false to disable). This is name-based harm reduction, not a hermetic control — query is an open read channel by design.
Sanitized errors. Connection failures are reported to the agent as coarse categories (authentication failed, connection refused, ...); full details go to the server log only, so hostnames/usernames never leak into the conversation.
Local only. No network calls, no telemetry, no cloud. Data stays on your machine.
For production databases, the strongest setup is still a least-privilege role: a PostgreSQL user with SELECT only on the tables/views you want exposed. dbecho's layers protect against accidents and prompt-injected agents; the database's own grants are the final word.
src/dbecho/
config.py TOML config loading, env var expansion, validation
db.py DatabaseManager: connections, SQL validation, schema, queries, stats, trends, anomalies
server.py FastMCP server: 14 tools, 3 resources, 3 prompts~2700 lines of Python total. No framework beyond mcp and psycopg.
git clone https://github.com/ginkida/dbecho.git
cd dbecho
pip install -e ".[dev]"
pytest -vTests are fully mocked, no PostgreSQL instance needed. CI runs on Python 3.10-3.13.
coverage run --branch -m pytest -q
coverage report --show-missing --include='src/*'Because the suite never touches a server, catalog-level SQL (partition trees,
pg_stat_user_tables joins, index introspection) should be checked by hand
against a throwaway instance before it lands — e.g.
docker run --rm -d -e POSTGRES_HOST_AUTH_METHOD=trust -p 55434:5432 postgres:16,
then point a scratch dbecho.toml at it. Mocks pin the plumbing; only a real
server tells you the query is right.
MIT
Profile a table: row count, column types, null percentages, distinct values, min/max/avg for numeric columns, top values for low-cardinality text columns.
Args: database: Name of the database from config. table: Name of the table to analyze.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | ||
| table | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the tool is read-only, its performance impact (e.g., full table scan), required permissions, or any side effects. The output list is given but behavioral traits are absent.
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?
The description is short (two sentences plus an Args block) and efficiently conveys the tool's purpose. However, the Args section is minimally formatted and could be more streamlined. Overall, every sentence adds value.
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?
Given the tool's complexity and the presence of an output schema, the description covers core functionality and arguments. However, it lacks context about when to use this tool versus siblings, potential performance implications, and any prerequisites, leaving important gaps for an AI agent.
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?
With 0% schema description coverage, the description must compensate but only adds trivial context: 'Name of the database from config' and 'Name of the table to analyze'. This does not provide format, constraints, examples, or validation beyond the schema's bare titles.
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?
The description clearly states the tool profiles a table with a detailed list of statistics (row count, column types, null percentages, etc.), which is a specific verb+resource combination. It distinguishes from sibling tools like 'schema' (column definition only) or 'summary' (possibly different aggregation).
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?
The description implies usage when profiling a table is needed but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings. The user must infer context from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find data quality issues in a table: high null rates, single-value columns, numeric outliers, future dates, possible duplicates.
Args: database: Name of the database from config. table: Name of the table to check.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | ||
| table | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full weight. It describes what anomalies are detected but does not explicitly state that the tool is read-only, nor does it mention permissions, rate limits, or side effects.
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?
The description is a single focused sentence followed by a concise Args list. Every word adds value, and the purpose is front-loaded with no unnecessary information.
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?
Given the low complexity (2 params) and existence of an output schema to explain return values, the description covers the main purpose and arguments. However, it could briefly mention that the tool is non-destructive.
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 0%, but the description adds meaningful context for both parameters: 'Name of the database from config' and 'Name of the table to check', which goes beyond the schema's title and type.
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?
The description clearly states 'Find data quality issues in a table' with a specific verb and resource, and lists concrete examples like high null rates, single-value columns, etc., which distinguishes it from sibling tools like analyze or 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?
The description implies usage for data quality checks but provides no explicit guidance on when to use this tool versus alternatives like analyze or sample, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the same SQL query across multiple databases and compare results side by side.
Args: sql: SQL query to execute on each database (must be SELECT). databases: List of database names to compare. If omitted, runs on all databases.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| databases | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds critical context beyond the schema: the SQL must be SELECT. It also implies the comparison is side-by-side. Missing details on error handling or result format, but output schema likely covers returns.
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?
The description is short and front-loaded with the main purpose. The Args format is not typical JSON but still clear. Every sentence adds value. Could be slightly more formal but overall concise.
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?
Given the tool's complexity (comparison across databases) and presence of an output schema, the description covers the essential behavior: it runs a SELECT query and compares results. It does not detail output structure, but the output schema handles that.
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 0%, so the description must explain parameters. It does so thoroughly: 'sql' is a SELECT query, 'databases' is an optional list (default all). This adds significant meaning beyond the schema's type-only definitions.
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?
The description clearly states the action: 'Run the same SQL query across multiple databases and compare results side by side.' It uses a specific verb ('Run', 'compare') and resource ('SQL query', 'databases'), and distinguishes from siblings like 'query' (single database) and 'analyze' (analysis).
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?
The description explains when to use the tool (to compare across databases) and notes that omitting 'databases' runs on all databases. However, it does not explicitly state when not to use it (e.g., for single-database queries, use 'query'), though this is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show entity-relationship diagram as text: tables, primary keys, and foreign key relationships.
Args: database: Name of the database from config.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully inform about behavioral traits. It only states 'Show', implying a read operation, but does not disclose potential side effects, permissions, or safety guarantees.
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?
The description is extremely concise, consisting of two short sentences that convey the purpose and parameter. Every sentence adds value, with no redundant information.
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?
Given the presence of an output schema, the description does not need to detail return values. It covers the tool's core function and parameter. However, missing usage guidelines and behavioral transparency means completeness is only moderate for a tool with a single parameter.
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 schema coverage is 0% for the single parameter 'database'. The description adds meaning by stating it is 'Name of the database from config', which goes beyond the schema's minimal title. However, it lacks clarity on what config refers to and any format constraints.
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?
The description clearly states the tool shows an entity-relationship diagram as text, listing tables, primary keys, and foreign key relationships. The verb 'Show' and specific resource 'entity-relationship diagram' provide a clear purpose, though it does not explicitly differentiate from siblings like 'schema' or 'summary'.
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?
No guidance on when to use this tool versus alternatives (e.g., 'schema' or 'summary') is provided. The description lacks any context about prerequisites or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check connectivity and basic info for all configured databases.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It states 'check connectivity and basic info', which implies a read-only operation. No additional behavioral details are given, but the simplicity of the tool means this is adequate.
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?
The description is a single concise sentence with no extraneous information, perfectly front-loaded.
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?
Given zero parameters and an output schema exists, the description fully covers what the tool does. No additional details are necessary for a simple health check tool in this context.
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 input schema has zero parameters, so schema description coverage is trivially 100%. No parameter info is needed, so baseline for zero parameters is 4.
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?
The description clearly states it checks connectivity and basic info for all configured databases, using a specific verb and resource. It distinguishes from sibling tools like query, analyze, etc., which are for data operations rather than connectivity checks.
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?
Usage context is implied as a health check, but no explicit guidance on when to use this versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured PostgreSQL databases with their descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only operation but does not explicitly state that it is non-destructive or requires no special permissions. For a simple list operation, the disclosure is adequate but lacks detail.
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?
The description is a single sentence with no unnecessary words. It is perfectly concise and front-loaded with the verb and resource.
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?
Given the tool has no parameters and an output schema exists, the description is complete enough. It states what is listed (databases and descriptions). A slight improvement could mention ordering or scope, but it is adequate for a simple list 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?
There are no parameters, and schema description coverage is 100% (trivially). The description adds no parameter information, but the baseline is 3 when coverage is high.
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?
The description clearly states 'List all configured PostgreSQL databases with their descriptions.' It uses a specific verb ('List') and resource ('databases'), and distinguishes from sibling tools that focus on analysis, queries, or schema details.
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?
The description does not provide explicit guidance on when to use this tool versus alternatives. The context of listing all databases is implied, but no usage conditions, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only SQL query on a database and return results as a formatted table.
Only SELECT, WITH, EXPLAIN, and SHOW queries are allowed.
Args: database: Name of the database from config. sql: SQL query to execute (read-only).
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | ||
| sql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses read-only nature and allowed statements, but lacks details on error handling, timeouts, authentication requirements, or response pagination.
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?
The description is succinct with three clear sentences plus parameter breakdown. Purpose is front-loaded, and every word adds value without repetition or fluff.
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?
Given the simple input schema and presence of an output schema, the description covers essential behavioral and usage aspects. It could mention error scenarios or result limits, but overall is sufficient for an agent to understand the tool's function.
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 0%, but the description includes an Args section that explains both parameters (database from config, sql is read-only query), adding necessary context beyond the schema's type information.
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?
The description clearly states the tool executes a read-only SQL query and returns formatted tables. It specifies allowed statement types (SELECT, WITH, EXPLAIN, SHOW), distinguishing it from siblings like analyze or schema which provide predefined analyses.
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?
The description indicates when to use (raw SQL queries) and the read-only restriction, but does not provide guidance on when not to use it or how it compares to siblings like list_databases or sample for specific data exploration needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show sample rows from a table to understand the data format.
Args: database: Name of the database from config. table: Name of the table. limit: Number of rows to return (default 5, max 50).
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | ||
| table | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies read-only operation but does not explicitly state non-destructive nature or other behavioral traits like rate limits or auth needs. Some context on limit is provided.
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?
The description is concise, one paragraph with an args list. Front-loaded with main purpose, no unnecessary words.
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?
Given output schema exists, description is fairly complete: explains purpose, parameter constraints. Missing mention of how rows are selected (random/first) but adequate for a simple 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 0%, so description must compensate. It adds meaning for 'limit' (default 5, max 50) but only names 'database' and 'table' without further explanation. Partial compensation, not fully detailed.
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?
The description clearly states the tool shows sample rows from a table to understand data format, using specific verb 'show' and resource 'sample rows'. It distinguishes from siblings like 'query' or 'summary'.
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?
The description implies usage for understanding data format but does not explicitly state when to use this tool versus alternatives like query, schema, or summary. No exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full schema of a database: tables, columns, types, primary keys, row counts, and sizes.
Args: database: Name of the database from config (use list_databases to see available).
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It correctly indicates a read operation ('Get') with no destructive hints. However, it does not mention any potential size limits, performance impacts, or authentication requirements.
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?
The description is two sentences long, with the purpose stated upfront. Every sentence adds value: the first specifies what the tool returns, the second explains the parameter usage. No unnecessary words.
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?
The description specifies the return content (tables, columns, types, primary keys, row counts, sizes) without needing to duplicate an output schema. It also references a sibling tool (list_databases) for prerequisite info. Given the tool's complexity, this is fully adequate.
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?
Although the input schema itself has no parameter description (coverage 0%), the tool description explicitly documents the parameter: 'database: Name of the database from config (use list_databases to see available).' This adds meaning beyond the schema's type-only definition.
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?
The description clearly states 'Get the full schema of a database' with specific components (tables, columns, types, primary keys, row counts, sizes). This verb+resource clarity distinguishes it from siblings like list_databases (which lists database names only) and query (which runs queries).
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?
The description implicitly advises using list_databases first to see available databases, providing a clear usage context. No explicit when-not or alternative tools for similar tasks, but for this simple informational tool, the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a quick overview of all databases: table counts, total rows, largest tables, database sizes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It clearly states the tool is read-only ('get') and lists the returned data points (table counts, total rows, etc.). It does not disclose whether data is real-time or cached, but the succinct listing of outputs is sufficient for a straightforward overview tool.
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?
The description is a single, well-structured sentence that front-loads the main purpose ('Get a quick overview of all databases') followed by specific items. Every word adds value, and it is perfectly sized for the tool's simplicity.
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?
Given zero parameters and the presence of an output schema (which likely details the return structure), the description is complete. It explains the tool's purpose and the key data it provides, leaving no ambiguity. The tool is simple, and the description covers all necessary context.
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 has zero parameters, so there is nothing to explain beyond what the schema (empty) shows. The description correctly implies no input is needed. Baseline 4 is appropriate as no additional parameter information is required.
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?
The description uses a clear verb 'get' and specifies the resource 'overview of all databases' with concrete elements: table counts, total rows, largest tables, database sizes. It distinguishes itself from sibling tools like 'list_databases' (which likely only lists names) and 'schema' (which provides structural details).
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?
The phrase 'quick overview' implies a lightweight, informative tool for initial understanding. Although no explicit when-to-use or when-not-to-use guidance is provided, the context is clear due to the tool's simplicity and zero parameters. A slight deduction for not mentioning alternatives, but siblings are obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze time series data: group rows by time period and show counts, averages, and totals.
Args: database: Name of the database from config. table: Name of the table. date_column: Name of the date/timestamp column to group by. value_column: Optional numeric column to aggregate (avg, sum). If omitted, shows counts only. period: Grouping period: day, week, month, quarter, year. Default: month.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | ||
| table | Yes | ||
| date_column | Yes | ||
| value_column | No | ||
| period | No | month |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the tool's behavior: grouping by time period, computing counts, averages, or totals, and clarifies that omitting 'value_column' yields counts only. It does not mention auth needs, rate limits, or side effects, but the read-only nature is implied.
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?
The description is concise with a clear opening sentence followed by parameter explanations in a structured list-like format. It avoids redundancy and focuses on essential details, though the structure could be slightly improved with bullet points.
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?
Given the presence of an output schema (not shown), the description need not detail return values. It covers the core functionality and parameter semantics adequately. However, it could mention potential output format or restrictions (e.g., only numeric value_column) for fuller context.
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 0%, so the description must compensate. It explains each parameter: 'database', 'table', 'date_column', 'value_column' (optional with aggregation types), and 'period' (enumeration of groupings with default). This adds significant meaning beyond the bare schema.
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?
The description clearly states the tool analyzes time series data by grouping rows by time period and showing counts, averages, totals. It uses specific verbs and resources ('Analyze time series data', 'group rows by time period') and distinguishes itself from sibling tools like 'analyze' or 'compare' by its focus on temporal aggregation.
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?
The description implies usage for time-based data analysis but does not explicitly state when to use it versus alternatives like 'analyze' or 'compare'. No exclusions or when-not-to-use guidance is provided, leaving the agent to infer context from the tool name and parameters.
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. Dates show when Glama detected each change.
v0.1.1analyzeanomaliescompareerdhealthlist_databasesquerysampleschemasummarytrendEach tool has a clearly distinct purpose: profiling (analyze) vs anomaly detection (anomalies) vs schema exploration (schema) vs time series (trend) etc. No two tools appear to do the same thing, and descriptions make boundaries clear.
All names use lowercase with underscores for multi-word terms, but the part-of-speech varies (verbs like analyze, query vs nouns like anomalies, schema). The pattern is mostly predictable, but lacks the strict verb_noun consistency seen in higher-scoring sets.
11 tools is squarely in the optimal range for a database analysis server. Each tool addresses a specific analytical need without redundancy, and the number feels complete without being overwhelming.
The tool surface covers all major database exploration tasks: listing, schema, profiling, sampling, querying, comparison, anomaly detection, time trends, and health checks. No obvious gaps for the stated purpose of database analysis.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
GibsonAI MCP server: manage your databases with natural language
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ginkida/dbecho'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
