spectral_sky_native

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers several important behaviors: the subprocess invocation (gensdaymtx), the degradation to a command plan if Radiance 6.x is missing, the timeout behavior and its default, the fact that gensdaymtx always processes every EPW hour, performance scaling with mf, and the error return on timeout ({ok: False, timed_out: True}) instead of raising. This is thorough, though it does not mention side effects like file writing (work_dir) or the output format beyond the matrix specification, which is partially covered by the output schema.

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 compact and efficient, with no fluff. The main purpose is front-loaded, followed by mode, fallback, timeout, performance, and error handling. Each sentence contributes unique information, and the technical details are relevant. It is slightly dense but not overly long, making it easy to scan for key facts.

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?

Given that an output schema exists, the description does not need to explain return values, and it does not. It covers prerequisites (Radiance 6.x), fallback behavior, performance characteristics, timeout handling, and parameter semantics. It does not explain what the matrix output is used for or how to interpret the melanopic collapse, but these are likely domain-specific and may not be necessary for tool selection. Overall, it is complete for an expert user and sufficiently guides the agent on behavior and limitations.

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?

The schema description coverage is 0%, so the description must compensate for parameter meaning. It explains mode with its possible values, timeout with its default and effect, and mf with its performance implications ('cost grows steeply... Trim the EPW, or raise mf only as needed'). It also implies epw's role ('from an EPW'). However, it does not describe the 'run' or 'work_dir' parameters, though these are relatively self-explanatory. Overall, it adds significant meaning for the most important parameters, but not all.

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 clearly states the tool's purpose: generating a native Radiance 6.x spectral sky from an EPW file using gensdaymtx, and specifies the output as a 20-band W/sr/m² matrix. It is specific about the verb (generate), resource (spectral sky), and method, but it does not explicitly contrast with sibling tools like spectral_sky_from_epw, leaving differentiation to the word 'Native' and the technical details. The description is clear enough for an agent to understand what it does, but lacks explicit sibling differentiation.

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 description mentions the mode parameter ('all | sun (-d) | sky (-s)') but does not explain when to use this tool versus alternatives like spectral_sky_from_epw or colored_sky. It only describes a fallback when Radiance 6.x is not installed, which is a condition, not usage guidance. There is no explicit statement about when to prefer this tool over siblings or when not to use it, leaving the agent to infer from the name and description.

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