MCP PostgreSQL Operations

Overview Schema Source Related Servers Discussions Admin

get_io_stats

Analyze PostgreSQL I/O statistics and buffer cache efficiency to identify storage bottlenecks across database operations, with compatibility for versions 12–17.

Instructions

[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

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of results to return (1-100, default 20)
`database_name`	No	Target database name (optional)

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: +"Target database name (optional)"
```
- addedInput schema / properties / limit / description
```
Added value: +"Maximum number of results to return (1-100, default 20)"
```
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

A3.9/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, and it does substantial work: it discloses version-gated behavior and a fallback path (pg_stat_io vs pg_statio_*), which materially changes what the agent will get, and it clarifies the operation is read-only by prohibiting tuning/reset actions. It stops short of stating permissions or cost/latency expectations for a stats scan.

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?

Clearly front-loaded with purpose first, then mechanics, then usage gates — good information ordering. The bracketed section labels ([Tool Purpose], [Exact Functionality], [Strictly Prohibited Use Cases]) and some restated phrasing add mild overhead, but no sentence is genuinely wasteful.

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?

With an output schema present, return values needn't be explained, and both parameters are fully documented in the schema, so the remaining burden is behavioral and routing context — which the version fallback and use-case gates largely cover. The one real gap is disambiguation from the four I/O-focused siblings, which an agent would need in order to pick this 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 100% — both 'limit' (1-100, default 20) and 'database_name' are fully documented in the schema. The description adds nothing about what limiting means here (top-N by what?) or how database scoping interacts with instance-level pg_stat_io, so the 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?

The description gives a specific verb+resource ('Analyze comprehensive I/O statistics across all database operations') and even discloses version-dependent implementation (pg_stat_io for 16+, pg_statio_* for 12-15). It does not, however, explicitly distinguish itself from close siblings like get_table_io_stats, get_index_io_stats, or get_per_backend_io_stats, so the agent must infer the scope difference from 'across all database operations'.

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

Usage Guidelines4/5

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

Strong explicit context: enumerated trigger phrases ('I/O stats', 'buffer cache analysis'), four use cases, and three strictly prohibited cases (config changes, storage modification, stats reset). What it lacks is named alternatives — it never says to use get_table_io_stats or get_per_backend_io_stats for the narrower scopes, which is the main ambiguity among these siblings.

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

Deploy Server