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

Annotations already establish read-only, idempotent, closed-world, non-destructive behavior, so the safety profile needs no restatement. The description adds real value beyond that by declaring validity boundaries — the ideal Rayleigh model excludes slit and aberration limits — which tells the agent when the numeric results stop being trustworthy. It stops short of stating failure modes (e.g., no real order exists for some angle/wavelength combinations) or unit conventions on output.

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?

Two sentences, both dense and load-bearing: the first establishes model and provenance, the second enumerates outputs and the scope limit. Nothing is padding, and the core 'what it does' is front-loaded.

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?

With no output schema, the description usefully compensates by listing the six returned quantities, which is exactly what an agent needs to know the result shape. All five inputs are schema-documented with defaults. The remaining gap is error/edge-case behavior for physically invalid inputs, which for a deterministic calculator is minor but not zero.

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 100% and the five parameters carry defaults, so the baseline is 3. The description names the physical quantities being solved for but adds no parameter-level detail — it doesn't clarify the sign convention on incidence_deg, or that width_mm means illuminated footprint rather than aperture (only hinted at by the slit exclusion). Essentially it repeats none of the schema and adds none either.

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 gives a specific verb and resource: it 'solves the signed reflection grating equation and ideal Rayleigh resolution,' and names the references (Hecht 5th ed., Newport handbook). It also enumerates the returned quantities (order bounds, dispersion, groove count, linewidth, Littrow angle, FSR), so the agent knows exactly what physics is computed. It doesn't explicitly contrast itself with the closest sibling, bragg_peak, which keeps it from a 5.

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?

There is no explicit when-to-use or when-to-use-alternatively guidance, so selection between this and e.g. bragg_peak or xray_spectrum is inferred from subject matter alone. The phrase 'excludes slit and aberration limits' does set a scope boundary that implicitly tells the agent not to rely on this for instrument-limited resolution. That is a partial usage signal, not a routing rule.

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