voltage_diagnose

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description doesn't need to restate safety. It adds valuable behavioral detail: it computes implicit journal information, returns specific edits ordered blocker-first, and distinguishes between a burst that never ran vs. ran but did nothing. This goes well beyond the annotation, providing non-obvious nuances.

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 a crisp summary, then explains the key distinction and ends with an actionable workflow. Every sentence earns its place; there is no fluff or redundancy. Structure is clear and scannable.

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 that an output schema exists (the description doesn't need to detail return structure) and annotations cover safety, the description covers the essential context: the diagnostic purpose, the key distinction between two root causes, and the iterative workflow. The only minor gap is the run_id parameter semantics, which slightly detracts from completeness for an otherwise simple 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?

Schema description coverage is 0%, so the description carries the full burden for the single parameter run_id. It never mentions run_id, its format, how to obtain it, or whether it's required (though the schema marks it optional). The name 'run_id' is self-explanatory by convention, but the description provides no explicit guidance, and with only one parameter to cover, this is a noticeable gap.

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 opens with a specific verb and resource: 'Explain why a run behaved as it did, and what to change.' It then contrasts itself with reading the journal, making its purpose distinct from voltage_journal. No ambiguity about what the tool does.

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 explicitly instructs to call this instead of reading the journal by hand, giving clear when-to-use context. It also provides a workflow (apply highest-severity finding, re-run, diagnose again). However, it doesn't name alternative siblings like voltage_doctor or voltage_observe, or describe conditions where those might be more appropriate, so it stops short of complete guidance.

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