Open an existing .nlogo model file.

Execute a NetLogo command (e.g. 'setup', 'go', 'create-turtles 10').

Evaluate a NetLogo reporter expression and return its value.

Run the simulation for N ticks and collect reporter data each tick.

Run the simulation SLOWLY so a human can watch it in the GUI window.

Unlike run_simulation (full speed, returns data), this steps go once per tick with a pause between steps — use it for demos and teaching when the user wants to see the dynamics unfold live. In headless mode it works but there's nothing to watch; prefer run_simulation there.

Set a NetLogo global variable / slider / switch value.

Get the current world state: tick count, agent counts, world dimensions.

Returns JSON with ticks, turtle/patch/link counts, and world bounds.

Get patch data as a 2D grid (useful for heatmaps / spatial analysis).

Return a sample of agents with selected variables as a markdown table.

Filling the gap between get_world_state (aggregates only) and hand-crafted report calls. Picks N random agents from the named breed (or all turtles when breed is None) and reports the requested per-agent attributes.

Export the current NetLogo view as a PNG image.

Returns the image so Claude can see the model visualization.

Create a new NetLogo model from code and load it.

Update the currently loaded model's code in place and reload it.

Prefer this over create_model when iterating on an existing model: the same .nlogox file is rewritten and reloaded, so the NetLogo window stays on one model and the models directory doesn't grow a new file per iteration.

List all .nlogo model files in the configured models directory.

Returns a JSON array of {name, path, size_kb} objects.

Save NetLogo model code to a .nlogox file in the models directory.

This saves the model so you can open it in the NetLogo desktop app for live visualization with GUI, sliders, and real-time animation.

Export the full world state to a CSV file.

Saves all turtle, patch, and link data. Useful for checkpointing a simulation or analyzing the complete state offline.

Returns the path to the exported CSV file.

Unload the currently loaded model and reset the workspace.

Useful when you want to discard pending state (mid-run agents, set parameters, pending plots) and start fresh, or before opening a new model file from disk to make sure cached compilation state isn't carried forward.

Note: this does NOT shut down the JVM or NetLogo workspace — only the model. The next open_model / create_model call will reuse the same JVM (no 30-60s warmup).

Return a snapshot of the running NetLogo MCP server's configuration.

Useful as a no-cost health check for the AI / user — returns the server version, configured paths, GUI mode, currently-loaded model, and whether a NetLogo headless launcher is reachable for BehaviorSpace runs.

No JVM round-trip; this is a pure config / filesystem inspection so it works even before the workspace is fully initialized.

Search the CoMSES Net computational model library.

Get detailed metadata for a specific CoMSES model.

Download and safely extract a COMSES model archive.

Standalone "fetch but don't open" tool. Most AI flows should use open_comses_model instead — it subsumes this tool and also loads NetLogo models into the workspace.

Safety guarantees:

• version="latest" is resolved to a concrete version BEFORE any cache path is computed. Cache dirs are named by the resolved version.

• HEAD request screens oversize archives before streaming.

• Stream enforces the byte cap mid-download; overruns abort and delete the partial file.

• Zip members are validated against path traversal before extraction.

• Uncompressed total is checked against 2 × cap to reject zip bombs.

• Extract happens in a temp directory; only a successful extract is moved atomically into the cache. A .comses_complete marker is written on success; future calls only trust cached dirs with the marker.

Download (or reuse cache), then open a COMSES model ready to use.

This is the single entry point most AI flows should call.

Behavior:

• Resolves "latest" to a concrete version BEFORE any cache path is computed. The returned resolved_version is what every follow-up read_comses_files call MUST pass — never re-pass "latest" in the same flow, or you risk inspecting a different cache slot than the model you just loaded.

• If the cache for (identifier, resolved_version) is already complete (has .comses_complete), skips download.

• Otherwise, downloads + extracts safely (same logic as download_comses_model).

• If the model is NetLogo, picks one .nlogo / .nlogox per Section 4.4 rules (exactly one → use it; else prefer code/; else prefer .nlogox; else lex-largest relative path — a deterministic tie-breaker, NOT semver-aware).

• If NetLogo, loads it into the workspace.

• If not NetLogo, returns structured info for manual follow-up.

Returns JSON with:

• status: "loaded_netlogo", "not_runnable_in_netlogo", or "no_netlogo_file".

• resolved_version: concrete version string (never "latest").

• identifier, title, language, license, cached.

• extracted_path: absolute path to cached model directory.

• all_netlogo_files: list of every NetLogo file found.

• loaded_netlogo_file: the one selected (if any).

• code_files: source files by extension.

• odd_doc: ODD / README path, if any.

• message: short text for the AI to show the user.

Return text contents of source and documentation files from a downloaded COMSES model.

The model MUST already be downloaded by open_comses_model or download_comses_model. If the cache is absent, this tool returns an error telling the AI to call one of those first.

The AI should pass the resolved_version it captured from open_comses_model — not the literal string "latest" — or it risks inspecting a different cache slot than the model it just loaded. When version="latest" is passed, this tool calls the COMSES API to resolve it (so it works standalone) and surfaces the concrete version in the resolved_version field of the response.

Behavior:

• Files are UTF-8 decoded with errors="replace" so binary junk never aborts the call. Every file that matches extensions is returned as a string (may contain replacement characters for non-text bytes).

• Files are included in priority order: ODD docs → NetLogo source → other code → other .md/.txt → everything else matching extensions.

• Total body is capped at max_total_bytes (default 50 KB — sized to fit in a single conversational-LLM tool response). When the cap is hit mid-file, that file is truncated at a line boundary; subsequent files are listed in omitted_files with reason byte_cap_reached. For larger pulls, pass a higher value explicitly.

• Files matching no extensions filter are listed in omitted_files with reason extension_not_in_filter.

List BehaviorSpace experiments saved inside a NetLogo model file.

Reads the <experiments> section of a .nlogox (or .nlogo) without starting a JVM, so it's instant. By default it inspects the model the AI most recently loaded; pass model_path to inspect a specific file.

Returns JSON: {"model_path": ..., "experiments": [<spec>...]} where each spec includes name, repetitions, time_limit, setup_commands, go_commands, metrics, variables (with expanded_size per variable), and total_runs. An empty list means the file has no saved experiments — you can still pass an inline spec to run_experiment.

Show the run plan for a BehaviorSpace experiment WITHOUT executing it.

Use this before run_experiment to verify the parameter combinations, total runs, and rough time estimate. Two modes:

• By name: pass experiment_name (must match a saved experiment in the model file). The other args are ignored.

• Inline: omit experiment_name and pass metrics + (optionally) variables, repetitions, time_limit, setup_commands, go_commands, stop_condition.

Returns JSON with the resolved spec, total_runs, and a coarse estimated_seconds_lower_bound derived from time_limit × total_runs assuming roughly 1k ticks/s per run (real models are usually slower).

Run a BehaviorSpace experiment headlessly and return summarized results.

Two ways to specify the experiment:

• By name — pass experiment_name matching a saved experiment in the loaded model (.nlogox <experiments> section). All other experiment-shape args are ignored.

• Inline — omit experiment_name. Required: metrics. Optional: variables (list of {"name", "values"} or {"name", "first", "step", "last"}), repetitions, time_limit, setup_commands, go_commands, stop_condition.

Variable shapes (Cartesian product of all expanded values is run for each repetition)::

[{"name": "density", "values": [50, 60, 70]},
 {"name": "growth-rate", "first": 0.1, "step": 0.05, "last": 0.3}]

Long-run controls: - max_total_runs — refuse to start if total_runs exceeds this. - timeout_seconds — kill the launcher after this many seconds. Partial results in the table CSV are preserved. - threads — parallel runs (0 = let NetLogo decide; default ~75% of CPUs).

The launcher runs in a SEPARATE JVM, so the GUI workspace this server is hosting is unaffected. Run before calling this only matters insofar as the model file must be saved on disk (it is, after open_model / create_model / open_comses_model).

Returns JSON with: output_csv, runs, metrics_summary, per_combination, duration_seconds, command, timed_out. The full per-tick data is in output_csv for offline analysis.

Generate and save a synthetic audience from a YAML spec.

The audience is a frozen, seeded population of personas plus a social network — the same spec always produces the same people, so campaign variants can be tested against an identical audience.

List saved synthetic audiences.

Show a saved audience: spec summary, archetypes, and sample persona cards.

Create and save a campaign (one audience x one or more ad/email variants).

List saved campaigns.

Run a saved campaign against its audience and log every reaction.

Runs every variant x replicate with a PAIRED design (identical audience, reach and network randomness per replicate across variants), so A/B differences are attributable to the creative.

Cognition: personas react via the configured backend — a live local LLM when SYNTH_LLM_MODE=live (Ollama etc.), otherwise the deterministic heuristic model.

Generate the pre-flight report for a campaign that has been run.

Includes: funnel with confidence intervals (simulated / calibrated / industry benchmark), segment breakdown, top objections with verbatim quotes, word-of-mouth stats, weak-point diagnosis, and the A/B verdict. Also writes an HTML version with interactive charts.

Paired A/B comparison of a campaign's variants (winner, lift, significance). Subset of get_campaign_report for quick checks.

Ask a follow-up question to persona(s) — an on-demand focus group.

Calibrate simulated funnel rates to real-world levels.

Two modes:

• With csv_path: fit against a REAL past campaign's stats. The CSV needs columns sent, opened, clicked, converted (one or more rows). Requires campaign_name for the simulated side of the fit.

• Without csv_path: anchor the campaign's simulated rates to industry benchmark base rates (a sane default until you have real data).

After calibrating, get_campaign_report shows a calibrated column.

Status of the market-simulation module: LLM config, saved audiences, campaigns, and where artifacts live.