ModelRisk MCP

Official

Overview Schema Source Related Servers Discussions Admin

run_simulation

Run Monte Carlo risk simulations on an Excel workbook to generate outcome data, saving results to a .vmrs file for analysis.

Instructions

ModelRisk: Run a Monte Carlo simulation on the active (or named) workbook and save the results to a .vmrs file. Defaults to 1000 iterations with a fixed seed for reproducibility, and saves the .vmrs next to the workbook as <book>.vmrs. The simulation is run via the same XLL commands ModelRisk's own ribbon uses (VoseStartSimulCustom12 + VoseGetDataSZ12 with the SaveResultsToFile session), so behaviour matches what you'd see clicking 'Simulate' manually. ModelRisk simulates the active workbook, so a named workbook is made active first. The saved .vmrs is checked to hold this run (workbook, start time, iterations) before success is reported. Blocks until the simulation completes. After this returns, call get_simulation_results — the produced .vmrs is automatically pinned as the active results source. engine='turbo' runs ModelRisk's Turbo engine (its 'Fast Simulation'), often much faster. Turbo cannot evaluate every function: the engine's own check runs first, and the classic engine runs instead (see note and engine in the result) when Turbo cannot run the workbook or returns NaN outputs. Turbo can still give results that differ from the classic engine's for some functions, so confirm figures that matter with the classic engine. A Turbo run shows ModelRisk's progress window and opens its results in the Results Viewer.

Input Schema

Name	Required	Description	Default
`seed`	No	Random seed for reproducibility (fixed seed).
`engine`	No	'classic' (default): ModelRisk's own engine, in Excel. 'turbo': ModelRisk's Turbo engine; .xlsx and .xlsm workbooks only, and falls back to classic when it cannot run the workbook.	classic
`samples`	No	Iteration count. Default: 1000. Either `samples` or `iterations` is accepted (they mean the same thing). If both are passed, `samples` wins.
`save_to`	No	Absolute path to write the .vmrs. Default: next to the workbook as `<book_stem>.vmrs`. For OneDrive-hosted workbooks (where path resolution can fail) the default falls back to the user's Desktop folder.
`iterations`	No	Alias for `samples`. ModelRisk's UI calls this 'samples'; many users call it 'iterations'. Both work.
`workbook_name`	No	Workbook file name (e.g. 'model.xlsx'). Omit for the active workbook.

Output Schema

Name	Required	Description	Default
`note`	No	Set when ModelRisk's own save returned a different run (its Results Viewer had another run loaded) and the .vmrs was rebuilt from this run's ModelRisk run file, or when Turbo was asked for and the classic engine ran instead, and why. The results are this run's either way.
`seed`	Yes
`engine`	No	The engine whose run was saved. 'classic' after a request for 'turbo' means Turbo could not run the workbook; `note` says why.	classic
`samples`	Yes
`next_step`	Yes	Suggested follow-up call for the MCP client — typically `get_simulation_results` to pull the per-output statistics.
`vmrs_path`	Yes
`workbook_name`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.4.4Oct 4, 2026

addedInput schema / properties / engine

Added value: +{
+  "default": "classic",
+  "description": "'classic' (default): ModelRisk's own engine, in Excel. 'turbo': ModelRisk's Turbo engine; .xlsx and .xlsm workbooks only, and falls back to classic when it cannot run the workbook.",
+  "enum": [
+    "classic",
+    "turbo"
+  ],
+  "title": "Engine",
+  "type": "string"
+}

addedOutput schema / properties / engine

Added value: +{
+  "default": "classic",
+  "description": "The engine whose run was saved. 'classic' after a request for 'turbo' means Turbo could not run the workbook; `note` says why.",
+  "enum": [
+    "classic",
+    "turbo"
+  ],
+  "title": "Engine",
+  "type": "string"
+}

addedOutput schema / properties / note

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Set when ModelRisk's own save returned a different run (its Results Viewer had another run loaded) and the .vmrs was rebuilt from this run's ModelRisk run file, or when Turbo was asked for and the classic engine ran instead, and why. The results are this run's either way.",
+  "title": "Note"
+}

First observedv0.3.13Jul 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so richly: blocking behavior, result-file pinning, the internal XLL command path, a post-run validation check on workbook/start time/iterations, Turbo's fallback-to-classic behavior and NaN caveat, and the visible progress window. These are exactly the behavioral traits an agent needs before invoking.

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?

Dense and front-loaded with the core action first, but it is long and contains some restatement (e.g. explaining twice that the active workbook is simulated / named workbook made active) that could be tightened without losing information.

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?

An output schema exists so return values need not be explained, and for a zero-required-parameter simulation tool the description covers engine choice, file output, blocking semantics, and downstream tooling. Nothing essential to correct invocation is missing.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the fixed-seed reproducibility default, the samples/iterations aliasing and precedence, the .vmrs naming convention, and Turbo's engine-specific constraints and fallback semantics.

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?

States a specific verb+resource+outcome: run a Monte Carlo simulation on the active/named workbook and save results to a .vmrs. It also clearly distinguishes itself from the follow-up tool by naming get_simulation_results and the sibling run_scenarios is not conflated with it.

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?

Gives strong sequencing guidance ('After this returns, call get_simulation_results') and clear engine-selection advice including when to re-confirm figures with classic. It does not, however, say when to prefer this tool over siblings like run_scenarios or when a simulation is unnecessary.

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

Deploy Server