voltage_validate_playbook

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

Annotations only mark readOnlyHint:true. The description adds substantial behavioral detail: it returns a complete list of errors rather than one at a time, reports unreachable states and dead transitions, and explains how to interpret warnings. This fully complements the annotation and does not contradict it.

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 tightly written, starting with the primary purpose, then detailing checks, then error behavior, then usage guidance and a warning interpretation. Every sentence serves a purpose—no filler. It front-loads the action and clearly organizes information in short block format.

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?

For a single-parameter validation tool with an output schema declared (though not shown explicitly), the description covers what it does, how it behaves, when to call it, and how to interpret results. With annotations covering read-only safety and the output schema expected to define return values, nothing essential is missing for an agent to decide and invoke correctly.

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?

The input schema only defines a generic 'playbook' object with no description (0% coverage). The description compensates by making clear that the parameter is the Playbook being validated, and it describes what validation entails (schema, guards, bursts, references). This gives the agent enough context to pass the correct object, even without knowing its internal structure.

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, unambiguous statement: 'Fully check a Playbook without running it.' It enumerates the exact validations performed (schema, guards, bursts, transition targets, probe references) and reports unreachable states/dead transitions, distinguishing this validation tool from siblings like voltage_run and voltage_execute_burst. The verb 'validate' matches the tool name and clears its role.

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?

Explicitly guides usage with 'Always call this before voltage_run,' which states when to use this tool relative to its primary sibling. It also adds a practical hint about interpreting warnings (e.g., 'tests for X but X is not in watch'). It does not list explicit exclusions, but the directive is clear and directly actionable.

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