Skip to main content
Glama
deenesjakoruzh
call518

MCP PostgreSQL Operations

by call518
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP Server for PostgreSQL Operations and Monitoring

License: MIT Python Docker Pulls PostgreSQL Nerq Trust Score BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Architecture & Internal (DeepWiki)

Ask DeepWiki

Related MCP server: Postgres MCP Pro

Overview

MCP-PostgreSQL-Ops is a professional MCP server for PostgreSQL database operations, monitoring, and management. Supports PostgreSQL 12-18 with comprehensive database analysis, performance monitoring, and intelligent maintenance recommendations through natural language queries. Most features work independently, but advanced query analysis capabilities are enhanced when pg_stat_statements and (optionally) pg_stat_monitor extensions are installed.

Features

  • ✅ Zero Configuration: Works with PostgreSQL 12-18 out-of-the-box with automatic version detection.

  • ✅ Natural Language: Ask questions like "Show me slow queries" or "Analyze table bloat."

  • ✅ Production Safe: Read-only operations, RDS/Aurora compatible with regular user permissions.

  • ✅ Extension Enhanced: Optional pg_stat_statements and pg_stat_monitor for advanced query analytics.

  • ✅ Comprehensive Database Monitoring: Performance analysis, bloat detection, and maintenance recommendations.

  • ✅ Smart Query Analysis: Slow query identification with pg_stat_statements and pg_stat_monitor integration.

  • ✅ Schema & Relationship Discovery: Database structure exploration with detailed relationship mapping.

  • ✅ VACUUM & Autovacuum Intelligence: Real-time maintenance monitoring and effectiveness analysis.

  • ✅ Multi-Database Operations: Seamless cross-database analysis and monitoring.

  • ✅ Enterprise-Ready: Safe read-only operations with RDS/Aurora compatibility.

  • ✅ Developer-Friendly: Simple codebase for easy customization and tool extension.

🔧 Advanced Capabilities

  • Version-aware I/O statistics (enhanced on PostgreSQL 16+, byte columns on PG 18+).

  • Real-time connection and lock monitoring.

  • Background process and checkpoint analysis.

  • Replication status and WAL monitoring.

  • Database capacity and bloat analysis.

  • Wait event catalog with descriptions (PG 17+).

  • WAL summarizer monitoring for incremental backups (PG 17+).

  • Async I/O subsystem monitoring (PG 18+).

  • Per-backend I/O and WAL statistics (PG 18+).

Tool Usage Examples

📸 More Examples with Screenshots →

MCP-PostgreSQL-Ops Usage Screenshot

MCP-PostgreSQL-Ops Usage Screenshot

⭐ Quickstart (5 minutes)

Note: The postgresql container included in docker-compose.yml is intended for quickstart testing purposes only. You can connect to your own PostgreSQL instance by adjusting the environment variables as needed.

If you want to use your own PostgreSQL instance instead of the built-in test container:

  • Update the target PostgreSQL connection information in your .env file (see POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB).

  • In docker-compose.yml, comment out (disable) the postgres and postgres-init-extensions containers to avoid starting the built-in test database.

Flow Diagram of Quickstart/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Environment Setup

Note: While superuser privileges provide access to all databases and system information, the MCP server also works with regular user permissions for basic monitoring tasks.

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### Check and modify .env file
cp .env.example .env
vim .env
### No need to modify defaults, but if using your own PostgreSQL server, edit below:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # External port for host access (mapped to internal 5432)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.

Note: PGDATA=/data/db is preconfigured for the Percona PostgreSQL Docker image, which requires this specific path for proper write permissions.

2. Start Demo Containers

# Start all containers including built-in PostgreSQL for testing
docker-compose up -d

# Alternative: If using your own PostgreSQL instance
# Comment out postgres and postgres-init-extensions services in docker-compose.yml
# Then use the custom configuration:
# docker-compose -f docker-compose.custom-db.yml up -d

⏰ Wait for Environment Setup: The initial environment setup takes a few minutes as containers are started in sequence:

  1. PostgreSQL container starts first with database initialization

  2. PostgreSQL Extensions container installs extensions and creates comprehensive test data (~83K records)

  3. MCP Server and MCPO Proxy containers start after PostgreSQL is ready

  4. OpenWebUI container starts last and may take additional time to load the web interface

💡 Tip: Wait 2-3 minutes after running docker-compose up -d before accessing OpenWebUI to ensure all services are fully initialized.

🔍 Check Container Status (Optional):

# Monitor container startup progress
docker-compose logs -f

# Check if all containers are running
docker-compose ps

# Verify PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"

3. Access to OpenWebUI

http://localhost:3003/

  • The list of MCP tool features provided by swagger can be found in the MCPO API Docs URL.

    • e.g: http://localhost:8003/docs

4. Registering the Tool in OpenWebUI

📌 Note: Web-UI configuration instructions are based on OpenWebUI v0.6.22. Menu locations and settings may differ in newer versions.

  1. logging in to OpenWebUI with an admin account

  2. go to "Settings" → "Tools" from the top menu.

  3. Enter the postgresql-ops Tool address (e.g., http://localhost:8003/postgresql-ops) to connect MCP Tools.

  4. Setup Ollama or OpenAI.

5. Complete!

Congratulations! Your MCP PostgreSQL Operations server is now ready for use. You can start exploring your databases with natural language queries.

🚀 Try These Example Queries:

  • "Show me the current active connections"

  • "What are the slowest queries in the system?"

  • "Analyze table bloat across all databases"

  • "Show me database size information"

  • "What tables need VACUUM maintenance?"

📖 Next Steps:

(NOTE) Sample Test Data Overview

The create-test-data.sql script is executed by the postgres-init-extensions container (defined in docker-compose.yml) on first startup, automatically generating comprehensive test databases for MCP tool testing:

Database

Purpose

Schema & Tables

Scale

ecommerce

E-commerce system

public: categories, products, customers, orders, order_items

10 categories, 500 products, 100 customers, 200 orders, 400 order items

analytics

Analytics & reporting

public: page_views, sales_summary

1,000 page views, 30 sales summaries

inventory

Warehouse management

public: suppliers, inventory_items, purchase_orders

10 suppliers, 100 items, 50 purchase orders

hr_system

HR management

public: departments, employees, payroll

5 departments, 50 employees, 150 payroll records

Test users created: app_readonly, app_readwrite, analytics_user, backup_user

Optimized for testing: Intentional table bloat, various indexes (used/unused), time-series data, complex relationships

Tool Compatibility Matrix

Automatic Adaptation: All tools work transparently across supported versions - no configuration needed!

🟢 Extension-Independent Tools (No Extensions Required)

Tool Name

Extensions Required

PG 12

PG 13

PG 14

PG 15

PG 16

PG 17

PG 18

System Views/Tables Used

get_server_info

❌ None

✅

✅

✅

✅

✅

✅

✅

version(), pg_extension

get_active_connections

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_activity

get_postgresql_config

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_settings

get_database_list

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_database

get_table_list

❌ None

✅

✅

✅

✅

✅

✅

✅

information_schema.tables

get_table_schema_info

❌ None

✅

✅

✅

✅

✅

✅

✅

information_schema.*, pg_indexes

get_database_schema_info

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_namespace, pg_class, pg_proc

get_table_relationships

❌ None

✅

✅

✅

✅

✅

✅

✅

information_schema.* (constraints)

get_user_list

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_user, pg_roles

get_index_usage_stats

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_indexes

get_database_size_info

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_database_size()

get_table_size_info

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_total_relation_size()

get_vacuum_analyze_stats

❌ None

✅

✅

✅

✅

✅

✅

✅ Enhanced

pg_stat_user_tables

get_current_database_info

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_database, current_database()

get_table_bloat_analysis

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_tables

get_database_bloat_overview

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_tables

get_autovacuum_status

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_tables

get_autovacuum_activity

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_tables

get_running_vacuum_operations

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_activity

get_vacuum_effectiveness_analysis

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_user_tables

get_lock_monitoring

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_locks, pg_stat_activity

get_wal_status

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_current_wal_lsn()

get_database_stats

❌ None

✅

✅

✅

✅

✅

✅

✅ Enhanced

pg_stat_database

get_table_io_stats

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_statio_user_tables

get_index_io_stats

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_statio_user_indexes

get_database_conflicts_stats

❌ None

✅

✅

✅

✅

✅

✅

✅

pg_stat_database_conflicts

🚀 Version-Aware Tools (Auto-Adapting)

Tool Name

Extensions Required

PG 12

PG 13

PG 14

PG 15

PG 16

PG 17

PG 18

Special Features

get_io_stats

❌ None

✅ Basic

✅ Basic

✅ Basic

✅ Basic

✅ Enhanced

✅ Enhanced

✅ Enhanced

PG16+: pg_stat_io support; PG18+: byte columns

get_bgwriter_stats

❌ None

✅

✅

✅

✅

✅

✅ Special

✅ Enhanced

PG17: Separate checkpointer stats; PG18+: num_done, slru_written

get_replication_status

❌ None

✅ Compatible

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

PG13+: wal_status, safe_wal_size; PG16+: enhanced WAL receiver; PG17+: invalidation_reason, inactive_since

get_all_tables_stats

❌ None

✅ Compatible

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

PG13+: n_ins_since_vacuum tracking for vacuum maintenance optimization

get_user_functions_stats

⚙️ Config Required

✅

✅

✅

✅

✅

✅

✅

Requires track_functions=pl

get_wait_events

❌ None

✅ Fallback

✅ Fallback

✅ Fallback

✅ Fallback

✅ Fallback

✅ Native

✅ Native

PG17+: pg_wait_events catalog; PG12-16: fallback to pg_stat_activity current waits

get_wal_summarizer_status

❌ None

❌

❌

❌

❌

❌

✅

✅

PG17+: WAL summarizer monitoring for incremental backups

get_async_io_status

❌ None

❌

❌

❌

❌

❌

❌

✅

PG18+: pg_aios async I/O subsystem monitoring

get_per_backend_io_stats

❌ None

❌

❌

❌

❌

❌

❌

✅

PG18+: Per-backend I/O and WAL statistics

🟡 Extension-Dependent Tools (Extensions Required)

Tool Name

Required Extension

PG 12

PG 13

PG 14

PG 15

PG 16

PG 17

PG 18

Notes

get_pg_stat_statements_top_queries

pg_stat_statements

✅ Compatible

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

PG12: total_time → total_exec_time; PG13+: native total_exec_time; PG17+: stats_since

get_pg_stat_monitor_recent_queries

pg_stat_monitor

✅ Compatible

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

✅ Enhanced

PG12: total_time → total_exec_time; PG13+: native total_exec_time

🆕 Version-Specific Features

PostgreSQL 17

  • pg_wait_events view: Native wait event catalog with descriptions (used by get_wait_events)

  • WAL summarizer: Monitoring for incremental backup support (used by get_wal_summarizer_status)

  • Replication slot enhancements: invalidation_reason and inactive_since columns (used by get_replication_status)

  • pg_stat_statements stats_since: Track when statistics were last reset (used by get_pg_stat_statements_top_queries)

  • VACUUM progress: Index vacuum tracking in progress views (future enhancement for get_running_vacuum_operations)

PostgreSQL 18

  • pg_aios view: Async I/O subsystem monitoring (used by get_async_io_status)

  • Per-backend I/O stats: Individual backend I/O and WAL statistics (used by get_per_backend_io_stats)

  • VACUUM/ANALYZE time columns: total_vacuum_time, total_autovacuum_time, total_analyze_time, total_autoanalyze_time cumulative timing (used by get_vacuum_analyze_stats)

  • pg_stat_io byte columns: read_bytes, write_bytes, extend_bytes (used by get_io_stats)

  • Parallel worker stats: parallel_workers_launched, parallel_workers_to_launch (used by get_database_stats)

  • Checkpointer enhancements: num_done, slru_written columns (used by get_bgwriter_stats)

Usage Examples

Claude Desktop Integration

(Recommended) Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

"Show all active connections in a clear and readable html table format." Claude Desktop Integration

"Show all relationships for customers table in ecommerce database as a Mermaid diagram." Claude Desktop Integration

Installation

From PyPI (Recommended)

# Install the package
pip install mcp-postgresql-ops

# Or with uv (faster)
uv add mcp-postgresql-ops

# Verify installation
mcp-postgresql-ops --help

From Source

# Clone the repository
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

# Install with uv (recommended)
uv sync
uv run mcp-postgresql-ops --help

# Or with pip
pip install -e .
mcp-postgresql-ops --help

MCP Configuration

Claude Desktop Configuration

(Optional) Run with Local Source:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_postgresql_ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

Run MCP-Server as Standalon

/w Pypi and uvx (Recommended)

# Stdio mode
uvx --python 3.12 mcp-postgresql-ops \
  --type stdio

# HTTP mode
uvx --python 3.12 mcp-postgresql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

(Option) Configure Multiple PostgreSQL Instances

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

/w Local Source

# Method 1: Module execution (for development, requires PYTHONPATH)
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type stdio

# Method 2: Direct script (after uv installation in project directory)
uv run mcp-postgresql-ops \
  --type stdio

# Method 3: Installed package script (after pip/uv install)
mcp-postgresql-ops \
  --type stdio

# HTTP mode examples:
# Development mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

# Production mode (after installation)
mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

CLI Arguments

  • --type: Transport type (stdio or streamable-http) - Default: stdio

  • --host: Host address for HTTP transport - Default: 127.0.0.1

  • --port: Port number for HTTP transport - Default: 8000

  • --auth-enable: Enable Bearer token authentication for streamable-http mode - Default: false

  • --secret-key: Secret key for Bearer token authentication (required when auth enabled)

  • --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) - Default: INFO

Environment Variables

Variable

Description

Default

Project Default

PYTHONPATH

Python module search path (only needed for development mode)

-

/app/src

MCP_LOG_LEVEL

Server logging verbosity (DEBUG, INFO, WARNING, ERROR)

INFO

INFO

FASTMCP_TYPE

MCP transport protocol (stdio for CLI, streamable-http for web)

stdio

streamable-http

FASTMCP_HOST

HTTP server bind address (0.0.0.0 for all interfaces)

127.0.0.1

0.0.0.0

FASTMCP_PORT

HTTP server port for MCP communication

8000

8000

REMOTE_AUTH_ENABLE

Enable Bearer token authentication for streamable-http mode (Default: false if undefined/null/empty)

false

false

REMOTE_SECRET_KEY

Secret key for Bearer token authentication (required when auth enabled)

-

your-secret-key-here

PGSQL_VERSION

PostgreSQL major version for Docker image selection

17

17

PGDATA

PostgreSQL data directory inside Docker container (Do not modify)

/var/lib/postgresql/data

/data/db

POSTGRES_HOST

PostgreSQL server hostname or IP address

127.0.0.1

host.docker.internal

POSTGRES_PORT

PostgreSQL server port number

5432

15432

POSTGRES_USER

PostgreSQL connection username (needs read permissions)

postgres

postgres

POSTGRES_PASSWORD

PostgreSQL user password (supports special characters)

changeme!@34

changeme!@34

POSTGRES_DB

Default database name for connections

testdb

ecommerce

POSTGRES_MAX_CONNECTIONS

PostgreSQL max_connections configuration parameter

200

200

DOCKER_EXTERNAL_PORT_OPENWEBUI

Host port mapping for Open WebUI container

8080

3003

DOCKER_EXTERNAL_PORT_MCP_SERVER

Host port mapping for MCP server container

8080

18003

DOCKER_EXTERNAL_PORT_MCPO_PROXY

Host port mapping for MCPO proxy container

8000

8003

DOCKER_INTERNAL_PORT_POSTGRESQL

PostgreSQL container internal port

5432

5432

Note: POSTGRES_DB serves as the default target database for operations when no specific database is specified. In Docker environments, if set to a non-default name, this database will be automatically created during initial PostgreSQL startup.

Port Configuration: The built-in PostgreSQL container uses port mapping 15432:5432 where:

  • POSTGRES_PORT=15432: External port for host access and MCP server connections

  • DOCKER_INTERNAL_PORT_POSTGRESQL=5432: Internal container port (PostgreSQL default)

  • When using external PostgreSQL servers, set POSTGRES_PORT to match your server's actual port

Prerequisites

Required PostgreSQL Extensions

For more details, see the ## Tool Compatibility Matrix

Note: Most MCP tools work without any PostgreSQL extensions. section below. Some advanced performance analysis tools require the following extensions:

-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

Quick Setup: For new PostgreSQL installations, add to postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'

Then restart PostgreSQL and run the CREATE EXTENSION commands above.

  • pg_stat_statements is required only for slow query analysis tools.

  • pg_stat_monitor is optional and used for real-time query monitoring.

  • All other tools work without these extensions.

Minimum Requirements

  • PostgreSQL 12+ (tested with PostgreSQL 17 and 18)

  • Python 3.12

  • Network access to PostgreSQL server

  • Read permissions on system catalogs

Required PostgreSQL Configuration

⚠️ Statistics Collection Settings: Some MCP tools require specific PostgreSQL configuration parameters to collect statistics. Choose one of the following configuration methods:

Tools affected by these settings:

  • get_user_functions_stats: Requires track_functions = pl or track_functions = all

  • get_table_io_stats & get_index_io_stats: More accurate timing with track_io_timing = on

  • get_database_stats: Enhanced I/O timing with track_io_timing = on

Verification: After applying any method, verify the settings:

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

Method 1: postgresql.conf (Recommended for Self-Managed PostgreSQL)

Add the following to your postgresql.conf:

# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on

# Required for function statistics tools
track_functions = pl    # Enables PL/pgSQL function statistics collection

# Optional but recommended for accurate I/O timing
track_io_timing = on    # Enables I/O timing statistics collection

Then restart PostgreSQL server.

Method 2: PostgreSQL Startup Parameters

For Docker or command-line PostgreSQL startup:

# Docker example
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# Direct postgres command
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

Method 3: Dynamic Configuration (AWS RDS, Azure, GCP, Managed Services)

For managed PostgreSQL services where you cannot modify postgresql.conf, use SQL commands to change settings dynamically:

-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';

-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';

-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();

Alternative for session-level testing:

-- Set for current session only (temporary)
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

Note: When using command-line tools, run each SQL statement separately to avoid transaction block errors.

RDS/Aurora Compatibility

  • This server is read-only and works with regular roles on RDS/Aurora. For advanced analysis enable pg_stat_statements; pg_stat_monitor is not available on managed engines.

  • On RDS/Aurora, prefer DB Parameter Group over ALTER SYSTEM for persistent settings.

    -- Verify preload setting
SHOW shared_preload_libraries;

-- Enable extension in target DB
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Recommended visibility for monitoring
GRANT pg_read_all_stats TO <app_user>;

Example Queries

🟢 Extension-Independent Tools (Always Available)

  • get_server_info

    • "Show PostgreSQL server version and extension status."

    • "Check if pg_stat_statements is installed."

  • get_active_connections

    • "Show all active connections."

    • "List current sessions with database and user."

  • get_postgresql_config

    • "Show all PostgreSQL configuration parameters."

    • "Find all memory-related configuration settings."

  • get_database_list

    • "List all databases and their sizes."

    • "Show database list with owner information."

  • get_table_list

    • "List all tables in the ecommerce database."

    • "Show table sizes in the public schema."

  • get_table_schema_info

    • "Show detailed schema information for the customers table in ecommerce database."

    • "Get column details and constraints for products table in ecommerce database."

    • "Analyze table structure with indexes and foreign keys for orders table in sales schema of ecommerce database."

    • "Show schema overview for all tables in public schema of inventory database."

    • 📋 Features: Column types, constraints, indexes, foreign keys, table metadata

    • ⚠️ Required: database_name parameter must be specified

  • get_database_schema_info

    • "Show all schemas in ecommerce database with their contents."

    • "Get detailed information about sales schema in ecommerce database."

    • "Analyze schema structure and permissions for inventory database."

    • "Show schema overview with table counts and sizes for hr_system database."

    • 📋 Features: Schema owners, permissions, object counts, sizes, contents

    • ⚠️ Required: database_name parameter must be specified

  • get_table_relationships

    • "Show all relationships for customers table in ecommerce database."

    • "Analyze foreign key relationships for orders table in sales schema of ecommerce database."

    • "Get database-wide relationship overview for ecommerce database."

    • "Find all tables that reference products table in ecommerce database."

    • "Show cross-schema relationships in inventory database."

    • 📋 Features: Foreign key relationships (inbound/outbound), cross-schema dependencies, constraint details

    • ⚠️ Required: database_name parameter must be specified

    • 💡 Usage: Leave table_name empty for database-wide relationship analysis

  • get_user_list

    • "List all database users and their roles."

    • "Show user permissions for a specific database."

  • get_index_usage_stats

    • "Analyze index usage efficiency."

    • "Find unused indexes in the current database."

  • get_database_size_info

    • "Show database capacity analysis."

    • "Find the largest databases by size."

  • get_table_size_info

    • "Show table and index size analysis."

    • "Find largest tables in a specific schema."

  • get_vacuum_analyze_stats

    • "Show recent VACUUM and ANALYZE operations."

    • "List tables needing VACUUM."

  • get_current_database_info

    • "What database am I connected to?"

    • "Show current database information and connection details."

    • "Display database encoding, collation, and size information."

    • 📋 Features: Database name, encoding, collation, size, connection limits

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

  • get_table_bloat_analysis

    • "Analyze table bloat in the current database."

    • "Show dead tuple ratios and bloat estimates for user_logs table pattern."

    • "Find tables with high bloat that need VACUUM maintenance."

    • "Analyze bloat in specific schema with minimum 100 dead tuples."

    • 📋 Features: Dead tuple ratios, bloat size estimates, VACUUM recommendations, pattern filtering

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

    • 💡 Usage: Extension-Independent approach using pg_stat_user_tables

  • get_database_bloat_overview

    • "Show database-wide bloat summary by schema."

    • "Get high-level view of storage efficiency across all schemas."

    • "Identify schemas requiring maintenance attention."

    • 📋 Features: Schema-level aggregation, total bloat estimates, maintenance status

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

  • get_autovacuum_status

    • "Check autovacuum configuration and trigger conditions."

    • "Show tables needing immediate autovacuum attention."

    • "Analyze autovacuum threshold percentages for public schema."

    • "Find tables approaching autovacuum trigger points."

    • 📋 Features: Trigger threshold analysis, urgency classification, configuration status

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

    • 💡 Usage: Extension-Independent autovacuum monitoring using pg_stat_user_tables

  • get_autovacuum_activity

    • "Show autovacuum activity patterns for the last 48 hours."

    • "Monitor autovacuum execution frequency and timing."

    • "Find tables with irregular autovacuum patterns."

    • "Analyze recent autovacuum and autoanalyze history."

    • 📋 Features: Activity patterns, execution frequency, timing analysis

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

    • 💡 Usage: Historical autovacuum pattern analysis

  • get_running_vacuum_operations

    • "Show currently running VACUUM and ANALYZE operations."

    • "Monitor active maintenance operations and their progress."

    • "Check if any VACUUM operations are blocking queries."

    • "Find long-running maintenance operations."

    • 📋 Features: Real-time operation status, elapsed time, impact level, process details

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

    • 💡 Usage: Real-time maintenance monitoring using pg_stat_activity

  • get_vacuum_effectiveness_analysis

    • "Analyze VACUUM effectiveness and maintenance patterns."

    • "Compare manual VACUUM vs autovacuum efficiency."

    • "Find tables with suboptimal maintenance patterns."

    • "Check VACUUM frequency vs table activity ratios."

    • 📋 Features: Maintenance pattern analysis, effectiveness assessment, DML-to-VACUUM ratios

    • 🔧 PostgreSQL 12-18: Fully compatible, no extensions required

    • 💡 Usage: Strategic VACUUM analysis using existing statistics

  • get_lock_monitoring

    • "Show all current locks and blocked sessions."

    • "Show only blocked sessions with granted=false filter."

    • "Monitor locks by specific user with username filter."

    • "Check exclusive locks with mode filter."

  • get_wal_status

    • "Show WAL status and archiving information."

    • "Monitor WAL generation and current LSN position."

  • get_replication_status

    • "Check replication connections and lag status."

    • "Monitor replication slots and WAL receiver status."

  • get_database_stats

    • "Show comprehensive database performance metrics."

    • "Analyze transaction commit ratios and I/O statistics."

    • "Monitor buffer cache hit ratios and temporary file usage."

  • get_bgwriter_stats

    • "Analyze checkpoint performance and timing."

    • "Show me checkpoint performance."

    • "Show background writer efficiency statistics."

    • "Monitor buffer allocation and fsync patterns."

  • get_user_functions_stats

    • "Analyze user-defined function performance."

    • "Show function call counts and execution times."

    • "Identify performance bottlenecks in custom functions."

    • ⚠️ Requires: track_functions = pl in postgresql.conf

  • get_table_io_stats

    • "Analyze table I/O performance and buffer hit ratios."

    • "Identify tables with poor buffer cache performance."

    • "Monitor TOAST table I/O statistics."

    • 💡 Enhanced with: track_io_timing = on for accurate timing

  • get_index_io_stats

    • "Show index I/O performance and buffer efficiency."

    • "Identify indexes causing excessive disk I/O."

    • "Monitor index cache-friendliness patterns."

    • 💡 Enhanced with: track_io_timing = on for accurate timing

  • get_database_conflicts_stats

    • "Check replication conflicts on standby servers."

    • "Analyze conflict types and resolution statistics."

    • "Monitor standby server query cancellation patterns."

    • "Monitor WAL generation and current LSN position."

  • get_replication_status

    • "Check replication connections and lag status."

    • "Monitor replication slots and WAL receiver status."

🚀 Version-Aware Tools (Auto-Adapting)

  • get_io_stats (New!)

    • "Show comprehensive I/O statistics." (PostgreSQL 16+ provides detailed breakdown)

    • "Analyze I/O statistics."

    • "Analyze buffer cache efficiency and I/O timing."

    • "Monitor I/O patterns by backend type and context."

    • 📈 PG16+: Full pg_stat_io with timing, backend types, and contexts

    • 📊 PG12-15: Basic pg_statio_* fallback with buffer hit ratios

  • get_bgwriter_stats (Enhanced!)

    • "Show background writer and checkpoint performance."

    • 📈 PG17+: Separate checkpointer and bgwriter statistics via pg_stat_checkpointer

    • 📊 PG12-16: Combined bgwriter stats (includes checkpointer data)

  • get_server_info (Enhanced!)

    • "Show server version and compatibility features."

    • "Check server compatibility."

    • "Check what MCP tools are available on this PostgreSQL version."

    • "Displays feature availability matrix and upgrade recommendations."

  • get_all_tables_stats (Enhanced!)

    • "Show comprehensive statistics for all tables." (version-compatible for PG12-18)

    • "Include system tables with include_system=true parameter."

    • "Analyze table access patterns and maintenance needs."

    • 📈 PG13+: Tracks insertions since vacuum (n_ins_since_vacuum) for optimal maintenance scheduling

    • 📊 PG12: Compatible mode with NULL for unsupported columns

  • get_wait_events (New!)

    • "Show wait event types and descriptions."

    • "What wait events are available on this PostgreSQL version?"

    • 📈 PG17+: Native pg_wait_events catalog with full descriptions

    • 📊 PG12-16: Fallback to pg_stat_activity current waits grouped by type

  • get_wal_summarizer_status (New! PG 17+)

    • "Show WAL summarizer status for incremental backups."

    • "Monitor WAL summarization progress."

    • 📈 PG17+: WAL summarizer monitoring via pg_get_wal_summarizer_state()

    • ❌ PG12-16: Not available (returns informational message)

  • get_async_io_status (New! PG 18+)

    • "Show async I/O subsystem status."

    • "Monitor pg_aios for async I/O operations."

    • 📈 PG18+: pg_aios view for async I/O monitoring

    • ❌ PG12-17: Not available (returns informational message)

  • get_per_backend_io_stats (New! PG 18+)

    • "Show per-backend I/O and WAL statistics."

    • "Analyze I/O patterns by individual backend process."

    • 📈 PG18+: Per-backend I/O stats with WAL statistics

    • ❌ PG12-17: Not available (returns informational message)

🟡 Extension-Dependent Tools

  • get_pg_stat_statements_top_queries (Requires pg_stat_statements)

    • "Show top 10 slowest queries."

    • "Analyze slow queries in the inventory database."

    • 📈 Version-Compatible: PG12 uses total_time → total_exec_time mapping; PG13+ uses native columns

    • 💡 Cross-Version: Automatically adapts query structure for PostgreSQL 12-18 compatibility

  • get_pg_stat_monitor_recent_queries (Optional, uses pg_stat_monitor)

    • "Show recent queries in real time."

    • "Monitor query activity for the last 5 minutes."

    • 📈 Version-Compatible: PG12 uses total_time → total_exec_time mapping; PG13+ uses native columns

    • 💡 Cross-Version: Automatically adapts query structure for PostgreSQL 12-18 compatibility

💡 Pro Tip: All tools support multi-database operations using the database_name parameter. This allows PostgreSQL superusers to analyze and monitor multiple databases from a single MCP server instance.

Troubleshooting

Connection Issues

  1. Check PostgreSQL server status

  2. Verify connection parameters in .env file

  3. Ensure network connectivity

  4. Check user permissions

Extension Errors

  1. Run get_server_info to check extension status

  2. Install missing extensions:

    CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;

  3. Restart PostgreSQL if needed

Configuration Issues

  1. "No data found" for function statistics: Check track_functions setting

    SHOW track_functions;  -- Should be 'pl' or 'all'

    Quick fix for managed services (AWS RDS, etc.):

    ALTER SYSTEM SET track_functions = 'pl';
SELECT pg_reload_conf();

  2. Missing I/O timing data: Enable timing collection

    SHOW track_io_timing;  -- Should be 'on'

    Quick fix:

    ALTER SYSTEM SET track_io_timing = 'on';
SELECT pg_reload_conf();

  3. Apply configuration changes:

    • Self-managed: Add settings to postgresql.conf and restart server

    • Managed services: Use ALTER SYSTEM SET + SELECT pg_reload_conf()

    • Temporary testing: Use SET parameter = value for current session

    • Generate some database activity to populate statistics

Performance Issues

  1. Use limit parameters to reduce result size

  2. Run monitoring during off-peak hours

  3. Check database load before running analysis

Version Compatibility Issues

For more details, see the ## Tool Compatibility Matrix

  1. Run compatibility check first:

    # "Use get_server_info to check version and available features"

  2. Understanding feature availability:

    • PostgreSQL 18: All features including async I/O, VACUUM timing, per-backend stats

    • PostgreSQL 17: Separate checkpointer stats, wait events, WAL summarizer

    • PostgreSQL 16: pg_stat_io view

    • PostgreSQL 14+: Parallel query tracking

    • PostgreSQL 12-13: Core functionality only

  3. If a tool shows "Not Available":

    • Feature requires newer PostgreSQL version

    • Tool will automatically use best available alternative

    • Consider upgrading PostgreSQL for enhanced monitoring

Development

Testing & Development

# Clone and setup for development
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops
uv sync

# Test with MCP Inspector (loads .env automatically)
./run-mcp-inspector-local.sh

# Direct execution methods:
# 1. Using uv run (recommended for development)
uv run mcp-postgresql-ops --log-level DEBUG

# 2. Module execution (requires PYTHONPATH)
PYTHONPATH=src python -m mcp_postgresql_ops --log-level DEBUG

# 3. After installation
mcp-postgresql-ops --log-level DEBUG

# Test version compatibility (requires different PostgreSQL versions)
# Modify POSTGRES_HOST in .env to point to different versions

Running Tests

Two test suites are available:

Suite

File

Requires Docker

Unit tests (version compatibility logic)

tests/test_version_compat.py

No

Integration tests (all tools × PG 12–18)

tests/test_tools_integration.py

Yes

Option A — Run everything with a single command (recommended)

uv run pytest automatically starts the Docker test containers (PG 12–18), waits for them to be fully initialized, runs all tests, then tears everything down.

# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v

# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v

# Integration tests only
uv run pytest tests/test_tools_integration.py -v

Option B — Manual control via helper script

# Full run: docker up → wait → pytest → docker down
uv run python scripts/run-tests.py

# Pass pytest options directly
uv run python scripts/run-tests.py -v --tb=short

# Keep containers running after tests (for debugging)
uv run python scripts/run-tests.py --no-cleanup

Note: Docker must be running. The test stack uses ports 5412–5418 (PG 12–18).


### Version Compatibility Testing

The MCP server automatically adapts to PostgreSQL versions 12-18. To test across versions:

1. **Set up test databases**: Different PostgreSQL versions (12, 14, 15, 16, 17, 18)
2. **Run compatibility tests**: Point to each version and verify tool behavior
3. **Check feature detection**: Ensure proper version detection and feature availability
4. **Verify fallback behavior**: Confirm graceful degradation on older versions

---

## Security Notes

- All tools are **read-only** - no data modification capabilities
- Sensitive information (passwords) are masked in outputs
- No direct SQL execution - only predefined queries
- Follows principle of least privilege

---

## Contributing

🤝 **Got ideas? Found bugs? Want to add cool features?**

We're always excited to welcome new contributors! Whether you're fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better.

**Ways to contribute:**
- 🐛 Report issues or bugs
- 💡 Suggest new PostgreSQL monitoring features
- 📝 Improve documentation 
- 🚀 Submit pull requests
- ⭐ Star the repo if you find it useful!

**Pro tip:** The codebase is designed to be super friendly for adding new tools. Check out the existing `@mcp.tool()` functions in `mcp_main.py`.

---

## MCPO Swagger Docs

> [MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs

![MCPO Swagger APIs](img/screenshot-swagger-api.png)

---

## 🔐 Security & Authentication

### Bearer Token Authentication

For `streamable-http` mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

> **Default Policy**: `REMOTE_AUTH_ENABLE` defaults to `false` if undefined, null, or empty. This ensures backward compatibility and prevents startup errors when the variable is not set.

#### Configuration

**Enable Authentication:**

```bash
# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345

Or via CLI:

# Module method
python -m mcp_postgresql_ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

# Script method
mcp-postgresql-ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

Security Levels

  1. stdio mode (Default): Local-only access, no authentication needed

  2. streamable-http + REMOTE_AUTH_ENABLE=false: Remote access without authentication ⚠️ NOT RECOMMENDED for production

  3. streamable-http + REMOTE_AUTH_ENABLE=true: Remote access with Bearer token authentication ✅ RECOMMENDED for production

Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer my-test-secret-key-12345"
      }
    }
  }
}

Security Best Practices

  • Always enable authentication when using streamable-http mode in production

  • Use strong, randomly generated secret keys (32+ characters recommended)

  • Use HTTPS when possible (configure reverse proxy with SSL/TLS)

  • Restrict network access using firewalls or network policies

  • Rotate secret keys regularly for enhanced security

  • Monitor access logs for unauthorized access attempts

Error Handling

When authentication fails, the server returns:

  • 401 Unauthorized for missing or invalid tokens

  • Detailed error messages in JSON format for debugging

🚀 Adding Custom Tools

This MCP server is designed for easy extensibility. Follow these 4 simple steps to add your own custom tools:

Step-by-Step Guide

1. Add Helper Functions (Optional)

Add reusable data functions to src/mcp_postgresql_ops/functions.py:

async def get_your_custom_data(target_database: str = None, limit: int = 20) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    try:
        # Example implementation - adapt to your PostgreSQL needs
        query = """
        SELECT 
            schemaname,
            tablename,
            attname as column_name,
            n_distinct,
            most_common_vals,
            most_common_freqs
        FROM pg_stats 
        WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        ORDER BY schemaname, tablename, attname
        LIMIT $1
        """
        
        results = await execute_query(query, [limit], database=target_database)
        return results
        
    except Exception as e:
        logger.error(f"Failed to get custom data: {e}")
        raise

2. Create Your MCP Tool

Add your tool function to src/mcp_postgresql_ops/mcp_main.py:

@mcp.tool()
async def get_your_custom_analysis(limit: int = 50, database_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Exact Functionality]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Database monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Use Cases]:
    - When user asks "your specific analysis request"
    - Your PostgreSQL-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        database_name: Target database name (optional, uses default if not specified)
    
    Returns:
        Formatted analysis results
    """
    try:
        # Always validate input limits
        limit = max(1, min(limit, 100))
        
        # Get your custom data
        results = await get_your_custom_data(target_database=database_name, limit=limit)
        
        if not results:
            return "No data found for custom analysis."
        
        # Format and return results
        return format_table_data(results, f"Custom Analysis Results (Top {len(results)})")
        
    except Exception as e:
        logger.error(f"Failed to get custom analysis: {e}")
        return f"Error: {str(e)}"

3. Update Imports

Add your helper function to the imports section in src/mcp_postgresql_ops/mcp_main.py (around line 30):

from .functions import (
    execute_query,
    execute_single_query,
    format_table_data,
    format_bytes,
    format_duration,
    get_server_version,
    check_extension_exists,
    get_pg_stat_statements_data,
    get_pg_stat_monitor_data,
    sanitize_connection_info,
    read_prompt_template,
    parse_prompt_sections,
    get_current_database_name,
    POSTGRES_CONFIG,
    get_your_custom_data,  # Add your new function here
)

4. Update Prompt Template (Recommended)

Add your tool description to src/mcp_postgresql_ops/prompt_template.md for better natural language recognition:

### **Your Custom Analysis Tool**

### X. **get_your_custom_analysis**
**Purpose**: Brief description of what your tool does
**Usage**: "Show me your custom analysis" or "Get custom analysis for database_name"
**Features**: Data aggregation, database monitoring, performance metrics
**Optional**: `database_name` parameter for specific database analysis
**Limit**: Results limited to 1-100 records for performance

5. Test Your Tool

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker stack
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me your custom analysis"
# "Get custom analysis for ecommerce database"
# "Analyze custom data with limit 25"

Important Notes

  • Multi-Database Support: All tools support the optional database_name parameter to target specific databases

  • Input Validation: Always validate limit parameters with max(1, min(limit, 100))

  • Error Handling: Return user-friendly error messages instead of raising exceptions

  • Logging: Use logger.error() for debugging while returning clean error messages to users

  • PostgreSQL Compatibility: Your custom queries should work across PostgreSQL 12-18

  • Extension Dependencies: If your tool requires specific extensions, check availability with check_extension_exists()

Advanced Patterns

For version-aware queries or extension-dependent features, see existing tools like get_pg_stat_statements_top_queries for reference patterns.

That's it! Your custom tool is ready to use with natural language queries through any MCP client.

License

Freely use, modify, and distribute under the MIT License.

⭐ Other Projects

Other MCP servers by the same author:

Available Tools

34 tools
get_active_connectionsA

[Tool Purpose]: Retrieve all active connections and session information on current PostgreSQL server

[Exact Functionality]:

  • Retrieve list of all currently active connected sessions

  • Display user, database, and client address for each connection

  • Include session status and currently executing query information

[Required Use Cases]:

  • When user requests "active connections", "current sessions", "connection status", etc.

  • When server load or performance problem diagnosis is needed

  • When checking connection status of specific users or applications

[Strictly Prohibited Use Cases]:

  • Requests for forceful connection termination or session management

  • Requests for detailed query history of specific sessions

  • Requests for connection security or authentication-related changes

Returns: Information including PID, username, database name, client address, status, and current query

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by specifying what information is returned (PID, username, database name, client address, status, current query) and clarifying it's a read-only monitoring tool (prohibited use cases exclude destructive operations). However, it doesn't mention potential limitations like data freshness, permission requirements, or rate limits, which would be helpful for a monitoring tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) and is front-loaded with purpose. While slightly verbose due to the structured format, every sentence adds value (e.g., prohibited use cases prevent misuse). Minor trimming of redundant phrasing could improve efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (monitoring active connections), no annotations, 0 parameters, and an output schema exists, the description is complete. It explains purpose, functionality, use cases, prohibitions, and return information, providing all necessary context for an agent to understand when and how to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on the tool's functionality and use cases, which adds value beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Retrieve all active connections and session information on current PostgreSQL server' with specific verbs ('retrieve', 'display', 'include') and resources ('active connections', 'session information'). It clearly distinguishes from sibling tools by focusing on connection monitoring rather than table stats, replication, or other PostgreSQL metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., 'When user requests active connections', 'When server load or performance problem diagnosis is needed') and 'Strictly Prohibited Use Cases' (e.g., 'Requests for forceful connection termination', 'Requests for detailed query history of specific sessions'). This gives clear guidance on when to use this tool versus alternatives or when to avoid it entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_all_tables_statsA

[Tool Purpose]: Get comprehensive statistics for all tables (including system tables if requested)

[Exact Functionality]:

  • Show detailed access statistics for all tables in database

  • Include sequential scans, index scans, and tuple operations

  • Provide live/dead tuple estimates and maintenance history

  • Option to include system catalog tables

[Required Use Cases]:

  • When user requests "all tables stats", "complete table statistics", etc.

  • When analyzing overall table usage patterns

  • When investigating table maintenance needs across the database

  • When getting comprehensive database activity overview

[Strictly Prohibited Use Cases]:

  • Requests for table maintenance operations (VACUUM, ANALYZE)

  • Requests for statistics reset or modification

  • Requests for table optimization actions

Args: database_name: Database name to analyze (uses default database if omitted) include_system: Include system tables in results (default: False)

Returns: Comprehensive table statistics including access patterns and maintenance history

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
include_systemNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (read-only statistical analysis), what it includes (system tables optionally), and what it doesn't do (no modifications, maintenance, or optimizations). However, it doesn't mention potential performance impact, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and every sentence adds value. However, it could be slightly more concise by combining some of the use case descriptions, and the 'Args' and 'Returns' sections somewhat duplicate information already covered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (comprehensive statistics analysis), no annotations, and the presence of an output schema, the description provides excellent context. It explains purpose, functionality, use cases, prohibitions, parameters, and return values, making it complete enough for an agent to understand when and how to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining both parameters in detail: 'database_name: Database name to analyze (uses default database if omitted)' and 'include_system: Include system tables in results (default: False)'. This provides clear semantic meaning beyond what the bare schema offers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Get comprehensive statistics for all tables' with specific details about what statistics are included (access statistics, sequential/index scans, tuple operations, live/dead tuple estimates, maintenance history). It distinguishes itself from sibling tools by focusing on comprehensive statistics for all tables rather than specific aspects like bloat analysis, size info, or individual table stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (when user requests all tables stats, analyzing overall usage patterns, investigating maintenance needs, getting database activity overview) and 'Strictly Prohibited Use Cases' (requests for table maintenance operations, statistics reset/modification, optimization actions). This gives clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_autovacuum_activityA

[Tool Purpose]: Monitor recent autovacuum and autoanalyze activity patterns and execution history

[Exact Functionality]:

  • Track recent autovacuum and autoanalyze execution patterns

  • Analyze autovacuum frequency and timing intervals

  • Show tables with most/least autovacuum activity

  • Calculate average time between autovacuum executions

  • Identify tables with irregular autovacuum patterns

[Required Use Cases]:

  • When user requests "autovacuum activity", "autovacuum history", "vacuum patterns", etc.

  • When monitoring autovacuum performance and effectiveness

  • When troubleshooting autovacuum scheduling issues

  • When analyzing autovacuum workload distribution

[Strictly Prohibited Use Cases]:

  • Requests for autovacuum process control or restart

  • Requests for autovacuum configuration modifications

  • Requests for manual vacuum scheduling

Args: database_name: Target database name (uses default database from POSTGRES_DB env var if omitted) schema_name: Schema to analyze (analyzes all user schemas if omitted) hours_back: Time period to analyze in hours (default: 24, max: 168 for 7 days) limit: Maximum number of tables to show (1-100, default: 50)

Returns: Recent autovacuum activity analysis with patterns and timing statistics

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNo
hours_backNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing behavioral traits: it's a monitoring/analysis tool (not for control/modification), specifies time period defaults and limits (24h default, max 168h, limit 1-100), and mentions environmental dependency (POSTGRES_DB env var). It doesn't cover rate limits or auth needs, but provides substantial context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), but somewhat verbose with repetitive phrasing ('autovacuum' appears 15 times). Each sentence earns its place, but could be more concise while maintaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, analysis functionality), no annotations, and an output schema exists (so return values needn't be explained), the description is complete. It covers purpose, usage, exclusions, parameters, and behavioral context adequately for the agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all 4 parameters: database_name (target database with env var fallback), schema_name (scope with default behavior), hours_back (time period with default and max), and limit (range and default). It adds crucial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('monitor', 'track', 'analyze', 'show', 'calculate', 'identify') and resources ('autovacuum and autoanalyze activity patterns and execution history'). It distinguishes from sibling tools like 'get_autovacuum_status' by focusing on patterns and history rather than current status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., monitoring performance, troubleshooting scheduling) and 'Strictly Prohibited Use Cases' (e.g., process control, configuration modifications). It clearly defines when to use this tool versus alternatives for related tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_autovacuum_statusA

[Tool Purpose]: Analyze autovacuum configuration and current maintenance status for tables

[Exact Functionality]:

  • Analyze autovacuum trigger conditions based on dead tuple thresholds

  • Calculate current dead tuple ratios vs autovacuum trigger points

  • Show autovacuum configuration settings per table

  • Identify tables requiring immediate autovacuum attention

  • Estimate next autovacuum execution likelihood

[Required Use Cases]:

  • When user requests "autovacuum status", "autovacuum configuration", "vacuum trigger analysis", etc.

  • When planning autovacuum optimization and tuning

  • When troubleshooting autovacuum performance issues

  • When identifying tables with autovacuum problems

[Strictly Prohibited Use Cases]:

  • Requests for autovacuum configuration changes

  • Requests for manual VACUUM execution

  • Requests for autovacuum process restart or control

Args: database_name: Target database name (uses default database from POSTGRES_DB env var if omitted) schema_name: Schema to analyze (analyzes all user schemas if omitted) table_pattern: Table name pattern to filter (SQL LIKE pattern, e.g., 'user%', '%log%', 'temp_*') limit: Maximum number of tables to analyze (1-100, default: 50)

Returns: Autovacuum configuration status with trigger analysis and maintenance recommendations

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNo
table_patternNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by specifying what the tool does (analysis only) and what it doesn't do (no changes, no manual execution). It discloses behavioral constraints like 'analyzes all user schemas if omitted' and default parameter behavior. However, it doesn't mention potential performance impact of the analysis or any rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), front-loading the purpose, and every sentence earns its place by providing specific guidance or information. No redundant or vague statements are present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (analysis of autovacuum status with 4 parameters), no annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, functionality, usage guidelines, prohibitions, parameter semantics, and return overview, leaving no significant gaps for the agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining all 4 parameters in the Args section, including default behaviors (e.g., 'uses default database from POSTGRES_DB env var if omitted'), filtering logic ('analyzes all user schemas if omitted'), and format details ('SQL LIKE pattern'). It adds meaningful context beyond the bare schema, though it could provide more examples for the table_pattern parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze autovacuum configuration and current maintenance status for tables' with specific functionality details like analyzing trigger conditions, calculating dead tuple ratios, and identifying tables needing attention. It clearly distinguishes from sibling tools like 'get_autovacuum_activity' (which likely shows active operations) and 'get_vacuum_effectiveness_analysis' (which likely evaluates past vacuum performance).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests autovacuum status, planning optimization, troubleshooting) and 'Strictly Prohibited Use Cases' (e.g., configuration changes, manual VACUUM execution, process restart). This gives clear guidance on when to use this tool versus alternatives like configuration modification tools or manual vacuum execution tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bgwriter_statsA

[Tool Purpose]: Analyze background writer and checkpoint performance statistics with version compatibility

[Exact Functionality]:

  • Show checkpoint execution statistics (timed vs requested)

  • Display checkpoint timing information (write and sync times)

  • Provide buffer writing statistics by different processes

  • Analyze background writer performance and efficiency

  • Automatically adapts to PostgreSQL version (15+ uses separate checkpointer view)

[Required Use Cases]:

  • When user requests "checkpoint stats", "bgwriter performance", "buffer stats", etc.

  • When analyzing I/O performance and checkpoint impact

  • When investigating background writer efficiency

  • When troubleshooting checkpoint-related performance issues

[Strictly Prohibited Use Cases]:

  • Requests for checkpoint execution or configuration changes

  • Requests for background writer parameter modifications

  • Requests for statistics reset

Returns: Background writer and checkpoint performance statistics with version-appropriate data

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It does well by describing key behavioral traits: it's a read-only analysis tool (implied by 'show', 'display', 'provide', 'analyze'), it automatically adapts to PostgreSQL version (15+ uses separate checkpointer view), and it returns performance statistics. However, it doesn't mention potential limitations like data freshness, permission requirements, or performance impact of running the tool. With no annotations, this is strong but not perfect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], [Required Use Cases], [Strictly Prohibited Use Cases], Returns). Every sentence earns its place by providing specific guidance or information. Despite being comprehensive, it avoids redundancy and stays focused on helping the agent understand when and how to use this tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has 0 parameters, no annotations, but does have an output schema, the description provides excellent contextual completeness. It explains what the tool does, when to use it, when not to use it, and what it returns. The output schema will handle the return value details, so the description appropriately focuses on usage context rather than output structure. For a parameterless analysis tool, this description is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't waste space discussing parameters that don't exist. It focuses instead on what the tool analyzes and returns, which is the correct approach for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze background writer and checkpoint performance statistics with version compatibility' in the [Tool Purpose] section. It clearly distinguishes this from sibling tools by specifying it focuses on background writer/checkpoint statistics rather than connections, tables, replication, or other database metrics. The description provides specific verbs ('analyze', 'show', 'display', 'provide') and resources ('background writer', 'checkpoint performance statistics').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes both [Required Use Cases] and [Strictly Prohibited Use Cases] sections that provide explicit guidance. It specifies when to use this tool ('When user requests "checkpoint stats", "bgwriter performance", etc.', 'When analyzing I/O performance', 'When troubleshooting checkpoint-related performance issues') and when not to use it ('Requests for checkpoint execution or configuration changes', 'Requests for background writer parameter modifications', 'Requests for statistics reset'). This clearly distinguishes it from potential alternatives for configuration changes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_current_database_infoA

[Tool Purpose]: Get information about the current database connection

[Exact Functionality]:

  • Show the name of the currently connected database

  • Display database-specific information like encoding, locale, and size

  • Provide connection context for clarity in multi-database environments

[Required Use Cases]:

  • When user asks "what database am I connected to?", "current database", etc.

  • When clarifying database context for analysis operations

  • When troubleshooting connection issues or confirming target database

[Strictly Prohibited Use Cases]:

  • Requests for database structure changes or creation/deletion

  • Requests for user authentication or permission changes

  • Requests for configuration modifications

Args: database_name: Target database to get info for (uses default connection if omitted)

Returns: Current database name and related information for connection clarity

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior as a read-only operation (implied by 'Get information'), specifies it provides connection context, and clarifies it uses a default connection if no database_name is provided. However, it doesn't mention potential rate limits, error conditions, or authentication requirements, leaving some behavioral aspects uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded key information. It's appropriately sized for the tool's complexity, with no redundant sentences. A minor point: the 'Args' and 'Returns' sections are somewhat redundant with the structured fields, but they're brief and integrated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 optional parameter), no annotations, but with an output schema (which handles return values), the description is complete. It covers purpose, usage guidelines, behavioral aspects, and parameter semantics adequately, providing all necessary context for an AI agent to use the tool correctly without over-explaining.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context for the single parameter beyond the schema (which has 0% coverage). It explains that database_name is optional ('uses default connection if omitted') and specifies it's the 'Target database to get info for,' clarifying its role. This compensates well for the low schema coverage, though it doesn't detail format constraints (e.g., string requirements).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Get information about the current database connection' with specific details about what information is retrieved (name, encoding, locale, size, connection context). It clearly distinguishes from siblings like get_database_list (which lists databases) or get_database_schema_info (which provides schema details) by focusing on the current connection's metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with '[Required Use Cases]' (e.g., when user asks about current database, clarifying context, troubleshooting) and '[Strictly Prohibited Use Cases]' (e.g., structure changes, authentication, configuration modifications). This clearly defines when to use this tool versus alternatives, including exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_bloat_overviewA

[Tool Purpose]: Provide database-wide bloat overview and summary statistics

[Exact Functionality]:

  • Summarize bloat statistics across all schemas

  • Identify schemas and tables with highest bloat ratios

  • Calculate total estimated bloat size per schema

  • Show aggregate dead tuple counts and maintenance status

[Required Use Cases]:

  • When user requests "database bloat overview", "bloat summary", etc.

  • When getting high-level view of database storage efficiency

  • When planning database maintenance activities

  • When investigating overall database performance issues

[Strictly Prohibited Use Cases]:

  • Requests for automatic maintenance operations

  • Requests for bloat cleanup or removal

  • Requests for schema or database restructuring

Args: database_name: Target database name (uses default database from POSTGRES_DB env var if omitted) limit: Maximum number of schemas to show (1-50, default: 10)

Returns: Database-wide bloat summary by schema with totals and recommendations

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's read-only nature by prohibiting maintenance/cleanup operations and specifying it provides 'overview' and 'summary' data. However, it doesn't mention potential performance impacts, data freshness, or authentication requirements, leaving some behavioral aspects uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) making it well-structured and easy to parse. While somewhat lengthy, each section adds value (purpose, functionality, usage guidelines, parameters, returns) without redundant information. The front-loaded purpose statement immediately clarifies the tool's intent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (database analysis with 2 parameters), no annotations, but with an output schema mentioned, the description provides comprehensive coverage: clear purpose, detailed functionality, explicit usage guidelines, parameter explanations, and return value description. The output schema existence means the description doesn't need to detail return structure, making this complete for the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 2 parameters, the description compensates well by explaining both parameters: 'database_name' specifies the target database with fallback to environment variable, and 'limit' defines the maximum schemas to show with range and default. This adds meaningful context beyond the basic schema, though it doesn't detail format constraints for database_name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Provide database-wide bloat overview and summary statistics' and details specific functionalities like summarizing bloat statistics, identifying high-bloat schemas/tables, calculating total bloat size, and showing aggregate dead tuple counts. This clearly distinguishes it from sibling tools like 'get_table_bloat_analysis' which focuses on individual tables rather than database-wide overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a '[Required Use Cases]' section listing specific scenarios (e.g., user requests for 'database bloat overview', planning maintenance, investigating performance issues) and a '[Strictly Prohibited Use Cases]' section explicitly stating when NOT to use it (e.g., automatic maintenance, bloat cleanup, restructuring). This provides clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_conflicts_statsA

[Tool Purpose]: Analyze query conflicts in standby/replica database environments

[Exact Functionality]:

  • Show conflict statistics for standby servers (only relevant on replicas)

  • Display conflicts by type (tablespace, lock, snapshot, bufferpin, deadlock)

  • Help diagnose replication-related performance issues

  • Provide conflict resolution statistics

[Required Use Cases]:

  • When user requests "replication conflicts", "standby conflicts", etc.

  • When analyzing replica server performance issues

  • When troubleshooting replication lag or conflicts

  • When monitoring standby server health

[Strictly Prohibited Use Cases]:

  • Requests for conflict resolution actions

  • Requests for replication configuration changes

  • Requests for statistics reset

Args: database_name: Database name to analyze (uses default database if omitted)

Returns: Database conflict statistics (meaningful only on standby servers)

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a read-only analysis tool (not for resolution actions), specifies it's only meaningful on standby servers, and indicates it provides statistics rather than performing operations. However, it doesn't mention potential limitations like data freshness or access permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) to organize information efficiently. Every sentence adds value with no redundancy. The structure makes it easy to scan while maintaining comprehensive coverage of the tool's capabilities and constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (conflict analysis in replica environments), the description provides complete context: purpose, functionality, usage guidelines, prohibitions, parameter semantics, and return value explanation. With an output schema present, the description appropriately focuses on behavioral context rather than return format details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for its single parameter, but the description provides excellent parameter semantics in the 'Args' section. It explains that 'database_name' is optional (uses default if omitted) and clarifies its purpose as 'Database name to analyze'. This fully compensates for the schema's lack of documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze query conflicts in standby/replica database environments' with specific functionality details like showing conflict statistics by type and diagnosing replication-related performance issues. It clearly distinguishes from siblings by focusing specifically on conflict analysis rather than general monitoring or configuration tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests 'replication conflicts', when analyzing replica server performance) and 'Strictly Prohibited Use Cases' (e.g., requests for conflict resolution actions, replication configuration changes). This gives clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_listA

[Tool Purpose]: Retrieve list of all databases and their basic information on PostgreSQL server

[Exact Functionality]:

  • Retrieve list of all databases on the server

  • Display owner, encoding, and size information for each database

  • Include database connection limit information

[Required Use Cases]:

  • When user requests "database list", "DB list", "database info", etc.

  • When need to check what databases exist on the server

  • When database size or owner information is needed

[Strictly Prohibited Use Cases]:

  • Requests for tables or schemas inside specific databases

  • Requests for database creation or deletion

  • Requests related to user permissions or security

Returns: Table-format information including database name, owner, encoding, size, and connection limit

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It clearly describes what the tool returns (table-format information with specific columns) and its read-only nature (prohibited use cases exclude creation/deletion). However, it doesn't mention potential limitations like server load impact, timeout behavior, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers but contains some redundancy (e.g., 'Retrieve list of all databases' appears twice). The 'Returns' section repeats information already implied in the 'Exact Functionality' section. While well-structured, it could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, has an output schema (mentioned in context signals), and the description comprehensively covers purpose, usage guidelines, return format, and behavioral constraints, it provides complete context for a read-only listing tool. The existence of an output schema means the description doesn't need to detail return value structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage. The description appropriately doesn't discuss parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema fully documents the empty input structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Retrieve list of all databases and their basic information on PostgreSQL server' with specific details about what information is included (owner, encoding, size, connection limit). It clearly distinguishes from sibling tools like get_table_list or get_database_schema_info by focusing only on database-level metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (when user requests database list, needs to check existing databases, or needs size/owner info) and 'Strictly Prohibited Use Cases' (requests for tables/schemas inside databases, creation/deletion operations, or permission/security requests). This gives clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_schema_infoA

[Tool Purpose]: Retrieve detailed information about database schemas (namespaces) and their contents

[Exact Functionality]:

  • Show all schemas in a database with their owners and permissions

  • Display schema-level statistics including table count and total size

  • List all objects (tables, views, functions) within specific schema

  • Show schema access privileges and usage patterns

[Required Use Cases]:

  • When user requests "database schema info", "schema overview", "namespace structure", etc.

  • When analyzing database organization and schema-level permissions

  • When exploring multi-schema database architecture

[Strictly Prohibited Use Cases]:

  • Requests for actual data inside tables

  • Requests for schema structure changes or DDL operations

  • Requests for individual table details (use get_table_schema_info for that)

Args: database_name: Database name to query (REQUIRED - specify which database to analyze) schema_name: Specific schema name to analyze (if None, shows all schemas)

Returns: Detailed database schema information including objects, sizes, and permissions

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameYes
schema_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by listing what information is retrieved (schemas, owners, permissions, statistics, objects) and clarifying it's for analysis/exploration only, not for data retrieval or DDL operations. However, it doesn't mention potential limitations like performance impact or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), making it easy to parse. While slightly verbose, each section adds value (e.g., prohibited use cases prevent misuse). Minor trimming could improve efficiency without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (schema analysis with multiple facets), no annotations, and an output schema present, the description is highly complete. It covers purpose, functionality, use cases, prohibitions, parameter semantics, and return value overview, providing all necessary context for an agent to use the tool correctly without needing to infer behavior from sparse structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: database_name is 'REQUIRED - specify which database to analyze' and schema_name 'if None, shows all schemas'. This clarifies usage beyond the basic schema types, though it doesn't detail format constraints or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool retrieves detailed information about database schemas and their contents, specifying verb ('retrieve') and resource ('database schemas'). It clearly distinguishes from sibling tools like get_table_schema_info by emphasizing schema-level analysis rather than table details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., when user requests 'database schema info') and 'Strictly Prohibited Use Cases' (e.g., requests for actual data inside tables). It names a specific alternative tool (get_table_schema_info) for table details, offering clear when-to-use and when-not-to-use instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_size_infoA

[Tool Purpose]: Analyze size information and storage usage status of all databases in PostgreSQL server

[Exact Functionality]:

  • Retrieve disk usage for each database

  • Analyze overall server storage usage status

  • Provide database list sorted by size

[Required Use Cases]:

  • When user requests "database size", "disk usage", "storage space", etc.

  • When capacity management or cleanup is needed

  • When resource usage status by database needs to be identified

[Strictly Prohibited Use Cases]:

  • Requests for data deletion or cleanup operations

  • Requests for storage configuration changes

  • Requests related to backup or restore

Returns: Table-format information with database names and size information sorted by size

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden of behavioral disclosure. It effectively communicates that this is a read-only analysis tool (implied by 'retrieve', 'analyze', 'provide' and prohibited deletion/configuration cases). It describes the return format (table-format information sorted by size) and scope (all databases in PostgreSQL server). However, it doesn't mention potential limitations like performance impact on large servers or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) which provides good structure. However, some sections are redundant (the 'Returns' section largely repeats what's in 'Exact Functionality'). The description could be more concise by eliminating repetition while maintaining the valuable usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 0 parameters, no annotations, but has an output schema, the description provides good context. It explains what the tool does, when to use it, what it returns, and what it doesn't do. The output schema existence means the description doesn't need to detail return value structure. For a read-only analysis tool with no parameters, this description covers the essential context well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't waste space discussing non-existent parameters. It focuses instead on what the tool does with its zero-parameter interface, which is the correct approach for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as analyzing size information and storage usage status of all databases in PostgreSQL server. It distinguishes itself from siblings like get_database_list (which lists databases without size info) and get_table_size_info (which focuses on tables rather than databases). The description uses specific verbs like 'retrieve', 'analyze', and 'provide' with clear resources (disk usage, storage usage, database list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' section listing specific scenarios (user requests for database size, capacity management, resource usage identification) and 'Strictly Prohibited Use Cases' section clearly stating what this tool should NOT be used for (deletion, configuration changes, backup/restore). This gives clear when-to-use and when-not-to-use guidance, distinguishing it from potential alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_database_statsA

[Tool Purpose]: Get comprehensive database-wide statistics and performance metrics

[Exact Functionality]:

  • Show database-wide transaction statistics (commits, rollbacks)

  • Display block I/O statistics (disk reads vs buffer hits)

  • Provide tuple operation statistics (returned, fetched, inserted, updated, deleted)

  • Show temporary file usage and deadlock counts

  • Include checksum failure information and I/O timing data

[Required Use Cases]:

  • When user requests "database statistics", "database performance", "transaction stats", etc.

  • When analyzing overall database performance and activity

  • When investigating I/O performance or buffer cache efficiency

  • When checking for deadlocks or temporary file usage

[Strictly Prohibited Use Cases]:

  • Requests for statistics reset or modification

  • Requests for database configuration changes

  • Requests for performance tuning actions

Returns: Comprehensive database statistics including transactions, I/O, tuples, and performance metrics

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It effectively discloses behavioral traits: it's a read-only operation (implied by 'Get' and prohibited modification cases), returns comprehensive metrics (listed in detail), and includes scope limitations (database-wide vs. table-specific). However, it doesn't mention potential performance impact or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), but it's verbose with redundant information. For example, the 'Returns' section repeats what's in [Exact Functionality]. Some sentences could be more concise while maintaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (database statistics), the description is complete: it explains purpose, detailed functionality, specific use cases, prohibitions, and return values. With an output schema present, it doesn't need to detail return format, and the schema coverage is 100% for 0 parameters, so no gaps exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on functionality and use cases. A baseline of 4 is applied since there are no parameters to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Get comprehensive database-wide statistics and performance metrics' with a clear verb ('Get') and resource ('database-wide statistics and performance metrics'). It distinguishes from siblings like get_table_io_stats or get_index_io_stats by emphasizing 'database-wide' scope, making the distinction clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' with specific query examples ('database statistics', 'database performance', etc.) and analysis scenarios. It also includes 'Strictly Prohibited Use Cases' that clearly state when NOT to use this tool (e.g., for statistics reset or configuration changes), offering clear alternatives by implication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_index_io_statsA

[Tool Purpose]: Analyze I/O performance statistics for indexes (disk reads vs buffer cache hits)

[Exact Functionality]:

  • Show index-level I/O statistics and buffer hit ratios

  • Identify indexes with poor buffer cache performance

  • Provide detailed I/O performance metrics per index

  • Help optimize index and buffer cache usage

[Required Use Cases]:

  • When user requests "index I/O stats", "index buffer performance", etc.

  • When analyzing index-level I/O performance

  • When identifying indexes causing excessive disk I/O

  • When optimizing index buffer cache efficiency

[Strictly Prohibited Use Cases]:

  • Requests for index optimization actions

  • Requests for buffer cache configuration changes

  • Requests for statistics reset

Args: database_name: Database name to analyze (uses default database if omitted) schema_name: Schema name to filter (default: public)

Returns: Index I/O statistics including buffer hit ratios and performance metrics

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNopublic

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by explaining what the tool does (analyzes I/O statistics, identifies performance issues, helps optimization) and what it doesn't do (no optimization actions, configuration changes, or statistics reset). It could improve by mentioning if this is a read-only operation or has any side effects, but provides substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded with purpose. While somewhat verbose, every sentence adds value (use cases, prohibitions, parameter explanations) and there's no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's analytical nature, 2 parameters, no annotations, but with an output schema (confirmed by context signals), the description is complete: it explains purpose, functionality, use cases, prohibitions, parameters, and return values. The output schema handles return format details, so the description appropriately focuses on context and usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining both parameters in the Args section: 'database_name: Database name to analyze (uses default database if omitted)' and 'schema_name: Schema name to filter (default: public)'. This adds meaning beyond the bare schema, though it doesn't provide format examples or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze I/O performance statistics for indexes (disk reads vs buffer cache hits)' with specific verbs ('analyze', 'show', 'identify', 'provide', 'help optimize') and clearly distinguishes it from siblings like get_table_io_stats (index vs table focus) and get_index_usage_stats (I/O performance vs usage patterns).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with '[Required Use Cases]' listing four specific scenarios and '[Strictly Prohibited Use Cases]' listing three clear exclusions, giving comprehensive when-to-use and when-not-to-use instructions that help differentiate from potential alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_index_usage_statsA

[Tool Purpose]: Analyze usage rate and performance statistics of all indexes in database

[Exact Functionality]:

  • Analyze usage frequency and efficiency of all indexes

  • Identify unused indexes

  • Provide scan count and tuple return statistics per index

[Required Use Cases]:

  • When user requests "index usage rate", "index performance", "unnecessary indexes", etc.

  • When database performance optimization is needed

  • When index cleanup or reorganization is required

[Strictly Prohibited Use Cases]:

  • Requests for index creation or deletion

  • Requests for index reorganization or REINDEX execution

  • Requests for statistics reset

Args: database_name: Database name to analyze (uses default database if omitted)

Returns: Index usage statistics including schema, table, index name, scans, and tuples read

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's functionality ('analyze usage frequency', 'identify unused indexes', 'provide scan count and tuple return statistics'), scope ('all indexes in database'), and limitations (prohibited use cases). However, it doesn't mention potential performance impact, permissions required, or data freshness, leaving some behavioral aspects unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded key information. However, some sections like 'Exact Functionality' could be more concise, and the overall length is moderate but not minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (analyzing index usage), no annotations, and the presence of an output schema (which handles return values), the description is complete. It covers purpose, functionality, use cases, prohibitions, parameters, and returns, providing sufficient context for an AI agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It adds meaningful context for the single parameter by explaining 'database_name: Database name to analyze (uses default database if omitted)', clarifying the optional nature and default behavior. This goes beyond the basic schema information, though it doesn't detail format constraints or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze usage rate and performance statistics of all indexes in database' with specific verbs ('analyze', 'identify', 'provide') and resources ('indexes', 'database'). It clearly distinguishes from siblings like 'get_index_io_stats' by focusing on usage frequency and efficiency rather than I/O statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., 'When user requests index usage rate', 'When database performance optimization is needed') and 'Strictly Prohibited Use Cases' (e.g., 'Requests for index creation or deletion', 'Requests for index reorganization'). This clearly defines when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_io_statsA

[Tool Purpose]: Analyze comprehensive I/O statistics across all database operations with version compatibility

[Exact Functionality]:

  • PostgreSQL 16+: Shows detailed I/O statistics from pg_stat_io (reads, writes, hits, timing)

  • PostgreSQL 12-15: Falls back to pg_statio_* views with basic I/O information

  • Provides buffer cache efficiency analysis and I/O timing when available

  • Identifies I/O patterns and performance bottlenecks

[Required Use Cases]:

  • When user requests "I/O stats", "I/O performance", "buffer cache analysis", etc.

  • When analyzing storage performance and buffer efficiency

  • When identifying I/O bottlenecks across different backend types

  • When comparing I/O patterns between relation types

[Strictly Prohibited Use Cases]:

  • Requests for I/O configuration changes or buffer tuning

  • Requests for storage or filesystem modifications

  • Requests for I/O statistics reset

Args: limit: Maximum number of results to return (1-100, default 20) database_name: Target database name (optional)

Returns: Comprehensive I/O statistics with version-appropriate detail level

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining version-dependent behavior (PostgreSQL 16+ vs 12-15), what data is returned (buffer cache efficiency, I/O timing, patterns), and prohibited actions. However, it doesn't mention potential side effects, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) that make it scannable and front-loaded. While comprehensive, some sections could be more concise; every sentence earns its place by adding specific guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of version-dependent behavior, 2 parameters with no schema descriptions, and the presence of an output schema, the description is remarkably complete. It covers purpose, functionality, usage guidelines, prohibitions, parameters, and return values - providing everything needed for proper tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining both parameters in the Args section: 'limit' with its range and default, and 'database_name' as optional target. This adds meaningful context beyond the bare schema, though it could elaborate on database_name implications.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze comprehensive I/O statistics across all database operations with version compatibility' in the [Tool Purpose] section. It clearly distinguishes from siblings like get_index_io_stats and get_table_io_stats by specifying it covers 'all database operations' rather than specific components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes both [Required Use Cases] with specific trigger phrases and scenarios, and [Strictly Prohibited Use Cases] that explicitly state when NOT to use this tool. This provides comprehensive guidance on when to select this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_lock_monitoringA

[Tool Purpose]: Monitor current locks and potential deadlocks in PostgreSQL

[Exact Functionality]:

  • List all current locks held and waited for by sessions

  • Show blocked and blocking sessions, lock types, and wait status

  • Help diagnose lock contention and deadlock risk

  • Filter results by granted status, state, mode, lock type, or username

[Required Use Cases]:

  • When user requests "lock monitoring", "deadlock check", "blocked sessions", etc.

  • When diagnosing performance issues due to locking

  • When checking for blocked or waiting queries

  • When filtering specific types of locks or users

[Strictly Prohibited Use Cases]:

  • Requests for killing sessions or force-unlocking

  • Requests for lock configuration changes

  • Requests for historical lock data (only current state is shown)

Args: database_name: Database name to analyze (uses default database if omitted) granted: Filter by granted status ("true" or "false") state: Filter by session state ("active", "idle", "idle in transaction", etc.) mode: Filter by lock mode ("AccessShareLock", "ExclusiveLock", etc.) locktype: Filter by lock type ("relation", "transactionid", "virtualxid", etc.) username: Filter by specific username

Returns: Table-format information showing PID, user, database, lock type, relation, mode, granted, waiting, and blocked-by info

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
grantedNo
stateNo
modeNo
locktypeNo
usernameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a read-only monitoring tool (implied by 'list', 'show', 'diagnose'), shows only current state (not historical data), and returns table-format information. It doesn't mention rate limits, authentication needs, or performance impact, but covers the core functionality well given the annotation gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Tool Purpose, Exact Functionality, etc.), making it easy to scan. It's appropriately sized for a 6-parameter tool with no annotations, though some redundancy exists (e.g., 'Filter results by...' in Exact Functionality and again in Args). Every sentence adds value, but minor trimming could improve conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, 0% schema coverage, no annotations) and the presence of an output schema (implied by 'Returns: Table-format information...'), the description is highly complete. It covers purpose, usage guidelines, behavioral context, parameter semantics, and return format, leaving no significant gaps for the agent to operate effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It provides a detailed 'Args' section that explains each parameter's purpose (e.g., 'Filter by granted status', 'Filter by specific username'), adding essential meaning beyond the bare schema. This is crucial for the 6 parameters with no schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose in the first line: 'Monitor current locks and potential deadlocks in PostgreSQL.' It provides specific verbs ('list', 'show', 'diagnose', 'filter') and clearly distinguishes this tool from siblings by focusing exclusively on lock monitoring, unlike other tools that handle connections, tables, replication, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes dedicated sections for 'Required Use Cases' (e.g., 'When user requests "lock monitoring", "deadlock check", etc.') and 'Strictly Prohibited Use Cases' (e.g., 'Requests for killing sessions or force-unlocking'), providing explicit guidance on when to use this tool versus alternatives or when to avoid it entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pg_stat_monitor_recent_queriesA

[Tool Purpose]: Analyze recently executed queries and detailed monitoring information using pg_stat_monitor extension

[Exact Functionality]:

  • Retrieve detailed performance information of recently executed queries

  • Display client IP and time bucket information by execution period

  • Provide more detailed monitoring data than pg_stat_statements

[Required Use Cases]:

  • When user requests "recent queries", "detailed monitoring", "pg_stat_monitor", etc.

  • When real-time query performance monitoring is needed

  • When client-specific or time-based query analysis is required

[Strictly Prohibited Use Cases]:

  • When pg_stat_monitor extension is not installed

  • Requests for query execution or data modification

  • Requests for monitoring configuration changes or data reset

Args: limit: Number of recent queries to retrieve (default: 20, max: 100) database_name: Database name to analyze (uses default database if omitted)

Returns: Detailed monitoring information including query text, execution statistics, client info, and bucket time

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a read-only monitoring tool (implied by 'retrieve' and 'display'), requires the pg_stat_monitor extension to be installed (a prerequisite), and provides detailed performance information. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some behavioral aspects uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with labeled sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded key information. Each sentence adds value, such as differentiating from pg_stat_statements and specifying use cases. However, it could be slightly more concise by integrating the 'Args' and 'Returns' details more seamlessly into the main text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (monitoring queries with 2 parameters), no annotations, and an output schema present, the description is complete. It covers purpose, functionality, use cases, prohibitions, parameter semantics, and return information. The output schema handles return values, so the description doesn't need to detail them further, making it adequately comprehensive for the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for both parameters: 'limit' is described as 'Number of recent queries to retrieve (default: 20, max: 100)' and 'database_name' as 'Database name to analyze (uses default database if omitted)'. This provides clear context beyond the schema's basic titles, though it doesn't elaborate on format constraints or edge cases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze recently executed queries and detailed monitoring information using pg_stat_monitor extension' with specific verbs ('analyze', 'retrieve', 'display', 'provide') and resources ('queries', 'monitoring information', 'client IP', 'time bucket information'). It clearly distinguishes from sibling tools like 'get_pg_stat_statements_top_queries' by noting it provides 'more detailed monitoring data than pg_stat_statements'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit 'Required Use Cases' (e.g., when user requests 'recent queries', 'detailed monitoring', 'pg_stat_monitor', etc.) and 'Strictly Prohibited Use Cases' (e.g., when pg_stat_monitor extension is not installed, requests for query execution or data modification). It provides clear when-to-use and when-not-to-use guidance with specific alternatives implied (e.g., avoiding data modification tools).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pg_stat_statements_top_queriesA

[Tool Purpose]: Analyze top queries that consumed the most time using pg_stat_statements extension

[Exact Functionality]:

  • Retrieve top query list based on total execution time

  • Display call count, average execution time, and cache hit rate for each query

  • Support identification of queries requiring performance optimization

[Required Use Cases]:

  • When user requests "slow queries", "performance analysis", "top queries", etc.

  • When database performance optimization is needed

  • When query performance monitoring or tuning is required

[Strictly Prohibited Use Cases]:

  • When pg_stat_statements extension is not installed

  • Requests for query execution or data modification

  • Requests for statistics data reset or configuration changes

Args: limit: Number of top queries to retrieve (default: 20, max: 100) database_name: Database name to analyze (uses default database if omitted)

Returns: Performance statistics including query text, call count, total execution time, average execution time, and cache hit rate

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing behavioral traits: it's a read-only analysis tool (implied by 'retrieve' and 'display'), requires pg_stat_statements extension, and specifies what data is returned. It doesn't mention rate limits or authentication requirements, but covers core functionality adequately.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The structured format with clear sections ([Tool Purpose], [Exact Functionality], etc.) is well-organized and front-loaded. Some sections could be more concise (e.g., 'Required Use Cases' lists could be tighter), but overall it's efficiently structured with minimal waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (performance analysis with prerequisites), no annotations, and an output schema exists, the description provides comprehensive context: purpose, functionality, use cases, prohibitions, parameter semantics, and return value explanation. It covers all necessary aspects for an agent to understand and use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully. It provides clear semantic meaning for both parameters: 'limit' specifies number of top queries with default and max values, 'database_name' explains it's optional and uses default if omitted. This adds substantial value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as analyzing top queries based on execution time using pg_stat_statements extension. It clearly distinguishes from siblings by focusing specifically on query performance analysis rather than general database monitoring, connections, or table statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (performance analysis, optimization requests) and 'Strictly Prohibited Use Cases' (when extension not installed, execution/modification requests). It clearly defines when to use this tool versus alternatives, including specific scenarios and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_postgresql_configA

[Tool Purpose]: Retrieve and analyze PostgreSQL server configuration parameter values

[Exact Functionality]:

  • Retrieve all PostgreSQL configuration parameters (when config_name is not specified)

  • Retrieve current value and description of specific configuration parameter

  • Filter configurations by text pattern (when filter_text is specified)

  • Display whether configuration can be changed and if restart is required

[Required Use Cases]:

  • When user requests "PostgreSQL config", "config", "parameters", etc.

  • When checking specific configuration values is needed

  • When searching for configurations containing specific text

  • When configuration status identification is needed for performance tuning

[Strictly Prohibited Use Cases]:

  • Requests for configuration value changes or modifications

  • Requests for PostgreSQL restart or reload

  • Requests for system-level configuration changes

Args: config_name: Specific configuration parameter name to retrieve (shows all configs if omitted) filter_text: Text to filter configuration names or descriptions (optional)

Returns: Configuration information including parameter name, current value, unit, description, and changeability

ParametersJSON Schema
NameRequiredDescriptionDefault
config_nameNo
filter_textNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (retrieve and analyze configuration values), what information it displays (current value, description, changeability, restart requirements), and importantly specifies prohibited use cases that reveal behavioral constraints (no modifications, no restarts). The only minor gap is lack of explicit mention about permissions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], [Required Use Cases], [Strictly Prohibited Use Cases], Args, Returns) and every sentence earns its place. It could be slightly more concise by integrating the Args/Returns into the structured sections rather than as separate elements, but overall it's efficiently organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (configuration retrieval with filtering options), no annotations, and the presence of an output schema (which handles return value documentation), the description provides complete context. It covers purpose, functionality, use cases, prohibitions, parameter semantics, and return information - everything needed for an agent to understand and use this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage (no descriptions in the input schema), the description fully compensates by explaining both parameters in detail: 'config_name: Specific configuration parameter name to retrieve (shows all configs if omitted)' and 'filter_text: Text to filter configuration names or descriptions (optional)'. It provides clear semantics beyond just parameter names, including default behavior when omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Retrieve and analyze PostgreSQL server configuration parameter values' with specific verbs ('retrieve', 'analyze') and resource ('PostgreSQL server configuration parameters'). It clearly distinguishes from sibling tools like get_server_info or get_database_stats by focusing specifically on configuration parameters rather than general server information or database statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (when user requests PostgreSQL config, checking specific values, searching for configurations, performance tuning) and 'Strictly Prohibited Use Cases' (configuration changes, restart/reload requests, system-level changes). This gives clear guidance on when to use this tool versus alternatives, including what this tool should NOT be used for.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_prompt_templateB

Returns the MCP prompt template (full, headings, or specific section). Args: section: Section number or keyword (optional) mode: 'full', 'headings', or None (optional)

ParametersJSON Schema
NameRequiredDescriptionDefault
sectionNo
modeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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 this is a read operation ('Returns') which implies it's non-destructive, but doesn't disclose any behavioral traits like authentication requirements, rate limits, error conditions, or what happens when parameters are invalid. The description is minimal and doesn't provide the behavioral context needed for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences: a purpose statement followed by parameter documentation. It's front-loaded with the core functionality. Every sentence earns its place, though the parameter documentation could be slightly more integrated rather than a separate 'Args:' section.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values), 2 parameters with 0% schema coverage, no annotations, and moderate complexity, the description is minimally adequate. It covers purpose and parameters but lacks behavioral context and usage guidance. The existence of an output schema reduces the burden, but more context about the template structure would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining both parameters in the Args section. It clarifies that 'section' accepts section numbers or keywords, and 'mode' accepts 'full', 'headings', or None. This adds meaningful semantics beyond the bare schema, though it doesn't provide examples or explain what 'headings' mode returns versus 'full'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Returns') and resource ('MCP prompt template'), and specifies what can be returned (full, headings, or specific section). It distinguishes itself from sibling tools which are all PostgreSQL monitoring tools, making this a specialized template retrieval function. However, it doesn't explicitly contrast with any similar template-related tools since none exist among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, appropriate contexts, or contrast with other tools (though sibling tools are unrelated PostgreSQL monitoring functions, so no direct alternatives exist). The parameter documentation implies usage scenarios but doesn't explicitly state when to choose specific parameter values.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_replication_statusA

[Tool Purpose]: Monitor PostgreSQL replication status and statistics

[Exact Functionality]:

  • Show current replication connections and their status

  • Display replication lag information for standbys

  • Monitor WAL sender and receiver processes

  • Provide replication slot information and statistics

[Required Use Cases]:

  • When user requests "replication status", "standby lag", "replication monitoring", etc.

  • When diagnosing replication issues or performance problems

  • When checking replication slot usage and lag

[Strictly Prohibited Use Cases]:

  • Requests for replication configuration changes

  • Requests for replication slot creation or deletion

  • Requests for failover or switchover operations

Returns: Replication status including connections, lag information, slots, and statistics

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It effectively communicates this is a monitoring/read-only tool (implied by 'Monitor', 'Show', 'Display', 'Provide') and specifies what information is returned. However, it doesn't mention potential limitations like data freshness, permission requirements, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) to organize information efficiently. Every sentence adds value with no redundancy, and the structure helps the agent quickly understand purpose, functionality, usage guidelines, and returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a monitoring tool with 0 parameters, 100% schema coverage, and an output schema exists, the description provides excellent context. It covers purpose, exact functionality, when to use, when not to use, and what's returned - making it complete for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on what the tool monitors and returns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Monitor PostgreSQL replication status and statistics' with specific functionality details like showing replication connections, lag information, WAL processes, and slot information. It clearly distinguishes this tool from sibling monitoring tools by focusing exclusively on replication aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests replication status, diagnosing issues) and 'Strictly Prohibited Use Cases' (e.g., configuration changes, slot creation/deletion, failover operations). This gives clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_running_vacuum_operationsA

[Tool Purpose]: Monitor currently running VACUUM and ANALYZE operations in real-time

[Exact Functionality]:

  • Show all currently active VACUUM, ANALYZE, and REINDEX operations

  • Display operation progress, elapsed time, and process details

  • Identify blocking or long-running maintenance operations

  • Provide process IDs for operation tracking

[Required Use Cases]:

  • When user requests "running VACUUM", "active maintenance", "current VACUUM status", etc.

  • When troubleshooting slow or stuck VACUUM operations

  • When monitoring maintenance operation progress

  • When identifying maintenance operations that may be affecting performance

[Strictly Prohibited Use Cases]:

  • Requests for terminating or controlling VACUUM processes

  • Requests for starting new VACUUM operations

  • Requests for changing VACUUM parameters or configuration

Args: database_name: Target database name (shows operations in all databases if omitted)

Returns: Real-time status of running VACUUM/ANALYZE operations with timing and progress information

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a monitoring/read-only tool (implied by 'monitor', 'show', 'display'), provides real-time status, and explicitly prohibits write/control operations. However, it doesn't mention potential rate limits, authentication needs, or what happens if no operations are running.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) which aids structure, but it's verbose with some redundancy (e.g., 'Returns' section repeats functionality). Some sentences could be more concise while maintaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's monitoring purpose, single optional parameter, and presence of an output schema, the description is complete enough. It covers purpose, functionality, use cases, prohibitions, parameter meaning, and return value description. The output schema existence means the description doesn't need to detail return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the single parameter's semantics: 'Target database name (shows operations in all databases if omitted)'. This adds crucial context beyond the schema's basic type information, though it doesn't specify format constraints or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Monitor currently running VACUUM and ANALYZE operations in real-time' with specific verbs (monitor, show, display, identify, provide) and resources (VACUUM, ANALYZE, REINDEX operations). It clearly distinguishes from sibling tools like 'get_vacuum_analyze_stats' by focusing on real-time active operations rather than historical statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests running VACUUM, troubleshooting slow operations) and 'Strictly Prohibited Use Cases' (e.g., terminating processes, starting new operations). This gives clear guidance on when to use this tool versus alternatives, though it doesn't explicitly name sibling alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_server_infoA

[Tool Purpose]: Check basic information and connection status of PostgreSQL server

[Exact Functionality]:

  • Retrieve PostgreSQL server version information

  • Display connection settings (with password masking)

  • Verify server accessibility

  • Check installation status of extensions (pg_stat_statements, pg_stat_monitor)

[Required Use Cases]:

  • When user requests "server info", "PostgreSQL status", "connection check", etc.

  • When basic database server information is needed

  • When preliminary check is needed before using monitoring tools

[Strictly Prohibited Use Cases]:

  • Requests for specific data or table information

  • Requests for performance statistics or monitoring data

  • Requests for configuration changes or administrative tasks

Returns: Comprehensive information including server version, connection info, and extension status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it retrieves server version, displays connection settings with password masking, verifies accessibility, and checks extension status. It also specifies the return format. However, it doesn't mention potential errors, timeouts, or authentication requirements, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), front-loaded with the core purpose, and every sentence adds value without redundancy. It efficiently communicates necessary information in a organized manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, output schema exists), the description is complete: it explains purpose, functionality, usage guidelines, prohibitions, and return values. With an output schema handling return details, the description provides all necessary context for an agent to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters, focusing instead on functionality and use cases, which is correct for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Check basic information and connection status of PostgreSQL server' with specific verbs ('retrieve', 'display', 'verify', 'check') and resources ('PostgreSQL server version', 'connection settings', 'server accessibility', 'extensions'). It clearly distinguishes from siblings by focusing on basic server info rather than monitoring, statistics, or configuration details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' listing specific user requests and scenarios, and 'Strictly Prohibited Use Cases' detailing when NOT to use this tool (e.g., for data queries, performance stats, or admin tasks). It effectively distinguishes from sibling tools that handle those prohibited cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_bloat_analysisA

[Tool Purpose]: Analyze table bloat based on dead tuple statistics and size information

[Exact Functionality]:

  • Calculate bloat ratio based on dead tuples vs total tuples

  • Estimate bloat size in bytes and human-readable format

  • Show last VACUUM/AUTOVACUUM timestamps for maintenance tracking

  • Identify tables requiring VACUUM maintenance

  • Filter tables by name pattern using SQL LIKE or ILIKE matching

  • Sort results by bloat severity (dead tuple ratio and count)

[Required Use Cases]:

  • When user requests "table bloat", "bloat analysis", "dead tuples", etc.

  • When identifying tables that need VACUUM maintenance

  • When investigating database storage efficiency and space usage

  • When troubleshooting performance issues related to table bloat

  • When analyzing specific table groups (e.g., tables with "user", "log", "temp" in names)

[Strictly Prohibited Use Cases]:

  • Requests for automatic VACUUM execution

  • Requests for bloat removal or cleanup operations

  • Requests for table restructuring or data modification

Args: database_name: Target database name (uses default database from POSTGRES_DB env var if omitted) schema_name: Schema to analyze (analyzes all user schemas if omitted) table_pattern: Table name pattern to filter (SQL LIKE pattern, e.g., 'user%', '%log%', 'temp_*') min_dead_tuples: Minimum dead tuples to include in results (default: 1, shows all tables with any bloat) limit: Maximum number of results to return (1-100, default: 20)

Returns: Table bloat analysis with bloat ratios, sizes, and maintenance recommendations

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNo
table_patternNo
min_dead_tuplesNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It effectively describes what the tool does (analysis, not modification), output characteristics (bloat ratios, sizes, maintenance recommendations), and operational constraints (filtering via SQL LIKE/ILIKE, sorting by severity). It doesn't mention rate limits, authentication needs, or performance characteristics, but provides substantial behavioral context beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) that make it easy to parse. While comprehensive, some sections could be more concise - the [Exact Functionality] uses 6 bullet points where 3-4 might suffice. However, every sentence adds value and the structure helps with quick scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's analytical complexity, 5 parameters with 0% schema coverage, no annotations, but with an output schema, the description is remarkably complete. It covers purpose, functionality, usage guidelines, parameter semantics, and return value description. The output schema existence means the description doesn't need to detail return structure, allowing it to focus on operational context, which it does thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 5 parameters, the description provides excellent parameter semantics. The Args section clearly explains each parameter's purpose, default values, constraints (e.g., '1-100' for limit), and usage examples (e.g., SQL LIKE pattern examples). This fully compensates for the lack of schema descriptions and adds meaningful context beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze table bloat based on dead tuple statistics and size information' in the [Tool Purpose] section, which is a specific verb+resource combination. It clearly distinguishes this from sibling tools like get_database_bloat_overview (database-level vs table-level analysis) and get_vacuum_effectiveness_analysis (different analytical focus).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides comprehensive usage guidance with dedicated sections: [Required Use Cases] lists five specific scenarios when to use this tool, and [Strictly Prohibited Use Cases] explicitly states three scenarios when NOT to use it (e.g., 'Requests for automatic VACUUM execution'). This gives clear alternatives (use other tools for those prohibited actions) and context for appropriate application.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_io_statsA

[Tool Purpose]: Analyze I/O performance statistics for tables (disk reads vs buffer cache hits)

[Exact Functionality]:

  • Show heap, index, and TOAST table I/O statistics

  • Calculate buffer hit ratios for performance analysis

  • Identify tables with poor buffer cache performance

  • Provide detailed I/O breakdown by table component

[Required Use Cases]:

  • When user requests "table I/O stats", "buffer performance", "disk vs cache", etc.

  • When analyzing table-level I/O performance

  • When identifying tables causing excessive disk I/O

  • When optimizing buffer cache efficiency

[Strictly Prohibited Use Cases]:

  • Requests for I/O optimization actions

  • Requests for buffer cache configuration changes

  • Requests for statistics reset

Args: database_name: Database name to analyze (uses default database if omitted) schema_name: Schema name to filter (default: public)

Returns: Table I/O statistics including heap, index, and TOAST performance metrics

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNopublic

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

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 behavioral traits such as the tool's analytical nature (not for optimization actions), the types of statistics shown (heap, index, TOAST), and performance analysis capabilities. However, it doesn't mention potential limitations like data freshness, permissions required, or rate limits, which would be useful for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), making it easy to parse. It's appropriately sized with no redundant information. However, some sections like '[Exact Functionality]' could be more concise, as bullet points like 'Calculate buffer hit ratios for performance analysis' and 'Identify tables with poor buffer cache performance' overlap slightly in intent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (analytical tool with no annotations), the description is complete. It covers purpose, functionality, usage guidelines, parameters, and return values. With an output schema present, the description doesn't need to detail return values, and it adequately explains what the tool does and when to use it, making it sufficient for an AI 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the parameters in the 'Args' section: 'database_name: Database name to analyze (uses default database if omitted)' and 'schema_name: Schema name to filter (default: public)'. This adds meaning beyond the bare schema, clarifying defaults and usage. However, it doesn't provide additional context like valid values or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose in the '[Tool Purpose]' section: 'Analyze I/O performance statistics for tables (disk reads vs buffer cache hits)'. It provides a specific verb ('Analyze') and resource ('I/O performance statistics for tables'), and distinguishes from siblings like 'get_index_io_stats' by focusing on tables rather than indexes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes '[Required Use Cases]' with specific scenarios (e.g., 'When user requests "table I/O stats"', 'When analyzing table-level I/O performance') and '[Strictly Prohibited Use Cases]' with clear exclusions (e.g., 'Requests for I/O optimization actions', 'Requests for buffer cache configuration changes'). This provides explicit guidance on when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_listA

[Tool Purpose]: Retrieve list of all tables and their information from specified database (or current DB)

[Exact Functionality]:

  • Retrieve list of all tables in specified database

  • Display schema, owner, and size information for each table

  • Distinguish table types (regular tables, views, etc.)

[Required Use Cases]:

  • When user requests "table list", "table listing", "schema info", etc.

  • When need to understand structure of specific database

  • When table size or owner information is needed

[Strictly Prohibited Use Cases]:

  • Requests for data inside tables

  • Requests for table structure changes or creation/deletion

  • Requests for detailed column information of specific tables

Args: database_name: Database name to query (uses currently connected database if omitted)

Returns: Table-format information including table name, schema, owner, type, and size

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (retrieves table lists with metadata), what it doesn't do (prohibited use cases), and the default behavior when database_name is omitted (uses currently connected database). However, it doesn't mention performance characteristics, error conditions, or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded key information. While somewhat verbose with section headers, every sentence adds value and there's no redundant information. The structure helps with quick scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (1 parameter, no annotations, but has output schema), the description provides comprehensive coverage. It explains purpose, functionality, use cases, prohibitions, parameter semantics, and return format. The output schema exists, so the description doesn't need to detail return values, making this complete for the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It clearly explains the single parameter's purpose ('Database name to query') and default behavior ('uses currently connected database if omitted'), adding meaningful context beyond the bare schema. However, it doesn't specify format requirements or constraints for the database_name parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Retrieve list of all tables and their information from specified database' with specific details about what information is included (schema, owner, size, table types). It clearly distinguishes this from sibling tools like get_table_schema_info (detailed column info) and get_table_size_info (size only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (table list requests, understanding database structure, needing size/owner info) and 'Strictly Prohibited Use Cases' (data inside tables, structure changes, detailed column info). This gives clear guidance on when to use this tool versus alternatives like get_table_schema_info for column details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_relationshipsA

[Tool Purpose]: Analyze table relationships including foreign keys, dependencies, and inheritance

[Exact Functionality]:

  • Show foreign key relationships (inbound and outbound)

  • Display view dependencies and table references

  • Analyze inheritance and partition relationships

  • Identify orphaned tables and relationship patterns

[Required Use Cases]:

  • When user requests "table relationships", "foreign keys", "dependencies", etc.

  • When analyzing database schema design and data model

  • When planning data migration or schema changes

[Strictly Prohibited Use Cases]:

  • Requests for actual data inside tables

  • Requests for relationship modifications or DDL operations

  • Requests for performance statistics (use other tools for that)

Args: database_name: Database name to query (REQUIRED - specify which database to analyze) table_name: Specific table name to analyze (if None, shows database-wide relationship overview) schema_name: Schema name to search in (default: "public") relationship_type: Type of relationships to show ("all", "foreign_keys", "dependencies", "inheritance")

Returns: Detailed relationship information including foreign keys, dependencies, and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameYes
table_nameNo
schema_nameNopublic
relationship_typeNoall

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (analyzes relationships, shows foreign keys, displays dependencies, analyzes inheritance, identifies orphaned tables) and clarifies it's a read-only analysis tool (prohibits 'relationship modifications or DDL operations'). However, it doesn't mention potential limitations like query performance impact or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.) and front-loaded key information. While comprehensive, some sections could be more concise (e.g., the bullet points in [Exact Functionality] are slightly repetitive). Every sentence earns its place by adding value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, 0% schema coverage, no annotations) and the presence of an output schema, the description is complete. It covers purpose, functionality, usage guidelines, parameter semantics, and return value description ('Detailed relationship information including foreign keys, dependencies, and metadata'), leaving no significant gaps for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Given 0% schema description coverage, the description compensates fully by explaining each parameter's purpose in the 'Args' section: 'database_name: Database name to query (REQUIRED - specify which database to analyze)', 'table_name: Specific table name to analyze (if None, shows database-wide relationship overview)', etc. This adds crucial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze table relationships including foreign keys, dependencies, and inheritance' with a clear verb ('analyze') and resource ('table relationships'). It distinguishes from siblings like 'get_table_schema_info' or 'get_table_list' by focusing specifically on relationship analysis rather than general schema or listing functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with '[Required Use Cases]' listing specific scenarios (e.g., 'When user requests "table relationships", "foreign keys", "dependencies", etc.') and '[Strictly Prohibited Use Cases]' clearly stating what not to use it for (e.g., 'Requests for actual data inside tables'). It also mentions alternatives ('use other tools for that') for performance statistics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_schema_infoA

[Tool Purpose]: Retrieve detailed schema information for specific table or all tables in a database

[Exact Functionality]:

  • Retrieve detailed column information including data types, constraints, defaults

  • Display primary keys, foreign keys, indexes, and other table constraints

  • Show table-level metadata such as size, row count estimates

[Required Use Cases]:

  • When user requests "table schema", "column info", "table structure", etc.

  • When detailed table design information is needed for development

  • When analyzing database structure and relationships

[Strictly Prohibited Use Cases]:

  • Requests for actual data inside tables

  • Requests for table structure changes or DDL operations

  • Requests for performance statistics (use other tools for that)

Args: database_name: Database name to query (REQUIRED - specify which database to analyze) table_name: Specific table name to analyze (if None, shows all tables) schema_name: Schema name to search in (default: "public")

Returns: Detailed table schema information including columns, constraints, and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameYes
table_nameNo
schema_nameNopublic

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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 behavioral traits such as the tool being read-only (implied by 'Retrieve' and prohibitions on data changes), the scope of information returned (column details, constraints, metadata), and exclusions like performance statistics. However, it lacks details on error handling or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with labeled sections ([Tool Purpose], [Exact Functionality], etc.), making it front-loaded and easy to scan. However, some redundancy exists (e.g., repeating parameter info in the Args section), slightly reducing efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (3 parameters, 0% schema coverage, no annotations) and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage, parameters, and exclusions, providing sufficient context for an agent to invoke the tool correctly without needing additional explanations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining each parameter's role (e.g., 'database_name: Database name to query (REQUIRED - specify which database to analyze)') and default behaviors (e.g., 'if None, shows all tables'), though it doesn't fully detail constraints or formats beyond the schema's basic types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose with specific verbs ('Retrieve detailed schema information') and resources ('specific table or all tables in a database'), distinguishing it from siblings like get_table_list (which lists tables) or get_table_size_info (which focuses on size metrics). The structured sections reinforce this clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., 'When user requests "table schema"') and 'Strictly Prohibited Use Cases' (e.g., 'Requests for actual data inside tables'), including clear alternatives ('use other tools for that'). This directly addresses when to use this tool versus others in the sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_table_size_infoA

[Tool Purpose]: Analyze size information and index usage of all tables in specified schema

[Exact Functionality]:

  • Retrieve size information of all tables within schema

  • Analyze index size and total size per table

  • Provide table list sorted by size

[Required Use Cases]:

  • When user requests "table size", "schema capacity", "index usage", etc.

  • When storage analysis of specific schema is needed

  • When resource usage status per table needs to be identified

[Strictly Prohibited Use Cases]:

  • Requests for table data deletion or cleanup operations

  • Requests for index creation or deletion

  • Requests for table structure changes

Args: schema_name: Schema name to analyze (default: "public") database_name: Database name to analyze (uses default database if omitted)

Returns: Information sorted by size including table name, table size, index size, and total size

ParametersJSON Schema
NameRequiredDescriptionDefault
schema_nameNopublic
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing behavioral traits: it specifies the tool retrieves and analyzes information (read-only operation), provides sorted output, and explicitly prohibits destructive operations like deletion or structural changes. However, it doesn't mention potential rate limits, authentication needs, or performance impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with labeled sections (Tool Purpose, Exact Functionality, etc.), but it includes redundant elements like 'Args:' and 'Returns:' that repeat information from other sections. Some sentences could be more concise, but overall it's organized and front-loaded with key purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but has output schema), the description is complete: it covers purpose, functionality, usage guidelines, prohibitions, parameters, and return values. The output schema existence means the description doesn't need to detail return format, and it adequately addresses all necessary context for a read-only analysis tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains that 'schema_name' is the 'Schema name to analyze' with a default of 'public', and 'database_name' is 'Database name to analyze' with a default if omitted. This adds meaningful context beyond the bare schema, though it doesn't detail format constraints or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze size information and index usage of all tables in specified schema' with specific verbs (retrieve, analyze, provide) and resources (tables, schema). It clearly distinguishes from siblings like get_table_list (lists tables) or get_table_io_stats (I/O statistics) by focusing on size and index analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit 'Required Use Cases' (e.g., when user requests 'table size', 'schema capacity') and 'Strictly Prohibited Use Cases' (e.g., table data deletion, index creation/deletion). This provides clear guidance on when to use this tool versus alternatives, including what it should not be used for.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_functions_statsA

[Tool Purpose]: Analyze performance statistics for user-defined functions

[Exact Functionality]:

  • Show execution count and timing statistics for user functions

  • Calculate average execution time per function call

  • Identify performance bottlenecks in user-defined functions

  • Provide total and self execution time breakdown

[Required Use Cases]:

  • When user requests "function stats", "function performance", etc.

  • When analyzing user-defined function performance

  • When identifying slow or frequently called functions

  • When optimizing application function usage

[Strictly Prohibited Use Cases]:

  • Requests for function modification or optimization

  • Requests for statistics reset

  • Requests for function execution or testing

Args: database_name: Database name to analyze (uses default database if omitted)

Returns: User-defined function performance statistics including call counts and timing

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by detailing what the tool does (performance analysis) and what it doesn't do (modification, reset, execution). It clarifies the tool is read-only and diagnostic, though it could add more on behavioral traits like data freshness or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], etc.), front-loaded key information, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no annotations, and an output schema present, the description is complete. It covers purpose, functionality, usage guidelines, parameters, and returns, providing sufficient context for an agent to invoke it correctly without needing to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, but the description compensates by explaining the 'database_name' parameter as 'Database name to analyze (uses default database if omitted)', adding meaning beyond the bare schema. However, it doesn't detail format constraints or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Analyze performance statistics for user-defined functions' and details specific functionalities like execution count, timing statistics, and bottleneck identification. It clearly distinguishes from siblings by focusing on user functions rather than tables, indexes, or database-level metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests 'function stats') and 'Strictly Prohibited Use Cases' (e.g., requests for function modification), offering clear guidance on when to use this tool versus alternatives. It helps differentiate from siblings by specifying its niche in function performance analysis.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_listA

[Tool Purpose]: Retrieve list of all user accounts and permission information on PostgreSQL server

[Exact Functionality]:

  • Retrieve list of all database user accounts

  • Display permission information for each user (superuser, database creation rights, etc.)

  • Include account creation date and expiration date information

[Required Use Cases]:

  • When user requests "user list", "account info", "permission check", etc.

  • When user permission management or security inspection is needed

  • When account status overview is needed

[Strictly Prohibited Use Cases]:

  • Requests for user password information

  • Requests for user creation, deletion, or permission changes

  • Requests for specific user sessions or activity history

Returns: Table-format information including username, superuser status, permissions, and account status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It clearly describes this as a read-only retrieval operation (not creation/deletion), specifies the return format as 'Table-format information', and outlines what information is included. It doesn't mention rate limits, authentication requirements, or pagination behavior, but provides substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses clear section headers ([Tool Purpose], [Exact Functionality], etc.) making it easy to scan. While slightly verbose with bullet points, every section adds value and there's no redundant information. The structure helps the agent quickly understand different aspects of the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema (which handles return value documentation), the description provides excellent context. It covers purpose, functionality, use cases, prohibitions, and return format. Given the tool's simplicity and the presence of output schema, this description is complete and well-balanced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage. The description appropriately doesn't discuss parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema fully documents the absence of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Retrieve list of all user accounts and permission information on PostgreSQL server' with specific details about what information is included (superuser status, permissions, creation/expiration dates). It clearly distinguishes this from sibling tools like get_database_list or get_table_list by focusing specifically on user accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (user list requests, permission management, security inspection, account status overview) and 'Strictly Prohibited Use Cases' (password information, user creation/deletion, session/activity history). This gives clear guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vacuum_analyze_statsA

[Tool Purpose]: Analyze VACUUM and ANALYZE execution history and statistics per table

[Exact Functionality]:

  • Retrieve last VACUUM/ANALYZE execution time for each table

  • Provide Auto VACUUM/ANALYZE execution count statistics

  • Analyze table activity with tuple insert/update/delete statistics

[Required Use Cases]:

  • When user requests "VACUUM status", "ANALYZE history", "table statistics", etc.

  • When database maintenance status overview is needed

  • When performance issues or statistics update status verification is required

[Strictly Prohibited Use Cases]:

  • Requests for VACUUM or ANALYZE execution

  • Requests for Auto VACUUM configuration changes

  • Requests for forced statistics update

Args: database_name: Database name to analyze (uses default database if omitted)

Returns: Schema name, table name, last VACUUM time, last ANALYZE time, and execution count statistics

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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 effectively discloses behavioral traits: it's a read-only analysis tool (implied by 'retrieve', 'provide', 'analyze' without mutation terms), specifies what data it returns (execution times, counts, activity statistics), and clarifies limitations (e.g., no execution or configuration changes). However, it lacks details on rate limits, error handling, or authentication needs, which could be relevant for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with labeled sections ([Tool Purpose], [Exact Functionality], etc.), making it easy to parse. It's appropriately sized—each sentence adds value, such as detailing functionality and use cases without redundancy. However, it could be slightly more concise by integrating some sections (e.g., merging 'Exact Functionality' with 'Returns').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (analysis of database maintenance stats), the description is complete: it covers purpose, functionality, usage guidelines, parameter semantics, and return values. With an output schema present, the description doesn't need to detail return format, and it adequately addresses gaps from missing annotations (e.g., behavioral transparency). This provides a comprehensive understanding for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage (no schema descriptions), but the description compensates by explaining the single parameter: 'database_name: Database name to analyze (uses default database if omitted)'. This adds crucial context beyond the schema's basic type/name, clarifying its optional nature and default behavior. Since there's only one parameter, this is sufficient for high utility.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as analyzing VACUUM and ANALYZE execution history and statistics per table, using specific verbs ('retrieve', 'provide', 'analyze') and clearly identifying the resource (database tables). It distinguishes itself from siblings like get_running_vacuum_operations (which monitors active operations) and get_vacuum_effectiveness_analysis (which focuses on effectiveness rather than history/statistics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., when users request 'VACUUM status' or need maintenance overview) and 'Strictly Prohibited Use Cases' (e.g., requests for VACUUM execution or configuration changes). It clearly differentiates when to use this tool versus alternatives, such as avoiding it for active operations or configuration tasks handled by other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vacuum_effectiveness_analysisA

[Tool Purpose]: Analyze VACUUM effectiveness and maintenance patterns using existing statistics

[Exact Functionality]:

  • Compare manual VACUUM vs autovacuum effectiveness patterns

  • Analyze VACUUM frequency vs table activity (DML operations)

  • Identify tables with suboptimal VACUUM patterns

  • Calculate maintenance efficiency ratios without performance impact

  • Show VACUUM coverage analysis across all tables

[Required Use Cases]:

  • When user requests "VACUUM effectiveness", "maintenance efficiency", "VACUUM analysis", etc.

  • When planning manual VACUUM schedules or autovacuum tuning

  • When identifying tables with poor maintenance patterns

  • When analyzing overall database maintenance health

[Strictly Prohibited Use Cases]:

  • Requests for VACUUM execution or scheduling

  • Requests for autovacuum configuration changes

  • Requests for maintenance operation control

Args: database_name: Target database name (uses default database from POSTGRES_DB env var if omitted) schema_name: Schema to analyze (analyzes all user schemas if omitted) limit: Maximum number of tables to analyze (1-100, default: 30)

Returns: VACUUM effectiveness analysis with maintenance patterns and recommendations

ParametersJSON Schema
NameRequiredDescriptionDefault
database_nameNo
schema_nameNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is an analysis tool ('analyze', 'calculate', 'show') rather than an execution tool, and explicitly states it works 'without performance impact'. However, it doesn't mention authentication requirements, rate limits, or what specific statistics it accesses, leaving some behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections ([Tool Purpose], [Exact Functionality], [Required Use Cases], [Strictly Prohibited Use Cases], Args, Returns). Each section is focused and adds value. While somewhat detailed, every sentence serves a purpose in clarifying the tool's scope and usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's analytical nature, 3 parameters, no annotations, but with an output schema (implied by 'Returns' statement), the description provides comprehensive context. It covers purpose, functionality, usage guidelines, prohibitions, parameter semantics, and return value description. The output schema existence means the description doesn't need to detail return structure, making this complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by providing clear parameter explanations in the Args section. It explains that database_name uses a default from environment variable if omitted, schema_name analyzes all user schemas if omitted, and limit has a range and default. This adds meaningful context beyond the basic schema, though it doesn't explain the format or constraints of database/schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as analyzing VACUUM effectiveness and maintenance patterns using existing statistics. It specifies the exact functionality including comparing manual vs autovacuum, analyzing frequency vs activity, identifying suboptimal patterns, calculating efficiency ratios, and showing coverage analysis. This distinguishes it from sibling tools like get_autovacuum_activity or get_vacuum_analyze_stats which focus on different aspects of vacuum operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Required Use Cases' (e.g., when user requests VACUUM effectiveness, planning schedules, identifying poor patterns) and 'Strictly Prohibited Use Cases' (e.g., requests for VACUUM execution, autovacuum configuration changes, maintenance operation control). This gives clear guidance on when to use this tool versus alternatives that might handle execution or configuration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_wal_statusA

[Tool Purpose]: Monitor WAL (Write Ahead Log) status and statistics

[Exact Functionality]:

  • Show current WAL location and LSN information

  • Display WAL file generation rate and size statistics

  • Monitor WAL archiving status and lag

  • Provide WAL-related configuration and activity metrics

[Required Use Cases]:

  • When user requests "WAL status", "WAL monitoring", "log shipping status", etc.

  • When diagnosing replication lag or WAL archiving issues

  • When monitoring database write activity and WAL generation

[Strictly Prohibited Use Cases]:

  • Requests for WAL configuration changes

  • Requests for manual WAL switching or archiving

  • Requests for WAL file manipulation or cleanup

Returns: WAL status information including current LSN, WAL files, archiving status, and statistics

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by listing what it monitors (e.g., WAL location, archiving status, statistics) and explicitly prohibits write operations. However, it doesn't mention potential side effects like performance impact or data freshness, leaving some behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Tool Purpose, Exact Functionality, etc.), making it easy to parse. It's appropriately sized for the complexity, but some redundancy exists (e.g., 'Returns' section repeats functionality). Every sentence adds value, though minor trimming could improve conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (monitoring WAL status), no annotations, an output schema exists, and 0 parameters, the description is complete. It covers purpose, functionality, use cases, prohibitions, and return values, providing sufficient context for an AI agent to understand and invoke the tool correctly without relying on structured fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter semantics beyond the schema, but this is appropriate since there are no parameters. A baseline of 4 is applied as it adequately handles the parameter-less case without unnecessary details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'Monitor WAL (Write Ahead Log) status and statistics' with a clear verb ('Monitor') and resource ('WAL status and statistics'). It distinguishes from sibling tools by focusing specifically on WAL monitoring rather than connections, tables, replication, or other database metrics, making the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance with 'Required Use Cases' (e.g., when user requests WAL status, diagnosing replication lag) and 'Strictly Prohibited Use Cases' (e.g., WAL configuration changes, manual WAL switching). This clearly defines when to use this tool versus alternatives, though it doesn't name specific sibling tools, the use cases implicitly differentiate it from other monitoring tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 34 tool updatesv1.0.0
    • Addedget_active_connections
    • Addedget_all_tables_stats
    • Addedget_autovacuum_activity
    • Addedget_autovacuum_status
    • Addedget_bgwriter_stats
    • Addedget_current_database_info
    • Addedget_database_bloat_overview
    • Addedget_database_conflicts_stats
    • Addedget_database_list
    • Addedget_database_schema_info
    • Addedget_database_size_info
    • Addedget_database_stats
    • Addedget_index_io_stats
    • Addedget_index_usage_stats
    • Addedget_io_stats
    • Addedget_lock_monitoring
    • Addedget_pg_stat_monitor_recent_queries
    • Addedget_pg_stat_statements_top_queries
    • Addedget_postgresql_config
    • Addedget_prompt_template
    • Addedget_replication_status
    • Addedget_running_vacuum_operations
    • Addedget_server_info
    • Addedget_table_bloat_analysis
    • Addedget_table_io_stats
    • Addedget_table_list
    • Addedget_table_relationships
    • Addedget_table_schema_info
    • Addedget_table_size_info
    • Addedget_user_functions_stats
    • Addedget_user_list
    • Addedget_vacuum_analyze_stats
    • Addedget_vacuum_effectiveness_analysis
    • Addedget_wal_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation3/5

The tools have clear descriptions but significant overlap exists in monitoring areas. For example, get_autovacuum_activity, get_autovacuum_status, get_vacuum_analyze_stats, and get_vacuum_effectiveness_analysis all focus on vacuum operations with subtle distinctions that could confuse agents. Similarly, multiple I/O and statistics tools (get_io_stats, get_table_io_stats, get_index_io_stats, get_database_stats) have overlapping purposes despite targeting different objects.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'get_' prefix, making them predictable and readable. The naming convention is uniformly applied across all 34 tools, with clear descriptive names that indicate their purpose (e.g., get_table_bloat_analysis, get_replication_status).

Tool Count2/5

34 tools is excessive for a PostgreSQL monitoring server, creating cognitive overload. While PostgreSQL has many monitoring aspects, the tool set feels bloated with redundant tools (e.g., four vacuum-related tools) and could be consolidated. A more focused set of 15-20 tools would better serve the domain.

Completeness4/5

The tool set provides comprehensive monitoring coverage for PostgreSQL administration, including connections, performance, replication, vacuum, bloat, and configuration. Minor gaps exist in areas like session management (e.g., no tool for session termination) and real-time query execution, but core monitoring workflows are well-covered.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Postgres MCP Server

    itsalfredakku
    F
    license
    A
    quality
    Not graded
    maintenance
    Enables comprehensive PostgreSQL database management through natural language including queries, schema operations, user management, and administrative tasks. Features enterprise-grade connection pooling, transaction support, and full database administration capabilities.
    11
    121
    1
    -

  • Postgres MCP Pro

    BACH-AI-Tools
    A
    license
    B
    quality
    D
    maintenance
    Enables comprehensive PostgreSQL database management including index tuning, query plan analysis, health monitoring, schema-aware SQL generation, and safe SQL execution with configurable access control for both development and production environments.
    9
    MIT

  • mcp-postgres

    divinedev111
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with PostgreSQL databases through schema intelligence, query execution, and DBA tooling including index analysis and health monitoring. Features configurable access levels and audit logging for secure database operations.
    751
    MIT

  • postgres-mcp-server

    mukul975
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to manage, monitor, and optimize PostgreSQL databases with over 200 specialized tools for operations, security, performance tuning, and diagnostics.
    29
    8
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/call518/MCP-PostgreSQL-Ops'

If you have feedback or need assistance with the MCP directory API, please join our Discord server