Skip to main content
Glama

DEM Pack Submit

dem_pack_submit

Submits a background YADE simulation that pours and settles monodisperse spheres under gravity, then measures the random close-packing fraction and checks it against the RCP band.

Instructions

Pour N monodisperse spheres into a box and settle them under gravity with the REAL YADE discrete-element engine, then measure the random close-packing fraction φ of the settled bed — gated against granular_screen('packing') (RCP band 0.60–0.66, well below the crystalline 0.7405). YADE is GPL-3.0 and is run ONLY in a subprocess (the parent never imports it — same arm's-length isolation as the GPL Elmer/OpenFOAM binaries). Runs OFF the MCP channel via a background job, so a multi-second settle never blocks the worker.

box_m is the [Lx, Ly] floor footprint (m; default [0.06, 0.06]); the column height is sized to hold n_spheres. friction_deg is the inter-particle friction angle; young_pa the contact modulus; density the grain density. Returns {job_id, status, cache_hit, oracle} (poll job_status / job_result); the job result carries the oracle band PLUS the measured {packing_fraction, packing_fraction_bulk, in_band, gated_on, gated_fraction, n_settled, settled_height_m, mean_coordination, positions:[[x,y,z,r]]}. in_band judges the wall-free bulk φ (the whole-bed φ is deflated by loose wall and surface layers); it falls back to the whole-bed φ only when the bed is too small to have a bulk region, and gated_on names which fraction was judged. Absent YADE: {ok:false, reason, install, oracle}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "dem_pack_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
box_mNo
stepsNo
densityNo
radius_mNo
young_paNo
n_spheresNo
workspaceNoRun this call in this named workspace
friction_degNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

The description adds substantial behavioral detail beyond the annotations: the tool runs YADE in an isolated subprocess, executes off the MCP channel as a background job, returns a job_id for polling, and has a defined fallback when YADE is absent. It also explains the wall-free bulk packing judgment and the fallback to whole-bed packing for small beds.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and scope are front-loaded, and the dense detail is mostly relevant for a complex asynchronous simulation tool. Some parenthetical licensing and isolation context is extra, but it does not bury the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema and the complexity of the async job, the description is unusually complete: it names the returned job envelope, polling tools, and the rich job result payload including packing fractions, in_band, gated_on, settled height, coordination, and positions. It also covers the missing-YADE failure shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 13%, so the description must carry parameter meaning, and it does explain the key physical inputs: box_m as the floor footprint, friction_deg, young_pa, density, and n_spheres through column sizing. It leaves steps and radius_m unexplained, which keeps it from a 5 despite compensating for most important parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: pour N monodisperse spheres into a box, settle them under gravity with YADE, and measure the random close-packing fraction. It distinguishes the operation from flow or screening siblings by naming the packing metric, RCP band, and the granular_screen('packing') gate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context is clear: use this for a settled sphere bed whose packing fraction should be checked against the RCP band 0.60–0.66. It also explains the absent-YADE failure path, but it does not explicitly compare this tool to dem_flow_submit or state 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.

Deploy Server

Other Tools