Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ottosim Import bracket.step, mesh it, and run a steady thermal study at 80 °C"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give an AI assistant first-order engineering physics on a real CAD model. This local stdio MCP server carries a STEP file through explicit meshing in Gmsh to a typed study in Elmer — steady and transient thermal, linear static structural, modal, DC conduction, and laminar flow — and returns revisioned results, with no cloud service and no prepared solver input.
Every engineering input is explicit: the materials, boundaries, and mesh are stated, never inferred, and each study, mesh, and result is revision-bound so a number can always be traced back to what produced it.
Qualified against analytic references. Gmsh 4.15.2 and Elmer (devel, most
recently released as 26.2.1) complete production-SIF qualifications for every
advertised physics — steady and transient thermal, static structural, modal
frequency, DC potential, and steady and transient laminar flow — each against an
analytic reference with mesh (or timestep) refinement.
Runs on Node 26 / TypeScript 7 against MCP SDK 2.4.0, with a Python Gmsh worker over
a one-request/one-response JSON-file protocol (protocol: 1).
Distribution targets match Geometry MCP: Windows x64, macOS ARM64 (Apple Silicon), and Linux x64. Intel macOS, Linux ARM64, and Windows ARM64 are outside the target matrix. CI runs unit/artifact/process checks on these three targets, builds the pinned serial Elmer solver on each target, caches the native install, runs the analytic integration and qualification suites, then packs and smoke-tests the published tarball. This validates native execution; a standalone runtime package is not yet published.
The repository owns its artifact schema in contracts/. Builds bundle that
schema and the Python worker; Gmsh and Elmer runtimes are installed separately.
From this directory:
nix develop
just setup
just build
export SIMULATION_INPUT_ROOTS='["/absolute/path/to/models"]'
export SIMULATION_WORKSPACE=/absolute/path/to/run-workspace
just start.envrc already contains use flake; direnv allow is an alternative to
nix develop. .env.example documents variables; .env is not auto-loaded.
just setup installs npm dependencies without lifecycle scripts. The flake
pins nixpkgs (and thus Gmsh) by commit, and pins upstream Elmer by commit.
Elmer's transitive inputs use its checked-in lock.
Nix provisions the solver toolchain only on x86_64-linux.
packages.<system>.toolchain provisions Node, Gmsh, the Python wrapper and
headless upstream Elmer built serially without MPI, OpenMP, ElmerIce or Lua. The analytic
thermal benchmark passes with that serial solver. The dev shell also provisions
Python, Ruff and Nix tooling;
TypeScript language server/formatter/linter/test deps are project-local npm
dependencies. Gmsh's Python module lives under its Nix package's lib, supplied
through PYTHONPATH. Elmer is an external package, not compiled by npm.
Non-Nix deployments must provide compatible Gmsh Python bindings and native
library plus ElmerGrid and ElmerSolver with HeatSolve, FluxSolver,
SaveData and ResultOutputSolve modules. Executables are operator configuration:
Variable | Default / meaning |
| Required JSON array of existing absolute input roots |
|
|
|
|
|
|
|
|
| 120000 per worker/conversion/solve; maximum 3600000 |
Generic host configuration example (environment may instead be inherited from the Nix shell):
{
"command": "node",
"args": ["/absolute/path/to/simulation/dist/src/index.js"],
"env": {
"SIMULATION_INPUT_ROOTS": "[\"/absolute/path/to/models\"]",
"SIMULATION_WORKSPACE": "/absolute/path/to/run-workspace",
"SIMULATION_PYTHON": "/absolute/path/to/provisioned/simulation-python",
"SIMULATION_ELMERGRID": "/absolute/path/to/ElmerGrid",
"SIMULATION_ELMERSOLVER": "/absolute/path/to/ElmerSolver"
}
}Related MCP server: COMSOL MCP
The public workflow is get_capabilities → inspect_model → query_model →
validate_study → prepare_study → run_study → inspect_job →
query_results. list_jobs recovers recent jobs after context loss and
cancel_job stops an active preparation or solver process.
inspect_job accepts waitMs (up to 60 s) and then waits in-process for a
terminal state instead of returning immediately, so
prepare_study → inspect_job(waitMs) → run_study → inspect_job(waitMs) → query_results is normally five calls rather than dozens of polls. The state
is returned whether or not the window expires. A cancelled or timed-out
client request stops the mesh or the solve: ctx.signal is forwarded to the
job's abort path and the record ends cancelled. Preparation and
solver execution return job IDs immediately. Jobs survive client disconnects,
not server shutdown. Interrupted jobs are recorded and are not resumed.
get_capabilities reports the available physics and the study shape
(required and optional fields, notes, and a worked example); the machine-readable
simulation://help resource carries the full study schema — per-physics
material and boundary fields with units, regimes, observation quantities with
time/mode selectors, enums, and a parseable example. Both are generated from one
catalog so discovery cannot drift from the accepted study schema.
steady-thermal, transient-thermal, static-structural, modal,
dc-conduction, and laminar-flow are implemented and benchmarked. Other physics reported by
get_capabilities remain unavailable, not implied by the fact that Elmer has
upstream solvers for them.
Transient studies require explicit density and heat capacity per solid,
one uniform initial temperature, a positive timestep, and a step count capped
at 10,000. Fixed-temperature, insulated and inward-heat-flux boundaries are
supported; time-varying conditions and per-region initial
temperatures are not. Transient scalar and VTU results are validated at every
step. An observation may select a positive timestep-aligned time in seconds;
without time, it observes the final step. Acceptance thresholds remain in the
quantity's units (for example, K), not seconds.
Static structural studies require an explicit isotropic Young's modulus and Poisson ratio for every solid, and an explicit fixed-displacement, prescribed-displacement, uniform-traction, or free condition for every surface. The supported model is static, linear-elastic, and small-strain; displacement and stress summaries are unweighted nodal samples, not volume averages.
Modal studies require explicit density in addition to elastic properties, fixed-displacement/free surface assignments, and request 1–20 modes. The first modal implementation reports eigenfrequencies only; it does not expose mode shapes, damping, prestress, or harmonic response. Modal observations select a mode number and use Hz.
DC conduction studies require explicit positive isotropic electrical conductivity per solid, explicit prescribed-potential or insulated conditions on every surface, and at least two distinct prescribed potentials per disconnected conductive component. Results report the nodal potential field; current, Joule heating, magnetic effects, and transient/capacitive behavior are not modeled.
Laminar-flow studies model incompressible Newtonian fluids with explicitly
assigned constant density and dynamic viscosity. Every fluid surface must be
explicitly assigned either a prescribed pressure or a no-slip wall; each
disconnected fluid region needs at least two distinct prescribed pressures.
Steady and transient runs are supported; transient runs use first-order BDF,
constant timestep, and an explicit quiescent initial velocity. The solver is
Elmer's monolithic FlowSolve module; qualification covers pressure-driven
square-duct flow and transient startup against the analytic rectangular-duct
solution, inlet/outlet flux conservation, and mesh/timestep refinement. Flux and
section averages are not exposed; reported velocity and pressure values are nodal
extrema. Elmer's segregated IncompressibleNS module is installed but not
qualified. Turbulence, compressibility, moving walls, nonzero initial velocity,
and thermal/electric coupling are not modeled.
Selections use dimension-qualified inspection entity IDs (for example 3:1
for a volume or 2:7 for a surface), have unique names and cannot mix solids
and surfaces. Every inspected entity must be assigned exactly once. Each solid
selection needs one material; every surface selection defaults to insulated
in thermal studies unless explicitly overridden. Structural, modal, and DC
studies require explicit conditions on every surface. A thermal default is a
declared engineering assumption, not an inferred boundary condition. The
solver uses SI units, but study quantities may be supplied in compatible
engineering units (for example mm, in, psi, ksi, lbf, degC) and are
converted at the API boundary. Mesh sizes default to metres and accept mm,
cm, in or ft through mesh.units. Results are SI by default; an optional
displayUnits block (for example { "length": "in", "pressure": "ksi" })
returns observations in the engineer's units. Linear tetrahedra are still the
only supported element type.
Material entries may carry an optional reference with the designation, source
name/revision, and basis returned by a reference tool such as Standards. The
study preserves this caller-supplied context alongside the explicit numeric
properties; Simulation does not fetch or verify the source. A typical value
remains distinct from a qualified design allowable.
Example steady thermal study after inspecting the STEP file:
{
"schemaVersion": "1",
"name": "Bar conduction",
"objective": "Estimate the steady temperature and heat flux",
"model": {
"source": {
"revision": "sha256:<64 lowercase hex digits>",
"uri": "file:///.../source.step",
"format": "step",
"units": "mm"
},
"inspection": {
"revision": "sha256:<64 lowercase hex digits>",
"uri": "file:///.../inspection.json",
"format": "json"
}
},
"selections": [
{ "name": "bar", "entities": ["3:1"] },
{ "name": "hot_end", "entities": ["2:2"] },
{ "name": "cold_end", "entities": ["2:3"] },
{ "name": "other_faces", "entities": ["2:4", "2:5", "2:6", "2:7"] }
],
"mesh": { "minSize": 0.003, "maxSize": 0.006, "elementOrder": 1 },
"physics": {
"kind": "steady-thermal",
"defaultBoundary": "insulated",
"materials": [
{
"selection": "bar",
"conductivity": { "value": 10, "units": "W/(m.K)" }
}
],
"sources": [],
"boundaries": [
{
"selection": "hot_end",
"kind": "temperature",
"temperature": { "value": 400, "units": "K" }
},
{
"selection": "cold_end",
"kind": "temperature",
"temperature": { "value": 300, "units": "K" }
}
]
},
"observations": [{ "id": "max_temperature", "quantity": "temperature_max" }],
"acceptanceCriteria": [
{
"observationId": "max_temperature",
"operator": "<",
"threshold": { "value": 410, "units": "K" }
}
],
"assumptions": []
}The example entity tags are illustrative; use tags from query_model and
confirm each selection against the actual part. prepare_study returns a
jobId; poll inspect_job until it succeeds, then pass its prepared artifact
to run_study, which returns another jobId. query_results reports solver
evidence separately from observation
values and criterion outcomes; a failed criterion is an engineering result, not
a solver error. Its response is bounded by default — observation values without
duplicate backing summaries, de-duplicated field descriptors, and one page of
artifact refs (limit/cursor, artifactCount). Summaries are returned when
requested with include:["summaries"], or as a fallback when no observations
were declared. Pass time to select one frame or observations to filter. Scalar
means are nodal, not volume averages or integrated heat
rates. Arbitrary SIF, procedures, expressions, scripts and solver commands are
never study inputs.
Tool failures use MCP isError. Domain failures from the service return a JSON
{ code, message } object (with revisioned diagnostic log refs where available);
invalid tool arguments are rejected by the MCP layer before the handler runs and
are returned as plain text. The domain error codes are a closed, documented set
(listed under enums.error_codes in simulation://help): invalid_input,
invalid_study, invalid_physics, invalid_selection, invalid_job_kind,
unsupported_condition, unsupported_physics, unsupported_format,
stale_artifact, path_policy, file_not_found, too_large, bad_mesh,
bad_groups, malformed_results, solver_failed, worker_failed,
conversion_failed, process_failed, spawn_error, output_limit,
persistence_failed, cancelled, timeout, interrupted, worker_protocol,
and internal_error. Failed solves return inspectable run metadata rather than
disguising partial outputs as successful results.
Server diagnostics are written as newline-delimited JSON to stderr (stdout is the
MCP channel). Set MCP_LOG_LEVEL (debug|info|warn|error, default
info), MCP_LOG_FORMAT=human for a compact form, and
MCP_TRACE_ID to correlate events; secret-like fields are redacted.
This is a trusted-local tool, not a filesystem sandbox. Input roots are canonicalized and used to catch accidental path mistakes; the server assumes the local user and files are trusted. Do not expose it to untrusted clients.
Artifact revisions are SHA-256 digests of the exact bytes read or produced. Reusing a ref after its file changes fails explicitly, but concurrent edits during an operation are not defended against.
Processes use configured executables and argument arrays, no shell. The local process environment is inherited for runtime compatibility, with deterministic locale/thread settings applied; child tools therefore also inherit local env vars.
Per-process wall timeout, serial execution and 8 MiB combined captured-output bound are enforced. There is no portable memory, mesh-size, input-size or workspace-disk quota; provision OS quotas/cgroups if deployment needs them.
V1 supports separate solid regions and exterior BC groups. Internal/orphan native boundaries fail; no contact resistance, automatic fragmentation, repairs, nonconformal coupling, radiation, plasticity, or geometric nonlinearity. Transient thermal supports only the explicit constant-property/ time-step model above; structural support is isotropic, linear small-strain; modal support is undamped and unloaded.
Selectors are tied to exact source revision, Gmsh version and
gmsh-occ-import-v1. No Geometry SubjectRef-to-Gmsh topology equivalence is
claimed. Imported names are hints, never engineering intent.
No automatic deletion. Shut down the server, then explicitly archive/remove
UUID operation directories when refs are no longer needed. just clean
removes only compiled code. Interrupted records are not resumed. After an
ungraceful termination inspect/reap any orphaned solver processes before
restarting against that workspace. Graceful shutdown cancels owned runs.
Hosted deployments need an external isolation boundary (e.g. a container or VM with explicit input mounts and resource limits); application path checks are not a substitute. These outputs are numerical evidence, not engineering certification.
The Gmsh Python API owns STEP import, topology inventory, and mesh generation.
It communicates with TypeScript through a bounded JSON-file worker protocol;
no generated .geo script is required.
Typed inputs generate deterministic SIF. PyElmer and model-authored SIF are unnecessary for supported workflows.
ASCII MSH 2.2 transfers explicit physical groups to ElmerGrid; converted group membership and connectivity are verified instead of trusting labels alone.
Upstream Elmer and Gmsh are external tools provisioned by Nix, not downloaded by npm at server startup. Non-Nix deployments can configure executable paths.
Scalar summaries and VTU inventory are intentionally limited to the supported solver output. Geometry IDs are not cross-kernel mesh selectors.
Every reference identifies one exact byte stream with revision: "sha256:<64 lowercase hex digits>" and a format. A URI is an optional locator; operations
requiring bytes need an accessible local file: URI. Supported format identifiers
are step, gmsh-msh, elmer-mesh, vtu, elmer-sif, text, and json.
Derived artifacts receive their own digests. An Elmer mesh directory is not a
single artifact: its metadata references individual native files.
Linear tetrahedra only; studies are small-strain and use the physics kinds listed above. Every engineering input is explicit — materials, boundaries, and idealisations are never inferred.
Results are numerical evidence, not engineering certification; a failed acceptance criterion is an engineering result, not a solver error.
A job survives a client disconnect but not a server shutdown, and interrupted jobs are recorded rather than resumed.
Requires Node.js 26+ and just. A Nix flake and
.envrc provide the toolchain; run direnv allow after changing either.
Recipe | Purpose |
| Install dependencies (npm scripts disabled). |
| Run the server over stdio. |
| Run the compiled server. |
| Compile into |
| Run solver-independent unit tests. |
| Run the opt-in Gmsh/Elmer integration benchmark. |
| Run oxlint. |
| Rewrite formatting with Prettier. |
| Verify formatting. |
| Run |
|
|
| Regenerate the analytic bar fixture. |
| Remove build output. |
Server logs go to stderr as newline-delimited pino JSON. MCP_LOG_LEVEL
(debug|info|warn|error), MCP_LOG_FORMAT=human, and MCP_TRACE_ID tune
them; secret-like fields are redacted.
The lightweight checks shell includes Node and Ruff without building the
Gmsh/Elmer solver toolchain:
# Run from this repository.
nix develop .#checks --accept-flake-config --command just setup
nix develop .#checks --accept-flake-config --command just check
nix develop --accept-flake-config --command just test-integration
nix develop --accept-flake-config --command just check
nix develop --accept-flake-config --command just buildjust test-integration runs the opt-in direct-service Gmsh/Elmer benchmark. It is
server-owned integration coverage; public stdio acceptance runs separately
against the built server artifact.
In a source checkout, tests/fixtures/README.md documents analytic bar dimensions,
generation, and temperature/heat-flux tolerances. Unit checks do not require a
solver runtime. Native integration checks additionally cover malformed inputs,
solver failures, timeout/cancellation, restart persistence, and stale outputs.
Tests use the operating system's temporary directory;
SIMULATION_TEST_TMP can select another temporary root.
Licensing and upstream source references are recorded in third-party notices.
npm pack builds first and includes compiled runtime code, the local artifact
schema, Python worker, README, and third-party notices. Tests, source maps, and
Python caches are excluded. Install the tarball to check simulation-mcp-server
with a compatible MCP client. The server serves both protocol eras: the
2025-11-25 handshake that stock MCP hosts negotiate, and 2026-07-28
through server/discover. Native tools still require separate installation.
just check includes solver-independent stdio protocol tests for modern
discovery, workflow resources, tool errors, and both protocol eras.
MIT. Third-party toolchain terms are in THIRD_PARTY_NOTICES.md.
Cancel an active preparation or solver job owned by this server. Child processes are stopped before cancellation is reported; partial artifacts are retained.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Job id of the active preparation or solver job to stop. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds genuine new behavior: child processes are stopped before cancellation is reported (synchronous completion semantics) and partial artifacts are retained (post-cancel state). It stops short of noting permission requirements or the error outcome for already-completed or unknown job ids.
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, no filler, and the scoping constraint plus the process-stop guarantee are front-loaded before the artifact-retention note. Every clause conveys information an agent would otherwise have to guess.
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?
An output schema exists, so return values need no explanation, and the destructive/async semantics are largely covered. The remaining gap is failure-mode context: behavior when the job is already complete, already cancelled, or not owned by this server is unstated, which matters for a non-idempotent destructive tool.
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% for the single jobId parameter (uuid format, pattern, and its own description), so the schema already carries the burden. The description only adds the qualifier that the id refers to an active preparation or solver job, which is marginal added meaning. Baseline 3 applies.
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 verb (cancel) applied to a specific resource (an active preparation or solver job) and adds an ownership scope ('owned by this server'). The read-oriented siblings (inspect_job, list_jobs, query_results) are clearly a different operation class, so an agent can select this tool without opening a 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?
The word 'active' implies the precondition that only running jobs are cancellable, which is useful guidance. However, there is no explicit statement of when to cancel versus wait, no mention of what to call instead (e.g. inspect_job to check status first), and no note on what happens if the job is already finished or unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover implemented and benchmarked physics workflows actually available in this installation. Unavailable physics are never accepted for preparation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| study | Yes | |
| physics | Yes | |
| workflow | Yes | |
| schemaVersion | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds that availability is installation-specific and that unavailable physics are rejected downstream, but says nothing about the shape/freshness of results or caching, which the output schema partly covers.
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 short sentences with the capability statement front-loaded and the availability constraint second. No filler, no repetition of the title.
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 zero-parameter read tool with an output schema and full annotation coverage, the description supplies the purpose and the key installation-scoping caveat. Only the tie-in to the preparation workflow (when to call it) is left implicit.
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?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies the result is scoped to 'this installation' rather than passed as an argument.
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 verb ('Discover') and resource ('implemented and benchmarked physics workflows actually available in this installation'), scoped to the local installation. It does not explicitly contrast itself with siblings like inspect_model or query_model, which also read model state, so an agent must infer the boundary.
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?
Usage is only implied: the note that 'Unavailable physics are never accepted for preparation' hints that this should be consulted before prepare_study, but there is no explicit when-to-use statement or named alternative. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect preparation or solver job status, diagnostics and available artifacts. Pass waitMs to wait for a terminal state instead of polling; interrupted jobs are not resumed automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Job id from prepare_study or run_study. | |
| waitMs | No | Wait up to this many milliseconds for the job to finish, then return its state (max 60000). Prefer one call with waitMs 60000 over repeated polling; the status may still be preparing/running when the window expires. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, open-world, so safety is covered; the description adds two non-obvious traits beyond that: the blocking wait semantics and the fact that an interrupted job stays interrupted and must be re-triggered. It does not cover job retention or how long artifacts remain retrievable on an open-world backend.
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, no filler; the resource scope comes first and the wait/interruption caveats follow in a logical order. Every clause carries information an agent needs.
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?
An output schema exists so return shape needn't be described, and the description covers job types, blocking behavior, and the interruption caveat. The remaining gap is that it never clarifies when to inspect versus list_jobs or query_results for status, which matters given nine siblings.
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% — both jobId (source tools, UUID format) and waitMs (max 60000, prefer a single call over polling) are fully documented in the schema. The description's waitMs sentence largely restates the schema's 'prefer one call with waitMs 60000 over repeated polling' note, so it adds little beyond intent framing.
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?
Specific verb (inspect) plus resource (prepare/solver job) and the three things it returns: status, diagnostics, and available artifacts. It covers both job families, which helps distinguish it from narrower siblings, but it never names list_jobs, query_results, or cancel_job to route the agent away from them.
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?
Explicitly advises passing waitMs to block for a terminal state 'instead of polling', which is real usage guidance against an alternative behavior. It also flags that interrupted jobs are not resumed automatically, preventing a wrong assumption. No explicit when-not guidance relative to sibling tools like list_jobs or query_results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshot a local STEP file and inspect SI-normalized geometry. Supply exactly one URI or revisioned STEP artifact. Returned entity tags are scoped to the model inspection; labels are hints, never engineering assignments.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | STEP file to inspect, as a file: URI or absolute path. Supply this or source, not both. | |
| source | No | Revision-bound source artifact instead of a raw URI. Supply this or uri, not both. |
| Name | Required | Description |
|---|---|---|
| logs | Yes | |
| source | Yes | |
| inventory | Yes | |
| inspection | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare open-world, non-idempotent, non-destructive behavior, and the description adds key context: it creates a snapshot and returned entity tags are scoped to the inspection, with labels explicitly described as hints rather than authoritative assignments. It still does not explain snapshot persistence, lifetime, or cleanup semantics.
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 description is three compact sentences with the core action front-loaded. Each sentence carries useful information, though the wording around labels and revisioned artifacts is dense and could be slightly clearer.
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 a full input schema, an output schema, and annotations, the description supplies enough to invoke the tool safely. However, it does not explain when this tool should be chosen over query_model or validate_study, and it leaves the snapshot's side effects and lifecycle ambiguous.
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 coverage is 100%, so the schema already documents the uri/source choice and the revision-bound artifact structure. The description reinforces the mutual exclusivity of the two inputs, but adds little beyond the schema and may slightly narrow the source to STEP even though the schema's format enum includes non-STEP formats.
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 states a specific verb and resource: snapshot a local STEP file and inspect SI-normalized geometry. It is clear what the tool does, but it does not explicitly distinguish itself from nearby tools such as query_model or validate_study.
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?
It says to supply exactly one URI or revisioned STEP artifact, which is an input constraint rather than usage guidance. It gives no when-to-use guidance, no when-not-to-use guidance, and no explicit comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recover recent solver jobs after losing conversation context. Returns up to 100 jobs, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| jobs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavioral detail beyond annotations: it returns at most 100 jobs and orders them newest first. It does not explain truncation or what happens if more than 100 jobs exist.
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 short sentences with zero waste. The use case is front-loaded, followed immediately by the return volume and ordering.
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 zero-parameter tool with rich annotations and an output schema, the description covers the essential context: when to use it, how many jobs come back, and in what order. An agent can invoke it correctly without further description.
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?
The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter semantics because there are none to explain.
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 states a specific resource (recent solver jobs) and a clear recovery use case, distinguishing it implicitly from single-job tools like inspect_job. It is clear but does not explicitly name or contrast with sibling tools.
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?
It gives a clear triggering scenario: 'after losing conversation context.' However, it does not state when not to use it or explicitly name alternatives such as inspect_job for detailed job inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue validation, meshing and solver-input generation for an available study type in the background. Transient thermal requires density, heat capacity, a uniform initial temperature, timestep and step count. Transient flow uses first-order BDF with explicit quiescent initial velocity. Returns a jobId immediately; inspect_job polls until the prepared-study artifact is available.
| Name | Required | Description | Default |
|---|---|---|---|
| study | Yes | The study to prepare. get_capabilities.study lists every field; validate_study explains missing or unsupported inputs before anything is meshed. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| error | No | |
| jobId | Yes | Job id returned by prepare_study or run_study. |
| study | Yes | |
| status | Yes | |
| endedAt | No | |
| prepared | No | |
| artifacts | Yes | |
| createdAt | Yes | |
| startedAt | Yes | |
| diagnostics | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, open-world, non-idempotent, non-destructive. The description adds the key behavioural fact beyond them: work is asynchronous, returns immediately with a jobId, and the artifact only appears after polling. It also discloses solver specifics (first-order BDF, explicit quiescent initial velocity) that the schema does not state.
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?
Three sentences, front-loaded with the action and scope, then the kind-specific requirements, then the return/handoff. No filler and nothing repeated from structured fields verbatim.
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?
Output schema exists, so return values need not be spelled out; the description still gives the one fact that matters (jobId plus inspect_job). For a deeply nested six-variant physics schema it covers only the transient cases explicitly, leaving the steady, structural, modal, DC and steady-flow variants to the schema, which is acceptable but not exhaustive.
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 coverage is 100% for the single nested study parameter, so the baseline is 3. The description earns a bump by naming the per-physics-kind required inputs (density, heat capacity, initial temperature, timestep, step count) and the transient-flow discretisation, which reduces the need to reverse-engineer the oneOf branches.
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?
Names a specific verb chain (queue validation, meshing, solver-input generation) and the resource (a study), plus the background/async nature. It distinguishes itself from inspect_job by assigning polling to that sibling, though it never explicitly contrasts with validate_study or run_study, which are the closest neighbours.
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?
Establishes the workflow context: call this, then poll inspect_job until the prepared-study artifact exists. 'for an available study type' implies the study kind must be one the server supports. No explicit exclusions (e.g. validate first, or that this does not solve the study) are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List inspected model entities, optionally filtered by dimension. Entity IDs and labels belong to this exact inspection revision. Use returned IDs to define study selections.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Entities per page, at most 200 (default 100). | |
| model | Yes | The inspection artifact returned by inspect_model. | |
| cursor | No | Pagination cursor from the previous page. | |
| dimension | No | Keep only entities of this dimension: 2 = surfaces, 3 = solids. |
| Name | Required | Description |
|---|---|---|
| entities | Yes | |
| nextCursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent and non-destructive behavior, and the description adds the non-obvious constraint that entity IDs and labels are bound to one exact inspection revision — important because stale references would silently mislead. It says nothing about paging behavior or limits, so it stops short of 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?
Three short sentences, front-loaded with the action and scope, then the revision-binding caveat, then the downstream use. No filler or redundant restatement.
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?
Given an output schema, rich annotations and full schema coverage, the description supplies what structured fields cannot: revision scoping and how the result feeds study selections. It could add a note on pagination or on what happens with very large models, but nothing essential is missing.
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 schema description coverage at 100%, the schema already documents limit, cursor, dimension values and the revision pattern. The description only restates the presence of a dimension filter and adds no syntax or constraint details beyond the structured fields.
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 verb and resource ('List inspected model entities') plus the optional dimension filter, which separates it from siblings like query_results or list_jobs. It does not name an alternative tool outright, keeping it short of 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?
The phrase 'Use returned IDs to define study selections' implies the workflow position (after inspect_model, before prepare_study) but never states when to choose this over a sibling or when not to call it. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve bounded evidence for a solver job, including its job ID, source model and prepared-study reference, status, convergence, observations and acceptance, distinct output fields, and a paginated artifact page. Summaries are returned when explicitly requested with include:['summaries'], or as a fallback when no observations were declared. Pass observations to filter, time to select the frame for observations without an explicit time, and limit/cursor to page artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | For time-dependent studies: the timestep-aligned time in seconds to read. Defaults to the final step. | |
| jobId | Yes | Solver job id returned by run_study. | |
| limit | No | Artifacts per page, at most 500 (default 100). | |
| cursor | No | Pagination cursor from the previous page. | |
| include | No | Pass ['summaries'] to include the full summary history rather than only the latest observations. | |
| observations | No | Keep only these observation ids (as defined in the study). |
| Name | Required | Description |
|---|---|---|
| error | No | |
| jobId | Yes | Job id returned by prepare_study or run_study. |
| fields | Yes | |
| source | Yes | |
| status | Yes | |
| artifacts | Yes | |
| summaries | Yes | |
| acceptance | Yes | |
| nextCursor | No | |
| convergence | Yes | |
| diagnostics | Yes | |
| observations | Yes | |
| artifactCount | Yes | |
| preparedStudy | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: results are 'bounded', artifacts come back as a paginated page, and summaries appear either on explicit request or as a fallback when no observations were declared. That fallback rule is a non-obvious trait an agent could not learn from annotations or schema alone.
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-loaded with the return contents then the parameter guidance, with no filler. The opening enumeration is a long comma-chained list and the second sentence packs three clauses, but each clause carries operative information.
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?
An output schema exists, so return-field description is technically redundant, yet the description stays complete about paging, the summaries fallback, and the required job id coming from run_study. The missing piece is a stated relationship to inspect_job and list_jobs for a six-parameter tool with many sibling lookups.
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 coverage is 100%, so baseline is 3; the description goes past the schema by explaining parameter interplay — time only matters for observations lacking an explicit time, and limit/cursor page only artifacts, not observations. Those relational semantics are not visible in the per-property descriptions.
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 verb ('Retrieve bounded evidence') and resource ('for a solver job'), and enumerates the payload it returns: status, convergence, observations, acceptance, output fields, artifact page. An agent knows exactly what it gets back. However, it never distinguishes itself from sibling job tools such as inspect_job or list_jobs, so the boundary must be inferred.
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 second sentence gives real usage guidance for parameters ('Pass observations to filter', 'time to select the frame', 'limit/cursor to page artifacts') and for include:['summaries']. But there is no statement of when to call this versus inspect_job, which reads like the closest alternative. Context is implied rather than specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an immutable prepared study asynchronously. Returns a jobId; use inspect_job, list_jobs, query_results or cancel_job.
| Name | Required | Description | Default |
|---|---|---|---|
| prepared | Yes | The prepared-study artifact returned by prepare_study (inspect_job.prepared once the prepare job succeeds). It pins the mesh and solver inputs, so the solve cannot pick up a changed study. |
| Name | Required | Description |
|---|---|---|
| sif | Yes | |
| case | Yes | |
| kind | Yes | |
| logs | Yes | |
| mesh | Yes | |
| error | No | |
| jobId | Yes | Job id returned by prepare_study or run_study. |
| solver | Yes | |
| source | Yes | |
| status | Yes | |
| endedAt | No | |
| outputs | Yes | |
| results | Yes | |
| prepared | No | |
| createdAt | Yes | |
| execution | No | |
| startedAt | No | |
| summaries | Yes | |
| convergence | Yes | |
| diagnostics | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful context beyond the annotations: execution is asynchronous and the immediate return is a jobId, so the agent knows not to expect results inline. Annotations already cover the safety profile (readOnly=false, idempotent=false, destructive=false). It doesn't disclose anything about long-running behavior, failure modes, or whether the solve can be cancelled mid-flight beyond naming cancel_job.
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 tight sentences, zero waste, with the core action and asynchrony front-loaded before the follow-up tool routing.
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 an output schema, full parameter documentation, and annotations all present, the description only needs to supply the async contract and next steps, which it does. A note on the prepare→run lifecycle ordering would make it fully self-contained, but everything required to call it correctly is available.
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 nested ArtifactRef is documented in detail, including the revision-mismatch rejection rule. The description only reinforces immutability of 'prepared'; it adds no syntax or format detail beyond the schema, so baseline 3 applies.
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 verb and resource ('Execute an immutable prepared study') and the execution mode ('asynchronously'), which clearly separates it from prepare_study and validate_study. It doesn't explicitly name the prerequisite tool, but the resource name suffices to identify the operation.
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 second sentence routes the agent to follow-up tools (inspect_job, list_jobs, query_results, cancel_job), which is useful post-invocation guidance. However, it gives no explicit when-to-use guidance relative to the lifecycle (e.g., 'call after prepare_study succeeds and optionally after validate_study') and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a complete study draft and explain missing or unsupported inputs without launching Gmsh or Elmer. The study shape, per-physics fields and a worked example are in get_capabilities.study.
| Name | Required | Description | Default |
|---|---|---|---|
| study | Yes | The study draft. Required and optional fields, per-physics material and boundary fields, observation quantities, and a worked example are in get_capabilities.study; simulation://help carries the full JSON Schema. |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| issues | Yes | |
| deferredChecks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by clarifying no solver is launched and that the tool reports diagnostics rather than failing silently, which tells the agent what to expect from a call.
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 tightly written sentences with the core action and the no-solver guarantee front-loaded. Nothing is redundant or padded.
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?
An output schema exists, so return-value detail is not required, and the description correctly routes the agent to get_capabilities.study for the study shape. Minor gap: it doesn't clarify whether validation failures are returned as data or raised as errors, though the output schema likely covers this.
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 coverage is 100% and the single parameter's schema description already points to get_capabilities.study and simulation://help. The description repeats the same pointer without adding field-level detail, so baseline 3 applies.
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 verb and resource (validate a complete study draft) plus the observable outcome (explains missing or unsupported inputs). The clause 'without launching Gmsh or Elmer' implicitly distinguishes it from run_study, though no sibling is named explicitly.
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 phrase 'complete study draft' implies this is a pre-flight check applied to a finished draft rather than a partial one, which hints at when to call it. However, it never states when not to use it or names alternatives such as prepare_study or run_study, leaving the agent to infer the workflow position.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0cancel_jobget_capabilitiesinspect_jobinspect_modellist_jobsprepare_studyquery_modelquery_resultsrun_studyvalidate_studyScored across 10 tools
Each tool targets a distinct stage or resource in the simulation workflow: model inspection, model querying, capability discovery, study validation/preparation/execution, job inspection/listing/cancellation, and results querying. Closely related tools such as inspect_model/query_model and inspect_job/query_results are clearly differentiated by their descriptions.
All tools use a consistent snake_case verb_noun pattern, such as inspect_model, validate_study, prepare_study, run_study, inspect_job, list_jobs, query_results, and cancel_job. The repeated verbs are used coherently across model, study, and job resources.
Ten tools is well scoped for a simulation workflow spanning model inspection, study preparation, execution, job monitoring, and results retrieval. Each tool appears to earn its place without obvious redundancy or missing operational stages.
The surface covers the core lifecycle from STEP model inspection through study validation, preparation, execution, job monitoring, cancellation, and results retrieval. Minor gaps exist around explicit artifact export/download and recovering preparation-job history, but agents can work around these through inspect_job and query_results.
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Run FDS, OpenFOAM, CalculiX and other engineering simulations on cloudHPC from your AI assistant.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Structural FEM for AI agents: frames, plates, buckling, seismic and Eurocode checks, solved locally.
