woodpecker_diagnose_root_cause

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. While it explains what the tool returns and that it is deterministic, it fails to mention that the tool takes no input parameters (schema has zero properties). This omission may confuse an AI agent about how the tool is invoked or what context it requires. The description claims it 'localizes' root cause but does not state the implicit input or state it operates on.

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 a single, informative paragraph that front-loads the main purpose. It is concise yet covers key outcomes. Minor improvement could be breaking into bullet points, but overall it is well-structured and not verbose.

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 absence of an output schema, the description does explain return values partially. However, it lacks critical context: how the tool determines which services to analyze without parameters, and how it fits with sibling tools. The completeness suffers because the input mechanism is undefined, making it unclear for an AI agent to know when to call this 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?

There are zero parameters, so the schema provides 100% coverage by default. According to the rules, a baseline of 4 is appropriate when there are no parameters. The description does not need to add parameter semantics, but it lacks an explanation of how the tool operates without explicit input.

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 purpose: to deterministically localize the root cause by identifying the deepest failing service. It specifies what it returns (root cause, causal chain, blast radius, etc.) and distinguishes its deterministic nature from typical inference. This makes the purpose unmistakable.

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 context of use is clear: it is for diagnosing root cause when services are failing. However, it does not explicitly state when to use this tool versus its siblings (e.g., woodpecker_get_service_health for health checks) or when it would be inappropriate. The description implies its use for root cause but lacks explicit exclusionary guidance.

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