rhino_light_add

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

The annotations already indicate this is not read-only, and the description confirms a mutating action by stating it adds a light to the document. It adds some useful scope by listing the five light kinds, but it does not disclose behaviors like default placement when location is omitted, whether a target is required for spot lights, or how the resulting light is registered in the document.

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 a single, front-loaded sentence with no filler. Every word contributes to identifying the operation and the variation of light types supported.

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 description is minimally sufficient for a simple default invocation: an agent can understand that this adds a light and can choose a kind. However, it is incomplete for correct advanced usage because it does not explain placement requirements, the role of target/location for certain light types, or how this tool relates to the specialized light-adding sibling tools.

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 schema description coverage at 0%, the description needed to compensate for the wide range of parameters, but it only echoes the possible values of the 'kind' parameter. It does not explain location, target, intensity, color, width, length, layer, or spot_angle_deg, so meaningful parameter understanding still depends almost entirely on the schema and defaults.

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 uses a specific verb ('Add') and resource ('light to the document'), and it enumerates the supported light kinds: point, spot, directional, rectangular, and linear. It is clear about what the tool does, though it does not explicitly differentiate itself from sibling tools like rhino_add_point_light, rhino_add_spotlight, and rhino_add_directional_light.

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?

There is no guidance about when to use this unified light-add tool versus the more specific rhino_add_*_light sibling tools. The description provides no context about prerequisites, preferred workflows, or exclusions, leaving the agent to infer usage from the tool name alone.

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