Skip to main content
Glama

WAL and checkpoints

pg_wal_checkpoints
Read-onlyIdempotent

Diagnose scheduled versus forced checkpoint and WAL activity to explain write-heavy I/O spikes and archiving issues, and identify tuning actions like raising max_wal_size.

Instructions

Explain how checkpoints and WAL behave: scheduled versus forced checkpoints and the buffers they wrote (pg_stat_bgwriter up to PostgreSQL 16, pg_stat_checkpointer from 17), WAL volume (pg_stat_wal, 14+), the archiver (pg_stat_archiver), the current WAL position and the WAL-related settings, ending with a one-line reading such as "forced checkpoints: raise max_wal_size".

Use it for write-heavy servers, I/O spikes every few minutes and archiving problems. Counters accumulate since the statistics reset.

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_wal_checkpoints"
  }
}

Input Schema

NameRequiredDescriptionDefault
connectionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuinely useful context beyond them: the source views are version-dependent (pg_stat_bgwriter through 16, pg_stat_checkpointer from 17, pg_stat_wal on 14+), counters accumulate since the last statistics reset, and the output terminates in a diagnostic one-liner. It does not mention access requirements (typically pg_monitor) or per-view availability caveats, which keeps it at 4.

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?

The description is front-loaded with the scope of what is inspected before the usage triggers, and every clause carries information. The parenthetical version notes are dense but justified; the only mild cost is length in a single dense paragraph.

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 carries the burden of describing returns, and it does so by listing the statistical views covered and the summary reading line at the end. Version gating is disclosed, so an agent knows results vary by server version. Missing connection/role prerequisites is the only real gap.

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?

There is a single optional 'connection' parameter with 0% schema description coverage, and the description never mentions it or explains how the target server is selected. Because the parameter is optional, defaulted to null, and self-descriptively named, the gap is minor, but the description does not compensate for the coverage shortfall.

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 names a concrete resource domain (checkpoints and WAL) and enumerates exactly what is reported: scheduled vs forced checkpoints, buffers written, WAL volume, archiver, current WAL position, and WAL settings, plus a synthesized one-line reading. That scope is narrow and distinct enough that an agent can differentiate it from pg_activity, pg_health_check, or pg_database_stats without opening any 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?

It gives clear triggering conditions: write-heavy servers, I/O spikes recurring every few minutes, and archiving problems. That is a solid when-to-use signal. What is missing is any exclusion or named alternative (e.g., go to pg_cache_io for buffer cache pressure instead), so it stops short of a 5.

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