Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor. "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
Governed AI-ops for PostgreSQL DBA operations — connecting to a server with
psycopg 3 and reading the system catalogs and pg_stat_* views — with a
built-in governance harness: unified audit log, token/runaway
budget guard, undo-token recording, and descriptive risk-tier labels.
Beyond the mock test suite, the reads, a governed write, and its undo have been
exercised against a live PostgreSQL 16.14 instance — see docs/VERIFICATION.md.
Three flagship signature analyses, plus the guarded reads and writes around them:
Slow-query RCA — take the worst pg_stat_statements entry (plus an optional
EXPLAIN plan) and map its numbers — mean time, cache-hit ratio, temp spill,
call count, plan node types — to a cited cause and a concrete action. Every
finding carries its measured number, not a black-box verdict.
Bloat & vacuum analysis — combine per-table dead-tuple ratio and autovacuum recency into a ranked, cited recommendation (VACUUM / tune autovacuum).
Blocking lock-chain RCA — build the wait-for tree from pg_blocking_pids,
name the root blocker (blocks others, waits on none), and give the action;
a cycle is flagged as a likely deadlock.
Related MCP server: mysql-aiops
CLI (postgres-aiops ...): init, overview, server, activity, query, index, table, repl, analyze, remediate, secret, doctor, mcp.
MCP server (postgres-aiops mcp or postgres-aiops-mcp): 35 tools (25 read, 10 write), every one wrapped with the bundled @governed_tool harness.
Encrypted credentials: the role password lives in an encrypted store ~/.postgres-aiops/secrets.enc (Fernet + scrypt) — never plaintext on disk. Unlock with a master password from POSTGRES_AIOPS_MASTER_PASSWORD (MCP/CI) or an interactive prompt (CLI).
Reversibility: mutating writes fetch the real before-state first and record a faithful inverse — create_index↔drop_index; drop_index captures pg_get_indexdef so undo recreates it exactly; update_setting captures the prior value so undo sets it back. Irreversible ops (terminate_backend, cancel_query, run_vacuum, run_analyze, reindex, reset_query_stats) record prior stats for audit but declare no undo.
Safety: every state-changing CLI op supports --dry-run and requires double confirmation; every write MCP tool takes a dry_run preview. All identifiers that cannot be parameterised (table/index/GUC names) are validated and quoted; all values are bound query parameters.
Domain | Tools | Count | R/W |
Overview |
| 1 | read |
Server |
| 5 | read |
Activity |
| 3 | read |
Queries |
| 2 | read |
Indexes |
| 4 | read |
Tables |
| 3 | read |
Replication |
| 3 | read |
Analysis (flagship) |
| 3 | read |
Writes |
| 3 | write (high) |
| 6 | write (medium) | |
Undo |
| 1 | read |
| 1 | write (medium) |
The flagship analyses accept injected records for pure/offline analysis, or pull
live from a configured target. top_queries/slow_query_rca require the
pg_stat_statements extension; the read role should have pg_monitor.
It delivers PostgreSQL DBA operations — reads and writes — accurately and efficiently, and records every one of them. It does not decide whether a write is allowed to happen. That is the agent's judgement, or the permission of the account you connect it with: connect with a PostgreSQL role that has no write privileges (a read-only role, or one without INSERT/UPDATE/DELETE/DDL), and the writes fail at the server — the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.postgres-aiops/audit.db,
and destructive writes still capture their before-state and record an inverse
where one exists.
Each tool declares a
risk_level, carried into the audit row as a descriptive tier (none/confirm/review) — so a reviewer can see at a glance that a row was a high-risk delete. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install postgres-aiops@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with postgres-aiops init — see below.
uv tool install postgres-aiops # or: pipx install postgres-aiops
postgres-aiops init # wizard: add a target + store the password (encrypted)
postgres-aiops doctor # verify config, secrets, connectivity
postgres-aiops overview # one-shot cluster health snapshot
postgres-aiops analyze slow-query # RCA the worst pg_stat_statements entry
postgres-aiops table bloat # dead-tuple bloat proxy per tableRun as an MCP server (stdio):
export POSTGRES_AIOPS_MASTER_PASSWORD=... # unlock secrets non-interactively
postgres-aiops-mcpEvery MCP tool passes through the bundled @governed_tool harness:
Audit — every call (params, result, status, duration, risk tier, and any
operator-supplied approver/rationale) is logged to ~/.postgres-aiops/audit.db
(relocatable via POSTGRES_AIOPS_HOME). The CLI writes the same row the MCP
path does — there is no unaudited entry point.
Runaway guard — a safety backstop, not an authorization gate: the same call
hammered in a tight loop trips a circuit breaker. Disable with
POSTGRES_RUNAWAY_MAX=0; optional hard ceilings via POSTGRES_MAX_TOOL_CALLS /
POSTGRES_MAX_TOOL_SECONDS.
Undo recording — reversible writes record an inverse descriptor built from the fetched before-state.
Risk tier — a descriptive label on the audit row derived from risk_level;
it gates nothing.
This is the PostgreSQL DBA-ops member of the AIops-tools family (governed
AI-ops with audit + budget + undo + risk tiers). Do NOT use it for OT /
industrial edge (Modbus, OPC-UA, PROFINET) — see the separate industrial-aiops
line — nor for application-schema migrations or ORM management.
Coverage is intentionally a curated subset of PostgreSQL's catalogs and maintenance surface. Missing a view, a metric, or a maintenance command? Open an issue or PR — contributions welcome.
The mock test suite is complemented by a live run: the catalog / pg_stat_*
reads, the bloat_and_vacuum_analysis RCA, and the create_index / drop_index
governed write path (audit + undo, with drop_index capturing
pg_get_indexdef first) were exercised against a live PostgreSQL 16.14 instance running in
Docker. docs/VERIFICATION.md records exactly what was
and was not covered. postgres-aiops doctor is the fastest live check.
[READ] Per-table dead tuples, mods-since-analyze, and last (auto)vacuum times.
Args:
limit: Number of tables to inspect (default 50).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The '[READ]' prefix indicates a read-only operation, but no annotations exist to confirm safety. The description does not disclose any side effects, permissions required, or additional behavioral traits. It only lists the output fields, leaving ambiguity about whether modifications occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for purpose and two lines for parameters. It is well-structured and front-loaded with the read indicator and output summary. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a high-level idea of the return values but lacks detail on formatting, pagination, or edge cases (e.g., what happens when limit is exceeded). Sibling tools like 'bloat_and_vacuum_analysis' may offer more comprehensive analysis, but the description does not differentiate or clarify completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds clear explanations for both parameters: 'limit' as number of tables and 'target' as config name. This compensates for the schema gaps, though it does not specify if 'limit' is a maximum or exact count.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns per-table dead tuples, modification counts, and last vacuum times. The name 'autovacuum_status' aligns with this, and it is clearly distinct from sibling tools like 'run_vacuum' or 'bloat_and_vacuum_analysis'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'bloat_and_vacuum_analysis' or 'run_vacuum'. The description only states what it does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Rank tables needing vacuum from dead-tuple ratio + autovacuum recency.
Pass 'tables' (as from table_bloat) for pure/offline analysis, or omit to
pull the worst dead-tuple tables live. Each recommendation cites its numbers.
Args:
tables: Injected table-bloat rows; if omitted, pulled live.
limit: How many tables to pull when not injected (default 50).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| tables | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Starts with '[READ]' to indicate read-only behavior, especially important since no annotations are provided. Explains two modes and that each recommendation cites numbers. Does not mention potential performance implications of live mode, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short paragraphs, front-loaded with the purpose and [READ] tag. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage modes, parameters, and a hint about output (numbers). However, it does not explicitly describe the output format (e.g., list of tables with scores) or the exact ranking criteria, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains each parameter: 'tables' (injection vs. live), 'limit' (default 50, only when not injected), and 'target' (config target). Adds meaning beyond type and name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Rank' and the resource 'tables needing vacuum', with the criteria 'dead-tuple ratio + autovacuum recency'. It distinguishes from siblings by mentioning the 'tables' parameter can come from sibling 'table_bloat', indicating a complementary relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes two usage modes: offline analysis with injected tables (from table_bloat) and live querying without the 'tables' parameter. However, it does not explicitly exclude scenarios or compare to other analysis tools like autovacuum_status or run_vacuum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Build the wait-for tree from blocking pairs and name the root blocker.
Pass 'pairs' (as from the live blocking-pairs read) for pure/offline analysis,
or omit to pull the current blocking graph live.
Args:
pairs: Injected blocking pairs {blockedPid, blockingPid, ...}; if omitted,
pulled live from pg_blocking_pids.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| pairs | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description starts with '[READ]', indicating idempotent/safe behavior. It explains both data sources (injected pairs or live pull) and the action (building tree, naming root blocker). No side effects are implied, and the safety profile is clear despite no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a one-line summary followed by parameter-specific guidance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the output format. It says the tool builds a tree and names the root blocker, but does not describe the return value structure, which is essential for the agent to use the result. No output schema exists to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaningful details: 'pairs' are blocking pairs with {blockedPid, blockingPid} format, and 'target' is a config name. It explains their defaults and behaviors, which is crucial for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a wait-for tree from blocking pairs and identifies the root blocker. It distinguishes itself from siblings like list_locks and slow_query_rca by focusing on chain analysis and root cause identification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to pass 'pairs' (for offline analysis) versus omit them (for live analysis). However, it does not explicitly compare to sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=high] Cancel a backend's running query (pg_cancel_backend). No inverse.
Captures the backend's pid + query for audit; a cancel has no undo. Pass
dry_run=True to preview.
Refuses this tool's own backend pid — the query it would cancel is this very
call. Enforced under dry_run too.
Args:
pid: Backend process id (from list_activity).
dry_run: If True, preview without cancelling.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | ||
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses high risk, audit logging, no undo, and self-prevention. It transparently states the operation is destructive and irreversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with risk tags, and each sentence provides critical information. No redundancy; compact yet thorough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-risk mutation tool with no output schema, it covers purpose, parameters, and side effects. It lacks return value details but that is acceptable for a cancellation action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description details each parameter: pid from list_activity, dry_run for preview, target from config. It adds necessary context beyond the schema's titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels a running query via pg_cancel_backend. It distinguishes itself from siblings like terminate_backend and reset_query_stats by focusing on the query itself and noting the no-inverse property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use (cancel a query) and when not (refuses its own backend pid). It advises using dry_run for preview. However, it does not explicitly contrast with alternatives like terminate_backend.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Create an index. Reversible: undo drops the created name.
Supports CONCURRENTLY (non-blocking build). The created name is returned so
the harness records an undo that drops exactly this index. Pass dry_run=True
to preview. Alternatively pass ``definition`` (a captured pg_get_indexdef
statement — this is how drop_index's undo descriptor replays) INSTEAD of
table/columns.
Args:
table: Table to index (optionally schema-qualified). Required unless
``definition`` is given.
columns: Column names to index. Required unless ``definition`` is given.
name: Index name (auto-generated from table+columns when omitted).
unique: Create a UNIQUE index.
concurrently: Build with CONCURRENTLY (no table lock).
method: Index method — btree/hash/gist/gin/brin/spgist (default btree).
definition: A full CREATE [UNIQUE] INDEX statement to execute verbatim
(shape-validated). Mutually exclusive with table/columns.
dry_run: If True, preview without creating.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| table | No | ||
| method | No | ||
| target | No | ||
| unique | No | ||
| columns | No | ||
| dry_run | No | ||
| definition | No | ||
| concurrently | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses risk level ('medium'), WRITE nature, reversibility via undo, support for CONCURRENTLY, and dry-run preview. It also explains how the created name is returned for undo recording, offering comprehensive 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a header, explanatory paragraphs, and a bullet list. While somewhat verbose, each sentence adds value. The length is justified by the number of parameters and complexity, but could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema, no schema descriptions), the description is remarkably complete. It covers both usage modes, behavioral traits, parameter dependencies, and even hints at return value ('created name is returned'). Only minor omissions like error handling or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by detailing each parameter's purpose, required combinations, mutual exclusivity of table/columns with definition, defaults (auto-generated name, btree method), and behavior (dry_run preview). All 9 parameters are thoroughly explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates an index, distinguishes from drop_index and reindex by emphasizing creation and reversibility via undo. The verb 'Create' and resource 'index' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool (to create an index) and mentions an alternative mode using 'definition' for recreating indexes, which is related to drop_index's undo. However, it does not explicitly exclude usage when other tools like reindex would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=high] Drop an index. Reversible: captures pg_get_indexdef first.
Before dropping, the exact index definition is captured so the harness records
an undo that recreates it. Pass dry_run=True to preview.
Args:
name: Index name (optionally schema-qualified).
concurrently: Drop with CONCURRENTLY (no table lock).
dry_run: If True, preview without dropping.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| target | No | ||
| dry_run | No | ||
| concurrently | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that this is a write operation with high risk, and importantly states it captures the index definition before dropping for reversibility. Also highlights dry_run for preview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a clear header, body explaining behavior, and a bullet list for parameters. Every sentence adds value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the key aspects: purpose, risk, reversibility, and parameters. It could mention the return value or side effects more explicitly, but is sufficient for an experienced agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It explains each parameter: name (optionally schema-qualified), concurrently (no table lock), dry_run (preview), and target (config name). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Drop an index' with a [WRITE][risk=high] tag. It distinguishes this tool from siblings like create_index and reindex by specifying the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the reversible nature and dry_run option, but does not explicitly contrast with alternatives. It clearly indicates when to use (to drop an index) but lacks when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Return the JSON execution plan for sql (EXPLAIN).
analyze=False (default) plans without executing; analyze=True runs the
statement to collect real timing — only use it for read-only SQL.
Args:
sql: A single SQL statement to EXPLAIN.
analyze: If True, execute the statement to gather real row counts/timing.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| target | No | ||
| analyze | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the read behavior and the difference between planning and executing. It warns that analyze=True executes the statement and should be used only for read-only SQL, which is a key behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured: a single-line summary, a short paragraph on the key parameter, and a bullet list of args. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functionality and parameter semantics. However, it does not elaborate on the JSON return format or error handling, which could be helpful but is not critical given the standard EXPLAIN output is well-known.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but the description explains all three parameters: sql (statement to explain), analyze (whether to execute for real timing), and target (optional config target). This adds full meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the JSON execution plan for SQL, explicitly marking it as [READ] and distinguishing the two modes (analyze=False vs True). This directly identifies the resource and action, and the sibling tools are distinct for other database operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use analyze=True (only for read-only SQL) and describes the default behavior. Does not explicitly exclude use cases or compare to sibling tools, but the context of sibling names implies alternative tools for different concerns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Coarse index-bloat estimate (all inputs returned for transparency).
Args:
limit: Number of indexes to inspect, largest first (default 50).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry all behavioral transparency. It labels the operation as '[READ]' and 'coarse estimate', but fails to disclose potential performance impact, required permissions, or what exactly 'coarse' means in terms of accuracy or methodology.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two sentences plus a bullet list for parameters. The purpose is front-loaded with '[READ]' and no extraneous information. Every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple tool, the description omits crucial details about what the tool returns (e.g., a list of indexes with bloat percentages). It only mentions 'all inputs returned for transparency', which is insufficient. There is also no indication of whether this tool requires special permissions or has performance implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for parameters (0% coverage), but the description's 'Args' section adds meaning: 'limit' is explained as number of indexes inspected (largest first, default 50) and 'target' as target name from config. This sufficiently clarifies parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool estimates index bloat, with the '[READ]' tag and explicit mention of 'index-bloat estimate'. The name matches the purpose, and it distinguishes from sibling tools like 'table_bloat' and 'bloat_and_vacuum_analysis' by focusing on indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'bloat_and_vacuum_analysis' or 'table_bloat'. There is no discussion of prerequisites, context, or cases where this tool is preferred or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Invalid indexes (failed CONCURRENTLY builds) and duplicate indexes.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description includes '[READ]' to indicate read-only behavior, and specifies the output includes invalid and duplicate indexes. However, without annotations, it lacks details on permissions, performance impact, or response format, providing only basic transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single line for the purpose and a brief parameter note. Everything is front-loaded and essential, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal given the tool's purpose. It does not explain the output format, how to interpret duplicates or failed builds, or provide any caveats. With no output schema and many sibling tools, more context is needed for proper selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description adds meaningful context for the target parameter: 'Target name from config; omit for the default.' This clarifies its purpose and optionality, compensating for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves 'Invalid indexes (failed CONCURRENTLY builds) and duplicate indexes,' specifying the exact resource and type of information. The '[READ]' prefix reinforces it as a read operation, distinguishing it from mutation or advisory siblings like create_index and missing_index_hints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as unused_indexes or index_bloat. It does not explain use cases, prerequisites, or when to avoid this tool, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Current sessions (pg_stat_activity) with per-state counts.
Flags idle-in-transaction backends (open transactions holding resources).
Args:
state: Optional exact state filter (active, idle, 'idle in transaction').
include_idle: Include plain idle backends (default True).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | ||
| target | No | ||
| include_idle | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates the operation is read-only via the '[READ]' prefix and describes behavior like counting sessions and flagging idle-in-transaction. This is transparent, though it could mention permission requirements or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a one-line summary followed by bullet-pointed arguments. Every sentence adds value, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, behavior (per-state counts, idle-in-transaction flagging), and all arguments. It does not explicitly describe the return format, but for a list tool this is acceptable. Overall, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema. For 'state' it specifies 'optional exact state filter', for 'include_idle' it explains 'include plain idle backends (default True)', and for 'target' it clarifies it's a target from config. Since schema coverage is 0%, the description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a read operation that lists current sessions (pg_stat_activity) with per-state counts and flags idle-in-transaction backends. This distinguishes it from sibling tools like 'list_extensions' or 'long_running_queries'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives. Some context is implied (e.g., for viewing sessions), but no exclusions or comparisons are provided, leaving the agent to infer usage from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Databases with owner, encoding and on-disk size (largest first).
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description starts with [READ], clearly signaling a non-destructive operation, and mentions the output fields (owner, encoding, size) and sorting. No annotations exist, but the description adequately conveys the behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the operation type and output details without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description fully covers what is returned (owner, encoding, size, largest first) and explains the single optional parameter, making it complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'target' parameter by explaining it is a name from config and that omitting it uses the default, which goes beyond the schema's minimal definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists databases with specific attributes (owner, encoding, on-disk size) and sort order (largest first), distinguishing it from sibling list tools like list_activity or list_extensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving database information but does not explicitly state when to use it versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Installed extensions and whether a newer version is available.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the tool reads data and includes version-checking, but does not disclose any potential side effects, authorization needs, or rate limits. For a read-only tool, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two clear lines: one for purpose and one for the parameter. It uses a front-loaded '[READ]' label and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one optional param, no output schema), the description covers the core functionality and parameter meaning adequately. It could optionally mention the output format or the significance of 'newer version,' but remains complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'target' is a target name from config and can be omitted for default, adding valuable context beyond the schema's anyOf/null definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists installed extensions and checks for newer versions, with a '[READ]' prefix indicating read-only nature. It clearly distinguishes from sibling tools like 'list_databases' or 'list_roles'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the tool lists extensions and the optional target argument, but lacks explicit when-to-use or when-not-to-use guidance, and does not mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Held/awaited locks joined to their owning backend and object.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It identifies the operation as read-only via '[READ]' and describes the join, but does not disclose performance implications, rate limits, or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with a clear structure: a one-line summary followed by an 'Args' section. It is efficient, though the parameter line could be more compactly integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one parameter, the description covers the core purpose and parameter. However, it lacks details about output structure or fields, which would help an agent anticipate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It does so for 'target', saying it's 'Target name from config; omit for the default', which adds meaning beyond the generic schema type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool reads 'Held/awaited locks' and joins them to owning backends and objects. This is specific and distinguishes it from sibling tools like blocking_lock_chain_rca which focus on lock chains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as blocking_lock_chain_rca or other lock-related tools. The only usage hint is an optional parameter, lacking context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Roles and their attributes (superuser/login/replication/…).
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only indicates a read operation via '[READ]' but does not mention authentication, permissions, safety, or potential side effects. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose line followed by a parameter note. No extraneous words, though formatting could be slightly improved for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and parameter, but lacks details on output structure or help in distinguishing from sibling tools. For a simple list tool, it is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful context for the 'target' parameter, explaining it is a config name and that omitting uses the default. This adds significant value beyond the schema, which lacks any parameter description (0% coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'READ' and the resource 'Roles and their attributes', including specific attribute examples. However, it does not explicitly differentiate from sibling tools like list_activity or list_databases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or context for its invocation. The '[READ]' prefix implies read-only usage but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Active queries running at least min_seconds, oldest first.
Args:
min_seconds: Minimum age in seconds (default 60).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| min_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The '[READ]' prefix indicates read-only behavior, but no annotations are provided to confirm. The description does not disclose permissions, rate limits, or return format. For a listing tool, behavioral traits beyond read-only are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear structure: a one-line purpose preceded by a '[READ]' tag, followed by an Args section. Every word is useful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no required params, no output schema), so minimal completeness is acceptable. However, it does not describe what fields or data are returned, which could help agents interpret results. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the Description's Args section explains both parameters: min_seconds (minimum age, default 60) and target (target name, optional). This provides essential meaning beyond the schema's type/default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists active queries running at least min_seconds, ordered oldest first. It defines the verb (implied list), resource (active queries), and condition. While it doesn't explicitly distinguish from sibling tools like 'top_queries', the purpose is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'top_queries' or 'blocking_lock_chain_rca'. The description lacks context for when it is appropriate or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Tables with heavy sequential scans and few index scans (index hints).
Args:
min_seq_scan: Minimum cumulative sequential scans to flag (default 1000).
min_live_tup: Minimum live tuples for a table to qualify (default 10000).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| min_live_tup | No | ||
| min_seq_scan | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the tool as '[READ]' indicating no destructive action, but no annotations exist. It lacks details on potential performance impact or queries against system catalogs. With no annotations, the description provides minimal behavioral context beyond safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single-line purpose and a clear list of arguments. Every sentence adds value, and the structure is front-loaded with the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read operation, 3 parameters) and absence of output schema, the description covers the core functionality and parameter semantics. However, it could mention the output format or potential caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains all three parameters ('min_seq_scan', 'min_live_tup', 'target') with meaningful context, such as minimum sequential scans (default 1000) and live tuples (default 10000), fully compensating for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Tables with heavy sequential scans and few index scans (index hints)', specifying the verb 'read' and the resource 'tables'. It distinguishes from sibling tools like 'unused_indexes' which focus on existing indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for finding missing indexes but does not explicitly state when to use this tool over alternatives like 'unused_indexes' or 'index_bloat'. No exclusions or contextual guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] One-shot cluster health snapshot.
Version + uptime, connections by state, idle-in-transaction count, the
longest-running query, the worst dead-tuple table, and standby replay lag —
each section captured defensively so one failing probe does not sink the rest.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It explicitly marks the tool as '[READ]' and notes defensive capture behavior ('each section captured defensively so one failing probe does not sink the rest'), adding useful context beyond a simple read hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Headline clearly states purpose, bullet points list captured metrics efficiently, and parameter description is direct. No extraneous words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema but provides a comprehensive list of captured metrics, giving the agent a solid understanding of what to expect. Could benefit from a note on response format or error handling, but adequate for a health snapshot tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'target' has schema coverage 0%, but the description adds meaningful context: 'Target name from config; omit for the default.' This clarifies its purpose and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a '[READ] One-shot cluster health snapshot' and lists specific metrics (version, uptime, connections by state, etc.). This differentiates it from sibling tools like list_activity or long_running_queries which focus on specific aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for quick health check via the bullet points, but does not explicitly describe when to use vs. sibling tools or when not to use it. Provides basic guidance on the 'target' parameter but lacks broader context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] REINDEX an index/table/schema (rebuild in place, no undo).
Rebuilds physical index storage; there is no inverse. Pass dry_run=True to
preview.
Args:
target_name: The index/table/schema name to reindex.
kind: INDEX, TABLE, or SCHEMA (default INDEX).
concurrently: Rebuild with CONCURRENTLY.
dry_run: If True, preview without rebuilding.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | INDEX | |
| target | No | ||
| dry_run | No | ||
| target_name | Yes | ||
| concurrently | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It specifies '[WRITE][risk=medium]' and 'no undo', but lacks details on performance impact, locking behavior, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first line and a parameter list. It is reasonably concise, though the docstring format adds some verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core behavior, parameters, and warns about irreversibility. It does not cover return values or error conditions, but given no output schema, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes a detailed docstring explaining each parameter's purpose (e.g., 'dry_run: If True, preview without rebuilding'), fully compensating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'REINDEX' and the resource 'index/table/schema', and it distinguishes from siblings like 'create_index' and 'drop_index' by focusing on in-place rebuild.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'no undo' and suggests using dry_run for preview, providing basic guidance. However, it does not explicitly contrast with alternatives like 'run_vacuum' or other index maintenance tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Replication slots, flagging inactive slots that retain WAL.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral burden. It mentions 'flagging inactive slots', but does not clarify what the flagging entails (e.g., warnings in output, side effects) or any authorization requirements. This is minimal disclosure for a diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: one line for purpose and one line for the parameter. It is front-loaded with the key action and avoids any filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description should explain the return format or what the tool outputs (e.g., a list of slots with status). It only mentions 'flagging inactive slots' without specifying the output structure. This leaves the agent guessing about the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'target' has 0% schema description coverage, but the description adds: 'Target name from config; omit for the default.' This explains that it's an optional config reference with a default behavior, which is a meaningful addition beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a read operation on replication slots, with the specific function of flagging inactive ones that retain WAL. This verb+resource combination is precise and distinguishes it from siblings like replication_status and wal_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as replication_status or wal_status. It does not mention prerequisites, exclusions, or context for deciding between this and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Connected standbys and their replay lag (pg_stat_replication).
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates it's a read operation but lacks details on permissions, empty results, or error conditions. With no annotations, it provides minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Returns standbys and replay lag but does not describe response structure; adequate for a simple list but missing details on no-standby scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'target' is described as 'Target name from config; omit for the default,' adding context beyond the schema's type definition, compensating for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads connected standbys and their replay lag from pg_stat_replication, which distinguishes it from siblings like replication_slots and wal_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The [READ] prefix implies safe usage, but no explicit guidance on when to use versus alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Reset pg_stat_statements accumulators (irreversible).
The counters cannot be restored, so no undo is recorded. Pass dry_run=True
to preview.
Args:
dry_run: If True, preview without resetting.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses irreversibility and a dry-run option, but does not mention authorization requirements, performance impact, or other side effects beyond the stated risk level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with a risk tag, then a brief sentence, followed by parameter explanations. No redundant sentences; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 2 parameters and no output schema, the description covers the core behavior and key parameter semantics, but it lacks information about the return value or side effects beyond irreversibility, and the target parameter remains ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains dry_run as a preview mode and target as an optional config name, but 'target' is vague ('from config') and could leave agents confused about valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resets pg_stat_statements accumulators, using specific verbs 'reset' and 'irreversible'. It distinguishes from sibling tools, which are mostly read or analysis tools, but it could be more explicit about what exactly is reset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies caution by highlighting irreversibility and suggesting dry_run=True for preview, but it does not explicitly state when to use this tool versus alternatives or provide conditions that warrant resetting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] ANALYZE a table to refresh planner statistics.
No undo; captures prior stats for audit. Pass dry_run=True to preview.
Args:
table: Table name (optionally schema-qualified).
dry_run: If True, preview without running.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: it is a write operation with medium risk, has no undo, captures prior stats for audit, and offers a dry_run option to preview. Despite no annotations being provided, these details give the agent sufficient context about the tool's safety and effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a tag format ([WRITE][risk=medium]) and brief bullet-style argument list. Every sentence adds value: the action, risk, undo/audit note, dry_run tip, and parameter descriptions. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers the essential behavioral and usage aspects: what the tool does, preconditions (no undo), risk level, and dry run. It does not detail return values or performance impact, but these are not expected for a maintenance tool with no output schema. Overall sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides basic semantics for all three parameters: 'table' (optionally schema-qualified), 'dry_run' (preview behavior), and 'target' (from config, defaults omitted). However, the explanations are minimal, especially for 'target' which is vague. With 0% schema description coverage, the description compensates partially but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'ANALYZE a table to refresh planner statistics.' This is a specific verb and resource. However, it does not differentiate this tool from sibling tools like 'run_vacuum' or 'bloat_and_vacuum_analysis', which also perform maintenance. Lack of explicit distinction reduces the score from 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description implies usage for refreshing stats but does not mention when not to use it or which sibling tools might be more appropriate for related tasks (e.g., vacuuming, index analysis).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] VACUUM a table (optionally FULL/ANALYZE). Records prior stats.
No undo (a vacuum has no inverse); the prior dead-tuple/last-vacuum stats are
captured for the audit trail. VACUUM FULL takes an exclusive lock. Pass
dry_run=True to preview.
Args:
table: Table name (optionally schema-qualified, e.g. public.orders).
full: Run VACUUM FULL (rewrites the table, exclusive lock).
analyze: Also refresh planner statistics (VACUUM ANALYZE).
dry_run: If True, preview without running.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| table | Yes | ||
| target | No | ||
| analyze | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description fully carries burden. Discloses irreversibility, exclusive lock, prior stats capture, and audit trail. Well beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with risk indicator and clear summary. Parameter descriptions are structured as a list, but could be slightly more concise (e.g., inline instead of bullet style).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key behavioral and parameter details. Lacks explicit mention of return value or side effects on other transactions, but overall sufficient given sibling context and tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description provides detailed explanations for each parameter (table, full, analyze, dry_run, target), adding essential context beyond schema names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool performs VACUUM on a table with optional FULL and ANALYZE. Uses specific verb and resource, and the [WRITE] tag distinguishes it from read-only siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides important constraints (no undo, exclusive lock for FULL) and dry_run preview. Implicitly differentiates from analysis tools but does not explicitly list when to use vs. siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Server version, uptime, recovery state, and data directory.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Declares read-only nature via '[READ]', implying no side effects. Lists output fields but does not mention permissions, rate limits, or any potential impact. Adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a single line for the purpose and a one-line argument description. Front-loaded with '[READ]'. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description is adequate. It names the key outputs and one parameter. However, it lacks details on return format or any prerequisites. Could be more complete but sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no descriptions (0% coverage), so description adds value by explaining 'target' as a config name and default behavior. This provides context beyond the schema's minimal definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it is a [READ] operation and lists specific information: server version, uptime, recovery state, and data directory. This distinguishes it from sibling tools that are administrative or analytical. However, it does not elaborate on the format or exact fields, so not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance for the 'target' parameter but no explicit when-to-use or when-not-to-use compared to sibling tools. Usage is implied by the read nature, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Configuration parameters from pg_settings.
Args:
pattern: Optional case-insensitive substring to filter setting names
(e.g. 'work_mem', 'autovacuum').
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only labels the tool as [READ] without elaborating on side effects, authorization needs, or other behavioral traits. The description lacks depth beyond indicating a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one line plus a short bullet list. It is concise, front-loaded with the main purpose, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 2 parameters and no output schema, the description covers purpose and parameters well. It does not explain return format or error conditions, but for an informational tool this is acceptable. Minor gap given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It does so by explaining 'pattern' (case-insensitive substring filter with examples like 'work_mem') and 'target' (optional target name). This provides practical context beyond the schema's titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads configuration parameters from pg_settings, specifying it's a READ operation. This distinguishes it from sibling tools that deal with queries, vacuum, or other actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the arguments and their usage but does not explicitly state when to use this tool versus alternatives (e.g., when to use show_settings vs update_setting or other info tools). Usage is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] RCA for the worst pg_stat_statements entry, with cause + action.
Picks the statement with the greatest total execution time and maps its
numbers (mean time, cache-hit ratio, temp spill, calls) — plus an optional
EXPLAIN plan — to cited causes and concrete actions. Pass 'statements' for
pure/offline analysis, or omit to pull the top statements live.
Args:
statements: Injected pg_stat_statements rows (as from top_queries); if
omitted, the worst statements are pulled live.
explain_sql: Optional SQL to EXPLAIN so plan node types feed the RCA.
limit: How many statements to pull when not injected (default 20).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No | ||
| statements | No | ||
| explain_sql | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Declares read-only via '[READ]', explains it picks the statement with greatest total time, maps metrics to causes/actions, and notes optional offline mode. Does not disclose side effects or permissions, but for a read tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: one sentence for purpose/behavior, clear bullet-style parameter descriptions. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and does not describe return format (e.g., structure of causes and actions). Agent knows the tool returns causes and actions but cannot predict structure. For an RCA tool, this is a notable gap given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, but the description's Args section explains each param: statements (injected rows or live), explain_sql (optional SQL), limit (default 20), target (target name). Adds substantial meaning beyond type/defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with '[READ] RCA for the worst pg_stat_statements entry, with cause + action.' Clearly identifies the tool as a root cause analysis on the worst query, specifying it reads and provides actionable insights. Distinguishes it from siblings like top_queries (lists queries) and explain_query (just explains).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use for analyzing the worst query with causes and actions. Explains optional parameters for offline vs live analysis. However, no explicit when-not-to-use or comparison to sibling tools beyond implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Dead-tuple bloat proxy per table (dead / (live + dead)), worst first.
Args:
limit: Number of tables to inspect (default 50).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It marks the tool as [READ] but provides no additional behavioral context (e.g., no side effects, permissions, or error handling). The formula and ordering are disclosed, but nothing about data freshness or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for purpose, then parameter docs. Front-loaded with the key purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately conveys the tool's function for selection, but lacks details about return format (e.g., columns, data types) and edge cases. Given no output schema, a bit more context on what is returned would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must explain parameters. It does so clearly: 'limit' is number of tables to inspect with default 50, 'target' is target name from config with null default. This adds value beyond the schema's type/default info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads dead-tuple bloat proxy per table, calculated as dead/(live+dead), sorted worst first. This distinguishes it from sibling tools like index_bloat (index-level) and bloat_and_vacuum_analysis (comprehensive analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for monitoring table bloat but does not explicitly state when to use this tool versus alternatives like bloat_and_vacuum_analysis or index_bloat. No when-not-to conditions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Largest tables by total relation size (table + indexes + TOAST).
Args:
limit: Number of tables to return, largest first (default 20).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly marks the operation as read-only with '[READ]', and no destructive hints are needed. It does not mention side effects, but for a read-only query that seems acceptable. It adds the detail about including indexes and TOAST.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: two sentences and parameter info. The '[READ]' prefix front-loads the most critical behavioral information. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description covers the essentials: what it returns, default behavior, and the target parameter. It does not describe the return format, but for a list of largest tables this is acceptable. Could be improved by mentioning that results are sorted descending.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, so description compensates fully. It explains 'limit' (number of tables, default 20) and 'target' (target name, optional). This adds meaning beyond the schema's raw structure, though it could clarify what 'target' refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('list' implied) and clear resource ('largest tables by total relation size'). It specifies the computation (table + indexes + TOAST), making the tool's purpose distinct from sibling tools like 'table_bloat' or 'missing_index_hints'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives. The read-only nature is implied by '[READ]', but no exclusions or comparisons to siblings are given. Adequate for a simple information tool, but lacks context for an agent to decide between this and similar tools like 'overview' or 'table_bloat'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=high] Terminate a backend (pg_terminate_backend). No safe inverse.
Captures the backend's pid + query for the audit trail; a terminate cannot be
undone, so no undo is offered. Pass dry_run=True to preview.
Refuses this tool's own backend pid — including under dry_run, which must
report a refusal rather than preview a call that will be refused.
Args:
pid: Backend process id (from list_activity).
dry_run: If True, preview without terminating.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | ||
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In absence of annotations, description fully discloses write operation, high risk, no undo, audit trail capture, refusal of own PID, and dry_run behavior. No contradiction with annotations (none provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with tags [WRITE][risk=high], clear summary, then args. Slightly verbose but efficient for the complexity. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input semantics and constraints well, but does not describe return value/output. Given no output schema and moderate complexity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description adds valuable meaning for all three parameters: pid (source from list_activity), dry_run (preview vs. execute), and target (config-driven, optional).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Terminate a backend (pg_terminate_backend)' and distinguishes from sibling tools like cancel_query by noting high risk, no inverse, and audit trail capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use (dry_run for preview) and behavior under refusal, but does not explicitly compare to alternative tool cancel_query or state when not to use terminate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Top statements from pg_stat_statements by a whitelisted metric.
Args:
order_by: One of total_time, mean_time, calls, rows, io.
limit: Number of statements to return (1..200, default 20).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No | ||
| order_by | No | total_time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The [READ] prefix indicates a read-only operation, which is the primary behavioral trait. However, no annotations are provided, and the description does not disclose potential performance impact or other side effects. Basic transparency is achieved, but more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two opening lines and a parameter list. The list format is effective but could be integrated into prose for better readability. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Parameter details are complete, but the description omits output format or return values. Given no output schema, this is a gap. The [READ] prefix partly covers behavioral context, but overall completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description thoroughly explains each parameter: order_by lists valid metric values, limit specifies range and default, target describes usage with config. This adds significant meaning beyond the input schema, which has 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves top statements from pg_stat_statements by a metric, with a [READ] prefix. While the verb 'Top' is slightly vague, it effectively distinguishes from sibling tools like long_running_queries and slow_query_rca.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like long_running_queries or slow_query_rca. The description does not specify prerequisites or exclusions, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so its risk tier and audit
row are recorded there. Pass dry_run=True to preview the inverse call
without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| dry_run | No | ||
| undo_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: it's a write operation (risk medium), invokes an inverse tool that logs its own risk/audit, provides a dry-run mode, and enforces single-use tokens. This is sufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (8 lines) and well-structured: a header with risk level, a sentence on behavior, and a bulleted Args list. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description fully explains the tool's purpose, parameters, and constraints (single-use, dry-run). It provides all necessary information for an AI agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description includes an 'Args' section explaining each parameter's purpose and source (e.g., undo_id from undo_list, target passed through). This adds critical context beyond the schema's titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Apply' and the resource 'recorded undo', with a specific mechanism 'dispatch its inverse tool'. It distinguishes from sibling tools like 'undo_list' by focusing on execution rather than listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (to apply an undo) and provides usage hints like 'dry_run=True' and 'token can only be applied once'. It does not explicitly state when not to use or compare to alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that ``undo_apply``
would run, and a human note. Use the ``undoId`` with ``undo_apply``.
Each entry carries ``effectVerified``. False means the original write
lost its response, so the change it reverses is PROBABLE, not confirmed —
check the live state before applying, and do not report the result as a
restore of a state that may never have been reached.
Args:
limit: Max rows to return (default 50).
target: Unused (undo state is host-local); accepted for CLI uniformity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It declares the operation as read-only via [READ] prefix and explains the effectVerified field's implications. It does not mention side effects or rate limits but covers key behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary followed by structured details on fields and parameters. Each sentence adds value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return format (fields: original tool, inverse tool, human note, effectVerified) and usage context. No critical information is missing for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description explains limit's default and meaning (max rows) and clarifies target is unused. This adds value beyond the schema, though limit's exact interpretation could be slightly more precise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recorded undo tokens, sorted most recent first. The [READ] prefix and explanation of fields distinguish it from sibling tools like undo_apply.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the output (use undoId with undo_apply) and provides guidance on effectVerified (check live state). It notes the target param is unused, though it could be more explicit about when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Non-unique, non-primary indexes with zero scans (drop candidates).
Args:
min_size_bytes: Only report indexes at least this large (default 0).
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| min_size_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The [READ] annotation indicates no side effects, and 'zero scans' clarifies the selection criteria. However, with no annotations provided, the description lacks details on potential costs, permissions needed, or whether results are live or historical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose and [READ] tag. The Args section is clearly structured. Every sentence adds value, though the overall brevity is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description explains inputs and purpose but does not describe return format, pagination, or result details. It is adequate for a simple list tool but leaves gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds useful context beyond the schema for both parameters: 'target' is explained as a config name, and 'min_size_bytes' filters by size with a default. This compensates for the 0% schema coverage reported, though the coverage seems accurate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports non-unique, non-primary indexes with zero scans, suggesting drop candidates. The [READ] tag and resource specification distinguish it from sibling tools like missing_index_hints or index_bloat, though the verb is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'drop candidates' implies a use case, but there is no explicit guidance on when to use this tool versus alternatives among the many index-related siblings. The context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] ALTER SYSTEM SET (or RESET) a parameter. Reversible.
Writes postgresql.auto.conf; most parameters need SELECT pg_reload_conf() (or
a restart for postmaster-context settings) to take effect — reported but NOT
performed automatically. The prior state is captured so the harness records
an undo. Pass dry_run=True to preview.
reset=True issues ALTER SYSTEM RESET, dropping the parameter's auto.conf
entry so postgresql.conf or the built-in default applies again. That is the
recorded inverse when the parameter had no auto.conf entry to begin with:
writing the prior value back would leave a pin that shadows postgresql.conf.
Refuses the connection-affecting postmaster settings (listen_addresses,
port, max_connections, superuser_reserved_connections, ssl, hba_file):
nothing breaks now, but the operator's next restart applies them and strands
the undo. Enforced under dry_run too.
Args:
name: The configuration parameter name (e.g. work_mem).
value: The new value (as a string). Omit when reset=True.
reset: If True, ALTER SYSTEM RESET the parameter instead of setting it.
dry_run: If True, preview without changing.
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| reset | No | ||
| value | No | ||
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility. It thoroughly discloses the write behavior, writes to postgresql.auto.conf, need for pg_reload_conf, undo capture, refusal of certain settings, and dry_run support. This is exemplary transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a front-loaded summary, risk marker, clear explanation of side effects, and a structured Args block. Despite its length, every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers effects, restrictions, undo, and preview mode thoroughly. The only minor gap is not explicitly stating the return value/response format, though 'reported but NOT performed' implies this. Given the complexity, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates fully with an 'Args' section that explains each parameter: name, value (omit when reset), reset behavior, dry_run, and target. This adds meaning well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'ALTER SYSTEM SET (or RESET) a parameter.' It names the specific SQL command and resource (PostgreSQL parameters), distinguishing it from read-only sibling tools like show_settings or other maintenance tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: use dry_run to preview, reset to drop an entry, and warns against specific postmaster settings. However, it does not explicitly position this against alternatives (e.g., 'for viewing settings, use show_settings'), leaving the comparison to the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] WAL position, level, size settings and archiver health.
Args:
target: Target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. The [READ] tag indicates a read-only operation, which is good. However, it does not mention any potential side effects, required permissions, or error conditions (e.g., invalid target). The description is adequate for a simple read but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences covering overall purpose and parameter. The [READ] prefix and Args block are well-structured and front-loaded. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description is mostly complete. It clearly states the read nature and what aspects of WAL are reported. However, it does not describe the return structure or behavior when target is invalid, which would be helpful for an agent to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description adds essential meaning: 'Target name from config; omit for the default.' This tells the agent that 'target' refers to a config key and that omitting uses a default value, which is beyond the schema's type-only definition. It could be improved by specifying the default value or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (WAL) and the specific attributes (position, level, size settings, archiver health) returned. The [READ] prefix signals a read-only operation, and the tool name 'wal_status' is self-explanatory. Among sibling tools like 'replication_status', this one is uniquely focused on WAL status, providing clear distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not explain how 'wal_status' differs from 'replication_status' or other monitoring tools. The description states what it does but not the specific context or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.8.0update_setting5 fields changedInput schema / properties / resetAdded value: +{
+ "default": false,
+ "title": "Reset",
+ "type": "boolean"
+}Input schema / properties / value / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / value / defaultAdded value: +nullInput schema / properties / value / typeRemoved value: -"string"Input schema / requiredPrevious value: -[
- "name",
- "value"
-]New value: +[
+ "name"
+]v0.1.0autovacuum_statusbloat_and_vacuum_analysisblocking_lock_chain_rcacancel_querycreate_indexdrop_indexexplain_queryindex_bloatinvalid_indexeslist_activitylist_databaseslist_extensionslist_lockslist_roleslong_running_queriesmissing_index_hintsoverviewreindexreplication_slotsreplication_statusreset_query_statsrun_analyzerun_vacuumserver_versionshow_settingsslow_query_rcatable_bloattable_sizesterminate_backendtop_queriesundo_applyundo_listunused_indexesupdate_settingwal_statusEach tool targets a distinct aspect of PostgreSQL monitoring and management. For example, list_activity and long_running_queries serve different purposes, and table_sizes vs table_bloat are clearly differentiated. There is minimal overlap.
All tool names follow a consistent verb_noun snake_case pattern (e.g., list_activity, create_index, drop_index). Even complex names like blocking_lock_chain_rca adhere to the convention.
With 35 tools, the server is comprehensive but may be considered heavy. While each tool serves a clear purpose, the count is above the typical well-scoped range (3-15). It borders on too many, but the breadth of PostgreSQL operations justifies it partially.
The tool set covers a wide range of PostgreSQL operations: monitoring activity, queries, locks, indexes, vacuum, settings, replication, databases, roles, and includes an undo mechanism. It appears very complete for an AIOps-oriented server.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AIops-tools/Postgres-AIops'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
