cocos_set_ambient

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that colors are floats 0..1 (not 0..255), that None values leave parameters unchanged, and provides the default sky_illum value (~20000 lux). However, it doesn't mention whether this is a read or write operation, what permissions are needed, or what happens if the scene doesn't have AmbientInfo. The description adds useful context but doesn't fully cover behavioral traits.

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 with four sentences that each add value: stating the purpose, explaining color format, describing parameter behavior with None, providing default illumination, and stating the prerequisite. There's no wasted text, and key information is front-loaded.

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?

Given the complexity (10 parameters, no annotations, no output schema), the description provides good basic context about parameter formats and prerequisites but lacks information about return values, error conditions, or what constitutes valid scene_path values. For a configuration tool with many parameters, more complete documentation would be helpful.

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 and 10 parameters, the description must compensate significantly. It explains the meaning of color parameters (floats 0..1, normalized like material PBR inputs), clarifies that sky_illum is in lux with a default value, and notes that passing None leaves parameters unchanged. However, it doesn't explain the scene_path parameter or differentiate between sky_color and ground color parameters beyond naming them.

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 specific action ('Configure ambient lighting'), target resource ('scene's cc.AmbientInfo'), and scope (lighting parameters). It distinguishes from sibling tools by focusing on ambient lighting configuration rather than scene creation, node manipulation, or other lighting types like directional or spot lights.

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 clear context for when to use this tool: when configuring ambient lighting on a scene that has been created via 'cocos_create_scene' (which auto-attaches AmbientInfo). It doesn't explicitly state when not to use it or name specific alternatives, but the prerequisite is clearly defined.

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