annual_daylight

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

With no annotations provided, the description carries the full burden of disclosing behavior. It reveals that it 'Runs Radiance if present, else returns the command sequence,' explains the ASE direct-only pass, and details the shading_model handling including the 'undeclared' fallback and lm83_conformant flag. This is substantive transparency about operational behavior, though it omits potential side effects or file modifications.

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 dense but well-structured. It leads with the core purpose, then explains parameters in a logical order, front-loading the critical input shapes. While it is lengthy, every sentence adds substantive information. It could be tightened, but it is not redundant or wasteful.

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 tool with 21 parameters, no annotations, and a complex domain, the description covers the most conceptually difficult inputs and behaviors but leaves gaps. It does not describe the output schema (though an output schema exists), nor does it explain many parameter defaults and their implications. The description is adequate for a user already familiar with the domain but not fully self-contained.

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%, so the description must compensate. It explains the most complex parameters (channel_scenes, points, sensor_set, occupancy, shading_model) with detailed syntax and defaults. However, it leaves many other parameters (e.g., run, wea, quality, udi_aut, udi_sup, thresholds, timestep_min) unexplained, and the schema itself provides no descriptions. The explanation is helpful but incomplete for the full parameter set.

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: 'Annual climate-based daylight metrics on the grid: per-point DA/cDA/UDI + spatial sDA/ASE.' It uses specific metric names and indicates the resource (grid). However, it does not explicitly differentiate from close siblings like run_annual or lm83_daylight beyond a passing reference to 'same shape as run_annual,' so it falls short of full clarity.

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 gives no explicit guidance on when to choose this tool over alternatives. It references run_annual's shape and the sensors tool for sensor_set, but does not state conditions like 'use this instead of run_annual when you need spatial sDA/ASE' or mention exclusions. The usage context is implied by the metric names but not articulated.

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