set_units

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

With no annotations, the description carries the full behavioral burden. It does well on partial-update semantics ('Only the settings given are changed') and on the system-dependent validity of unit names, but it never says which scene is targeted (active scene?), whether existing objects/scales are affected, or whether the change is persisted to the file.

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?

Front-loaded purpose sentence, then one line per parameter with no filler. The 'Returns' line merely restates the output schema and is the only text that doesn't earn its place.

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 eight-parameter tool with zero schema descriptions, the argument list makes it callable without guesswork, and the existence of an output schema makes the return note optional. The only real omission is which scene is modified and whether the change is durable.

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 0%, yet the description documents all eight parameters: valid unit values per system, the scale_length conversion with a worked example (0.001 so 1 unit reads 1 mm), the NONE-system case, and the use_separate compound-display behavior. This fully compensates for the empty schema.

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 verb and resource ('Set the scene's units') and adds a concrete motivating example (3D print in millimetres). It is clearly distinguishable from siblings like set_scene_property or set_render_resolution, though it never names an alternative explicitly.

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 real-world-size framing and the 3D-print example give a clear sense of when this tool is the right call, and 'Only the settings given are changed' sets partial-update expectations. There are no explicit when-not conditions or named alternatives, but the context is unambiguous.

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