granular_screen

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

With no annotations, the description carries the full burden and does disclose key traits: the tool is analytic/no-solver, outputs carry fidelity='correlation' plus a [low, high] band that 'IS the oracle', and results are correlations rather than exact theory. It also fixes units (SI: m, kg/m³, kg/s, degrees). It stops short of error/validation behavior or what happens on out-of-range or missing inputs, so not a 5.

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?

Front-loads the core claim ('Closed-form ... oracles') before the dispatch list, and the per-mode indented entries are information-dense with no padding. It is long, but the length is justified by five distinct modes with divergent signatures; only minor trims are possible.

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 17-param, zero-coverage, no-annotation, no-output-schema tool, the description must do nearly everything, and it covers dispatch, per-mode params, return contract (fidelity/band), units, and the escalate-vs-stop boundary. Missing pieces are minor: no statement of which params are required per mode beyond bracket convention, and no default (`problem` defaults to 'packing') is surfaced.

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% across 17 params, so the description must compensate — and it largely does by mapping parameters to each problem mode, e.g. 'beverloo (outlet_m, particle_d_m[, bulk_density_kg_m3 | material])' and 'beverloo_exponent (outlet1_m, flow1_kg_s, outlet2_m, flow2_kg_s [, particle_d_m])', using brackets to signal optionality. Parameters like `saturation`, `coordination`, `mu_low/mu_high`, and `repose_*` are placed in their modes, though none get unit or range semantics beyond the global SI note.

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?

States a specific resource and mechanism: 'Closed-form granular/powder-mechanics oracles — banded correlations, NO external solver', and explicitly ties itself to the sibling solve it is not ('the FreeCAD-free analytic twins the YADE DEM solve is gated against'). The dispatch-on-`problem` structure names each oracle ('packing', 'beverloo', 'beverloo_exponent', 'repose', 'repose_monotone'), so an agent can tell exactly what it does without opening the schema.

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?

Gives an explicit escalation rule with named alternatives and the exact conditions that select them: 'Escalate to dem_pack_submit / dem_flow_submit ... for polydisperse mixes, non-spherical grains, cohesion, or geometry this monodisperse idealization can't see.' It also frames the idealization boundary (monodisperse, spherical), leaving no inference about when not to use it.

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