Agent tools

The 70 tools of nagasim.agent_tools.TOOLS, which naga mcp publishes under the same names. "Reads" marks a tool that changes nothing. Each tool's full description and argument schema is what the server sends an agent; see Use with an agent.

core

Tool	Reads	What it does
new_model		Create an empty model in the workspace under name.
open_model		Load a model file from the workspace root into the workspace.
import_xmile		Translate an XMILE (Stella/iThink) system-dynamics file into a new model.
import_mdl		Translate a Vensim system-dynamics file into a new model.
save_model		Write a model in the workspace to disk as JSON.
list_models	yes	List the models currently open in the workspace, and the model files available under the workspace root.
get_model_summary	yes	A compact picture of a model: its blocks with their key parameters, its links in branch order, its resources, and how many problems it has.
get_model_json	yes	The complete model layout as the JSON that would be saved to disk.
undo		Undo the last edit to a model.
redo		Redo the edit that undo reversed.

model

Tool	Reads	What it does
add_block		Add one block to a model and optionally set its parameters in the same step (one undo entry).
update_block		Change an existing block: merge parameters, rename it, move it, or relabel it -- all as one undo entry.
remove_blocks		Delete blocks and every link touching them, as one undo entry.
connect		Link two blocks so entities flow from source to target, optionally with a transfer delay.
disconnect		Remove one link.
reorder_branches		Set the branch order of a block's outgoing links.
set_resources		REPLACE the model's whole resource table.
set_calendar		Give the model REAL DATES, or remove them.
set_entity_types		REPLACE the model's entity-type table.
set_simulation_settings		Set the model's default run settings; only the arguments you pass change.
set_sd_settings		Turn on the system-dynamics step grid, change it, or remove it (dt null).
auto_layout		Lay the model's blocks out left to right in a deterministic layered arrangement, one undo entry.

records

Tool	Reads	What it does
get_record_schema	yes	The JSON Schema of one record of section: what upsert_record expects.
list_records	yes	List every record of one section of the model, as stored.
upsert_record		Add a record to a section, or REPLACE the one with the same key.
remove_record		Delete one record.
upsert_table_from_csv		Read a CSV under the workspace root into a lookup table.
list_continuous	yes	List the model's time-series inputs, levels and flows in one answer.
upsert_timeseries_input_from_csv		Read a time,value CSV under the workspace root into a time-series input.
get_network	yes	The model's path network: the nodes assets sit on and the segments vehicles and walkers drive along, with the shortest-path distance between every pair of places.
upsert_node		Add a network node, or move the one with this name.
remove_node		Delete a network node AND the segments that used it (a segment with a dangling end is not a thing a model can mean).
upsert_segment		Add a drivable segment between two nodes, or replace the one already joining that ordered pair.
remove_segment		Delete one segment.
get_distance	yes	Shortest path between two places on the model's network.
list_sequences	yes	List the model's routing sequences and the stations they visit.
list_orders	yes	List the model's orders: released jobs with a due date.
upsert_orders_from_csv		REPLACE (or extend) the model's orders from a CSV release list.
upsert_scenario		Add or update a named scenario: a set of parameter overrides applied to the base model before a run.

runs

Tool	Reads	What it does
run_model		Run a model and return a COMPACT KPI digest -- never the raw frames.
get_kpi_table	yes	Page through one results frame of the last run_model for this model.
run_scenarios		Run the model's scenarios and compare them against the baseline with confidence intervals and a significance verdict.
investment_case		Run the model's scenarios and price each against the baseline: extra capex, saving per year, payback, NPV and ROI over the investment section's horizon, with confidence intervals from several replications.
run_to_precision		Keep adding replications until one KPI's confidence interval is narrow enough, then report how many it took.
run_reality_checks		Run the model's Vensim-style reality checks: an input imposed on the model (e.g.
run_loop_dominance		Which feedback loop drives an SD model's behaviour, and when (Loops That Matter, as in Stella).
suggest_warmup		Estimate how much of the run to discard as warm-up, using MSER-5 on the throughput-time series.
optimize		Search model parameters for the best value of one KPI within a replication budget, then confirm the winner statistically.
calibrate		Tune model parameters until the model reproduces measured KPIs.
forecast		Forecast a short horizon from the model's CURRENT state, with uncertainty bands and event probabilities.
export		Write the last run's results to a file: an Excel workbook, CSV folder, a self-contained HTML report, or JSON.
evaluate_policy		Evaluate a built-in controller against a Policy-mode DECIDE.
fit_surrogate		Run a design of experiments and fit a response-surface surrogate over it -- a fast stand-in for the simulation, for optimisation or what-if exploration without spending more replications.

data

Tool	Reads	What it does
resolve_data_bindings		Read the model's data bindings and report what each one produced.
set_initial_state		Give the model a WARM START: work already in the system at t=0.
fit_distribution	yes	Fit candidate distributions to observed data and rank them, so a block's duration comes from measurements instead of a guess.
get_plant_timeline	yes	Check a plant mapping against a model and, given a recorded plant log, say what the plant looked like at the log's last instant.
get_twin_monitor	yes	What the plant looks like now, as the running twin last wrote it.
get_twin_forecast	yes	The running twin's latest forecast, and how its earlier ones compare with what the plant then did.
get_twin_recommendations	yes	What the running twin recommends now, and what became of what it recommended before.

reference

Tool	Reads	What it does
list_block_types	yes	List every block type this build can place in a model, with a one-line summary and its required parameters.
describe_block_type	yes	Describe one block type: what it does and every parameter with its type, default and meaning.
list_distributions	yes	List the distribution names available for a duration or a random draw.
describe_distribution	yes	Describe one distribution: when to use it and what each parameter means.
get_expression_help	yes	Explain the expression language used by ASSIGN, DECIDE/HOLD conditions, RECORD, ranking expressions and expression-valued distribution parameters.
validate_model	yes	Validate a model and return every problem with a stable code, a JSON-pointer path, and a hint saying how to fix it.

wholemodel

Tool	Reads	What it does
get_model_format	yes	What a model file holds, compactly: call it ONCE before write_model.
write_model		Write a WHOLE model in one call: the complete model file as one JSON object.

debug

Tool	Reads	What it does
debug_run		Run one replication of a model under a debugger: start it, or continue it, until a stop, one step, a model time, a pending decision or the end.
debug_inspect	yes	Read the state of a model's debug run where it stands, without moving it.