io.github.AIops-tools/ceph-aiops

pg_dump_stuck

Read-only

Identifies stuck Ceph placement groups (inactive, unclean, stale, undersized, degraded) and returns implicated OSD IDs when recovery stalls.

Instructions

[READ] Stuck PGs (inactive/unclean/stale/undersized/degraded) with implicated OSDs.

Use this when a PG is not recovering — it surfaces the OSD ids to investigate. Returns {"stuck": [...], "returned": N, "limit": L, "truncated": bool}; when truncated is true there are more stuck PGs than were returned.

Args: target: Ceph target name from config; omit for the default. limit: Maximum stuck-PG rows to return. Default 200.

Tool call template

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

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

Input Schema

Name	Required	Description	Default
`limit`	No
`target`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.11.5Sep 19, 2026
- addedInput schema / properties / limit
```
Added value: +{
+  "default": 200,
+  "title": "Limit",
+  "type": "integer"
+}
```
First observedv0.1.0Jul 12, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations only give readOnlyHint=true, and the '[READ]' tag plus the explicit return envelope and truncation semantics add real value beyond that. It explains what 'truncated: true' implies, which is behavioral detail the annotations cannot carry. It does not cover cost, sorting, or refresh characteristics, so not a 5.

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?

Front-loaded with the operation and usage trigger, then the return shape, then Args — the important routing information appears first. The Args block repeats the schema default of 200, a minor redundancy, but nothing else is wasted.

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

Completeness4/5

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

With no output schema, the description compensates by declaring the return object keys and truncation flag. For a two-parameter read tool with readOnlyHint set, an agent has everything needed to call and interpret it; only sibling differentiation and pagination/ordering detail are absent.

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

Parameters4/5

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

Schema description coverage is 0%, so the description carries the burden, and it does document both parameters: target as 'Ceph target name from config; omit for the default' and limit as max stuck-PG rows with default 200. That meaningfully exceeds the bare schema, though 'limit' simply restates the schema default.

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

Purpose4/5

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

States a specific resource (stuck PGs) with a parenthetical enumeration of the states counted as stuck (inactive/unclean/stale/undersized/degraded) and the payload returned (implicated OSDs). It does not name or distinguish itself from the nearby pg_summary sibling, so it stops short of a full 5.

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

Usage Guidelines4/5

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

Gives a concrete trigger: 'Use this when a PG is not recovering — it surfaces the OSD ids to investigate.' That is clear operational context, though it names no alternative (e.g. pg_summary) and states no when-not-to-use condition.

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