vw_lighting_device_report

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

Annotations cover readOnly, but the description adds real value beyond them: it names the default column set, the sort behavior including blank-values-last, the return type, and the side effect of writing to output_path. That side effect is the key thing an agent needs. Only missing piece is any error/permission behavior when output_path is unwritable.

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?

Compact and front-loaded: purpose first, then defaults, sort, return, side effect. No filler sentences, though the fields/position omission slightly hurts density of useful info.

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?

The tool has an output schema, so return format needn't be over-explained, but two of five parameters (fields, position) are undocumented and the tool-vs-sibling choice isn't covered. Adequate for a read-only exporter, but not 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?

Schema coverage is 0%, so the description must carry parameter meaning, and it partially does: it documents sort_by (with blank-last semantics), format (CSV/JSON text returned), and output_path (writes file). But fields and position are never explained, leaving two parameters undocumented anywhere.

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?

States a specific deliverable: a paperwork export of Lighting Devices with named contents (channel hookup, instrument schedule). Clearly distinct from vw_list_lighting_devices and vw_set_lighting_device_fields.

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?

Usage is implied (you want a report/hookup export), but it never explicitly contrasts with vw_list_lighting_devices or says when to choose the list tool instead. No exclusions or prerequisites stated.

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