set_hlod_layer_parent

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

Annotations already declare idempotentHint and destructiveHint, yet the description adds substantial value beyond them: it explains what idempotency means concretely (nothing modified/saved, changed_parent=false), discloses that self-parent and circular-chain validation is performed because the engine's guard is editor-only and does not run headless, and notes the asset is saved. This is exactly the kind of headless caveat and side-effect disclosure an agent needs.

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 with the core action, then the clear/omit semantics, idempotency, and validation caveats in a logical order. Dense but every sentence carries an operational fact; the inline Returns line is somewhat listy but still informative.

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 mutating tool with no output schema, the description embeds the return shape (has_parent, changed_parent, saved, etc.) and covers idempotency, validation, and the save side effect. An agent has everything needed to call it correctly and interpret the outcome.

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% and the schema already documents both the hlod_layer_path and the clear-vs-absent semantics of parent_layer_path, so the description largely restates it. It adds the domain rationale for the parent parameter, but that is marginal against a fully documented schema; baseline 3 is appropriate.

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 the exact verb+resource ('Sets (or clears) the parent UHLODLayer of a UHLODLayer') and adds scope ('and saves it'). The domain explanation (parent chain drives nested HLOD generation, a layer's HLOD becomes input to its parent's) lets an agent distinguish this from set_hlod_layer_settings and create_hlod_layer without opening any schema.

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?

Gives precise usage mechanics: parent_layer_path="" clears to null, omitting it leaves the parent untouched, which removes ambiguity about the two call modes. It does not name alternative sibling tools or state when to prefer them, but the call-condition guidance is explicit and unambiguous.

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