Skip to main content
Glama

Granular Screen

granular_screen
Read-only

Computes closed-form granular mechanics correlations for packing fraction, hopper discharge, flow exponent, and repose angle, with honest low–high bands for quick screening before DEM solves.

Instructions

Closed-form granular/powder-mechanics oracles — banded correlations, NO external solver (the FreeCAD-free analytic twins the YADE DEM solve is gated against). These are correlations, not exact theory, so each returns fidelity='correlation' + an honest [low, high] band; the band IS the oracle. Dispatch on problem:

'packing' (regime='random_close'|'random_loose'|'fcc'[, coordination]) — monodisperse sphere solid-volume fraction φ. RCP ≈ 0.637 (band 0.60–0.66), the random pile a real settle must hit, well below the crystalline FCC/HCP 0.7405. 'beverloo' (outlet_m, particle_d_m[, bulk_density_kg_m3 | material]) — flat-bottom hopper discharge W = C·ρ·√g·(D−k·d)^2.5 [kg/s]; flow ∝ outlet to the 2.5 power, independent of fill height. 'beverloo_exponent' (outlet1_m, flow1_kg_s, outlet2_m, flow2_kg_s [, particle_d_m]) — recover the log-log flow exponent from two (outlet, flow) points; granular 2.5 (band 2.2–2.8) vs Torricelli 2.0. 'repose' (friction_coeff[, saturation]) — poured-pile repose angle θ ≈ atan(μ) + ±25% band. 'repose_monotone' (mu_low, repose_low_deg, mu_high, repose_high_deg) — the steeper-with-friction monotonicity gate.

SI units (m, kg/m³, kg/s, degrees). Escalate to dem_pack_submit / dem_flow_submit (the real YADE solve) for polydisperse mixes, non-spherical grains, cohesion, or geometry this monodisperse idealization can't see.

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": "granular_screen"
  }
}

Input Schema

NameRequiredDescriptionDefault
mu_lowNo
regimeNorandom_close
mu_highNo
problemNopacking
materialNo
outlet_mNo
outlet1_mNo
outlet2_mNo
workspaceNoRun this call in this named workspace
flow1_kg_sNo
flow2_kg_sNo
saturationNo
coordinationNo
particle_d_mNo
friction_coeffNo
repose_low_degNo
repose_high_degNo
bulk_density_kg_m3No

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.7/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description adds the material behavior an agent actually needs — results are correlations, not exact theory, each returns fidelity='correlation' plus a [low, high] band that 'IS the oracle'. It also discloses the absence of any external solver, so the agent knows latency and trust profile. This is substantive disclosure beyond the structured fields.

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?

Front-loading is strong — the core claim lands in sentence one, then a clean indented dispatch block, then units and escalation. Nearly every line earns its place given five problem types and eighteen parameters. Minor waste: the parenthetical 'the FreeCAD-free analytic twins the YADE DEM solve is gated against' is cryptic filler that doesn't help selection.

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

Completeness4/5

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

For an 18-param dispatch tool with no output schema and no enums, the description is impressively complete: it enumerates problem modes, units, expected ranges, return-band semantics, and the escalation path. What's missing is failure behavior (what happens with an unsupported `problem` string or an under-specified param set, since nothing is required) and the valid domain of `material`.

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?

With only 6% schema description coverage across 18 optional parameters, the description carries almost the whole burden and does so: it maps each `problem` value to its required inputs (e.g. 'beverloo' → outlet_m, particle_d_m[, bulk_density_kg_m3 | material]), fixes units, and gives expected magnitudes. Gaps remain: the acceptable values of `material` and the meaning/effect of `coordination` and `saturation` are never explained, and `workspace` is unmentioned.

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 opening states a specific resource class ('closed-form granular/powder-mechanics oracles — banded correlations') and immediately distinguishes it from the real solver it stands in for ('NO external solver ... the YADE DEM solve is gated against'), which differentiates it from siblings dem_pack_submit and dem_flow_submit. The dispatch list then names each concrete computation (packing, beverloo, repose), so an agent knows exactly what it will get.

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

Usage Guidelines5/5

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

The description gives an explicit dispatch rule ('Dispatch on `problem`:') with per-value conditions, plus a stated escalation clause: use dem_pack_submit / dem_flow_submit for polydisperse mixes, non-spherical grains, cohesion, or unseen geometry. That is both when-to-use and when-not-to-use with named alternatives, which is the top of the scale.

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