Skip to main content
Glama

Count rows

pg_count_rows
Read-onlyIdempotent

Count rows in a PostgreSQL table: get an instant planner-statistics estimate, or the exact count(*) by setting exact=true. Use the estimate on big tables to avoid a full scan.

Instructions

Count the rows of a table: an instant estimate from the planner statistics, and with exact=true the real count(*).

The estimate costs nothing and is usually within a few percent; it adds up the partitions or child tables of a partitioned table, and says when the table was last analyzed (a table never analyzed has no useful estimate). The exact count reads the whole table, so on a big table prefer the estimate, or filter with pg_query.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "table": "<table>"
    },
    "name": "pg_count_rows"
  }
}

Input Schema

NameRequiredDescriptionDefault
exactNo
tableYes
connectionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds substantial behavior beyond that: the estimate is derived from planner statistics, usually within a few percent, aggregates partitions/child tables, reports last-analyze time, and is useless on never-analyzed tables. It also warns that exact reads the whole table.

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?

Two focused paragraphs, front-loaded with the core action and the mode distinction, then the tradeoffs. Nearly every sentence carries information; only minor tightening is possible.

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?

No output schema exists, and the description does signal what the estimate path returns (a row estimate plus last-analyzed time), which is enough to interpret results. The undocumented connection parameter is the main remaining gap for a 3-parameter tool.

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 coverage is 0%, so the description must compensate. It fully explains the key parameter 'exact' (real count(*) vs planner estimate), but leaves the 'connection' parameter undocumented and says nothing about table naming/qualification.

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 ('Count the rows of a table') and immediately distinguishes its two modes, planner estimate vs exact count(*). An agent can tell this apart from pg_query or pg_sample_rows from the description alone.

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 a clear rule: the estimate is free and usually close, so on a big table prefer it; use exact=true when a true count is needed, or 'filter with pg_query' instead. It names the pg_query alternative but does not frame explicit when-not-to-use cases beyond size.

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