blocking_lock_chain_rca

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.