MCP PostgreSQL Operations

Overview Schema Source Related Servers Discussions Admin

get_table_bloat_analysis

Analyze PostgreSQL table bloat using dead tuple and size statistics to identify tables needing VACUUM maintenance and estimate storage waste.

Instructions

[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

Input Schema

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

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv3.4.3Oct 27, 2026

addedInput schema / properties / database_name / description

Added value: +"Target database name (uses default database from POSTGRES_DB env var if omitted)"

addedInput schema / properties / limit / description

Added value: +"Maximum number of results to return (1-100, default: 20)"

addedInput schema / properties / min_dead_tuples / description

Added value: +"Minimum dead tuples to include in results (default: 1, shows all tables with any bloat)"

addedInput schema / properties / schema_name / description

Added value: +"Schema to analyze (analyzes all user schemas if omitted)"

addedInput schema / properties / table_pattern / description

Added value: +"Table name pattern to filter (SQL LIKE pattern, e.g., 'user%', '%log%', 'temp_*')"

Changed14 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"
```
- removedInput schema / properties / min_dead_tuples / title
```
Removed value: -"Min Dead Tuples"
```
- addedInput schema / properties / schema_name / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedInput schema / properties / schema_name / title
```
Removed value: -"Schema Name"
```
- removedInput schema / properties / schema_name / type
```
Removed value: -"string"
```
- addedInput schema / properties / table_pattern / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedInput schema / properties / table_pattern / title
```
Removed value: -"Table Pattern"
```
- removedInput schema / properties / table_pattern / type
```
Removed value: -"string"
```
- removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
- removedOutput schema / title
```
Removed value: -"_WrappedResult"
```
Addedv1.0.0Jan 3, 2026

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden, and it does most of the work: it makes clear this is a read-only analysis that never executes VACUUM or modifies data, and explains that results are derived from dead tuple statistics and sorted by severity. It does not disclose cost/performance on large catalogs or the scope of scanning when schema_name is omitted, which are the remaining behavioral gaps.

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?

Headers (Purpose / Exact Functionality / Use Cases / Prohibited) make it front-loaded and skimmable, and each bullet is a distinct fact rather than filler. It is longer than strictly necessary for a single filtered-read tool, with some redundancy between the purpose line and the functionality bullets.

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 no explanation, and all five parameters are optional and schema-documented; the description fills in the analysis semantics and the safety boundaries an agent needs. The one missing piece is how to choose between this tool and get_database_bloat_overview or get_vacuum_analyze_stats when the user's intent is ambiguous.

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 coverage is 100%, so baseline is 3; the description adds real value by specifying that table_pattern supports SQL LIKE or ILIKE matching and by stating that schema_name omitted means 'all user schemas' and that database_name falls back to POSTGRES_DB. It does not elaborate on limit or min_dead_tuples beyond the schema text, so it stops short of a 5.

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 names a specific verb and resource ('Analyze table bloat based on dead tuple statistics and size information') and enumerates exactly what is computed (bloat ratio, bloat size, last VACUUM timestamps, severity sorting). It is clear what the tool does, but it never distinguishes itself from the closely-related siblings get_database_bloat_overview or get_table_size_info, so an agent must infer the split.

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?

It provides explicit 'Required Use Cases' with literal trigger phrases ('table bloat', 'dead tuples') and an explicit 'Strictly Prohibited Use Cases' block ruling out VACUUM execution, cleanup, and data modification. This is a full when-to-use / when-not-to-use contract, with only the sibling routing left implicit.

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

Deploy Server