Skip to main content
Glama
Sign In
MCPg - Production-grade PostgreSQL MCP Server

MCPg - Production-grade PostgreSQL MCP Server

by devopam
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Analyze lock hotspots

analyze_lock_hotspots
Read-only

Ranks PostgreSQL lock statistics by wait dominance and returns stable reason codes to identify contention hotspots and guide follow-up blocking-chain analysis.

Instructions

Rank PG 19 pg_stat_lock rows by wait dominance and surface stable reason codes. Read-only — never modifies state. Pair with find_blocking_chains for the active culprits on a specific hot lock_type. Returns an object with available (bool), server_version_num, detail, and hotspots — a list of objects with lock_type, waits, wait_time_us, reason (one of contention_dominant / high_wait_time / high_wait_count / low_contention), and suggested_followup (a human-readable next-step string).

Example: analyze_lock_hotspots()

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "analyze_lock_hotspots"
  }
}

Input Schema

NameRequiredDescriptionDefault
databaseNoOptional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected.

Output Schema

NameRequiredDescriptionDefault
detailYes
hotspotsYes
availableYes
server_version_numYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.8.4
    • changedInput schema / properties / database / description
      Previous value: -"Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids."New value: +"Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected."
  2. First observedv0.6.8

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the 'Read-only — never modifies state' sentence is largely redundant. What does add value is the PG 19 version dependency and the enumerated reason codes (contention_dominant, high_wait_time, high_wait_count, low_contention), which tell the agent how results will be bucketed and that classification is heuristic rather than absolute.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the sibling routing are front-loaded in the first two sentences, which is the right ordering. The last portion enumerates return fields that an output schema already declares, which is filler, though the example call is short and harmless.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, restating the return shape is unnecessary, but the description does supply the piece the schema cannot: the PG 19 version gate and what `available` implies for fallback behavior. An agent has enough to call it correctly; only the relationship to the raw-read lock siblings is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single optional database parameter whose schema description already covers it at 100%, including the secondary/primary targeting rule and rejection of unconfigured names. The description text adds no further meaning about that parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Rank PG 19 pg_stat_lock rows by wait dominance') and names the exact output artifact ('stable reason codes'). It also distinguishes itself from the nearby lock-related siblings by pointing at find_blocking_chains for active culprits, so an agent can choose between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing guidance: use this for ranked hotspot analysis, and pair with find_blocking_chains when you need the active culprits behind a specific hot lock_type. What is missing is any exclusion relative to read_pg_stat_lock or list_locks, which return the raw rows this tool ranks, so the agent must infer that boundary.

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

Deploy Server

Other Tools