visual_loop.record_verdict

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

Annotations are all false and provide no behavior hints, so the description carries the burden. It mentions 'Risk: standard' and export requirements, but never states what side effects occur, whether it mutates loop state, or what happens on invocation. The export snapshot note is ambiguous and not clearly tied to this tool's behavior.

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 short, but it wastes space on risk and maturity labels that serve little purpose for an agent selecting or invoking the tool. It lacks a clear, front-loaded statement of function and is under-specified rather than concise.

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?

This is a complex tool with 10 parameters, nested objects, and an output schema, yet the description provides no information about how to form a valid request, what the verdict recording implies, or what the output contains. The description is fundamentally incomplete for an agent to use the tool 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?

With 10 parameters and only 30% schema description coverage, the description must compensate for undocumented parameters, but it says nothing about the meaning of 'scores', 'judge', 'issues', 'nextActions', or '_transactionId'. No parameter semantics are provided beyond the schema's minimal type information.

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 only names the harness command and gives risk/maturity labels, with no verb or resource indicating what the tool actually does. It is effectively a tautology: the title already says visual_loop.record_verdict, and the description adds no action, target, or result.

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 lists prerequisites such as session policy and approved output root, but never explains when to call this tool or how it relates to siblings like visual_loop_record_capture or visual_loop_status. There is no when-to-use or alternative guidance.

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