sky_load

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

The description adds real behavioral context beyond the annotations: a .tbsky load replaces the entire sky, which tells the agent existing sky state is discarded — non-trivial information given destructiveHint=false. It also discloses the format-dependent outcome (panorama replacement vs. full sky swap). It does not cover error handling for unsupported formats or what happens to the prior sky (recoverable or not).

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?

A single sentence, front-loaded with the action, that uses a parallel clause to convey both behaviors with zero filler. Nothing could be removed without losing information.

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?

Return values are covered by the output schema and the safety profile by annotations, so the description's remaining burden is modest. Still, an unexplained `ref` parameter and no note on failure modes for unsupported or missing files leave an agent guessing on a mutating load call.

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% across two parameters, so the description carries the full burden. It only implicitly covers `path` via the file-extension discussion; the `ref` parameter (integer|string|null, default null) is never mentioned and remains completely opaque. With half the parameters undocumented in both schema and description, this falls below the minimum-viable bar.

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 (load) and resource (sky), and goes further by explaining the two file classes and their distinct effects: .tbsky replaces the whole sky, while an image becomes the panorama. That is a clear, non-tautological purpose. It does not, however, distinguish itself from near siblings such as sky_set, sky_get, or sky_set_background_image, which an agent must disambiguate on its own.

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?

Usage is implied rather than stated: the file-extension branch hints at when each mode applies, which is helpful. But there is no explicit guidance on when to choose this over sky_set or sky_set_background_image, and no mention of prerequisites such as an open scene or a valid file path.

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