voltage_learn

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

Annotations already indicate a mutating, potentially destructive action (readOnlyHint=false, destructiveHint=true); the description does not contradict these and adds that notes are stored against a target. It does not describe side effects or permissions, but given annotation coverage it provides acceptable additional context.

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 efficiently structured: it opens with the core purpose, gives clear good/bad examples, and ends with a concise classification of kind values. Every sentence adds value, and the format is well-balanced for the tool's complexity.

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 tool that records notes, the description covers the purpose, content quality, and kind taxonomy, which is sufficient for basic use. Gaps remain around `playbook` and exact behavior (e.g., confirmation, persistence), but the presence of an output schema and annotations mitigates these. Overall it is fairly complete.

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 compensates by explaining the meaning of `kind` (label, timing, policy, burst, observation) and prescribing the format for `note` via good/bad examples. It leaves `target` and `playbook` undefined, but `target` is self-evident and `playbook` remains ambiguous, so coverage is partial but effective.

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 records reusable facts against a target, with concrete good/bad examples that make the purpose unmistakable. It does not explicitly differentiate from sibling tools like voltage_lessons, but the 'carrying to the next run' phrasing is specific enough to convey its unique 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?

The description provides strong guidance on what to record (concrete facts, not narration) and explains the kind grouping, but it never mentions alternative tools or conditions under which to avoid this tool. Usage context is implied rather than explicit, and no exclusions or comparisons are given.

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