Skip to main content
Glama
YawLabs

@yawlabs/postgres-mcp

by YawLabs
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Estimate table bloat

pg_table_bloat
Read-onlyIdempotent

Measure dead tuples and free space to estimate table bloat, returning dead ratio and vacuum timestamps to identify tables needing VACUUM.

Instructions

Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM. On PostgreSQL 19+ every row also carries stats_reset: the last time THAT relation's counters were reset via pg_stat_reset_single_table_counters(). Read it before trusting anything else in the row -- a reset zeroes live_tuples and dead_tuples AND clears last_vacuum / last_autovacuum / last_analyze together, so a table reset a minute ago is indistinguishable from a pristine one without it. The key is ABSENT on older servers rather than null; null on PG19+ means this relation's counters have never been reset.

Three methods are available via the method parameter:

  • estimate (default): reads pg_stat_user_tables -- fast, no extensions, ANALYZE-driven approximations. Use this first.

  • approx: uses pgstattuple_approx() -- fast sampling pass, more accurate than estimates, requires the pgstattuple extension.

  • exact: uses pgstattuple() -- full table scan, exact counts, slow on large tables, requires the pgstattuple extension. Always pass schema with method='exact' -- scanning all user tables in one statement will hit statement_timeout on non-trivial databases. Install pgstattuple with CREATE EXTENSION pgstattuple (requires superuser).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax rows to return (default 50).
methodNoBloat measurement method. 'estimate' (default) uses pg_stat_user_tables (fast, no extensions). 'approx' uses pgstattuple_approx() (fast sampling, more accurate). 'exact' uses pgstattuple() (full scan, exact but slow). Both 'approx' and 'exact' require the pgstattuple extension.estimate
schemaNoLimit to one schema. If omitted, all user schemas are included.
minDeadRatioNoMinimum dead-tuple fraction to include - dead / (live + dead). Default 0.1 = 10%.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
rowsYes

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed8 schema fields changedv0.12.1
    • removedOutput schema / properties / rows / items / properties / last_analyze / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / rows / items / properties / last_analyze / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / rows / items / properties / last_autovacuum / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / rows / items / properties / last_autovacuum / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / rows / items / properties / last_vacuum / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / rows / items / properties / last_vacuum / type
      Added value: +[
+  "string",
+  "null"
+]
    • removedOutput schema / properties / rows / items / properties / stats_reset / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / rows / items / properties / stats_reset / type
      Added value: +[
+  "string",
+  "null"
+]
  2. Changed2 schema fields changedv0.12.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "rows": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "dead_ratio": {
+            "description": "dead / (live + dead), bounded [0, 1]. Rows with both counters at 0 are filtered.",
+            "type": "number"
+          },
+          "dead_tuples": {
+            "description": "Bigint as a decimal string.",
+            "type": "string"
+          },
+          "last_analyze": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_autovacuum": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_vacuum": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "live_tuples": {
+            "description": "Bigint as a decimal string.",
+            "type": "string"
+          },
+          "schema": {
+            "type": "string"
+          },
+          "size_bytes": {
+            "type": "string"
+          },
+          "size_pretty": {
+            "type": "string"
+          },
+          "stats_reset": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "PostgreSQL 19+ only, absent below that. When THIS relation's counters were last reset by pg_stat_reset_single_table_counters() -- which zeroes the tuple counts AND clears every last_* timestamp together. Null on PG19+ means never reset."
+          },
+          "table": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "schema",
+          "table",
+          "live_tuples",
+          "dead_tuples",
+          "dead_ratio",
+          "size_pretty",
+          "size_bytes",
+          "last_vacuum",
+          "last_autovacuum",
+          "last_analyze"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "rows"
+  ],
+  "type": "object"
+}
  3. First observedv0.7.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, non-destructive, yet the description goes far beyond them. It discloses the stats_reset caveat in detail, explaining how resets can masquerade as pristine tables and that the key is absent on older PG versions. It also reveals method tradeoffs, timeout risks, and superuser extension needs, providing substantial behavioral insight.

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?

Though long, every sentence carries operational weight: core purpose first, then a critical warning, then method guidance. The bulleted method breakdown makes scanning easy. No filler or redundancy; the length is justified by the complexity of the behavior.

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, the description is remarkably complete. It covers return fields, interpretation of dead_ratio with last_autovacuum, the PG19+ stats_reset nuance, method selection, extension prerequisites, and a concrete timeout warning. The presence of an output schema means return-value details need no further elaboration.

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 coverage is 100%, so baseline is 3, but the description enriches method semantics substantially beyond the schema. It explains the practical consequences of each method, the timeout danger of exact without schema, and when to prefer estimate. This added meaning directly helps an agent choose parameter values correctly.

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 opens with a specific verb and resource: 'Estimate table bloat (dead tuples + free space) for tables in a schema.' It clarifies exactly what the tool returns and stands apart from sibling tools, which all target different PG operations. No ambiguity remains about the tool's core function.

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?

The description gives clear method-selection guidance: 'Use this first' for estimate, warns that exact is slow, and mandates passing schema with exact to avoid timeouts. It also explains the extension requirement and install command. It does not explicitly contrast this tool with sibling tools, but the guidance within the tool is strong and context-rich.

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

Install Server

Other Tools

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/YawLabs/postgres-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server