circadian_metrics

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

With no annotations provided, the description fully owns behavioral disclosure. It transparently explains the difference between melanopic_lux and mel_edi, the effect of supplying an SPD (preserving within-bin structure, adding source_mel_der and transport_ratio), and the accuracy trade-offs when SPD is absent (exact for D65, ~1.5% for smooth spectra, up to ~8% high for narrow-band fluorescent). This goes beyond a simple 'computes X' and gives an agent a realistic model of the tool's behavior.

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 roughly 200 words, which is on the longer side, but every sentence adds substantive value. It is front-loaded with the core purpose, then explains the output nuances, then the spd behavior. The structure is logical and easy to parse, with clear separation of concerns. No redundant filler.

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 the tool's complexity and the presence of an output schema, the description is fairly complete. It covers the return format (single dict or list), the key output fields, the spd parameter's semantics and edge cases, and the behavioral differences between the two metric types. The only notable omission is an explanation of channel_type, which is a minor gap given that it has a default and likely represents a mode selector. Overall, an agent has enough 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 coverage is 0%, so the description must compensate. It thoroughly explains the spd parameter: what it is (source spectrum), its allowed forms ('.spd' path, 2-column text, or array), and why it matters (preserves within-bin structure). It also gives a brief hint about channels ('channel irradiances') in the opening line. However, the channel_type parameter is never mentioned, and channels is only indirectly described. Partial compensation for a critical gap.

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 opens with a clear statement: 'Photopic / melanopic / neuropic equivalent illuminance from channel irradiances.' It specifies the resource (channel irradiances) and the output quantities. While it doesn't explicitly name sibling tools like spectral_metrics or alpha_opic, the domain is distinct enough that the purpose is unambiguous.

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 provides practical guidance on interpreting results (e.g., 'pass mel_edi to compliance, never melanopic_lux') and explains when the spd parameter should be supplied. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Usage is implied by the domain but not spelled out.

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