Scene environment & atmosphere

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating, potentially destructive tool. The description adds useful context in disclosing the dual read/write behavior and the full scope of what it touches, but it does not explain reversibility or what removal actually destroys beyond what the schema already states ('refused while entities still use them').

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 sprawling sentence dense with parentheticals and ellipses. It is front-loaded with the read/change verb, but the packed example lists make it harder to parse than a structured multi-sentence form would be.

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 an 8-parameter destructive tool with nested objects and no output schema, the description covers the scope of every resource it manages and notes the read-vs-write behavior. The remaining gap is the lack of any routing versus the overlapping editor_camera and scene_edit siblings, but nothing essential to invoking it is absent.

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 100% schema description coverage the baseline is 3, but the description earns extra credit by giving concrete value-name examples for the atmosphere (time_of_day, color_grade_name, fog_density, sun_altitude) and environment (atmosphere_name, is_indoors, water_level) objects, clarifying what the otherwise opaque name→value maps should contain.

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 clear verb pair (reads or changes) and enumerates the specific resources involved: environment_properties, atmosphere.xml values, level definitions, and the editor camera in editor_data. It partially distinguishes itself from siblings by noting that entities join levels via scene_edit, but it is a bundled tool covering several resources at once, which blurs a single crisp purpose.

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?

'Without changes it lists the current values' implies the read mode, and the scene_edit reference hints at the level workflow. However, there is no explicit when-to-use guidance against the sibling tools editor_camera or scene_edit, which overlap directly with portions of this tool. Usage is implied rather than stated.

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