sky_get

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description contributes only a field inventory, which duplicates what the existing output schema provides, and omits behavior an agent would want: what happens with no ref (active scene?), whether missing sky returns an error or defaults, and whether procedural sun results are cached.

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?

It is one short front-loaded phrase with no filler, which is fine stylistically. But the terseness crosses into under-specification: the content is a bare field list rather than a statement of action and scope.

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 read-only getter with an output schema and rich annotations, the description can be brief — but it still needs to explain the ref argument and the default-target behavior, since neither schema nor annotations cover those. Those gaps are exactly what an agent needs in order to call it correctly.

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% and the single parameter 'ref' accepts integer, string, or null with no declared default meaning. The description never mentions ref, so the agent has no idea whether it names a scene, a sky node, or a handle, nor what null implies. One undocumented parameter at 0% coverage requires description compensation that is entirely absent.

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 enumerates the resource being read (sky mode, brightness, rotation, background, procedural sun, child lights), so an agent can infer this returns sky settings. But it never states a verb — it reads as a noun list rather than 'retrieves the current sky configuration' — and it does nothing to distinguish sky_get from close siblings like sky_set, sky_load, sky_save, or sky_compute_procedural.

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?

No when-to-use guidance at all. It doesn't say to call this before sky_set to inspect current values, nor how it differs from sky_load or sky_compute_procedural. The agent must infer usage purely from the name suffix.

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