Raptor Studio

List the tables that can be read or exported. Two groups: **Inputs** (the model's data: blocks, nodes, events, hierarchies, links, spare pools, resources, triggers, phases, system settings) and **Results** (a run's report sections, per-run figures and capacity samples). Pass `run_id` (from `simulate`) to include a run's result tables; without it only the inputs are listed and the result tables are shown as unavailable. Returns {tables: [{key, title, group, rows, available, reason, default}]}. `key` is what `get_table` and `export_tables` take, e.g. 'inputs.blocks' or 'results.summary'. `default` is false for the long ones (event log, end-of-run report, interim cost, all block columns).

Manage the model's named Rates library. action: 'list', 'add', 'update' or 'delete'. `expr` is an expression like "0.00015 * 20000 / 8760 # failure rate". Rates can then be referenced in any numeric field as `@RateName * k`, which keeps the derivation in the model's `formulas`. Returns {rates} for 'list', else the affected entry.

Create, list, edit or delete a resource pool (shared crew/equipment). Resources are what a block's `resource_name` points at and what `configure_sparing(mode="resource")` consumes. `action='delete'` refuses while a block still names the resource. Fields match the `inputs.resources` table: `num_in`, `spare_cost`, `fixed_per_use`, `per_time_unit`, `phases`.

Create, list, edit or delete a spare pool. action='list' returns every pool. `action='add'` needs `name`; `action='update'` patches only the fields you pass; `action='delete'` refuses while a block still has Pooled sparing that names the pool. These are the pools `configure_sparing(mode="pool")` draws from, with the stock and lead-time quantities spares planning needs. Field names match the `inputs.spare_pools` table and the .rbds `spare_pools` entries: `stock`, `new_spares`, `arrive_every` (restock interval, h), `eso`, `emer_time` (emergency shipping, h), `slo`, `level`, `quantity`, `slo_time`, `rso`, `spare_cost`, `emer_ship_cost`. The pool's own `stock` is what governs a Pooled block; the block's `stock` field is only used by Custom sparing.

Create, list, edit or delete a trigger (for triggered PM). `dist` takes a name ("Normal") or a code; `params` its parameters. A block's PM can only name a trigger that exists, so add it here first. Deleting is refused while a block's PM still names it.

Move a block, node, event or hierarchy to another hierarchy level. `parent=0` moves it back to the top level; otherwise pass a hierarchy id. `update_element` refuses `parent` because it is structural, and the only alternative used to be deleting and recreating the element (losing its links, sparing and PM settings). A hierarchy cannot be moved into itself or one of its own descendants.

Copy a model file into the workspace and return its handle. The original file is never mutated. Accepts a .rbds or .rbd path **relative to the workspace** (or an `--allow-read` directory), or a bundled example name like 'MotorDemo'. Absolute paths are refused, as are paths outside those roots, so the MCP boundary cannot read arbitrary files. Returns {model_id, summary}. Allowed under --read-only (it never changes the source file).

Health-check: returns 'pong' if the server is running.

Read a documentation source as text (paginated). `name` is 'rbds' (the `.rbds` format guide), 'rbds-schema' (its JSON Schema; open_model, build_model and validate_model check files against it), 'dependency' (the dependency tutorial chapter), 'mcp-guide' (this MCP chapter), a tutorial chapter stem like 'ch11-capacity', a chapter title fragment, or a path under `docs/` or `new_docs/`. `offset`/ `limit` page the lines (limit <= 400). Returns {name, file, total_lines, offset, next_offset, text}.

Step one edit forward again after `undo_last_edit` (multi-step). Fails with a clear error once there's nothing left to redo, or once a new edit has cleared the redo history.

Render the model diagram as a PNG image. `level` is a **hierarchy id**, not a depth index: 0 renders the whole model (home level); to render inside a hierarchy pass its id, e.g. the hierarchy `id=900` is `level=900` (read hierarchy ids from `describe_model`). Passing `1`/`2` is a common mistake and reports the available ids. `zoom_to` frames a **close-up** on one or more named/id'd elements (block/node/event/hierarchy) **within the current `level`** (it does not change which level is shown), padded by `margin` scene units — the way to render a large model legibly in sections. A selector is a name, a bare id, or `"Kind:id"` (e.g. `"Block:3"`); a selector that matches nothing, or a bare id matching two element kinds, is an error. The structured result carries `px_per_unit`, `effective_label_px` and `legible` (a heuristic: `effective_label_px >= 7`), so a caller can tell whether the text is readable and zoom in further if not. Returns image content plus structured {width, height, elements_drawn, elements_in_view, px_per_unit, effective_label_px, legible, png_path, resource_link}. `highlight` outlines named elements (e.g. the single points of failure). `theme` is 'light' or 'dark'. `include_annotations` draws the model's text/rect/ellipse/arrow annotations (default true). This is the only RAPTOR tool that returns a picture: results are always Markdown/data. The PNG is capped at 1600 px on the long edge and is also written to renders/ in the workspace.

Draw one level of the diagram as SVG text, without Qt. For checking layout, connections and annotations when `render_diagram` (a PNG of the GUI canvas) is unavailable, or when SVG text is easier to read than an image. It draws blocks, nodes (S/E, HI/HO, k/n), events, hierarchy ovals, links with arrowheads and annotations at the GUI's scene positions; it does not measure fonts (long names are shortened, the full name is in each element's `<title>`) or show state colours. `level` is 0 for the top level or a **hierarchy id** (not a depth). `zoom_to` frames the named elements on that level, padded by `margin` scene units; `highlight` outlines them. A selector is a name, a bare id or `"Kind:id"`. Returns the SVG in the text result (up to 200 KB; larger drawings are only written to the file) and structured {svg_path, width, height, elements_drawn, elements_in_view, links_drawn, annotations_drawn, highlighted, inline}. The file is written to renders/ in the workspace.

Progress of a job started with `start_run`. Returns {job_id, model_id, state, phase, setup, completed_runs, requested_runs, percent, elapsed_s, wall_seconds, run_id, summary, error}. `state` is queued, running, done, cancelled or failed. `phase` adds what a running job is doing: `setting_up` while a large model is prepared (`setup` then has `{stage, done, total, percent}`; it can take minutes before the first replication, and `completed_runs` stays 0), then `simulating`. Small models skip straight to `simulating` and `setup` is null. `run_id` is set once the batch has produced a run, and `summary` then carries the mean of each metric. Jobs are in-process only -- after a server restart the run is still in the workspace, the job id is not.

Save a model to a file path. The path must be inside the workspace or an --allow-write directory. format: 'rbds' (default) or 'rbd'. If `path` has **no extension** the format's own extension is appended (so `"out"` -> `out.rbds`). An explicit extension must match `format`; a mismatch or a path into the managed models/runs/renders trees is refused. A .rbd export runs validate() first and refuses on ERROR. The layout is saved as it is; `layout_warning` says when Raptor 7 would draw elements overlapping (call `auto_layout` first to space them out).

Search the RAPTOR tutorial docs for passages matching a query. Multi-word queries match passages containing **all** terms (so "capacity analysis system capacity" finds the capacity passages, not nothing). Returns {results}, each {chapter, file, anchor, text, score}. Use `read_doc` to read a whole document.

Run a simulation and return structured results. `hierarchy` (a name or id) runs just that hierarchy on its own, its input always available -- useful for checking part of a model. This is a port extension, not a Raptor feature: the result carries an `isolation` object (hazards at the boundary, the treatment applied to each) and must not be read as a whole-model figure. `treatments` is `{deps: up|system| refuse, pools: full|share|refuse, streams: keep|separate, items: {...}}`; call `extract_hierarchy` with `report_only` first to see the hazards. Long runs send MCP progress notifications about once a second and can be cancelled by the client (the engine stops between replications). Returns {run_id, model_id, model_hash, runs, requested_runs, truncated, wall_seconds, summary, warnings, caveats}; `summary` has each metric with min/mean/max/stdev/sem. With capacity analysis on, `summary` adds Units_Produced, Mean_Flow, Mean_Capacity, Capacity_Weighted_Availability (Mean_Flow / FlowGenerated: the delivered fraction, where Availability only means some flow got through) and Lost_Flow. `caveats` is the model-validation subset of `warnings` (surfaced separately so a client can show them first). The Markdown body is a table with units in the headers. The model is **validated first**; structural errors are returned with the issue list instead of running. The run is estimated first and refused with a clear message if the estimate exceeds `timeout_s`, unless `confirm_long_run=true`. `workers > 1` is faster but not bit-identical to a sequential batch. Leave `workers` out and a large model (500+ blocks, events and nodes) run 20+ times uses several cores (half the machine's, at most 8); the result reports the `workers` used and `workers_auto`. Pass `workers=1` for the sequential numbers. This is a server default only: the desktop app and the command line are unchanged. `seed` (optional, non-negative) re-rolls the batch reproducibly; leaving it unset keeps the engine's fixed…

Find single-point failures in the model. A single point failure is an element whose failure alone takes the system down, found as Raptor does (by failing each element in Failure Effects View, so dependencies and cold standby count). Returns {spofs, count, total, offset, next_offset, elapsed_seconds, cached}; each spof is {kind, id, name, crit} plus `phase` for a phased model. `limit` pages the response (default 100, use 0 for all); the full row set is still computed and cached by model content, so later pages and repeated calls are instant. `workers > 1` parallelises the candidate tests on an unphased model.

Start a simulation in the background and return a job id immediately. Same arguments as `simulate`, minus the hierarchy/isolation and importance options. Use this for batches that outlive one tool call (a 100-replication, 20-year run is tens of minutes): the engine runs on a daemon thread, `run_status` reports progress, `cancel_run` stops it between replications, and the completed run is an ordinary workspace run (`run_id`) whose results `get_run_results`, `get_table` and `get_report` can read. The model is validated and the batch size checked *before* the job starts, so a structural error is reported here rather than asynchronously. `workers` defaults as it does for `simulate`: a large model run 20+ times uses several cores unless you pass `workers=1`. Returns {job_id, state, phase, setup, requested_runs, ...}. `run_status` shows `phase` (`setting_up` while a big model is being prepared, then `simulating`) and `setup` progress, so a long quiet start is not a hang.

Sweep a parameter across values and measure the impact. Works on copies — the original model is untouched. `field` may be a friendly field or an indexed form like `repair_params[0]`. Each row carries the `run_id` and the `runs` count that produced it. Returns {rows, monotonic, all_rows_identical, warnings} plus a Markdown table; `all_rows_identical` is true when every row's metrics are bit-identical (which cannot be told apart from "the value was never applied"), and `warnings` says so. `monotonic` looks at the first swept metric and treats a flat or single-row series as monotonic; `all_rows_identical` needs at least two rows. Concurrent sweeps are serialised, so two in one batch both succeed.

Step one edit back (multi-step: call again to go further back). Every edit tool backs up the prior state first (up to 20 deep), so repeated calls walk further back rather than repeating the same restore. Each undo can itself be undone with `redo_last_edit`, until a new edit is made -- which clears the redo history, same as any other editor.

Patch one annotation. Accepts any style field, `text`, explicit geometry (`x`/`y`/`w`/`h`/ `x1`/`y1`/`x2`/`y2`, in scene pixels or with `"units": "model"`), or an anchor via `adjacent_to`/`location`/`gap` (text/rect/ellipse) or `from_`/`to` (arrow). Re-anchoring to another annotation uses `adjacent_to="Annotation:<id>"` (or its unique label). Moving an anchored annotation by coordinates removes its anchor, as dragging it in the GUI does; `"anchor": null` removes it and leaves the annotation where it is. Returns {annotation_id, annotation, summary}.

Update fields on an element. `selector` is an element name, 'Block:N' / 'Node:N' / 'Event:N', a link ('Link:N', which carries capacity: `nom_flow`, `max_flow`, `cap_pri`), or an auxiliary row by name ('Pool:RackSpares', 'Resource:Crew', 'Trigger:Storm', 'Phase:Summer' -- the bare name works too). `patch` accepts any friendly .rbds field (e.g. `fail_params`, `pm_freq`, pool `stock`) or a raw column name, including indexed forms like `repair_params[0]`. `fail_dist`/`repair_dist` take a distribution name ("Weibull") or a code. To make a block dependent on another element use `dep_type` (RBDBlock/RBDNode/RBDEvent/RBDHier), `dep_num` (the target's id; -1 = own node, -2 = whole system) and the effect split `dep_nothing`/`dep_idle`/`dep_pm`/`dep_fail` (percent); read it back with `get_element`. Numeric fields may be numbers OR expression strings such as "50.0 + @Rate * 1.4 # basis"; expressions are resolved to a float and their derivation is kept in the model's `formulas`. Returns {changed, warnings, element} where `element` is a compact {id, name, kind} summary; pass full=true for every field of the element. A value RAPTOR Studio's dialogs refuse (a PM stagger at or above the PM frequency, a cost below 0, a name with a space, ...) is refused with RAPTOR Studio's own message and the model is left unchanged. A problem the model already had (a file written elsewhere) does not block other edits.

Update many elements with one save. Same `selector` and `patch` semantics as `update_element`, but the whole list is applied inside one workspace batch: the model is written once at the end instead of once per element. On a large model this is the difference between seconds and tens of minutes (one `update_element` on a ~10k-element model costs ~10 s). The batch is atomic: if any item is refused, the model is restored to its state before the call and nothing is written. Returns {updated, results: [{selector, id, name, kind, changed}]}.

Validate a model for structural and parameter errors. Returns {errors, warnings, groups, runnable}. `groups` collapses the same rule firing on many elements into one row (rule, count, example elements), which is what makes a 700-error model readable; `errors` and `warnings` keep the verbatim per-element list. Always call this before a run.

Return the server workspace root and read/write rules. Learn where models/runs/renders live and which directories `save_model_as` may write to (the workspace plus any `--allow-write` dirs) and `open_model` may read from (the workspace, examples and any `--allow-read` dirs). Relative save paths resolve against the workspace root.