light_align_to_object

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

The description discloses concrete behavioral effects beyond the annotations: the light is moved above the target and the target point is snapped. This aligns with the destructiveHint=true annotation and clearly indicates that the operation mutates transforms. It does not address behavior for non-target lights beyond the movement, but that is a minor gap.

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 compact and front-loaded with the operation and result. The bilingual duplication adds some length, but the content is focused and contains no filler. The one-sentence format works well for this simple tool.

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 two-parameter mutating tool, the description plus schema is largely sufficient: it names the light, the target object, and the resulting behavior. Annotations cover the read-only and destructive nature. The only minor omission is explicit behavior for non-target lights, but this does not prevent correct invocation.

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 description coverage is 100%: both 'light' and 'objects' already have meaningful descriptions, including the note that the first object in the array is used. The description adds alignment context but does not add new parameter-level details beyond what the schema already states.

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 states a specific verb and resource ('Aim a light at an object') and specifies the mechanical result: the light moves above the target and a target-type light's target snaps to the object's position. This makes it clearly distinct from generic alignment tools like align_objects and camera tools like cam_align_to_view.

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 usage context is implied by the verb and effect: use this when you want to aim a light at an object. However, there is no explicit discussion of when not to use it or which alternative tools might be more appropriate, such as align_objects or constraint_look_at.

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