Skip to main content
Glama

Table and index bloat

pg_bloat
Read-onlyIdempotent

Estimate table and btree index bloat from planner statistics, rank relations by wasted bytes without scanning, or measure a specific table with pgstattuple for exact density.

Instructions

Estimate how much space tables and btree indexes waste (bloat) and rank them by wasted bytes, without scanning anything: the estimate comes from the row counts and average row widths in the planner statistics and is usually within 10 to 20 percent.

kind is tables, indexes or both; schema narrows the search; min_wasted_bytes hides small waste. Relations never analyzed are skipped (run ANALYZE). For a measurement instead of an estimate pass exact_table (name or schema.name): it reads that table with the pgstattuple extension (pgstattuple_approx when available) and also reports the density of its btree indexes, at the cost of reading the relation.

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": "pg_bloat"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoboth
limitNo
schemaNo
connectionNo
exact_tableNo
min_wasted_bytesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description still adds real value: the estimate is derived from planner statistics rather than a scan, accuracy is typically within 10-20 percent, unanalyzed relations are skipped, and the exact path depends on the pgstattuple extension. That is solid supporting context beyond the annotations, though the cost/risk of enabling pgstattuple is only hinted at.

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?

Front-loads the core purpose and accuracy caveat, then devotes a compact paragraph to parameter meaning and the estimate-vs-exact tradeoff. Nearly every clause carries information; no filler.

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 no output schema, the description still tells the agent what comes back (relations ranked by wasted bytes, plus btree index density in exact mode). Missing detail on limit/pagination and connection selection keeps it short of complete for a six-parameter 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 carry the load for six parameters. It explains kind, schema, min_wasted_bytes and exact_table (including its name/schema.name format), leaving limit and connection unexplained, which is a reasonable but not complete compensation.

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?

States a specific verb and resource ("Estimate how much space tables and btree indexes waste") plus the ranking criterion (wasted bytes), and explicitly separates the cheap estimate path from the exact measurement path, so an agent can tell the two behaviors apart without opening the schema.

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?

Gives clear when-to-use guidance: use the default for a fast estimate, pass exact_table for a measurement at the cost of reading the relation, run ANALYZE when relations are skipped. It does not contrast with sibling tools such as pg_table_stats or pg_index_stats, but the internal mode routing is well covered.

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