MCP PostgreSQL Operations

Overview Schema Source Related Servers Discussions Admin

get_pg_stat_statements_top_queries

Identify top queries by total execution time via pg_stat_statements, with call counts, average time, and cache hit rates to guide PostgreSQL performance tuning.

Instructions

[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

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_pg_stat_statements_top_queries"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Number of top queries to retrieve (default: 20, max: 100)
`database_name`	No	Database name to analyze (uses default database if omitted)

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv3.4.3Oct 27, 2026
- addedInput schema / properties / database_name / description
```
Added value: +"Database name to analyze (uses default database if omitted)"
```
- addedInput schema / properties / limit / description
```
Added value: +"Number of top queries to retrieve (default: 20, max: 100)"
```
Changed7 schema fields changedv3.4.2Oct 25, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / database_name / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedInput schema / properties / database_name / title
```
Removed value: -"Database Name"
```
- removedInput schema / properties / database_name / type
```
Removed value: -"string"
```
- removedInput schema / properties / limit / title
```
Removed value: -"Limit"
```
- removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
- removedOutput schema / title
```
Removed value: -"_WrappedResult"
```
Addedv1.0.0Jan 3, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the burden well: it names the prerequisite (pg_stat_statements installed), lists the metrics returned (call count, average execution time, cache hit rate), and the prohibited list implies a read-only nature. It does not explicitly declare read-only semantics or any limits, leaving a small 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?

Bracketed section headings front-load purpose, functionality and usage, and every section carries useful content. Slightly verbose formatting but no filler sentences.

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?

An output schema exists so return values need not be explained, and the description covers prerequisites, metrics, and scope. Complete enough to call correctly; only read-only semantics and any result-size caveats are unstated.

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 100%, so both 'limit' and 'database_name' are fully documented in the schema including default and max. The description adds no parameter-level detail beyond that, so baseline 3 applies.

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?

States a specific verb and resource ('Analyze top queries that consumed the most time') and scopes it to the pg_stat_statements extension, which implicitly separates it from the pg_stat_monitor sibling. It stops short of naming an alternative tool explicitly, so it is clear but not fully differentiated.

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?

Provides explicit 'Required Use Cases' (slow queries, performance analysis, tuning) and 'Strictly Prohibited Use Cases' (extension absent, query execution, reset/config changes). An agent has concrete trigger phrases and clear exclusions.

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

Deploy Server