Allows retrieving database credentials from AWS Secrets Manager for secure connection setup.
Supports connecting to PostgreSQL databases hosted on Fly.io.
Provides tools to connect to and manage PostgreSQL databases, including schema discovery, query analysis, health checks, security audits, and more.
Supports connecting to PostgreSQL databases hosted on Railway.
Supports connecting to PostgreSQL databases hosted on Render.
Supports connecting to Supabase PostgreSQL databases using pooler connection strings.
A PostgreSQL MCP server that gives AI assistants expert DBA capabilities.
Quick Start · Demo · Tools · Safety · Configuration · Docs
DBeast connects AI assistants such as Claude, Cursor, Windsurf, and VS Code Copilot to PostgreSQL through the Model Context Protocol. Instead of exposing one broad execute_sql escape hatch, DBeast provides 21 focused tools for schema discovery, safe query execution, impact analysis, performance review, security checks, maintenance reporting, replication monitoring, and data quality inspection.
Watch Claude use DBeast MCP tools to audit a PostgreSQL database, identify security and maintenance risks, and preview cleanup impact without executing destructive SQL.
Related MCP server: mcp-db-analyzer
AI assistant --MCP stdio--> DBeast server --asyncpg--> PostgreSQL
Claude/Cursor Python local Local, RDS,
Windsurf/VS Code subprocess Supabase, NeonDBeast runs as a local stdio MCP server. Your IDE or desktop assistant starts it as a subprocess and passes database credentials through environment variables. The assistant calls DBeast tools, DBeast queries PostgreSQL, and structured results come back to the assistant. No HTTP service or extra infrastructure is required.
git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .For development:
pip install -e ".[dev]"Optional: copy .env.example to .env and set your database credentials.
dbeastOr run the source entry point directly:
python src/server.pyMinimal Cursor or Windsurf config:
{
"mcpServers": {
"dbeast": {
"type": "stdio",
"command": "python",
"args": ["/absolute/path/to/DBeast/src/server.py"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}Common config locations:
Client | Config location |
Cursor |
|
VS Code |
|
Claude Desktop on macOS |
|
Claude Desktop on Windows |
|
Windsurf |
|
See SETUP.md for full client examples, Docker, RDS, Supabase, Neon, SSH tunnels, AWS Secrets Manager, and troubleshooting.
Once connected, your assistant can answer quick lookup questions and also run multi-step database investigations.
Simple examples:
Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.More complex examples:
Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.DBeast exposes 21 MCP tools across 10 categories.
Tool | Description |
| Connect to PostgreSQL, check current status, or discover local databases |
| Close the current database connection |
| Verify connectivity, pool health, PostgreSQL version, and extensions |
Tool | Description |
| List schemas, tables, columns, indexes, relationships, and optional Mermaid ERDs |
| Map object dependencies before renaming, dropping, or changing database objects |
Tool | Description |
| Run read-only |
Tool | Description |
| Parse and inspect query structure, warnings, and optimization hints |
| Recommend indexes and rewrites for a given query |
| Preview write-query impact, risk level, affected rows, and rollback context without executing |
Tool | Description |
| Review cache hit rates, connections, transaction age, table health, and overall health signals |
| Report slow or expensive queries from PostgreSQL statistics |
Tool | Description |
| Inspect roles, privileges, superuser accounts, and public schema exposure |
| Detect likely PII or secrets by column names and schema patterns |
Tool | Description |
| Review vacuum status, dead tuples, analyze timestamps, and index health |
| Inspect partition health, row distribution, and missing partition risks |
Tool | Description |
| Analyze null rates, cardinality, value distributions, and outliers |
| Find duplicate rows across selected key columns |
Tool | Description |
| Review PostgreSQL configuration and tuning opportunities |
| Inspect replication lag, WAL sender/receiver state, and replication slots |
Tool | Description |
| Retrieve logged MCP tool calls for a given date |
| List available audit log files |
Start by discovering schemas:
get_schema()
get_schema(schema='public')Run safe read queries:
execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')Preview risky writes:
analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')Check health and maintenance:
database_health()
maintenance_analysis(schema='public')
query_performance()Most analysis tools accept a schema parameter:
maintenance_analysis(schema='public') -> analyze one schema
maintenance_analysis(schema='all') -> analyze every schema
get_schema(format='mermaid') -> generate an ERD diagramProvider | Connection method |
Local PostgreSQL |
|
Docker PostgreSQL | Explicit variables or |
AWS RDS / Aurora | Direct URL, SSH tunnel, or AWS Secrets Manager |
Supabase | Pooler connection string from Dashboard settings |
Neon | Connection string from Console connection details |
Railway / Render / Fly.io | Provider connection string |
Any PostgreSQL host | Standard PostgreSQL URL |
Choose one connection method.
# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db
# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer
# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2You can also connect at runtime:
connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')Key settings:
Variable | Default | Description |
|
| Max rows returned by |
|
| Query execution timeout in seconds |
|
| SQL command timeout in seconds |
|
| Set |
|
| Schema cache TTL in seconds, |
|
| Log MCP tool calls |
|
| Audit log directory |
See SETUP.md for the complete configuration reference.
Query type | What DBeast does |
| Executes with automatic row limits |
| Never executed; returns an impact preview |
| Never executed; reports affected objects and risk |
Formatted and JSON responses use a consistent wrapper:
{
"success": true,
"data": { "...": "..." },
"meta": {
"connected": true,
"source": "tool"
}
}DBeast logs MCP tool calls for accountability and debugging.
DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_auditAudit files are stored as daily markdown files and include timestamps, tool names, durations, masked parameters, truncated responses, and errors.
pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/Start the optional local PostgreSQL test database:
docker compose up -d postgresLegacy Compose:
docker-compose up -d postgresSETUP.md - Full client setup, connection scenarios, configuration, and troubleshooting
CONTRIBUTING.md - Development setup, tests, style, commits, and PR process
CODE_OF_CONDUCT.md - Community guidelines
MIT
Preview DELETE/UPDATE/DROP impact WITHOUT executing. Shows affected rows and rollback SQL.
LEVEL: Query (write operation preview - never executes)
USE FOR: previewing write impact, cascade effects, risk assessment. DO NOT USE FOR: reading data (execute_query), INSERT operations.
Examples: analyze_impact(query="DELETE FROM users WHERE status='inactive'", schema='public') analyze_impact(query="UPDATE orders SET status='cancelled' WHERE id=1", schema='shipment')
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL DELETE/UPDATE/DROP query to preview | |
| sample_limit | No | Sample rows to show | |
| timeout_ms | No | Timeout in ms (5 min default) | |
| schema | No | Schema containing the table. REQUIRED. Use get_schema() to list available schemas. | |
| format | No | Output format | json |
| url | No | Database URL |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly states the tool does not execute (safe preview) and shows rollback SQL. No annotations are provided, so the description bears full burden. Could mention if it acquires locks or uses transactions, but current detail is strong.
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?
Well-structured with bullet points, examples, and a level note. Front-loaded main purpose. Every sentence adds value without redundancy.
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?
Covers key aspects: purpose, usage, examples. Output schema exists, so return values are documented elsewhere. Could mention prerequisite of a database connection, but that is implied by sibling tools.
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. Description does not add much beyond schema, but provides examples that demonstrate usage of 'query' and 'schema' parameters, which is helpful.
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 specific verbs ('preview', 'shows affected rows and rollback SQL') and clearly identifies the resource (DELETE/UPDATE/DROP impact). It distinguishes from siblings like execute_query by stating it does not execute.
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 ('previewing write impact, cascade effects, risk assessment') and when not to use ('reading data (execute_query), INSERT operations'), including an alternative tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate SQL syntax, detect anti-patterns, N+1, duplicates.
LEVEL: Query (SQL statement analysis - no DB connection needed for basic parsing)
USE FOR: SQL validation, N+1 detection, batch analysis. DO NOT USE FOR: running queries (execute_query), write impact (analyze_impact).
Examples: analyze_query(query='SELECT * FROM users') analyze_query(query='SELECT * FROM users', schema='shipment', include_explain=True)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL string or JSON array [{"id":"q1","sql":"..."}] | |
| detect_duplicates | No | Detect duplicates in batch | |
| include_explain | No | Include EXPLAIN plan | |
| schema | No | Schema name for batch analysis context. Required for EXPLAIN. Use get_schema() to list available schemas. | |
| format | No | Output format | json |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that basic parsing requires no DB connection, and that schema is required for EXPLAIN. It does not explicitly state lack of side effects, but that is implied. Output schema exists, reducing need for return value details.
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: a brief paragraph, LEVEL line, USE FOR/DO NOT USE FOR, and examples. It is front-loaded with purpose, no fluff, and well-structured.
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 output schema exists, the description adequately covers tool purpose, usage context (batch vs single, no DB needed), and parameter relevance. All aspects are addressed without missing critical details.
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%, but the description adds value by explaining batch input format (JSON array) and that schema is needed for EXPLAIN, directing users to get_schema(). This goes beyond the schema's parameter 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?
The description clearly states the tool validates SQL syntax and detects anti-patterns, N+1, and duplicates. It uses specific verbs and resources, and distinguishes from siblings like execute_query and analyze_impact.
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 'USE FOR' and 'DO NOT USE FOR' sections provide clear guidance on when to use (SQL validation, N+1 detection) and when not (running queries, write impact). Examples further clarify usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reviews PostgreSQL configuration settings and provides tuning observations.
LEVEL: Server (PostgreSQL instance configuration)
USE FOR: configuration, settings, postgresql.conf, parameters, tuning, memory, extensions, "why is DB slow globally?", "is autovacuum configured correctly?", server tuning review. DO NOT USE FOR: database-level health (use database_health), query optimization (use query_optimizer), replication settings (use replication_status), table-specific issues (use maintenance_analysis).
INCLUDE OPTIONS:
'all': Everything (default)
'memory': shared_buffers, effective_cache_size, work_mem analysis
'connections': max_connections, current utilization, pooling recommendations
'logging': log_min_duration_statement, log_checkpoints, statement_timeout
'autovacuum': autovacuum enabled, workers, thresholds
'extensions': Installed extensions, recommended extensions not installed
Examples: configuration_review() - Full configuration review configuration_review(include='memory') - Memory settings only configuration_review(include='connections') - Connection limits only configuration_review(include='autovacuum') - Autovacuum settings only configuration_review(include='logging') - Logging configuration configuration_review(include='extensions') - Installed extensions
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | What to include: 'all', 'memory', 'connections', 'logging', 'autovacuum', 'extensions' | all |
| url | No | Database URL for auto-connection | |
| format | No | Output format: 'json' or 'markdown' | json |
| 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 describes the tool's behavior as reviewing and providing tuning observations, and lists possible include options. It does not explicitly state that the tool is read-only or non-destructive, but the context implies it. The description could be slightly improved by noting no side effects, but it is still clear.
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 well-structured with clear headings (LEVEL:, USE FOR:, DO NOT USE FOR:, INCLUDE OPTIONS:, Examples:). It is concise yet comprehensive, with no wasted words. Every section adds value and is appropriately front-loaded with the purpose.
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 (3 parameters, one with enum, plus output schema), the description is complete. It covers all include options, provides multiple examples, explains the tool's level and valid use cases, and offers exclusions. The output schema exists, so return values do not need explanation.
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%. The description adds value beyond the schema by providing detailed examples for the include parameter and listing all option values. The url and format parameters are adequately described in the schema, and the description doesn't need to add more. The examples significantly enhance understanding.
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 reviews PostgreSQL configuration settings and provides tuning observations. It specifies the level (Server instance configuration) and lists specific use cases. It distinguishes from siblings by explicitly stating what NOT to use it for, with alternative tool names.
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 provides explicit guidance on when to use the tool (e.g., for configuration settings, tuning, 'why is DB slow globally?') and when NOT to use it (e.g., database-level health, query optimization), with clear alternative tool names in parentheses. This fully informs the agent's decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to PostgreSQL or check connection status.
LEVEL: Server (connection management)
USE FOR: connecting, checking status, discovering databases. DO NOT USE FOR: health metrics (database_health), queries (execute_query).
ERROR RECOVERY:
"connection refused": Check host/port, ensure PostgreSQL is running
"authentication failed": Verify user/password credentials
"database does not exist": List available databases with discover=True
"SSL required": Add use_ssl=True or check server SSL config
"certificate verify failed": Set ssl_verify=False for SSH tunnels
Examples: connect() - Check status connect(discover=True) - Find databases connect(url='postgresql://user:pass@localhost:5432/mydb')
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | PostgreSQL URL | |
| host | No | Database host | |
| port | No | Port (1-65535) | |
| user | No | Username | |
| password | No | Password | |
| database | No | Database name | |
| use_ssl | No | Use SSL | |
| ssl_verify | No | Verify SSL certificates (set False for SSH tunnels) | |
| aws_secret_name | No | AWS Secrets Manager secret | |
| aws_region | No | AWS region | us-west-1 |
| discover | No | Auto-discover PostgreSQL instances | |
| format | No | Output format | json |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries full transparency burden. It describes connection status, discovery, error scenarios and recovery, but does not explicitly state whether the tool has side effects (e.g., establishing a persistent session). The error handling details are strong enough for practical use.
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?
Description is well-structured with labelled sections (purpose, level, use for/not, error recovery, examples). Each sentence adds distinct value, and the whole is concise enough for quick scanning.
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 12 parameters (0 required) and an output schema present, the description covers essential use cases, parameter patterns, error recovery, and distinctions from siblings. No obvious gaps remain for an agent to connect 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% with descriptive parameter titles and descriptions. The description adds value beyond the schema by providing concrete usage examples (e.g., connect(discover=True), connect(url=...)) and attaching error recovery to specific parameters (e.g., use_ssl, ssl_verify).
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 primary verb 'connect' and resource 'PostgreSQL', and explicitly distinguishes from sibling tools by listing specific use cases and exclusions (e.g., 'DO NOT USE FOR: health metrics (database_health), queries (execute_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?
Provides explicit 'USE FOR' and 'DO NOT USE FOR' sections, naming sibling tools as alternatives. Also includes error recovery guidance, which helps agents handle failures appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live database health - monitors active connections, sessions, locks, transactions.
LEVEL: Database (single database monitoring)
USE FOR: "is database healthy?", connection issues, lock problems, blocked queries, idle transactions, deadlock detection, XID wraparound check, "why is DB slow right now?". DO NOT USE FOR: index analysis (use maintenance_analysis), slow query history (use query_performance), table sizes/stats (use maintenance_analysis), query optimization (use query_optimizer), PostgreSQL server config (use configuration_review), replication (use replication_status). REAL-TIME: Shows current state of database activity.
ERROR RECOVERY:
"not connected": Call connect() first or pass url parameter
"permission denied on pg_stat_*": User needs pg_monitor role or superuser
Use summary_only=True for large/busy databases to reduce payload size
INCLUDE OPTIONS:
'all': Everything (default)
'summary': Database stats, connections by state, checkpoint stats
'sessions': Session summary, by app/user/host, idle in transaction, active sessions
'locks': Lock summary, waiting locks, blocking tree, table lock hotspots, deadlocks
'transactions': XID wraparound status, transaction stats, long-running transactions
'queries': Active queries, long-running queries, wait events
'bloat': Tables needing vacuum
Examples: database_health() - Full health report database_health(include='locks') - Only lock information database_health(include='sessions') - Only session information database_health(include='transactions') - XID status and long transactions database_health(format='markdown') - Human-readable output
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | What to include: 'all', 'summary', 'sessions', 'locks', 'transactions', 'queries', 'bloat' | all |
| url | No | Database URL for auto-connection | |
| format | No | Output format: 'json' or 'markdown' | json |
| summary_only | No | Return only summary counts and critical issues, not detailed lists |
| 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 mentions real-time state, error recovery, and the summary_only option. It does not explicitly state if it is read-only, but the context implies monitoring. Overall, it discloses key behavioral 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?
The description is long but well-structured with clear sections (LEVEL, USE FOR, DO NOT USE FOR, REAL-TIME, ERROR RECOVERY, INCLUDE OPTIONS, Examples). It is front-loaded with purpose and organized for easy scanning, though slightly verbose.
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 (4 parameters, output schema exists), the description is thorough. It covers use cases, alternatives, error scenarios, and options comprehensively. With an output schema present, it does not need to describe return values.
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% with all 4 parameters described. The description adds value beyond the schema by providing detailed explanations of include options, examples, and usage scenarios for each parameter.
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 monitors live database health, listing specific metrics such as active connections, sessions, locks, and transactions. It distinguishes from sibling tools by explicitly stating what NOT to use it for, e.g., index analysis or slow query history.
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 provides explicit 'USE FOR' and 'DO NOT USE FOR' sections with concrete scenarios like connection issues, lock problems, blocked queries, etc. It also includes error recovery steps and options like summary_only for large databases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive data quality analysis - nulls, types, empty tables, outliers, soft deletes.
LEVEL: Database ↔ Schema ↔ Table ↔ Column (multi-level tool)
schema='all': Database level - quality analysis for ALL schemas
schema='': Schema level - all tables in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)
table='users': Table level - specific table analysis
outlier_column='age': Column level - outlier detection for specific column
REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.
USE FOR: data quality, data profiling, finding nulls, empty tables, outliers, soft deletes, cardinality analysis, "which columns have too many nulls?", data validation. DO NOT USE FOR: finding duplicates (use duplicate_detection), security/PII scan (use sensitive_data_scan), schema structure (use get_schema).
INCLUDE OPTIONS:
'all': Everything (default)
'nulls': Null analysis - columns with high NULL percentages
'cardinality': Cardinality analysis - unique value counts
'empty': Empty tables - tables with zero rows
'outliers': Outlier detection (requires table and outlier_column params)
'soft_delete': Soft delete patterns - finds deleted_at, is_deleted columns
'types': Data type consistency recommendations
Examples: data_quality_report() - All tables in public schema (default) data_quality_report(schema='all') - Database-wide analysis data_quality_report(schema='billing') - All tables in billing schema data_quality_report(include='nulls') - Only null analysis data_quality_report(include='empty') - Only empty tables data_quality_report(include='soft_delete') - Find soft delete patterns data_quality_report(table='users', include='outliers', outlier_column='age') - Outlier detection
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema to analyze. Omit for all schemas, or specify one. Use get_schema() to list available. | |
| table | No | Optional table name | |
| include | No | What to include: 'all', 'nulls', 'cardinality', 'empty', 'outliers', 'soft_delete', 'types' | all |
| outlier_column | No | For outlier detection: column name | |
| format | No | Output format: 'json' or 'markdown' | json |
| url | No | Database URL for auto-connection | |
| summary_only | No | Return only summary counts and issues, not detailed lists |
| 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 discloses behavioral traits like multi-level analysis, required schema specification, and include options. However, it does not explicitly state whether the tool is read-only or mention authentication/rate limits, which would strengthen transparency.
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 well-structured with sections (LEVEL, REQUIRED, USE FOR, DO NOT USE FOR, INCLUDE OPTIONS, Examples) and front-loaded with the main purpose. It is slightly verbose but every sentence adds value; minor conciseness gains could be made by consolidating some repeated 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 tool's complexity (7 parameters, multi-level, multiple include options), the description covers all necessary aspects: purpose, usage guidelines, parameter behavior, examples, and sibling differentiation. An output schema exists, so explanation of return values is not needed. The description is comprehensive enough for correct selection and invocation.
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?
Despite 100% schema description coverage, the tool description adds significant extra meaning: explains multi-level behavior for 'schema' parameter, details each include option, and notes that outlier_column requires table and outlier_column parameters. This goes well beyond the schema 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?
The description clearly states the tool performs comprehensive data quality analysis covering nulls, types, empty tables, outliers, soft deletes, and more. It specifies the multi-level scope (database, schema, table, column) and explicitly distinguishes from sibling tools like duplicate_detection and sensitive_data_scan, making the purpose unambiguous.
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 provides explicit usage guidance: USE FOR lists appropriate scenarios, DO NOT USE FOR lists exclusions with references to alternatives. It includes a REQUIRED section and examples demonstrating various parameter combinations, giving clear context for when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive dependency analysis - views, functions, triggers, sequences, FDW.
LEVEL: Database ↔ Schema ↔ Table (multi-level tool)
schema='all': Database level - dependencies for ALL schemas
schema='': Schema level - dependencies in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)
table='users': Table level - what depends on this specific table
REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.
USE FOR: dependencies, views, functions, triggers, sequences, extensions, FDW, lineage, "what depends on this table?", "what views exist?", impact analysis before DROP. DO NOT USE FOR: table structure (use get_schema), index analysis (use maintenance_analysis), security permissions (use security_audit).
INCLUDE OPTIONS:
'all': Everything (default)
'views': Views, materialized views, view dependencies
'functions': User-defined functions, trigger functions
'triggers': Triggers on tables
'sequences': Sequences and their usage
'extensions': Installed PostgreSQL extensions
'fdw': Foreign data wrappers, foreign servers, foreign tables
Examples: dependency_analysis() - All dependencies in public schema (default) dependency_analysis(schema='all') - Database-wide analysis dependency_analysis(schema='billing') - Dependencies in billing schema dependency_analysis(table='users') - What depends on users table dependency_analysis(include='views') - Only view dependencies dependency_analysis(include='functions') - Only functions dependency_analysis(include='triggers') - Only triggers dependency_analysis(include='fdw') - Foreign data wrappers only
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema to analyze. Omit for all schemas, or specify one. Use get_schema() to list available. | |
| include | No | What to include: 'all', 'views', 'functions', 'triggers', 'sequences', 'extensions', 'fdw' | all |
| table | No | Optional: analyze dependencies for specific table | |
| format | No | Output format: 'json' or 'markdown' | json |
| url | No | Database URL for auto-connection | |
| summary_only | No | Return only summary counts, not detailed object lists |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It details multi-level behavior (database, schema, table), required parameters, include options, and default behavior. It also provides examples showing how the tool responds to different inputs, making its behavior fully transparent.
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 comprehensive but relatively lengthy. However, it is well-organized with clear sections, bullet points, and examples. Every sentence provides useful information, so the length is justified.
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, the description covers all necessary aspects: purpose, usage guidelines, behavioral details, parameter semantics, and examples. The presence of an output schema further reduces the need for return value documentation. The description is fully complete.
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% for all 6 parameters, and the description adds significant value beyond the schema by providing usage context, default behavior, and examples for each parameter (e.g., explaining 'all' vs specific schema names, listing all include values).
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 identifies the tool as performing dependency analysis on database objects (views, functions, triggers, sequences, FDW) and distinguishes from siblings by explicitly stating 'DO NOT USE FOR' alternatives like table structure, index analysis, and security permissions.
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 provides explicit 'USE FOR' and 'DO NOT USE FOR' sections, lists concrete scenarios (impact analysis, lineage, what depends on a table), and names sibling tools as alternatives (get_schema, maintenance_analysis, security_audit).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the database connection and release pool resources.
LEVEL: Server (connection management)
USE FOR: ending session, cleanup, releasing connections. DO NOT USE FOR: checking status (use connect() or health_check).
| 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 full burden. It states the action but doesn't disclose side effects (e.g., what happens if connection already closed, or if transactions are pending). Basic transparency, but missing details.
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?
Compact and well-structured: purpose sentence, then level label, then bulleted USE FOR and DO NOT USE FOR. Every sentence earns its place with no redundancy.
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 simplicity (0 parameters, straightforward action) and presence of output schema, the description is complete. An agent can correctly select and invoke this tool based solely on the description.
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?
No parameters exist, so schema coverage is 100%. Description adds value by noting 'release pool resources' which implies resource cleanup beyond just closing. Baseline for 0 params is 4, and this meets it.
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 closes the database connection and releases pool resources, with a specific verb and resource. It distinguishes from siblings like connect (open connection) and health_check (check status).
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 lists use cases ('ending session, cleanup, releasing connections') and anti-use cases ('checking status') with alternatives (connect(), health_check). Perfect guidance for when and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect duplicate rows in a table based on specified columns.
LEVEL: Table ↔ Column (requires table and columns parameters)
USE FOR: finding duplicates, duplicate rows, "are there duplicate emails?", detecting duplicate records, data deduplication analysis. DO NOT USE FOR: general data quality (use data_quality_report), schema structure (use get_schema), null analysis (use data_quality_report with include='nulls').
Examples: duplicate_detection(table='users', columns='email', schema='public') duplicate_detection(table='orders', columns='customer_id,product_id', schema='shipment')
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name to check | |
| columns | Yes | Comma-separated column names (e.g., 'email,name') | |
| schema | No | Schema containing the table. REQUIRED. Use get_schema() to list available schemas. | |
| format | No | Output format: 'json' or 'markdown' | json |
| url | No | Database URL for auto-connection |
| 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 explains the tool's purpose and usage but does not disclose behavioral traits like output format details, read-only nature, performance considerations, or error behavior. The examples and level help, but more behavioral context is needed.
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 and well-structured: purpose statement, level note, use/not-use list, and examples. Every sentence serves a purpose and there is no 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 tool has 5 parameters (2 required) and an output schema, the description covers the core function, usage guidelines, and examples. It does not describe the output schema, but the rule states this is acceptable since the output schema exists. The description could mention the 'url' parameter, but overall it is 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?
Schema description coverage is 100%, so baseline is 3. The description adds value by including example parameter values (table='users', columns='email') and noting that columns are comma-separated. It reinforces required parameters and provides context beyond the 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 detects duplicate rows in a table based on specified columns. It provides a specific verb-resource pair, and the USE FOR/DO NOT USE FOR list distinguishes it from sibling tools like data_quality_report and get_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?
The description includes explicit USE FOR and DO NOT USE FOR sections with alternative tool names, plus a level indicator and example invocations. This gives clear guidance on when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute read-only SELECT queries. Writes are blocked.
LEVEL: Data (actual table data retrieval)
USE FOR: fetching data, counting rows, aggregations, joins. DO NOT USE FOR: INSERT/UPDATE/DELETE (use analyze_impact first).
ERROR RECOVERY:
"relation does not exist": Verify table name with get_schema()
"permission denied": User lacks SELECT privilege on table
"query timeout": Reduce limit, add WHERE clause, or increase timeout_ms
"not connected": Call connect() first
Examples: execute_query(query='SELECT * FROM users LIMIT 10') execute_query(query='SELECT COUNT(*) FROM orders')
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL SELECT query | |
| limit | No | Max rows (1-50000) | |
| timeout_ms | No | Timeout in ms (5 min default) | |
| format | No | Output format | json |
| url | No | Database URL |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses read-only behavior, write blocking, and connection requirements. Error recovery provides behavioral insights for common failure modes, adding depth beyond structured metadata.
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 well-structured with a bold intro, use/do-not-use sections, error recovery bullets, and examples. It is front-loaded with core purpose, and each section is concise and relevant, earning 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?
Given the tool's complexity (5 params, 1 required, no annotations) and the presence of an output schema, the description covers purpose, usage boundaries, error recovery, and examples comprehensively. It leaves no significant gaps for an 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?
Schema coverage is 100%, but the description adds substantial value with usage examples, error handling for timeouts and limits, and contextual guidance on parameters like format and limit. This goes well beyond the schema 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 'Execute read-only SELECT queries' with the verb 'execute' and resource 'SELECT queries'. It distinguishes from write operations and provides the data retrieval level, making its purpose unambiguous.
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 lists use cases (fetching data, aggregations) and forbids INSERT/UPDATE/DELETE, directing users to analyze_impact. Includes error recovery steps with specific error messages and actions, offering comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve MCP audit logs for accountability and debugging.
USE FOR: viewing tool call history, debugging issues, compliance audits.
Examples: get_audit_logs() - Today's logs get_audit_logs(date='2026-05-29') - Specific date get_audit_logs(limit=10) - Last 10 entries
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format (default: today) | |
| limit | No | Max entries to return | |
| format | No | Output format: 'markdown' or 'json' | markdown |
| 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 burden of behavioral disclosure. It explains the default behavior (today's logs) and how parameters affect output (limit and format). It does not mention authentication or rate limits, but for a simple retrieval tool, it provides sufficient transparency beyond the schema.
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 very concise: two clear sentences plus a 'USE FOR' line and three examples. Every sentence earns its place with no redundancy 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 tool's simplicity (3 optional params, no required fields) and the presence of an output schema (not shown but indicated by context signals), the description provides complete context. It covers purpose, use cases, parameter behavior, and examples, leaving no obvious gaps.
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. The description adds value by providing usage examples that demonstrate how each parameter is used (e.g., get_audit_logs(date='2026-05-29') for specific date). This clarifies parameter semantics beyond the schema 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?
The description clearly states the tool retrieves MCP audit logs for accountability and debugging. It lists specific use cases (viewing tool call history, debugging, compliance audits) and provides examples, making the purpose distinct from sibling tools like list_audit_files.
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 explicitly states when to use the tool (viewing tool call history, debugging, compliance audits) but does not mention when not to use it or provide alternatives. It implies no usage restrictions, which is adequate but could be improved by noting that list_audit_files may be used for file listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover database schema - tables, columns, relationships, indexes.
LEVEL: Database (lists all schemas) or Schema (specific schema details)
USE FOR: listing tables, columns, foreign keys, ERD generation. DO NOT USE FOR: table data (execute_query), index health (maintenance_analysis).
ERROR RECOVERY:
"schema not found": Call get_schema() without params to list all schemas
"no tables found": Schema exists but is empty, verify with execute_query
"not connected": Call connect() first or pass url parameter
PAGINATION: For large schemas (100+ tables), use limit/offset.
Examples: get_schema() - List all schemas get_schema(schema='public') - Tables in public get_schema(schema='public', limit=50, offset=50) - Page 2 get_schema(format='mermaid') - ERD diagram
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name. Omit or 'all' for all schemas; specific name for tables. | |
| format | No | Output format | json |
| limit | No | Max tables to return (1-500) | |
| offset | No | Skip first N tables (for pagination) | |
| url | No | Database URL for auto-connection |
| 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 behavioral transparency burden. It discloses error recovery scenarios, pagination limits, and format options. It also explains behavior with and without parameters. However, it does not explicitly state read-only nature, but it's 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 well-structured with clear sections (LEVEL, USE FOR, DO NOT USE FOR, ERROR RECOVERY, PAGINATION, Examples). Every sentence provides useful information without redundancy. It is concise yet comprehensive.
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 5 parameters, presence of an output schema, and context from sibling tools, the description is complete. It covers all relevant aspects: purpose, usage boundaries, parameter details, error recovery, pagination, and format options. No gaps remain.
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% for all 5 parameters. The description adds value by explaining how to use parameters for pagination (limit/offset), format output (mermaid for ERD), and auto-connection via url. Examples demonstrate typical usage patterns beyond the schema alone.
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 explicitly states it discovers database schema (tables, columns, relationships, indexes). It also distinguishes from siblings like execute_query and maintenance_analysis. The verb 'discover' combined with 'database schema' gives a specific resource and action.
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 includes explicit 'USE FOR' and 'DO NOT USE FOR' sections, listing when to use this tool (listing tables, columns, foreign keys, ERD generation) and when not to (use execute_query for data, maintenance_analysis for index health). Error recovery and pagination guidance are also provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check connection health - pool stats, version, extensions.
LEVEL: Server (connection management)
USE FOR: connection status, pool health, "is database reachable?". DO NOT USE FOR: database metrics (database_health), query stats (query_performance).
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format | json |
| 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 burden. It states what the tool does but does not disclose safety characteristics like read-only nature, idempotency, or side effects. For a health check, the implied behavior is safe, but more explicit transparency would be better.
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 every line earning its place. The most important information (purpose, level, usage) is front-loaded, and it uses clear formatting with a level line and separate USE FOR/DO NOT USE FOR sections.
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 low complexity (one optional parameter, output schema present), the description covers purpose and usage comprehensively. It could elaborate on what 'pool stats, version, extensions' mean but the output schema likely covers return structure. Minor gap, still complete enough.
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% with one parameter (format) having a description and enum. The description adds no additional meaning beyond the schema, so baseline of 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?
The description clearly states the tool checks connection health with specifics like pool stats, version, and extensions. It distinguishes from siblings by explicitly listing DO NOT USE FOR database_health and query_performance.
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?
Provides explicit USE FOR examples (connection status, pool health, 'is database reachable?') and DO NOT USE FOR with sibling tool names, giving clear guidance on when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available audit log files.
USE FOR: finding available log dates, checking log sizes.
Returns list of log files with date, size, and entry count.
| 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 bears the full burden. It correctly implies a read-only operation and specifies the return fields (date, size, entry count). However, it omits potential details like ordering, pagination, or access restrictions, which are relevant for a full behavioral picture.
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: one sentence for purpose, one line for usage, one line for return spec. Every sentence earns its place with no redundancy.
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?
For a zero-parameter list tool with an output schema, the description covers all needed information: what it does, when to use it, and what it returns. No gaps detected.
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 coverage is 100%. The description adds value by explicitly stating what the return data includes (date, size, entry count), complementing the output 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 lists available audit log files, with specific use cases for finding dates and sizes. It distinguishes from sibling tool get_audit_logs (retrieves content vs. listing files) implicitly, but does not explicitly differentiate.
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 explicitly provides use cases: 'finding available log dates, checking log sizes.' It does not mention exclusions or alternatives, but the context is sufficient for an agent to decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Table and index maintenance - analyzes indexes, vacuum status, table bloat, FK indexes.
LEVEL: Database ↔ Schema ↔ Table (multi-level tool)
schema='all': Database level - maintenance status for ALL schemas
schema='': Schema level - all tables in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)
table='users': Table level - specific table analysis
REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.
USE FOR: finding unused indexes, duplicate indexes, tables needing vacuum, FK missing indexes, table sizes, TOAST analysis, autovacuum status, "which indexes should I drop?". DO NOT USE FOR: live connections/locks (use database_health), slow query history (use query_performance), specific query optimization (use query_optimizer), schema structure (use get_schema), partitioned tables (use partition_analysis). STATIC: Analyzes stored statistics, not real-time activity.
ERROR RECOVERY:
"not connected": Call connect() first or pass url parameter
"schema not found": Verify schema exists with get_schema()
Large payload: Use summary_only=True or include='indexes' to filter results
"permission denied": User needs read access to pg_catalog views
INCLUDE OPTIONS:
'all': Everything (default)
'indexes': All indexes, unused indexes, duplicate indexes, tables needing indexes, largest indexes
'tables': Table statistics, hot tables (most active)
'vacuum': Bloated tables, never vacuumed, tables needing freeze, autovacuum settings
'fk_indexes': Foreign keys missing supporting indexes
'toast': TOAST storage analysis (large object storage)
Examples: maintenance_analysis() - All tables in public schema (default) maintenance_analysis(schema='all') - All schemas (database-wide) maintenance_analysis(schema='billing') - All tables in billing schema maintenance_analysis(schema='auth', table='users') - Specific table in auth schema maintenance_analysis(include='indexes') - Only index analysis maintenance_analysis(include='vacuum') - Only vacuum/bloat analysis maintenance_analysis(include='fk_indexes') - Only FK index analysis
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | What to include: 'all', 'indexes', 'tables', 'vacuum', 'fk_indexes', 'toast' | all |
| table | No | Specific table (or all tables if not specified) | |
| schema | No | Schema to analyze. Omit for all schemas, or specify one. Use get_schema() to list available. | |
| url | No | Database URL for auto-connection | |
| format | No | Output format: 'json' or 'markdown' | json |
| summary_only | No | Return only summary counts and issues, not detailed lists |
| 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 full burden. It discloses that the tool is 'STATIC: Analyzes stored statistics, not real-time activity' and explains the multi-level behavior (database, schema, table). It also covers error recovery. However, it does not explicitly state if the tool is read-only (implied but not stated), which slightly reduces transparency.
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 lengthy but well-structured with sections (LEVEL, REQUIRED, USE FOR, DO NOT USE FOR, STATIC, ERROR RECOVERY, INCLUDE OPTIONS, Examples). It front-loads the core purpose and uses bullet points for readability. While not maximally concise, the structure compensates.
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 (6 parameters, multi-level scope, multiple include options), the description is comprehensive. It covers error recovery, examples, parameter details, and usage boundaries. With an output schema present, return values are documented elsewhere, so this description provides sufficient context for an agent to invoke the tool 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 description coverage is 100% (all 6 parameters described in schema). The description adds significant value beyond the schema: it explains the 'include' options in detail, provides examples for schema/table parameters, and clarifies the behavior of default values. This goes beyond the baseline of 3.
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's function: 'Table and index maintenance - analyzes indexes, vacuum status, table bloat, FK indexes.' It also lists specific use cases like finding unused indexes, duplicate indexes, etc., and distinguishes from sibling tools through the 'DO NOT USE FOR' section.
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 provides explicit guidance on when to use ('USE FOR') and when not to use ('DO NOT USE FOR'), including specific sibling tool names. It also offers examples and error recovery steps, making it exceptionally clear for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partition analysis - list all partitioned tables or analyze specific table.
LEVEL: Schema ↔ Table (multi-level tool)
table=None (default): Lists all partitioned tables across ALL schemas
table='orders': Requires schema - detailed partition analysis for that table
USE FOR: partitions, partition analysis, partition details, partition size, inheritance, "which tables are partitioned?", partition skew detection, empty partition identification. DO NOT USE FOR: non-partitioned table maintenance (use maintenance_analysis), schema structure (use get_schema), index health (use maintenance_analysis).
INCLUDE OPTIONS (only when table is specified):
'all': Everything (default)
'details': Partition details - boundaries, row counts, dead rows
'size': Size distribution - partition sizes, percentages, skew detection
'activity': Partition activity - inserts, updates per partition
'indexes': Partition indexes
'maintenance': Empty partitions, maintenance candidates, default partitions
Examples: partition_analysis() - List all partitioned tables across all schemas partition_analysis(table='events', schema='logs') - Detailed analysis of events table partition_analysis(table='orders', schema='shipment', include='size') - Size distribution
| Name | Required | Description | Default |
|---|---|---|---|
| table | No | Partitioned table name (omit to list all partitioned tables) | |
| schema | No | Schema name. REQUIRED when table is specified. Use get_schema() to list available schemas. | |
| include | No | What to include: 'all', 'details', 'size', 'activity', 'indexes', 'maintenance' | all |
| format | No | Output format: 'json' or 'markdown' | json |
| url | No | Database URL for auto-connection |
| 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 discloses the two operational modes (list all vs analyze specific) and describes include options. However, it does not explicitly state that the tool is read-only or describe potential resource impact. Given the tool is analytical, this is mostly adequate but could be more explicit about safety.
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 well-structured with clear sections (main description, LEVEL, USE FOR/DO NOT USE FOR, INCLUDE OPTIONS, Examples). It is front-loaded with the main purpose and each sentence adds value. No redundancy or fluff. The examples are helpful and 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 (multi-level, many include options) and the presence of an output schema, the description is highly complete. It covers all aspects: purpose, when to use (including exclusions), parameter behavior, options, and examples. It also cross-references sibling tools effectively. No gaps are apparent.
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 description adds significant meaning beyond the input schema. For table, it explains the default behavior (list all). For schema, it notes 'REQUIRED when table is specified' and suggests get_schema() for listing schemas. For include, it describes each option. For format, it specifies output types. For url, it mentions auto-connection. This provides rich context for each parameter.
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 'Partition analysis - list all partitioned tables or analyze specific table.' It uses specific verbs 'list' and 'analyze' with a clear resource (partitioned tables). It distinguishes from siblings by explicitly listing DO NOT USE FOR alternatives like maintenance_analysis and get_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?
The description provides explicit 'USE FOR' and 'DO NOT USE FOR' sections listing use cases and alternatives. It also explains the multi-level behavior (table=None vs table specified) and gives examples for different scenarios. This makes it clear when to use this tool versus siblings like maintenance_analysis or get_schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optimize slow queries - EXPLAIN plan, table stats, index recommendations.
LEVEL: Query (single query optimization)
USE FOR: slow query diagnosis, CREATE INDEX suggestions, execution plans. DO NOT USE FOR: running queries (execute_query), syntax validation (analyze_query).
Examples: query_optimizer(query='SELECT * FROM orders WHERE customer_id=123', schema='shipment') query_optimizer(query='SELECT * FROM users', schema='public', run_explain=True)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL query to optimize | |
| run_explain | No | Run EXPLAIN ANALYZE (executes in rollback) | |
| timeout_ms | No | Timeout in ms (5 min default) | |
| schema | No | Schema for table stats lookup. REQUIRED. Use get_schema() to list available schemas. | |
| url | No | Database URL |
| 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 disclose behavior. It mentions that running EXPLAIN ANALYZE 'executes in rollback' and includes timeout, but does not explicitly state whether the tool is read-only or if it can create indexes (as implied by 'CREATE INDEX suggestions'). More explicit safety information would improve transparency.
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 well-structured with clear headings, bullet points, and examples. Key information is front-loaded, and every sentence adds value. No extraneous text.
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 (context signals indicate it exists) and the tool's moderate complexity, the description covers purpose, usage, parameters, and examples. It is sufficient for an agent to select and invoke the tool 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?
Parameter schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'schema' is REQUIRED (though not marked in schema) and suggests using get_schema() to list available schemas, and clarifies that 'run_explain' executes in a rollback. This goes beyond the schema 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?
The description clearly states the tool's purpose: 'Optimize slow queries - EXPLAIN plan, table stats, index recommendations.' It specifies the level (Query) and distinguishes from siblings by listing what not to use it for (execute_query, analyze_query). Examples further clarify its usage.
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 usage guidelines: 'USE FOR: slow query diagnosis, CREATE INDEX suggestions, execution plans' and 'DO NOT USE FOR: running queries (execute_query), syntax validation (analyze_query).' This provides clear context on when to use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical query stats - shows top queries by time/calls/IO from pg_stat_statements.
LEVEL: Database (database-wide query statistics)
USE FOR: "what queries are slowest?", finding high-frequency queries, cache hit analysis, queries using temp files, overall query patterns, "which queries consume most time?". DO NOT USE FOR: analyzing ONE specific query (use query_optimizer), live running queries (use database_health), index recommendations (use maintenance_analysis), query syntax validation (use analyze_query). REQUIRES: pg_stat_statements extension installed.
Examples: query_performance() - Top 20 queries by total time query_performance(order_by='calls') - Most frequently called queries query_performance(order_by='mean_time') - Slowest average execution query_performance(limit=50, min_calls=100) - Top 50, only queries called 100+ times
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of queries to return (1-500) | |
| order_by | No | Sort by: total_time, calls, mean_time, rows, shared_blks_hit, shared_blks_read | total_time |
| min_calls | No | Minimum call count filter | |
| url | No | Database URL for auto-connection |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool provides historical stats from a specific source, implies it is read-only and non-destructive, and clarifies the database-wide scope. However, it does not explicitly state that it does not modify data or require certain permissions, which are minor gaps.
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 well-structured with clear sections (main sentence, LEVEL, USE FOR, DO NOT USE FOR, REQUIRES, examples). It is front-loaded with the core purpose, every sentence adds value, and there is no redundancy or extraneous text. Concise yet comprehensive.
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 (4 parameters, output schema exists), the description covers all necessary context: data source, scope, usage guidelines, prerequisites, and examples. The output schema handles return structure, so no need to describe it. The description is fully sufficient for an agent to use the tool 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 description coverage is 100%, so baseline is 3. The description adds value by showing concrete examples of parameter usage (e.g., query_performance(order_by='calls'), query_performance(limit=50, min_calls=100)), illustrating how parameters combine meaningfully. This enhances understanding beyond the schema's individual 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?
The description clearly states it shows historical query stats from pg_stat_statements, with specific verb 'shows' and resource 'historical query stats'. It explicitly distinguishes from siblings like query_optimizer, database_health, maintenance_analysis, and analyze_query, making the purpose unambiguous.
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?
Provides explicit USE FOR and DO NOT USE FOR sections, listing specific alternatives for each non-use case (e.g., 'analyzing ONE specific query (use query_optimizer)'). Also states the prerequisite 'REQUIRES: pg_stat_statements extension installed.' This fully guides the agent on when and when not to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive replication health - physical, logical, CDC, slots, WAL, archiving.
LEVEL: Server (PostgreSQL instance level)
USE FOR: replication status, replica lag, standby, streaming replication, replication slots, CDC, logical replication, publications, subscriptions, WAL archiving, backup progress, "is replication healthy?", "how far behind is the replica?". DO NOT USE FOR: database-level health (use database_health), query performance (use query_performance), PostgreSQL settings (use configuration_review).
INCLUDE OPTIONS:
'all': Everything (default)
'physical': Standbys, streaming replication, replay lag
'logical': CDC status, wal_level, publications, subscriptions, logical slots
'slots': All replication slots (physical and logical), inactive slot warnings
'wal': WAL info, WAL settings
'archiving': Archive mode, archiver status, failed archives, active basebackups
Examples: replication_status() - Full replication report replication_status(include='physical') - Physical replication only replication_status(include='logical') - Logical replication/CDC only replication_status(include='slots') - Replication slots only replication_status(include='wal') - WAL status only replication_status(include='archiving') - WAL archiving status
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | What to include: 'all', 'physical', 'logical', 'slots', 'wal', 'archiving' | all |
| url | No | Database URL for auto-connection | |
| format | No | Output format: 'json' or 'markdown' | json |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It explains the options and examples, but does not disclose potential behavioral traits like required privileges, performance impact, or safety guarantees (e.g., read-only nature). Adequate but could be more explicit.
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 well-organized with labeled sections (LEVEL, USE FOR, DO NOT USE FOR, INCLUDE OPTIONS, Examples). It is concise, front-loaded with a summary, and each sentence is purposeful. No redundancy.
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 (server-level replication health with multiple facets) and the presence of an output schema, the description covers all necessary aspects: scope, usage, options, examples, and exclusions. It is fully informative for correct invocation.
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%. The description adds significant context beyond the schema for the 'include' parameter via the INCLUDE OPTIONS list and examples. For 'url' and 'format', it echoes schema but no added depth. Overall, it enhances understanding.
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's purpose: 'Comprehensive replication health - physical, logical, CDC, slots, WAL, archiving.' It specifies the server level and explicitly distinguishes from sibling tools by listing what not to use (database_health, query_performance, configuration_review).
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 provides explicit 'USE FOR' and 'DO NOT USE FOR' sections, naming alternatives (database_health, query_performance, configuration_review). It also includes examples for each option, guiding correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit roles, privileges, RLS, SSL, and security definer functions.
LEVEL: Schema or Database (schema='all') REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.
USE FOR: security audit, role permissions, RLS policies, SSL status. DO NOT USE FOR: PII detection (sensitive_data_scan), data quality.
INCLUDE: all, roles, privileges, rls, ssl, sensitive, functions
Examples: security_audit(schema='sales') - Audit sales schema security_audit(schema='all') - All schemas security_audit(schema='billing', include='roles') - Roles only in billing
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema to audit. Omit for all schemas, or specify one. Use get_schema() to list available. | |
| include | No | What to audit | all |
| format | No | Output format | json |
| url | No | Database URL |
| 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 full transparency burden. While it explains the level and required schema, it does not mention whether the tool is read-only, requires special permissions, or has performance implications. Basic behavioral traits are disclosed but not comprehensively.
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 lead sentence, followed by structured sections (LEVEL, REQUIRED, USE FOR, DO NOT USE FOR, INCLUDE, Examples). Every sentence adds necessary information without waste.
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 an output schema present, the description does not need to detail return values. It covers purpose, parameters, usage guidelines, and examples sufficiently for the complexity of a security audit tool. The examples further clarify usage.
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. The description adds value by clarifying the 'schema' parameter requirement ('use 'all' for all schemas or a specific schema name') and providing usage examples. It also enumerates the 'include' options in a list, though that is already in the 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 audits roles, privileges, RLS, SSL, and security definer functions. It also explicitly lists use cases and excludes PII detection and data quality, distinguishing it from siblings like sensitive_data_scan.
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 includes 'USE FOR' and 'DO NOT USE FOR' sections with concrete contexts and alternatives, such as explicitly naming sensitive_data_scan. It also specifies when to use 'all' vs a specific schema and provides requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find PII/PHI columns - passwords, credit cards, SSN, emails.
LEVEL: Database (scans all schemas by default) or Schema (if specified)
USE FOR: finding sensitive data, GDPR compliance, security review. DO NOT USE FOR: permissions (security_audit), data quality (data_quality_report).
Examples: sensitive_data_scan() - Scan all schemas sensitive_data_scan(schema='public') - Public schema only
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name to scan. Omit or pass null to scan ALL schemas. | |
| format | No | Output format | json |
| url | No | Database URL |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description implies read-only by 'Find' and scope (database or schema). Examples clarify behavior. Lacks explicit mention of read-only or auth needs, but sufficient for a scan 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?
Description is concise with clear sections: purpose, level, usage guidelines, examples. 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?
All parameters documented, output schema exists (so return values not needed), usage and scope fully explained. Complete for a scanning 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 descriptions are good. Description adds value by clarifying default behavior for schema parameter and providing examples, though baseline is 3 due to high 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?
The description clearly states the tool finds PII/PHI columns (passwords, credit cards, SSN, emails), specifying verb and resource. It also distinguishes from sibling tools like security_audit and data_quality_report by listing what not to use.
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?
Provides explicit 'USE FOR' and 'DO NOT USE FOR' sections with alternative tools (security_audit, data_quality_report), and examples for common use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool has a clearly defined domain with detailed descriptions that differentiate it from others. For example, database_health focuses on live monitoring, health_check on connection status, and connect on establishing connections. Even similar-sounding tools like analyze_impact and execute_query are well-differentiated.
All tool names follow a consistent verb_noun in snake_case pattern (e.g., analyze_impact, configuration_review, database_health). The few exceptions like 'connect' and 'disconnect' are standard naming conventions and do not break consistency.
With 21 tools, the set is slightly larger than the typical 3-15 range but fully justified by the comprehensive PostgreSQL DBA functionality covered. Each tool has a distinct purpose, so the count is appropriate for the domain.
The tool set covers virtually all major PostgreSQL administration aspects: connection management, health monitoring, query analysis/optimization, schema discovery, maintenance, data quality, security, replication, configuration, and auditing. No obvious gaps are present for a DBA assistant.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/snss10/DBeast'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
