DEM Pack Submit

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

The description discloses important behavioral traits beyond the sparse annotations: YADE is GPL-3.0 and runs only in a subprocess, the parent never imports it, the run happens off the MCP channel in a background job so it does not block the worker, and the absent-YADE behavior is specified. This goes well beyond what readOnlyHint/destructiveHint provide, and there is no contradiction.

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 prose is dense and well structured: purpose first, then licensing/execution constraints, then parameter meanings, then return shape. Some detail about the GPL Elmer/OpenFOAM arm's-length isolation could be trimmed, but nearly every sentence adds needed context for a complex asynchronous solver submission.

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 complex async submission with no output schema, the description covers the job result shape, the oracle band, the absent-YADE fallback, and most parameter semantics. It falls short only in leaving steps and radius_m to name/default inference and by carrying the box_m default inconsistency, which keeps it just shy of fully complete.

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?

With 0% schema description coverage, the description does add physical meaning for box_m, friction_deg, young_pa, density, and n_spheres. However, it omits explicit semantics for steps and radius_m, and it states box_m's default as [0.06, 0.06] while the schema default is null, creating a potentially confusing inconsistency. This is helpful but not fully complete.

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 concrete, specific operation: pour N monodisperse spheres into a box, settle under gravity with YADE, measure the random close-packing fraction, and gate it against granular_screen('packing'). This is an unambiguous verb+resource+scope statement that also distinguishes the tool from siblings like dem_flow_submit or granular_screen.

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 clearly establishes the operational context: it is an asynchronous background submit that should be polled via job_status/job_result, and it is explicitly gated against granular_screen('packing'). It does not name when-not-to-use alternatives explicitly, but the context is sufficient for an agent to route a packing-fraction request correctly.

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