The Stella MCP Server enables AI assistants to programmatically create, read, modify, validate, and save Stella system dynamics models (.stmx files in XMILE format) via the Model Context Protocol.
Model I/O: Create new models with custom time settings, load existing .stmx files, and save models to disk.
Model Building: Add stocks, flows, auxiliary variables, and connectors; supports graphical functions (lookup tables) and automatic positioning.
Variable Management: Rename and delete variables with consistency checks (updates references in equations, connectors, and modules).
Module Management: Create, rename, delete, and style modules/groups; assign member variables and auto-place boxes.
Model Inspection: List variables, modules, and connectors; preview raw XMILE XML output.
Validation: Check for undefined variables, mass balance issues, missing connections, orphan flows, circular dependencies, and module integrity.
Templates: List, inspect, load, and save reusable built-in or user-defined templates.
Multi-Model Sessions: Manage multiple models concurrently via an optional model_id parameter.
Compatibility Modes: Read, save, and export with permissive or strict XMILE compatibility checks.
Connector Routing: Set connector angles and waypoints.
Error Handling: Structured errors with codes, categories, and messages.
Enables the creation, reading, and validation of Stella system dynamics models by programmatically generating and parsing XMILE-compliant XML files.
Click on "Install 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., "@Stella MCP Server create a population model with a 5% growth rate starting at 100 people"
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.
A vendor-neutral Model Context Protocol (MCP)
server for creating and manipulating Stella
system dynamics models. Any compliant MCP client can build, read, validate, and
save .stmx files in the XMILE format; optional host features still vary.
Stella is a system dynamics modeling tool used for simulating complex systems in fields like ecology, biogeochemistry, economics, and engineering. This MCP server allows AI assistants to:
Create models from scratch - Build stock-and-flow diagrams programmatically
Read existing models - Parse and understand .stmx files
Validate models - Check for errors like undefined variables or missing connections
Modify models - Add stocks, flows, auxiliaries, and connectors
Save models - Export valid XMILE files that open in Stella Professional
This is particularly useful for:
Teaching system dynamics modeling
Rapid prototyping of models through natural language
Batch creation or modification of models
Documenting and explaining existing models
Related MCP server: OpenKer Modeler MCP Server
pip install stella-mcpgit clone https://github.com/bradleylab/stella-mcp.git
cd stella-mcp
pip install -e .Python 3.10+
mcp>=2.0.0,<3
If you have uv installed, the lowest-friction configuration runs the published package directly:
{
"mcpServers": {
"stella": {
"command": "uvx",
"args": ["stella-mcp"]
}
}
}Add to your claude_desktop_config.json:
{
"mcpServers": {
"stella": {
"command": "stella-mcp"
}
}
}Add to your .claude/settings.json:
{
"mcpServers": {
"stella": {
"command": "stella-mcp"
}
}
}If running from source:
{
"mcpServers": {
"stella": {
"command": "python",
"args": ["-m", "stella_mcp.server"],
"cwd": "/path/to/stella-mcp"
}
}
}For a new model:
On MCP 2026-07-28, call create_workspace and carry the returned
workspace_id through stateful calls. Legacy stdio clients may omit it.
build_model with a stable model_id and the full set of stocks,
auxiliaries, and flows in one call (connector sync and validation run by
default, so the response doubles as an inspection).
Fix validation errors with update_*, rename_variable, or delete_variable.
Extend incrementally with add_variables (batch) or the single-add tools.
simulate to sanity-check behavior (requires the sim extra).
Save with save_model.
For imported models:
read_model with compat_mode="permissive" to inspect warnings.
Run inspect_model to understand model structure.
Use compat_mode="strict" before final save when round-trip fidelity matters.
Tool | Description |
| Create a new model with name and time settings (start, stop, dt, method) |
| Update simulation time settings on an existing model |
| Load an existing .stmx file |
| Save model to a .stmx file |
| Remove a model from the workspace (saved files untouched) |
Tool | Description |
| List built-in and user-defined templates (supports source/query/tag filters) |
| Get detailed metadata for one template |
| Load a template as a model in the current workspace |
| Save the current model as a reusable user template (optional description/tags) |
Tool | Description |
| Create and populate a model in one call (atomic batch) |
| Add multiple variables/connectors/modules to an existing model (atomic batch) |
| Add a stock (reservoir) with initial value and units |
| Add a flow between stocks with an equation |
| Add an auxiliary variable (parameter or calculation) |
| Update stock fields while preserving relationships |
| Update flow fields while preserving stock links |
| Update auxiliary variable fields |
| Add a dependency connector between variables |
| Add missing dependency connectors inferred from equations |
| Set connector angle and explicit waypoint routing metadata |
| Rename a stock/flow/aux and update references in equations/connectors/modules |
| Delete a stock/flow/aux with consistency checks and cleanup |
| Create a logical module/group of variables |
| Add variables to an existing module/group |
| Remove variables from a module/group |
| Rename a module/group |
| Delete a module/group |
| Set explicit module box position/size on the diagram |
| Set module box style (border/background/font/label side) on the diagram |
| Auto-place module boxes around their members |
Notes:
MCP 2026-07-28 clients call create_workspace once and include its returned
workspace_id in stateful calls. Modern tool discovery marks that field as
required on stateful tools. The ID routes application state; it is not an
authorization credential.
Supported legacy stdio clients may omit workspace_id and use one
process-local compatibility workspace; legacy discovery keeps the field
optional.
Tools accept optional model_id so one workspace can manage multiple models safely.
create_model and read_model set the workspace's current model_id and return it.
add_flow and add_aux support optional graphical_function payloads (ypts plus exactly one of xscale or xpts).
add_stock/add_flow/add_aux reject duplicate variable names across variable types; add_connector requires both variables to exist.
set_connector_routing can target a connector by connector_uid or by from_var + to_var.
save_model and get_model_xml accept auto_layout (default true) and resolve_layout_violations (default false).
save_model, get_model_xml, and render_diagram return the latest layout
viewport, metrics, and warnings in structured content. Their text result names
any non-clean layout warning codes.
read_model, save_model, and get_model_xml accept compat_mode:
permissive (default): continue with warnings
strict: fail on compatibility issues
set_module_style updates module view styling and persists those attributes in XMILE view <group .../> elements.
save_as_template writes user templates to ~/.stella-mcp/templates by default (override via STELLA_MCP_TEMPLATE_DIR) and stores metadata in a .meta.json sidecar.
Tool failures return structured MCP errors with error.code, error.category, and error.message.
Every successful tool result retains readable text and supplies schema-validated
structuredContent described by its JSON Schema 2020-12 outputSchema.
Tool | Description |
| Create an isolated workspace, optionally with a caller-selected lifetime |
| Revoke a workspace and discard its in-memory models |
Tool | Description |
| List available workspace model IDs and indicate the current model |
| Return a structured model summary for agent inspection |
| List modules/groups in the current model |
| List connector IDs, endpoints, angles, and routing metadata |
| List all stocks, flows, and auxiliaries |
| Check for errors (undefined variables, missing connections, etc.) |
| Preview the XMILE XML output |
| Render the model as an SVG stock-and-flow diagram |
| Run the model via PySD and return time series + summaries ( |
| Run named what-if override sets against a baseline and report deltas ( |
| Sweep parameters one-at-a-time and rank their effect on an output metric ( |
| Fit constant parameters to an observed time-series (inverse of simulate) ( |
build_model creates and populates a model in one call. Items apply in the
order stocks → auxs → flows → connectors → modules; the whole batch is
all-or-nothing, and on failure the error names the failing item
(error.stage + error.index). The same item arrays work on an existing
model via add_variables.
{
"name": "build_model",
"arguments": {
"name": "SIR",
"model_id": "sir",
"sim_specs": {"start": 0, "stop": 100, "dt": 0.125, "time_units": "Days"},
"stocks": [
{"name": "Susceptible", "initial_value": "9999", "units": "people"},
{"name": "Infected", "initial_value": "1", "units": "people"},
{"name": "Recovered", "initial_value": "0", "units": "people"}
],
"auxs": [
{"name": "contact_rate", "equation": "6"},
{"name": "infectivity", "equation": "0.25"},
{"name": "recovery_time", "equation": "2", "units": "days"},
{"name": "total_population", "equation": "Susceptible + Infected + Recovered"}
],
"flows": [
{"name": "infection", "equation": "Susceptible * contact_rate * infectivity * Infected / total_population", "from_stock": "Susceptible", "to_stock": "Infected"},
{"name": "recovery", "equation": "Infected / recovery_time", "from_stock": "Infected", "to_stock": "Recovered"}
],
"modules": [
{"name": "Disease Dynamics", "members": ["Susceptible", "Infected", "Recovered"]}
]
}
}Connector sync and validation run by default (disable with
"sync_connectors": false / "validate": false); the response includes the
full structured model summary, so no follow-up inspect_model call is needed.
Create and switch between workspace models:
{"name":"create_model","arguments":{"name":"Population","model_id":"pop_v1"}}{"name":"create_model","arguments":{"name":"Carbon","model_id":"carbon_v1"}}{"name":"list_models","arguments":{}}{"name":"delete_model","arguments":{"model_id":"pop_v1"}}{"name":"inspect_model","arguments":{"model_id":"sir_baseline","include_validation":true}}List and load templates:
{"name":"list_templates","arguments":{}}{"name":"list_templates","arguments":{"source":"builtin","query":"epidem","tags":["epidemiology"]}}{"name":"get_template_info","arguments":{"template_name":"sir"}}{"name":"load_template","arguments":{"template_name":"sir","model_id":"sir_baseline"}}Save current model as a user template:
{"name":"save_as_template","arguments":{"model_id":"pop_v1","template_name":"my_population_template","description":"Baseline single-stock growth starter","tags":["intro","population"]}}Create and manage modules:
{"name":"create_module","arguments":{"model_id":"sir_baseline","name":"Disease Dynamics","members":["Susceptible","Infected","Recovered"]}}{"name":"add_to_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","members":["infection","recovery"]}}{"name":"list_modules","arguments":{"model_id":"sir_baseline"}}{"name":"remove_from_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","members":["recovery"]}}{"name":"rename_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","new_name":"Disease Core"}}{"name":"delete_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Core"}}Rename and delete variables safely:
{"name":"rename_variable","arguments":{"model_id":"sir_baseline","old_name":"population_total","new_name":"total_population"}}{"name":"delete_variable","arguments":{"model_id":"sir_baseline","name":"recovery"}}{"name":"delete_variable","arguments":{"model_id":"sir_baseline","name":"Susceptible","force":true}}Update an existing variable:
{"name":"update_flow","arguments":{"model_id":"pop_v1","name":"growth","equation":"Population * growth_rate * stress_modifier"}}Infer missing connectors from equations:
{"name":"sync_connectors_from_equations","arguments":{"model_id":"pop_v1"}}Set module view geometry directly:
{"name":"set_module_view","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","x":420,"y":280,"width":420,"height":240}}Set module view style:
{"name":"set_module_style","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","border_color":"#666666","background":"#FFF7E6","font_color":"#333333","font_size":"10pt","label_side":"top"}}Auto-place module boxes from current member positions:
{"name":"auto_place_module_boxes","arguments":{"model_id":"sir_baseline","padding":40,"only_missing":true}}Target a specific model in later calls:
{"name":"add_stock","arguments":{"model_id":"pop_v1","name":"Population","initial_value":"100"}}Read with strict compatibility checks:
{"name":"read_model","arguments":{"filepath":"./external_model.stmx","model_id":"imported","compat_mode":"strict"}}Preview XML in permissive mode (default) and return compatibility warnings when present:
{"name":"get_model_xml","arguments":{"model_id":"imported","compat_mode":"permissive"}}Valid graphical function payload:
{
"name": "add_aux",
"arguments": {
"model_id": "pop_v1",
"name": "lookup_rate",
"equation": "GRAPH(Time)",
"graphical_function": {
"xscale": {"min": 0, "max": 100},
"ypts": [0.1, 0.2, 0.4, 0.6],
"type": "continuous"
}
}
}Invalid graphical function payload (rejected):
{
"name": "add_aux",
"arguments": {
"name": "bad_lookup",
"equation": "GRAPH(Time)",
"graphical_function": {
"xscale": {"min": 0, "max": 100},
"xpts": [0, 10, 20, 30],
"ypts": [0.1, 0.2, 0.4, 0.6]
}
}
}User: Create a simple exponential growth model with a population starting at 100
and a growth rate of 0.1 per year
Claude: [Uses create_model, add_stock, add_aux, add_flow, add_connector, save_model]
Creates population_growth.stmx with:
- Stock: Population (initial=100)
- Aux: growth_rate (0.1)
- Flow: growth (Population * growth_rate) into PopulationUser: Read the carbon cycle model and explain what it does
Claude: [Uses read_model, list_variables]
This model has 3 stocks (Atmosphere, Land Biota, Soil) and 6 flows
representing carbon exchange through photosynthesis, respiration...User: Create a two-box ocean model with surface and deep nutrients
Claude: [Uses create_model, add_stock (x4), add_aux (x8), add_flow (x6), save_model]
Creates a model with nutrient cycling between surface and deep ocean
including upwelling, downwelling, biological uptake, and remineralizationThe render_diagram tool renders the model as an SVG stock-and-flow diagram
— stocks as rectangles, auxiliaries as circles, flows as valved pipes
(clouds mark sources/sinks), and dependency connectors as routed polylines. The SVG is
returned inline so an agent can inspect the layout, and optionally written
to a file you can open in any browser. It runs auto-layout first by default,
so a freshly built model renders without manual positioning.
{"name":"render_diagram","arguments":{"model_id":"sir_baseline","filepath":"./sir.svg"}}The diagram below is the built-in sir template rendered by render_diagram
(no manual positioning):
The simulate tool runs the current model and returns downsampled time
series plus per-variable summaries (initial/final/min/max), closing the
build→verify loop without opening Stella. It requires the optional
PySD dependency:
pip install 'stella-mcp[sim]'{"name":"simulate","arguments":{"model_id":"pop_v1","overrides":{"growth_rate":0.05},"include":["Population"],"max_points":50}}Notes and caveats:
PySD integrates with Euler only — models whose method is RK4 simulate
with Euler and the response carries a warning. Every PySD-backed response
identifies the installed PySD version, actual method, declared method,
unsupported-feature preflight, and warnings.
Arrays, compositional module instances, and additional top-level models are
preserved-only in 0.14. They fail before PySD with a structured
unsupported_model_feature error rather than being silently scalarized or
flattened.
PySD and Stella do not have identical output semantics in every supported scalar case. In the retained Lotka-Volterra fixture, Stella caps an outflow to enforce a non-negative stock while PySD reports the uncapped flow equation. The stock trajectories still reach zero together at the next model time.
overrides accepts variable names in display ("growth rate") or
underscore (growth_rate) form and replaces the variable with a constant.
save_results_csv writes the full-resolution results table with a time
column.
The workspace model is never modified by simulation (the run uses a throwaway copy).
The compare_scenarios tool answers "what happens under these alternative
assumptions?" — it runs several named override sets against a baseline (the
unmodified model by default) and reports how each diverges. Also requires the
sim extra.
{"name":"compare_scenarios","arguments":{"model_id":"pop_v1","include":["Population"],"scenarios":[{"name":"low growth","overrides":{"growth_rate":0.02}},{"name":"high growth","overrides":{"growth_rate":0.08}}]}}Each scenario reports its own downsampled series plus delta_vs_baseline per
variable: final_abs, final_pct (percent change of the final value), and
max_abs. Notes:
Every override name across all scenarios is validated before any run, so a typo fails fast and atomically — no scenario runs half-applied.
A scenario whose run produces NaN/inf reports the warning in that scenario's
warnings without aborting the others; final_pct is null when the
baseline final is zero (no divide-by-zero).
baseline is optional — pass an override set to measure deltas against, or
omit it to compare against the unmodified model.
save_comparison_csv writes a wide table with one column per
variable__scenario (and variable__baseline).
The compiled model is reused across every scenario in one call, so a comparison is roughly as cheap as a single simulation plus one run per scenario.
The sensitivity_analysis tool answers "which parameters actually move the
outcome?" — it sweeps each parameter one at a time across a range (holding the
others at their baseline) and reports how a single chosen output metric
responds. Also requires the sim extra.
{"name":"sensitivity_analysis","arguments":{"model_id":"pop_v1","parameters":[{"name":"growth_rate","start":0.02,"stop":0.08,"steps":7}],"output":{"variable":"Population","metric":"final"}}}For each parameter it returns the metric at every swept value, a
range_sensitivity (the metric's average slope across the swept range), and a
baseline-normalized elasticity (≈ Δoutput% / Δparam%) so parameters can be
ranked by influence. Notes:
One-at-a-time only. mode accepts "oat"; full-factorial (grid) and
Monte-Carlo sampling are reserved for a future release.
metric is one of final, max, min, mean, or time_to_threshold
(which needs an output.threshold and reports the first time the series
crosses it). max/min/mean cover finite values only; a non-finite or
never-crossing run reports null for that point with a warning.
A parameter spec is either start/stop/steps (evenly spaced, steps
≥ 2) or an explicit values list (≥ 2 entries).
max_runs (default 200) caps the total swept runs; an oversized sweep
errors rather than silently truncating. OAT runs are a sum across
parameters, not a product, so the cap only trips on genuinely large sweeps.
elasticity is null when it cannot be defined (a non-constant parameter,
or a zero baseline metric/parameter); range_sensitivity is still reported.
save_sweep_csv writes a long parameter, value, metric table.
Like scenario comparison, the model is compiled once and reused across the whole sweep.
The calibrate tool is the inverse of simulate: given an observed
time-series, it fits constant parameters so the model reproduces the data. Also
requires the sim extra.
{"name":"calibrate","arguments":{"model_id":"pop_v1","observations":{"time":[0,2,4,6,8,10],"targets":{"Population":[100,122,149,182,222,271]}},"parameters":[{"name":"growth_rate","initial":0.05,"min":0,"max":0.3}]}}It returns the fitted parameters (each with its bounds, an at_bound flag, and
a linearized std_error), the weighted objective trajectory
(initial/final weighted_sse and weighted_rmse), native-unit error
metrics for each target, optimizer status/configuration, and warnings. Notes:
Only constant auxiliaries and flows are calibratable. Stocks are rejected: PySD's parameter override pins a stock to a constant for the whole run rather than setting its initial value, which would silently flatten a dynamic model. Fitting stock initial conditions is not supported.
Two optimizers. least_squares (default) is local and fast and reports a
std_error; differential_evolution is global, stochastic, seeded for
reproducibility, and requires min/max bounds on every parameter. Its
maxiter generation cap defaults to 100.
Each parameter's initial defaults to the model's current constant value.
Bounds are optional for least_squares, required for differential_evolution.
std_error is a linearized approximation, not a posterior: it is the
covariance σ²·(JᵀJ)⁻¹ and is reported only when there are more observations
than parameters, the Jacobian is well-conditioned, and no parameter sits on a
bound; otherwise it is null with a warning. differential_evolution
returns null (no Jacobian). Under non-default weights, the standard-error
interpretation holds only for inverse-σ weights.
Alignment. The model runs over its native [start, stop] window and the
simulation is linearly interpolated onto the observation times. Observation
times outside the window are rejected (no extrapolation). All targets
share one strictly-increasing time grid; observations are loaded inline or
from a csv_path (first column time, the rest targets).
Optional per-target weights are residual multipliers: the optimizer uses
weight * (simulated - observed). Inverse measurement-standard-deviation
values give normalized residuals. Because weighted errors may mix units,
target_metrics reports an unweighted SSE and RMSE in each target's native
units; no aggregate native-unit RMSE is reported. save_fit_csv writes a long
time, target, observed, fitted table; return_fit_series attaches the
best-fit series. The model is compiled once and reused across the whole fit.
Beyond tools, the server exposes MCP-native affordances:
Tool annotations. Every tool carries hints (readOnlyHint,
destructiveHint, idempotentHint) so clients can manage permissions and
parallelize read-only calls. Inspection tools (inspect_model,
validate_model, list_*, get_model_xml) are read-only; delete_* are
marked destructive.
Resources. Templates and workspace models are readable as resources:
stella://templates/{name} — a built-in or user template's .stmx
stella://workspaces/{workspace_id}/models/{model_id} — an explicit
workspace model's current XMILE export
stella://models/{model_id} — the legacy stdio compatibility workspace only
Prompt. A build-stella-model prompt (argument: description) encodes
the recommended build → validate → simulate → render → save workflow, so it
is discoverable inside MCP clients.
The validate_model tool checks for:
Undefined variables - References to variables that don't exist
Mass balance issues - Stocks without flows, flows referencing non-existent stocks
Missing connections - Equations using variables without connectors (warning)
Connector endpoint integrity - Connectors pointing at missing variables (error)
Orphan flows - Flows not connected to any stock
Circular dependencies - Infinite loops in auxiliary calculations
Module integrity - Empty modules (warning) and modules referencing missing members (error)
Units present - A stock or flow missing units while others define them (warning)
Units consistency - A flow whose units don't read as stock-units/time-unit
when every attached stock shares the same units (warning; conservative —
stays silent on conversion flows and anything it can't confidently parse)
Unused auxiliaries - An auxiliary referenced by no equation or connector (warning); stocks and flows are never flagged
Output files use the XMILE standard
Compatible with Stella Professional 1.9+ and Stella Architect
permissive import/export preserves supported content and the selected
unsupported XML fragments where practical, while returning explicit warnings.
Editing supported variables does not guarantee references inside preserved-only
fragments are updated.
strict import/export rejects arrays, compositional module instances,
additional top-level models, and confirmed Stella/XMILE reserved identifiers.
Arrays and nested models are not implemented features in 0.14.
Reserved names such as beta and gamma are preserved with warnings in
permissive mode and rejected in strict mode. The built-in SIR template uses
transmission_rate and recovery_rate so Stella does not rename them on save.
Auto-layout uses a deterministic directed stock-flow backbone, distinct stock ports, obstacle-aware flow and connector routes, label collision checks, and page-grid sizing from complete visual bounds.
Authored coordinates, including coordinates supplied through update tools, and locked route points remain fixed. Auto-generated coordinates are recomputed on later exports so incrementally extended models can be ranked again instead of freezing after their first save.
Locked paths are reserved before unlocked routes, labels are selected in normalized-name order, and imported view-font sizes control label geometry in both analysis and SVG previews.
Information connectors use direct boundary-to-boundary segments whenever the complete diagram leaves them unobstructed and unshared. Stock-flow pipes stay orthogonal because Stella rewrites diagonal flow segments on save.
Clean planar benchmark layouts have no glyph, label, or route crossings. A
graph that cannot be drawn cleanly is still exported and reports a stable
layout.* warning; zero crossings are not promised for arbitrary non-planar
graphs.
Variable names with spaces are converted to underscores internally
Parser normalizes imported stock inflow/outflow and connector endpoint references
Time-step export avoids lossy reciprocal rounding (non-exact reciprocals are exported as plain dt)
Import/export preserves unknown attrs/elements on supported sections (header, sim_specs, variables, views/model extras) to reduce round-trip data loss
Compatibility corpus regression tests live in tests/fixtures/compat_corpus/.
A pinned, attributed subset of SDXorg test-models lives in
tests/fixtures/external_corpus/; both run offline in CI.
Maintainer helper: python scripts/sync_compat_corpus_manifest.py --check validates corpus manifest sync
The repository test suite covers the MCP stdio protocol, workspace isolation, model construction, validation, SVG rendering, XMILE import/export, simulation, scenario analysis, sensitivity analysis, calibration, and package installation. Run it from a source checkout with:
uv sync --locked --extra dev --extra sim
uv run python -m pytestPinned Stella-saved and external XMILE fixtures live under tests/fixtures/ and
run offline in CI. Generated reports, local planning files, and manual review
artifacts are intentionally not committed to the source tree.
See docs/architecture.md for dependency boundaries,
module ownership, workspace lifecycle, and compatibility contracts.
stella-mcp/
├── CHANGELOG.md
├── CITATION.cff
├── README.md
├── LICENSE
├── pyproject.toml
└── stella_mcp/
├── __init__.py
├── server.py # MCP server lifecycle and protocol wiring
├── tool_handlers.py # Compatibility facade for domain handlers
├── tool_schemas.py # Compatibility facade for the tool catalog
├── tools/ # Domain schemas and handlers
├── mcp_resources.py # MCP resources and prompts
├── session_store.py # Explicit application workspace state
├── simulate.py # PySD-backed simulation
├── analysis.py # Scenario comparison and sensitivity analysis
├── calibrate.py # Parameter fitting and native-unit error metrics
├── render_svg.py # Stock-and-flow SVG rendering
├── model_types.py # Model records and XMILE constants
├── model.py # StellaModel lifecycle and compatibility delegates
├── model_layout.py # Layout compatibility delegates and stock sizing
├── layout_graph.py # Directed graph ranking and component packing
├── layout_router.py # Boundary ports and obstacle-aware routing
├── layout_quality.py # Geometry analysis, metrics, and warnings
├── layout_pipeline.py # Staged deterministic layout orchestration
├── xmile.py # Public model compatibility facade
├── xmile_io.py # XMILE I/O compatibility facade
├── xmile_features.py # XMILE feature classification and typed errors
├── xmile_parse.py # XMILE parser and compatibility warnings
├── xmile_export.py # XMILE serialization and fragment retention
└── validator.py # Model validation logicContributions are welcome! Please feel free to submit issues or pull requests.
PyPI publishing is handled by .github/workflows/publish.yml using PyPI Trusted
Publishing. To release a new version:
Synchronize the version in pyproject.toml, stella_mcp/__init__.py,
CITATION.cff, and CHANGELOG.md; keep the citation and changelog release
dates identical.
Run uv lock --check, the core and simulation test suites, the MCP-floor
suite, and the package job. Prepare the draft GitHub release notes from the
matching CHANGELOG.md entry.
Before pushing the release branch, verify the protected main and v* tag
rules, the pypi environment's protected-tag policy, and the configured
PyPI Trusted Publisher.
Open a draft pull request so every release-critical check runs, require those exact checks, obtain review, and separately approve the merge.
Wait for a fresh main CI run at the exact merge commit. If the Chicago
release date has changed, correct the metadata through another reviewed pull
request before continuing.
With separate approval, create the lightweight version tag at that audited merge commit. With another approval, create and inspect the draft GitHub release from the matching notes file.
With final publication approval, publish the draft. The release event builds
and validates the source distribution and wheel without OIDC authority; the
pypi job's configured deployment policy accepts only tags matching the
protected v* release-tag policy before Trusted Publishing can upload the
verified artifacts.
Tagging, draft creation, and publication are distinct approval gates. Do not move or replace a public tag or uploaded distribution to repair a release.
MIT License - see LICENSE for details.
Model Context Protocol by Anthropic
ISEE Systems for Stella and the XMILE format
Add an auxiliary variable (parameter or intermediate calculation) to the current model
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position (optional, auto-positioned if not specified) | |
| y | No | Y position (optional, auto-positioned if not specified) | |
| name | Yes | Variable name | |
| units | No | Units | |
| equation | Yes | Equation or constant value | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| graphical_function | No | Graphical function (lookup table) definition |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| auxiliary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description's 'Add' confirms mutation. However, the description adds no extra behavioral context such as persistence, validation rules, effect on existing model elements, or error conditions.
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 a single, clear, front-loaded sentence with no wasted words. It immediately conveys the tool's core purpose and is appropriately sized for the information provided.
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?
The schema is rich and an output schema exists, so the description need not detail return values. However, given the complexity of the graphical_function parameter and the large sibling set, the description does not provide enough contextual guidance about when or how to apply this tool effectively.
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 input schema provides 100% coverage with descriptions for all parameters, including nested graphical_function details. The description adds only the semantic hint that an auxiliary variable is a parameter or intermediate calculation, which is useful but minimal beyond the schema.
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 clearly states the action ('Add'), the resource ('auxiliary variable'), and the target ('current model'). It distinguishes from stock/flow tools, though it could more explicitly distinguish from the sibling add_variables tool.
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?
No usage guidance is provided. The description does not mention when to use add_aux versus alternatives like add_variables or update_aux, nor does it state any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a connector (dependency arrow) between variables
| Name | Required | Description | Default |
|---|---|---|---|
| to_var | Yes | Target variable name (the one using from_var) | |
| from_var | Yes | Source variable name | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| connector | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds only the 'dependency arrow' clarification but doesn't disclose behaviors like duplicate handling, validation of variable existence, or whether existing connectors are affected. It is consistent with the annotations, so no contradiction, but the transparency is minimal.
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 a single, front-loaded sentence with no filler. It conveys the core action and object in ten words, earning a perfect score for conciseness.
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?
The tool is a simple write operation with full schema coverage and an output schema, so return values don't need explanation. However, the description omits usage context (when to use vs siblings) and edge-case behavior (duplicate connectors, required preconditions). It is minimally viable but not complete.
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 input schema covers 100% of parameters with detailed descriptions for from_var, to_var, model_id, and workspace_id. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 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?
The description clearly states 'Add a connector (dependency arrow) between variables' – a specific verb, resource, and clarifying detail. This distinguishes it from sibling tools like add_stock or add_flow by naming the resource type and providing the dependency-direction semantics.
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?
No guidance is provided on when to use this tool versus alternatives such as set_connector_routing or sync_connectors_from_equations. The description doesn't mention prerequisites, typical use cases, or exclusions, leaving the agent without enough context to choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a flow between stocks in the current model
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position (optional, auto-positioned if not specified) | |
| y | No | Y position (optional, auto-positioned if not specified) | |
| name | Yes | Flow name | |
| units | No | Units | |
| equation | Yes | Flow rate equation | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| to_stock | No | Destination stock (null for external sink) | |
| from_stock | No | Source stock (null for external source) | |
| non_negative | No | Prevent negative values | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| graphical_function | No | Graphical function (lookup table) definition |
| Name | Required | Description |
|---|---|---|
| flow | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating operation (readOnlyHint false), but the description adds no behavioral detail beyond that. It does not disclose whether adding a flow can overwrite existing flows, whether it requires existing stocks to exist, or how the model state is affected. For a model-building operation, this lack of context could lead to misuse.
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 a single, front-loaded sentence with no tautology or filler. It is appropriately concise, though it could incorporate a bit more context (e.g., mentioning equation or external connections) without becoming bloated.
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 the tool's complexity (11 params, nested objects, output schema), the description is too minimal. It does not convey the full range of flows (external sources/sinks, graphical functions, non_negative flag) and may mislead an agent into thinking flows only connect two stocks. The rich schema does not compensate for the lack of conceptual orientation in the 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?
Schema description coverage is 100%, with all 11 parameters including nested graphical_function fully described in the input schema. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.
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 clearly states the action ('Add a flow') and the resource ('between stocks in the current model'), distinguishing it from siblings like add_stock and add_connector. However, it narrows the scope by saying 'between stocks' when flows can also connect to external sources/sinks (from_stock/to_stock null), which is not mentioned.
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?
No guidance is provided on when to use this tool versus alternative tools like add_connector or update_flow. The description lacks contextual cues or exclusions, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a stock (reservoir) to the current model
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position (optional, auto-positioned if not specified) | |
| y | No | Y position (optional, auto-positioned if not specified) | |
| name | Yes | Stock name | |
| units | No | Units | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| non_negative | No | Prevent negative values | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| initial_value | Yes | Initial value (number or equation) |
| Name | Required | Description |
|---|---|---|
| stock | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is not burdened with that. It adds the context that the stock is added to the 'current model', but does not disclose prerequisites, side effects, or behavior beyond the schema. This is adequate but not rich.
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 a single, highly concise sentence that immediately states the action, resource, and target. There is no wasted text.
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 the tool's moderate complexity, the output schema, and full parameter descriptions, this short description is largely sufficient. It covers the core action and target. However, it does not mention any prerequisites or explicit differentiators from similar add_* tools, so it is not a 5.
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%, so the schema fully documents all 8 parameters. The description adds no parameter-specific meaning beyond the schema, meeting the baseline of 3.
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 uses a specific verb ('Add') and resource ('stock'), with a clarifying synonym ('reservoir'), and indicates the target context ('current model'). This clearly distinguishes it from sibling tools like add_flow, add_aux, and add_variables.
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 description provides clear context: it adds a stock to the current model. However, it does not explicitly state when to use this tool over alternatives (e.g., add_aux) or mention exclusions, so it falls short of the top criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add variables to an existing module
| Name | Required | Description | Default |
|---|---|---|---|
| members | Yes | Variable names to add | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| module_name | Yes | Existing module name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description merely states the action and adds no behavioral context beyond the annotations. It does not disclose potential side effects, error conditions, idempotency, or whether existing members are preserved. Annotations indicate a mutation (readOnlyHint=false) and non-destructive intent (destructiveHint=false), but the description itself offers no extra transparency.
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 a single concise sentence with no unnecessary words, making it easy to parse. However, it lacks any structural elements like parameter examples or usage notes that could aid understanding without increasing length significantly.
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 the presence of a full input schema, output schema, and annotations, the description is minimally adequate for a simple add operation. It does not, however, cover important context such as whether the module must already exist, how duplicate variables are handled, or any session/workspace requirements beyond the schema hints.
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 input schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds no supplementary meaning about the parameters; it just repeats 'variables' and 'module' which are already present in the schema. No additional clarification on types, constraints, or relationships is provided.
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 uses a specific verb 'Add' with a clear resource 'variables' and target 'existing module', which conveys the core action. However, it does not explicitly differentiate from the sibling tool 'add_variables', leaving potential ambiguity about whether this tool is module-specific or model-wide.
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 description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., module must exist, variables must already be defined) or situations where another tool like 'add_variables' or 'remove_from_module' would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add multiple stocks, auxiliaries, flows, connectors, and/or modules to an existing model in one call. All-or-nothing — on any item error the model is left unchanged and the error names the failing item (stage + index).
| Name | Required | Description | Default |
|---|---|---|---|
| auxs | No | Auxiliary variables to add (applied after stocks) | |
| flows | No | Flows to add (applied after stocks and auxs) | |
| stocks | No | Stocks to add (applied first) | |
| modules | No | Modules to create (applied last) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| validate | No | Include validation results in the response | |
| connectors | No | Explicit connectors to add (applied after variables) | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| sync_connectors | No | Run sync_connectors_from_equations after applying items |
| Name | Required | Description |
|---|---|---|
| added | Yes | |
| model | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive; the description adds valuable atomicity behavior: on any item error the model is left unchanged and the error names the failing item (stage + index). This goes beyond the structured annotation hints.
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 two sentences and front-loaded with the action and scope. The second sentence adds the critical all-or-nothing behavior without unnecessary detail.
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 the tool's complexity and the rich input/output schemas, the description is sufficient: it states target, item types, batch nature, and error behavior. It does not need to explain return values because an output schema exists, though it could have explicitly mentioned using single-item tools for one-off additions.
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 input schema has 100% description coverage for all 9 parameters, including per-item arrays and their nested fields. The tool description does not add extra parameter semantics beyond enumerating item types, so the baseline of 3 is appropriate.
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 clearly states the tool adds multiple stocks, auxiliaries, flows, connectors, and/or modules to an existing model in one call. This specific verb+resource+scope distinguishes it from single-item siblings like add_stock, add_flow, add_aux, and add_connector.
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 description implies batch use and atomicity ('in one call', 'all-or-nothing'), but it does not explicitly say when to prefer this over the single-add sibling tools or mention any exclusions. Usage guidance is therefore implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-place module view boxes around their member variables
| Name | Required | Description | Default |
|---|---|---|---|
| padding | No | Padding around module members in pixels | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| min_width | No | Minimum module box width in pixels | |
| min_height | No | Minimum module box height in pixels | |
| only_missing | No | Only place boxes for modules without explicit view geometry | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| modules | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive, but the description adds no additional context about side effects. It doesn't disclose whether existing module geometry is overwritten, whether a model must be loaded, or the scope of changes, which is a significant gap for a mutating operation.
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 single-sentence description is extremely concise and front-loaded, with no wasted words. It is appropriately sized for a simple tool, though its brevity limits the depth of information it provides.
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 the tool's mutating nature and six parameters, the description is too thin. It doesn't explain the layout algorithm, default behavior (all modules vs. only those with missing geometry), or any prerequisites. The output schema covers return values, but the operational context is largely absent.
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% with all six parameters documented, so the description adds no extra meaning beyond the schema. The baseline of 3 is appropriate since the schema carries the parameter-semantic burden.
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 uses a specific verb 'auto-place' and identifies the resource as 'module view boxes around their member variables,' conveying a clear layout operation. However, it doesn't explicitly differentiate from sibling tools like set_module_view or render_diagram, so while clear, it's not fully distinguishing.
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 description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The schema's 'only_missing' parameter hints at a default behavior (placing all boxes) but the description itself doesn't explain when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create and populate a model in one call: sim specs, stocks, auxiliaries, flows, connectors, and modules. All-or-nothing — on any item error nothing is registered and the error names the failing item (stage + index). Connector sync and validation run by default, so the response doubles as an inspection.
| Name | Required | Description | Default |
|---|---|---|---|
| auxs | No | Auxiliary variables to add (applied after stocks) | |
| name | Yes | Model name | |
| flows | No | Flows to add (applied after stocks and auxs) | |
| stocks | No | Stocks to add (applied first) | |
| modules | No | Modules to create (applied last) | |
| model_id | No | Optional model ID to assign in this session | |
| validate | No | Include validation results in the response | |
| sim_specs | No | Simulation time settings | |
| connectors | No | Explicit connectors to add (applied after variables) | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| sync_connectors | No | Run sync_connectors_from_equations after applying items |
| Name | Required | Description |
|---|---|---|
| added | Yes | |
| model | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral details beyond the sparse annotations (readOnlyHint=false, destructiveHint=false): all-or-nothing atomicity, error reporting that names the failing item with stage and index, default connector sync/validation behavior, and the response doubling as an inspection. This is substantial value-add.
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 compact yet information-dense: four sentences cover the tool's scope, atomicity, error granularity, and default behaviors. No filler or repetition; each sentence earns its place.
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 the high complexity (11 parameters, nested objects, output schema), the description provides enough behavioral context: scope, ordering, defaults, error semantics, and the response's role as an inspection. The presence of an output schema obviates the need to explain return structure, and sibling tool names clarify the tool's niche.
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 schema has 100% parameter descriptions, providing a baseline of 3. The description adds meaningful ordering semantics (e.g., 'applied after stocks', 'applied first', 'applied last') that are not in the schema, enhancing understanding of how the component arrays interact.
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 clearly states the tool creates and populates a model in one call, enumerating the component types (sim specs, stocks, auxiliaries, flows, connectors, modules). This distinguishes it from sibling tools like create_model or add_stock, which handle individual steps.
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 'in one call' implies a batch alternative to incremental add tools, and the atomic all-or-nothing behavior provides contextual guidance. However, it does not explicitly name alternatives or state when to prefer this over create_model plus add_* siblings, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fit constant model parameters to an observed time-series — the inverse of simulate. Only constant auxiliaries/flows can be calibrated (stocks are rejected: overriding a stock pins it to a constant rather than setting its initial value). least_squares (default) reports a linearized std_error; differential_evolution is a global, seeded alternative requiring bounds. Observation times must lie within the model window (no extrapolation). Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | differential_evolution seed (kept non-null for reproducibility) | |
| method | No | Optimizer: least_squares (local, gives std_error) or differential_evolution (global, seeded, needs bounds) | least_squares |
| maxiter | No | differential_evolution generation cap (default 100) | |
| popsize | No | differential_evolution population multiplier | |
| weights | No | Optional positive per-target residual multipliers; inverse-sigma values give normalized residuals and the usual statistical std_error interpretation | |
| max_nfev | No | least_squares function-evaluation cap | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| objective | No | Objective (sum of squared residuals; scale via weights) | sse |
| parameters | Yes | Constant parameters to fit (constant auxiliaries/flows only; stocks are rejected) | |
| observations | Yes | Observed data on one shared time grid: inline {time, targets} or {csv_path} (first CSV column is time) | |
| save_fit_csv | No | Optional path to write a long (time, target, observed, fitted) CSV | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| return_fit_series | No | Also return the best-fit downsampled series per target |
| Name | Required | Description |
|---|---|---|
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description explains key behavioral constraints: stock calibration is disallowed and why, the least_squares method reports a linearized std_error, differential_evolution is global and seeded, and no extrapolation is allowed. These details provide substantial context that the agent could not infer 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?
The description is three sentences, each earning its place: the first states the core purpose and inverse relation, the second covers calibration constraints and method differences, and the third addresses extrapolation and the optional dependency. It is front-loaded with the most critical information and contains no filler or repetition.
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 the complexity (13 parameters, nested objects, output schema), the description covers the main constraints and prerequisites well. The output schema handles return values. However, there is a slight ambiguity about whether calibration persists by modifying the model's current values or just returns fitted parameters; this is hinted by 'Fit constant model parameters' and the readOnlyHint, but not explicitly stated. This small gap prevents a 5.
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 baseline is 3. The description adds value by clarifying method-specific parameter semantics: it notes that differential_evolution requires bounds, which ties the method enum to the 'min' parameter's optionality, and it explains the stock rejection behavior beyond the parameter array's description. This strengthens the relationship between parameters and their intended use.
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 opens with a clear verb+resource: 'Fit constant model parameters to an observed time-series' and immediately distinguishes it from siblings with 'the inverse of simulate.' This makes the tool's purpose unambiguous and differentiates it from simulate, sensitivity_analysis, and other related 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?
The description gives explicit when/when-not guidance: stocks are rejected, observation times must be within the model window, and the two optimizer alternatives (least_squares vs. differential_evolution) are described with their trade-offs (local vs. global, needs bounds). It also mentions the required pysd dependency, adding a prerequisite context. 'Inverse of simulate' makes the alternative tool explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run several named what-if scenarios (each a set of constant parameter overrides) against a baseline and report how each diverges: per-variable final/max absolute deltas and final percent change. Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Variables to report and compare (default: all stocks) | |
| baseline | No | Override set to measure deltas against (default: the unmodified model) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| scenarios | Yes | Named override sets to compare (names must be unique) | |
| max_points | No | Maximum points per returned series | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| save_comparison_csv | No | Optional path to write a wide variable-by-scenario CSV |
| Name | Required | Description |
|---|---|---|
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and readOnlyHint=false. The description adds behavioral context beyond that by disclosing the optional pysd dependency and the kind of results returned. It doesn't mention side effects like CSV writing, but it does surface the dependency requirement, which is useful for the agent.
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 two sentences: the first conveys the core purpose and output in a dense, front-loaded manner; the second adds an essential prerequisite (pysd dependency) with an install command. No fluff, no repetition, and every sentence earns its place.
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 the tool's complexity (7 parameters, nested objects, output schema present), the description provides a solid high-level overview of behavior and prerequisites. The schema covers parameter details, and the output schema covers return values. The optional CSV writing is not mentioned, but that is a minor gap for a tool this well-specified.
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 input schema has 100% parameter documentation, so the baseline is 3. The description clarifies the concept of 'scenarios' as constant overrides and explains the divergence metrics, but it doesn't add per-parameter meaning beyond what the schema already provides, so no higher score is warranted.
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 clearly states the tool's action: 'Run several named what-if scenarios against a baseline and report how each diverges'. It specifies the output (per-variable final/max absolute deltas and final percent change), distinguishing it from sibling tools like simulate or sensitivity_analysis which do different kinds of analysis.
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 description gives clear context on when to use this tool: for comparing multiple named what-if scenarios against a baseline. It does not explicitly name alternatives, but the scenario-comparison focus makes the intended use evident. No exclusions are mentioned, which fits a 'clear context, no exclusions' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Stella model with specified time settings
| Name | Required | Description | Default |
|---|---|---|---|
| dt | No | Time step | |
| name | Yes | Model name | |
| stop | No | Simulation stop time | |
| start | No | Simulation start time | |
| method | No | Integration method (Euler or RK4) | Euler |
| model_id | No | Optional model ID to assign in this session | |
| time_units | No | Time units | Years |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write, which the description aligns with. The description adds minimal behavioral context such as 'with specified time settings', but does not disclose side effects, persistence, or workspace association beyond what schema parameters imply.
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 a single, front-loaded sentence with no filler or redundant information. It clearly states the tool's purpose without wasting words.
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 the rich input schema (100% parameter descriptions), output schema, and annotations, the description provides adequate context for an agent to understand the tool's role. It does not explain how the model is referenced later, but the schema's parameters (model_id, workspace_id) and output schema fill that gap.
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%, so the schema fully documents all 8 parameters. The description highlights time-related settings but does not add new meaning beyond the schema, warranting the baseline score of 3.
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 clearly identifies the action (create) and the resource (a new Stella model), with a specific scope of time settings. It is clear but does not explicitly differentiate from sibling tools like build_model, so it does not fully meet the 5-level standard.
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?
There is no guidance on when to use this tool versus alternatives such as build_model or load_template. The description implies use for creating a model but does not provide context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a logical module/group for organizing variables
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Module name | |
| members | No | Optional initial member variable names | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds the contextual detail that it creates a logical grouping for variables, but does not disclose any side effects, prerequisites (e.g., requiring a model), or behavior beyond the basic create action. This is adequate but minimal, meeting the lower bar set by existing annotations.
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 a single, concise sentence that immediately states the core function. It is front-loaded with the action and resource, with every word earning its place. No unnecessary elaboration or repetition.
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 the tool's simplicity, the 100% schema coverage, annotations, and presence of an output schema, the description is largely complete for a create operation. However, a brief note on how modules relate to other tools (e.g., 'modules can later be populated via add_to_module') would enhance completeness, so a small deduction is applied.
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 input schema provides 100% coverage with descriptions for all four parameters (name, members, model_id, workspace_id). The tool description itself adds no parameter-specific meaning, so the baseline score of 3 is appropriate given the schema's thoroughness.
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 clearly states the tool's action ('Create') and resource ('a logical module/group'), and specifies its purpose ('for organizing variables'). This distinguishes it from sibling tools like create_model, create_workspace, and add_to_module, making the intent unambiguous.
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 description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that add_to_module is for adding to existing modules, or that delete_module/rename_module handle other lifecycle operations. The use case is only implied by the tool name and generic purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an isolated application workspace for stateful Stella tool calls. The returned ID routes state and is not an authorization credential.
| Name | Required | Description | Default |
|---|---|---|---|
| ttl_seconds | No | Optional caller-selected lifetime. Omit for process-lifetime state. |
| Name | Required | Description |
|---|---|---|
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context beyond that: the returned ID routes state and is explicitly 'not an authorization credential', which helps prevent misuse. This is useful transparency without contradicting annotations.
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 concise sentences that front-load the purpose and immediately follow with a critical caveat. There is no filler or redundant restatement of the tool name.
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?
The tool is simple: one optional parameter, an output schema, and clear annotations. The description covers what the tool does, when to use it, and an important behavioral warning. Nothing essential is missing for an agent to select and invoke it correctly.
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 input schema already fully describes the only parameter (ttl_seconds) with a clear description and constraints, so schema coverage is 100%. The tool description adds no parameter-level detail, so the baseline score of 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?
The description opens with a specific verb ('Create') and resource ('isolated application workspace'), and clarifies its role ('for stateful Stella tool calls'). This clearly distinguishes it from siblings like revoke_workspace and other model/list 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?
The description provides clear context: use this tool when a stateful workspace is needed for Stella tool calls. It does not explicitly mention alternatives or exclusions, but given there is no direct create alternative, the usage context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a model from the current session. Saved .stmx files are not touched. model_id is required — there is deliberately no implicit 'delete current model'.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | Session model ID to remove | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| remaining | Yes | |
| current_model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds important nuance: it only removes from the current session, not from saved .stmx files, and deliberately requires model_id (no implicit 'current model'). This goes beyond the annotation to clarify the exact scope and safety profile, which is valuable for a destructive tool.
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 two sentences, front-loaded with the action ('Remove a model'), and every clause adds value: scope, safety, and requirement. There is no fluff or repetition.
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 simple deletion tool with full schema coverage, annotations, and an output schema, the description is sufficiently complete. It covers the essential aspects: what is removed, what is not touched, and the required parameter behavior, leaving no significant gaps.
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%, with both model_id and workspace_id adequately described. The description adds minimal parameter-level information beyond emphasizing that model_id is required and there is no implicit fallback. This slightly reinforces the schema but does not significantly enhance meaning.
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 uses a specific verb 'Remove' with a clear resource ('a model from the current session'), and further distinguishes itself by noting that saved .stmx files are untouched and that there is no implicit 'delete current model'. This clearly sets it apart from sibling tools like delete_variable or delete_module.
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 description provides clear context: it removes a session model only, does not affect saved files, and requires an explicit model_id. While it does not explicitly name alternative tools for other deletion tasks, the behavior and constraints are unambiguous enough for an agent to decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a module
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| module_name | Yes | Existing module name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| model_id | Yes | |
| module_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey that this is destructive (destructiveHint=true) and not read-only (readOnlyHint=false). The description adds no further behavioral context, such as whether deletion is permanent, whether dependent items are removed, or what the side effects are.
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 a single, front-loaded sentence with no unnecessary words. However, it is so minimal that it adds little value beyond the tool name, making it concise but not informationally efficient.
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 the tool is destructive and has sibling tools for module manipulation, the description lacks critical context about what happens when a module is deleted, any prerequisites, and how it differs from remove_from_module. While the annotations and schema cover some aspects, the description fails to provide a complete picture.
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 schema descriptions cover 100% of parameters, so by the baseline rule the score is 3 even though the tool description provides no additional parameter semantics. The description does not explain the relationship between parameters or convey any nuanced meaning beyond the schema.
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 'Delete a module' uses a specific verb (delete) and resource (module), making the tool's function immediately clear. It also distinguishes from sibling tools like delete_model and delete_variable by naming the specific resource type.
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?
No guidance is provided on when to use this tool versus alternatives such as remove_from_module or delete_model. The description lacks any context about prerequisites, use cases, or situations where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a stock/flow/aux and clean connectors/module membership
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Variable name to delete | |
| force | No | Allow deleting stocks that still have connected flows (flows are detached) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| name | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate destructiveness. It does add useful context about cleanup side effects ('clean connectors/module membership') beyond a simple delete. However, it doesn't disclose important behaviors like the constraint that stocks with connected flows require force=true (or the flows get detached), which is implied by the force parameter but not in the description. The added cleanup context earns a 3, not higher.
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 a single sentence that is front-loaded with the action and resource, and it includes the additional cleanup behavior succinctly. Every word earns its place; there is no fluff or repetition of schema details.
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 the annotations (destructiveHint), full parameter schema coverage, and an output schema, the description provides sufficient context for a delete operation. It adds the cleanup behavior which is valuable. It could mention the force requirement, but that is already in the parameter schema. Overall, the description plus structured metadata is complete enough for an agent to use the tool correctly.
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% – every parameter (name, force, model_id, workspace_id) has a clear description in the schema. The tool description adds no parameter-specific information beyond what the schema already provides. Per the baseline for high schema coverage, this is a 3.
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 uses the specific verb 'Delete' and clearly identifies the resource as 'stock/flow/aux' (variable types). It also adds the distinguishing cleanup behavior ('clean connectors/module membership'), which differentiates it from sibling tools like delete_model or delete_module. This is a clear and specific purpose statement.
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?
There is no explicit guidance on when to use this tool versus alternatives. It does not state conditions like 'use this to permanently remove a variable' or mention when not to use it (e.g., when a stock has connected flows unless force is true). The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the XMILE XML representation of the current model (for preview)
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| auto_layout | No | Whether to auto-layout before export | |
| compat_mode | No | Compatibility mode for export checks | permissive |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| resolve_layout_violations | No | Whether to run layout crossing/collision post-processing before export |
| Name | Required | Description |
|---|---|---|
| xml | Yes | |
| layout | Yes | |
| model_id | Yes | |
| truncated | Yes | |
| compatibility_warnings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds minimal extra behavior: it only notes the 'preview' intent. It does not disclose that auto_layout or resolve_layout_violations are performed before export, but those are visible in the schema and no contradiction exists.
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 a single, front-loaded sentence that gets straight to the point. Every word carries meaning: 'Get', 'XMILE XML representation', 'current model', and 'for preview'. There is zero filler.
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 a readOnly annotation, an output schema, and 100% schema coverage for parameters, the description is sufficiently complete for a straightforward export tool. It could improve by naming an alternative for non-preview exports, but the current level is adequate.
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%, so the parameters are fully documented in the input schema. The description itself adds no parameter-level meaning, which meets the baseline for high schema coverage but does not exceed it.
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 uses a specific verb 'Get' and names a precise resource: 'the XMILE XML representation of the current model'. This clearly distinguishes it from sibling tools like render_diagram or inspect_model, and the parenthetical '(for preview)' adds useful intent.
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 'for preview' gives a clear usage context—this is the tool to call when you need an XMILE XML preview of the model. It does not explicitly name alternatives or exclusions, but the context is strong enough to guide basic selection among the long sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed metadata for one template
| Name | Required | Description | Default |
|---|---|---|---|
| template_name | Yes | Template name |
| Name | Required | Description |
|---|---|---|
| template | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals this is a safe read operation, and the description is consistent with that. However, the description adds no additional behavioral context beyond 'detailed metadata', such as what fields are included or error behavior.
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 a single, front-loaded sentence with no wasted words. It clearly conveys the tool's purpose without unnecessary detail.
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 simple retrieval tool with one well-documented parameter, a readOnly annotation, and an output schema, the description is sufficiently complete. The tool's behavior and return value are covered by structured data.
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 schema fully describes the single parameter with 100% coverage, and the description does not add meaningful extra semantics beyond reinforcing that it targets one template. Baseline 3 is appropriate.
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 clearly states the tool gets detailed metadata for a single template, using a specific verb and resource. This distinguishes it from sibling tools like list_templates or load_template.
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 'one template' implies the tool is for retrieving a specific template's metadata, but it does not explicitly mention when to use it instead of alternatives like list_templates. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a structured summary of the current model for agent inspection
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| include_validation | No | Include validation issues in structured output |
| Name | Required | Description |
|---|---|---|
| model | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is a safe read operation. The description adds that it returns a structured summary and that the model_id defaults to the current model, but this is mostly reiterated from the schema. It does not disclose any other behavioral traits such as return size, performance considerations, or potential limitations, so the added value beyond annotations is modest.
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 a single, front-loaded sentence that conveys the core purpose without any redundant words. It is concise and well-structured, with every word earning its place.
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 the presence of a full output schema, complete input schema descriptions, and the readOnlyHint annotation, the description provides sufficient context for a straightforward inspection tool. It could enhance completeness by mentioning when to prefer this over validate_model or get_model_xml, but it is not severely lacking.
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 input schema provides 100% coverage with detailed descriptions for all three parameters, including optionality and defaults. The description does not add any parameter-specific meaning beyond what is already in the schema, landing at the baseline score.
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 clearly states the verb 'Return' and the resource 'structured summary of the current model', with the purpose 'for agent inspection'. It is specific and understandable, but it does not explicitly distinguish itself from sibling tools like read_model or validate_model, which could also serve inspection purposes.
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 'for agent inspection' provides a clear context for when to use this tool, implying it is for inspecting the model's current state. However, it does not mention any alternatives or exclusions, so it only partially guides the agent in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List connector metadata (uid, endpoints, angle, routing lock/points)
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| connectors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which already establishes that this is a safe read operation. The description adds the specific metadata fields returned, which is useful, but it does not disclose other behavioral traits such as pagination, volume limits, or dependencies. With annotation coverage, a baseline 3 is appropriate.
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 a single, front-loaded sentence that directly states the action and the scope of data with no redundant words. The field list is compact and informative.
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 simple read-only list operation, the description combined with the fully documented schema and output schema is sufficient. It does not explicitly mention model/workspace scoping, but the schema covers that; minor gap remains about the overall return set size or pagination behavior.
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?
Both parameters (model_id and workspace_id) have full schema descriptions, giving 100% coverage. The description adds no parameter-specific meaning beyond what the schema already provides, so it rests at the baseline.
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 uses a specific verb ('List') and a clear resource ('connector metadata'), and enumerates the metadata fields (uid, endpoints, angle, routing lock/points), which distinguishes it from sibling list tools like list_variables and list_modules.
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 description only states what the tool does; it provides no guidance on when to use it instead of alternatives like add_connector, set_connector_routing, or sync_connectors_from_equations. No context or exclusions are provided, so usage is entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all model IDs available in the current session
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| models | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already signals that this is a safe read operation. The description adds the scope 'current session' and clarifies that only model IDs are returned, not full model details. However, it does not disclose return format, pagination, or how workspace_id affects behavior, which would be useful context given the optional parameter.
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 a single sentence of ten words, front-loaded with the action verb and resource. It contains no filler or redundant phrases. Every word contributes value.
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 that an output schema exists and the readOnlyHint annotation is present, the description is mostly sufficient. The main gap is that 'current session' is ambiguous, and the optional workspace_id parameter may modify the scope but the description does not clarify this relationship. However, the schema's parameter description partially addresses this, so the tool is still usable with less risk.
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 schema fully describes the sole parameter workspace_id, including its purpose, MCP 2026-07-28 requirement, and legacy compatibility. The tool description adds no additional information about this parameter, so the baseline of 3 for high schema coverage is appropriate.
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 clearly states the verb 'List' and the resource 'model IDs' within the scope of the 'current session'. This distinguishes it from sibling tools like list_variables, list_modules, and list_connectors, which target different resources. The purpose is immediately understandable.
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 description provides no guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or when not to use it. It simply states what it does, leaving the agent to infer usage from the name and resource type. Sibling tools like list_variables are not referenced for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List modules/groups in the current model
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| modules | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint=true annotation, confirming a non-mutating operation. However, it adds minimal behavioral context beyond the annotation, such as whether empty groups are included or how modules and groups are organized. This meets the baseline but doesn't enrich the agent's understanding.
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 a single, front-loaded sentence that efficiently communicates the action and scope. There is no redundant wording; every word contributes to meaning, making it an exemplary concise description.
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 simple list operation with an output schema and fully documented parameters, the description is sufficiently complete. It captures the core purpose, while the schema and annotations cover return values and safety. Slight room for improvement by noting how modules/groups relate or pointing to complementary tools, but not necessary for basic use.
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 input schema provides 100% coverage for both parameters, with model_id and workspace_id clearly described. The description itself adds no parameter-level meaning, only restating the 'current model' concept already present in the schema. The baseline score of 3 is appropriate when the schema fully documents parameters.
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 clearly states a read-only enumeration of modules/groups within the current model scope, using an action verb and specific resource. It distinguishes from siblings like list_variables and list_connectors by naming the resource, but lacks additional context about the module hierarchy or relationship to other 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?
No guidance is provided on when to use this tool versus alternatives such as list_variables, list_connectors, or inspect_model. There is no mention of prerequisites (e.g., having an active model) or clear scenarios where this tool is the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List built-in and user-defined templates
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional required tags (all must match) | |
| query | No | Optional case-insensitive search against template name/title/description | |
| source | No | Optional source filter |
| Name | Required | Description |
|---|---|---|
| templates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the behavioral scope of including both built-in and user-defined templates. There is no mention of additional behavioral traits like pagination or default sorting, but the read-only nature is clear and consistent.
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 a single, front-loaded sentence: 'List built-in and user-defined templates'. It contains no filler, no redundancy, and succinctly communicates the core purpose.
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 the tool's simplicity, the read-only annotation, and the presence of an output schema, the description is largely complete. However, it does not explicitly mention the optional filter parameters or the fact that no filters return all templates, though the schema 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 description coverage is 100%, so the parameters (tags, query, source) are fully described in the schema. The tool description does not add any additional parameter-level meaning, so a baseline score of 3 is appropriate.
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 uses a specific verb ('List') and resource ('templates'), with clear scoping to 'built-in and user-defined' categories. This distinguishes it from sibling list tools like list_variables and list_modules, making the operation unambiguous.
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 description implies usage (when you want to list templates) but provides no explicit guidance on when not to use it or when alternatives like get_template_info or load_template might be more appropriate. No alternatives are mentioned, which limits the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all variables (stocks, flows, auxiliaries) in the current model
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| variables | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is handled. The description adds useful context by specifying it covers stocks, flows, and auxiliaries, and that it operates on the current model. No behavioral surprises are hidden, though it doesn't mention pagination or any performance aspects.
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 a single concise sentence that front-loads the action and scope. Every word earns its place, with no redundancy or filler.
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 the tool is a simple read-only list operation with full schema coverage and an output schema present, the description is sufficiently complete. It tells the user what it lists and the scope, while the output schema covers return details. Minor gaps like absence of any mention of filtering or ordering are acceptable for such a 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%, with both parameters (model_id and workspace_id) already described in the input schema. The description adds no additional parameter-level information, keeping the score at the baseline of 3.
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 clearly states the tool lists all variables (stocks, flows, auxiliaries) in the current model, using a specific verb ('List') and resource ('variables'). It distinguishes from sibling tools like list_models or add_variables by specifying scope and variable types.
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 description provides clear context for when to use the tool: to list variables in the current model. It doesn't explicitly mention alternatives or exclusions, but given the sibling tool set, no other tool performs this exact listing function, making the usage context clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a template into the current session as a model
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Optional model ID for the loaded template | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| template_name | Yes | Template name |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| model_id | Yes | |
| template | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is not read-only and not destructive. The description provides no additional behavioral context, such as whether the current model is replaced, whether a new model is created, or any prerequisites like saving the current session. It does not contradict annotations but adds nothing beyond them.
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 a single, front-loaded sentence with no filler. It communicates the essential action efficiently.
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?
The tool has an output schema and annotations that cover mutability and destructiveness, so the description does not need to describe return values. However, it lacks detail about how the load interacts with the current session (e.g., overwrites, creates new model) and does not mention any prerequisites. For a simple tool this might suffice, but there are clear gaps.
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 input schema already documents all three parameters with full coverage (100%). The description does not add any extra meaning to the parameters, so it does not improve upon the schema.
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 uses a specific verb ('load') and identifies the resource ('template') and the outcome ('into the current session as a model'). This clearly distinguishes it from sibling tools like list_templates, get_template_info, and save_as_template.
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 description implies the tool is used when a template should be instantiated as a model in the current session, but it does not explicitly state when to choose this over create_model or list_templates. No alternatives or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an existing .stmx file and load it as the current model
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Path to .stmx file | |
| model_id | No | Optional model ID to load into/assign in this session | |
| compat_mode | No | Compatibility mode for import parsing | permissive |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| filepath | Yes | |
| model_id | Yes | |
| compatibility_warnings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds that it loads the file as the current model, implying a session state change, but doesn't disclose side effects such as overwriting unsaved changes to the current model or any session-specific behavior. This is minimal extra context beyond the annotations.
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 a single, front-loaded sentence: 'Read an existing .stmx file and load it as the current model'. Every word contributes to understanding the action and outcome, with no redundant or filler content.
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 that an output schema exists and parameters are fully documented, the description covers the core purpose adequately. It could be more complete by noting what happens to the existing current model on load, but this is a minor gap given the schema annotations. The tool is part of a larger model-management set, and the description provides enough for an agent to understand basic invocation.
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 input schema has 100% parameter coverage with descriptions for all four fields, so the baseline is 3. The description does not add any parameter-level detail beyond referencing the .stmx file, relying entirely on schema 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?
The description uses the specific verb 'read' with the resource '.stmx file' and clearly states the effect 'load it as the current model'. This distinguishes it from siblings like create_model (new model) and load_template (template), and from inspect_model which does not change state.
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 description implies usage for opening an existing .stmx file into the session, but gives no explicit guidance on when to use this versus alternatives like create_model or load_template. It doesn't mention any exclusions or prerequisites, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove variables from an existing module
| Name | Required | Description | Default |
|---|---|---|---|
| members | Yes | Variable names to remove | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| module_name | Yes | Existing module name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false, so the agent knows it's a safe mutation. However, the description adds no extra behavioral context beyond the name, such as whether removing also deletes the variables themselves, whether the module must exist, or any side effects on dependent components. The word 'remove' could ambiguously imply deleting variables, which is not clarified.
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 a single sentence with no redundant words. It is front-loaded with the verb and resource, and every word adds meaning. Efficiently communicates the core function.
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?
The tool is relatively simple (remove members from an existing module), and the output schema exists, so return values are not needed. However, the description omits important context such as whether the removed variables are deleted or just unlinked, and whether there are any prerequisites or side effects. This gap prevents a higher score.
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 input schema provides 100% coverage with descriptions for all four parameters (members, model_id, module_name, workspace_id), so the description carries no parameter burden. Baseline of 3 is appropriate given the schema fully handles parameter semantics.
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 uses a specific verb ('remove'), identifies the resource ('existing module'), and specifies the object ('variables'). This clearly distinguishes it from siblings like add_to_module and delete_module, making the tool's function unambiguous.
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 description implies usage: when you want to remove variables from a module, use this tool. However, it provides no explicit context for when to use this over alternatives, no exclusions, and no mention of prerequisites such as the module existing or the variables being present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename an existing module
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| new_name | Yes | New module name | |
| module_name | Yes | Existing module name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no behavioral context such as reversibility, side effects on references, or permission requirements. It simply restates the operation without enriching the annotation-provided safety profile.
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 a single, concise sentence with no unnecessary words. It is not verbose, but it is also minimal and does not add contextual value beyond the core purpose.
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 the simple nature of the tool, the presence of full schema descriptions, and an output schema, the one-line description is partially adequate. However, it omits context about module identity, scoping via model_id/workspace_id, and potential side effects of renaming, leaving some gaps for the agent.
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%, with all four parameters individually described. The description itself adds no parameter semantics; the baseline of 3 applies because the schema carries the full burden.
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 clearly states the action ('Rename') and the resource ('existing module'). It is distinct from create/delete/add/remove module tools, though it does not explicitly differentiate from rename_variable, so it misses the full sibling distinction required for 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 description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when renaming is appropriate, or any interaction with other module operations, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a stock/flow/aux and update dependent references
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| new_name | Yes | New variable name | |
| old_name | Yes | Existing variable name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| new_key | Yes | |
| model_id | Yes | |
| new_name | Yes | |
| old_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds the crucial behavioral trait that dependent references are updated automatically, which is not captured in annotations or schema. This provides valuable side-effect context beyond the structured data.
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 a single front-loaded sentence that efficiently communicates both the operation and its key side effect. Every word earns its place, with no redundancy or extraneous detail.
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?
The tool is simple, has 100% schema coverage, an output schema, and annotations that cover the destructive profile. The description conveys the core purpose and side effect. Potential failure conditions are likely covered by error responses given the output schema, so the description is complete enough for this 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?
The input schema already documents all four parameters with descriptions (100% coverage), so the baseline is high. The description adds domain context that the variable types are stock/flow/aux, clarifying that old_name and new_name refer to these specific model elements, which the schema's generic 'variable name' descriptions do not convey.
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 clearly states the action 'rename' and the resource 'stock/flow/aux' plus the side effect 'update dependent references'. This distinguishes it from sibling tools like delete_variable and rename_module, making its purpose unambiguous.
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 description gives a clear context for use—when you need to rename a variable—and implicitly indicates it applies to stock/flow/aux. It does not explicitly mention alternatives or exclusions, but the context is sufficient for selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the current model as an SVG stock-and-flow diagram. The SVG is returned inline (for clients without file access) and optionally written to a file. Defaults to running auto-layout first so freshly built models render sensibly.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | No | Optional output path (.svg); parent directory must exist | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| auto_layout | No | Run auto-layout before rendering (same semantics as save_model) | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| svg | Yes | |
| layout | Yes | |
| filepath | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-read-only and idempotent, and the description adds behavioral details: returns SVG inline, may write to a file, and defaults to auto-layout. These specifics go beyond the annotation values and provide useful context about side effects and layout behavior. No contradiction with annotations.
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 two sentences long, front-loaded with the primary purpose, and every sentence adds meaningful context. No redundant or filler content.
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 present and all parameters documented in the input schema, the description covers the essential aspects: what it does, output modes, and auto-layout behavior. It is complete for a rendering tool and does not need to explain return values.
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 input schema provides 100% coverage with descriptions for all four parameters, so the description does not need to elaborate much. It mentions file output and auto-layout conceptually, but does not add per-parameter details beyond what the schema already offers. Baseline 3 is appropriate given high schema coverage.
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 clearly states the tool renders the current model as an SVG stock-and-flow diagram, specifying the output format and distinguishing itself from siblings like save_model or get_model_xml. The verb 'render' and resource 'model' are specific, and the SVG output makes the purpose unambiguous.
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 description gives clear context: use when a visual SVG diagram is needed, with inline output for clients lacking file access and optional file writing. It mentions auto-layout for fresh models but does not explicitly name alternative tools or exclusion scenarios. Overall, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke a workspace and discard all models stored in it.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| revoked | Yes | |
| workspace_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable detail that all models stored in the workspace are discarded, clarifying the scope of destruction beyond the annotation. This is consistent, not contradictory.
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?
Single sentence, front-loaded with the action, no filler. Every word adds 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?
For a one-parameter destructive tool with annotations and output schema, the description provides the key side effect. It could explicitly state irreversibility, but destructiveHint plus 'discard' sufficiently conveys permanence. Overall adequately complete.
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 description does not add parameter-level semantics beyond mentioning that the workspace contains models. The schema already fully documents workspace_id, so baseline 3 is appropriate.
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?
Clear verb 'Revoke' with resource 'workspace' and consequence 'discard all models stored in it'. This distinguishes it from sibling tools like create_workspace and delete_model by specifying it destroys the entire workspace and its contents.
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?
No explicit guidance on when to use this tool versus alternatives. Although sibling tools include delete_model for individual model removal, the description does not mention that use case or any prerequisites. This is implied usage at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current model as a user-defined template
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags for discovery/filtering | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| overwrite | No | Whether to overwrite an existing user template with the same name | |
| description | No | Optional template description for discovery | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| template_name | Yes | Template name to save |
| Name | Required | Description |
|---|---|---|
| template | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is not a read-only or destructive operation, but the description adds minimal behavioral context beyond that. It does not disclose side effects such as overwriting existing templates (only visible via the optional 'overwrite' parameter) or whether the operation is reversible. This is consistent with the annotations, so no contradiction exists.
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 a single compact sentence of eight words, front-loading the action, object, and result. There is zero redundancy or filler, making it highly scannable for an AI agent.
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 present and full parameter coverage in the input schema, the description is largely sufficient for a simple save operation. However, it doesn't mention that model_id defaults to the current model or that overwrite defaults to false, which are useful contextual details but not required given the schema's clarity.
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 input schema provides full descriptions for all six parameters, so the description carries no additional parameter meaning. The baseline of 3 applies because the schema already covers all parameter semantics, and the description adds no extra insight beyond what the schema states.
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 uses a specific verb ('Save'), a clear resource ('current model'), and a distinct artifact ('user-defined template'), which clearly differentiates it from sibling tools like save_model or list_templates. The phrase 'as a user-defined template' is specific enough to make the tool's function unambiguous.
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?
No guidance is provided about when to use this tool versus alternatives such as save_model or load_template. There are no usage conditions, exclusions, or references to sibling tools, leaving the agent to infer the intended context from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current model to a .stmx file
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | Output file path (.stmx) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| auto_layout | No | Whether to auto-layout before export | |
| compat_mode | No | Compatibility mode for export checks | permissive |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| resolve_layout_violations | No | Whether to run layout crossing/collision post-processing before export |
| Name | Required | Description |
|---|---|---|
| layout | Yes | |
| filepath | Yes | |
| model_id | Yes | |
| compatibility_warnings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond the basic action, such as whether existing files are overwritten, side effects on the in-memory model (e.g., auto_layout, resolve_layout_violations), or required permissions. It does not contradict annotations.
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 a single sentence that efficiently captures the core purpose without any unnecessary words. It is front-loaded with the key action and output format.
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 complete schema and output schema present, the description is adequate for the simple save operation, but it omits important context such as when to save (e.g., after building), whether the file is overwritten, and how 'current model' is determined. The tool has 6 parameters, so some usage context would be valuable.
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 input schema fully documents all 6 parameters (100% coverage), so the description does not need to repeat parameter details. It adds no additional meaning beyond the schema, which is acceptable given the high schema coverage.
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 clearly states the tool saves the current model to a .stmx file, specifying the verb, resource, and output format. It distinguishes from siblings like create_model or validate_model by focusing on persistence of the existing model.
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?
No guidance is provided on when to use this tool, prerequisites (e.g., model must be built or loaded), or alternatives. It does not explain how it differs from related tools like build_model or get_model_xml for serialization purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-at-a-time sensitivity: sweep each parameter across a range (holding the others at their baseline) and report how one chosen output metric responds, with a range slope and a baseline-normalized elasticity for ranking. Requires the optional pysd dependency (pip install 'stella-mcp[sim]').
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Sweep design; only one-at-a-time is available (grid/montecarlo reserved) | oat |
| output | Yes | The single output metric to track across the sweep | |
| max_runs | No | Hard cap on total swept runs; the call errors rather than truncating a larger sweep | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| parameters | Yes | Parameters to sweep, each one at a time | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| include_series | No | Also return each run's downsampled output series | |
| save_sweep_csv | No | Optional path to write the long (parameter, value, metric) CSV |
| Name | Required | Description |
|---|---|---|
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and readOnlyHint=false, but the description does not clarify potential side effects (e.g., writing a CSV via save_sweep_csv) or the error behavior when max_runs is exceeded. It does add context about the required pysd dependency and the product (slope/elasticity), which is useful but not exhaustive.
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 two sentences, front-loaded with the core behavior, and includes a crucial dependency note. Every sentence earns its place without redundancy.
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 tool with 8 parameters, nested objects, and an output schema, the description is adequate: it explains the OAT sweep method, output metric reduction, and the returned slope/elasticity. It misses the error-on-overflow behavior, but that is covered by schema descriptions. Overall, it is complete enough for an agent to invoke correctly without deep schema digging.
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%, so parameters are already well-documented. The description adds only high-level context (sweeping each parameter) without explaining specific parameter semantics, which is acceptable per baseline rules.
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 clearly states the tool performs one-at-a-time sensitivity analysis by sweeping each parameter across a range while holding others at baseline, then reports how a chosen output metric responds with slope and elasticity. This specific verb+resource distinguishes it from siblings like simulate, compare_scenarios, and calibrate.
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 description implies usage context: it is for OAT sensitivity analysis and explicitly notes the pysd dependency as a prerequisite. However, it does not explicitly mention alternatives or when-not-to-use, stopping short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set connector angle and/or explicit routing waypoints
| Name | Required | Description | Default |
|---|---|---|---|
| angle | No | Connector angle in degrees | |
| points | No | Optional connector waypoint list | |
| to_var | No | Connector target variable name (used for lookup when connector_uid is omitted) | |
| from_var | No | Connector source variable name (used for lookup when connector_uid is omitted) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| angle_locked | No | Whether to preserve the explicit connector angle | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| connector_uid | No | Connector UID. Optional if from_var+to_var uniquely identify a connector. | |
| points_locked | No | Whether to preserve explicit connector waypoints |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| connector | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint: false), so the description's 'set' is consistent. However, it does not explain behavioral nuances such as whether setting angle replaces existing waypoints, or how angle_locked/points_locked interact. Adds minimal context beyond annotations.
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?
Single sentence, no redundancy, efficiently states purpose.
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?
Tool has 9 optional params with multiple lookup paths (connector_uid vs from_var/to_var) and output schema exists. Description is minimal but schema and annotations compensate. However, it fails to mention required identification strategy or side effects, so not fully complete.
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 covers all 9 parameters with descriptions (100% coverage); description adds 'and/or' combo but no additional detail. Baseline 3 is appropriate.
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?
Description: 'Set connector angle and/or explicit routing waypoints' – uses specific verb 'set' and clearly identifies the resource (connector) and the attributes being modified (angle, waypoints). This distinguishes it from sibling creation tools like add_connector.
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?
No guidance on when to use this tool versus alternatives. Description does not mention that it operates on existing connectors, nor does it contrast with add_connector or sync_connectors_from_equations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set module box visual style in the diagram view
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| font_size | No | Module label font size (e.g., 9pt) | |
| background | No | Module fill/background color | |
| font_color | No | Module label font color | |
| label_side | No | Module label position: top, bottom, left, or right | |
| module_name | Yes | Module name | |
| border_color | No | Module border/line color | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive mutation. The description adds the context that it applies to module boxes in the diagram view but does not disclose behavioral traits such as whether unspecified style properties are preserved or overwritten, or any required permissions.
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 a single, front-loaded sentence with no superfluous content. It efficiently communicates the action and target.
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?
Despite the minimal description, the presence of full schema coverage, annotations, and an output schema provide a rich context. The description clearly conveys the tool's purpose. However, it does not clarify the effect on existing style settings when only some properties are provided, which prevents a perfect score.
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 input schema covers 100% of parameters with descriptions, so the description does not need to explain them. The description adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.
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 clearly states the action (set), the target (module box visual style), and the context (in the diagram view). This clearly distinguishes it from sibling tools like set_module_view (which likely controls viewing properties) and set_connector_routing (which affects connectors).
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 description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It only implies usage context through its purpose statement, which is insufficient for an agent to make confident tool-selection decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set explicit view box geometry for a module
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | Center X | |
| y | Yes | Center Y | |
| width | Yes | Box width | |
| height | Yes | Box height | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| module_name | Yes | Module name | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| module | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds 'explicit' but does not disclose side effects, reversibility, or interaction with auto-layout behavior. Minimal additional transparency beyond annotations.
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?
One concise sentence, front-loaded with the action and target. No redundant 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?
For a simple setter, the description is adequate but lacks context about when manual view-box setting is needed vs automatic placement. Output schema exists, so return semantics are covered, but a bit more orientation would improve completeness.
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%, so the schema documents all parameters. The description does not add any parameter-specific semantics beyond the schema's existing 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?
The description uses a specific verb ('set') and resource ('view box geometry for a module'), clearly distinguishing from sibling tools like set_module_style and auto_place_module_boxes.
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?
No guidance on when to use this tool versus alternatives such as auto_place_module_boxes. The word 'explicit' hints at manual override but no explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update simulation time settings on an existing model
| Name | Required | Description | Default |
|---|---|---|---|
| dt | No | Time step | |
| stop | No | Simulation stop time | |
| start | No | Simulation start time | |
| method | No | Integration method (Euler or RK4) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| time_units | No | Time units | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| sim_specs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive; the description adds that it operates on an existing model. It does not disclose any side effects or additional behavioral context beyond the mutation.
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 a single, front-loaded sentence with no filler. It is appropriately sized for a straightforward update tool.
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 the rich schema and output schema, the minimal description is acceptable but lacks guidance on how it fits into the simulation workflow. It does not mention that these settings are used in subsequent simulate calls.
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?
All 7 parameters are fully described in the schema, so the description adds little beyond the phrase 'simulation time settings', which only partially covers parameters like 'method' (an integration method, not a time setting). Baseline 3 is appropriate.
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 clearly states the tool updates simulation time settings on an existing model. It uses a specific verb and resource, though it does not explicitly distinguish it from sibling tools like 'simulate'.
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 description provides no guidance on when to use this tool versus alternatives, such as before running a simulation. It only implies an existing model without any exclusions or workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the model and return downsampled time series with per-variable summaries (initial/final/min/max). Requires the optional pysd dependency (pip install 'stella-mcp[sim]'). Integration is Euler regardless of the model's method setting.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Variables to report (default: all stocks) | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| overrides | No | Constant parameter overrides keyed by variable name (display or underscore form) | |
| max_points | No | Maximum points per returned series | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| save_results_csv | No | Optional path to write the full results table as CSV |
| Name | Required | Description |
|---|---|---|
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and readOnlyHint=false. The description adds valuable context: the mandatory pysd dependency and that integration always uses Euler regardless of the model's configured method, which affects result interpretation. No contradiction with annotations.
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 compact at three sentences, front-loaded with the primary action. Each sentence adds unique information—purpose, dependency, and integration method—with no redundancy or filler.
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 the comprehensive input schema and existence of an output schema, the description covers the essential behavioral aspects: what it does, output format, dependency, and numerical method. It does not explain default variable selection or csv file side effects, but those are inferable from the schema, making this slightly above baseline.
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%, so all six parameters are well-documented in the schema. The description adds no parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.
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 clearly states the tool runs the model and returns downsampled time series with per-variable summaries (initial/final/min/max). This is a specific verb+resource+output description, but it does not explicitly differentiate from siblings like sensitivity_analysis or compare_scenarios.
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?
No explicit guidance is given on when to use simulate versus alternatives. The description implies it is the basic model run tool but lacks direct instructions on selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add missing dependency connectors inferred from flow and auxiliary equations
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| added | Yes | |
| existing | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructiveHint=false. The description adds valuable context by specifying 'missing', which indicates it only adds absent connectors and does not alter existing ones. It also clarifies the inference mechanism from equations, enriching the safety profile beyond the annotation defaults.
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 a single, tightly worded sentence that front-loads the action and object. The qualifier 'inferred from flow and auxiliary equations' is essential context, not redundant fluff, and there is no wasted language.
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?
The tool has only 2 optional parameters and an output schema, so the description does not need to explain return values. It covers the core behavior well, though it omits explicit prerequisites (e.g., model must exist with flows/equations). Overall, it provides enough context for an agent to use the tool correctly.
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 input schema provides complete descriptions for both optional parameters (model_id and workspace_id), so the baseline is set at 3. The description does not add any extra parameter-level guidance, such as which parameter to use in different scenarios, but the schema itself is sufficient.
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 uses a specific verb ('Add') and resource ('missing dependency connectors'), while also stating the inference source ('from flow and auxiliary equations'). This clearly distinguishes it from the sibling tool add_connector, which suggests manual connector creation.
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 description implies usage after flows and auxiliary equations are defined to fill in connector gaps, but it does not explicitly state when to prefer this over add_connector or set_connector_routing, nor does it mention any exclusions. The context is present but only implicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update auxiliary variable fields
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position | |
| y | No | Y position | |
| name | Yes | Variable name | |
| units | No | Units | |
| equation | No | Equation or constant value | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| graphical_function | No | Graphical function (lookup table) definition |
| Name | Required | Description |
|---|---|---|
| model_id | Yes | |
| auxiliary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=false and destructiveHint=false, the description should clarify update semantics (whether partial or full replacement), but it merely repeats the title. No information about what happens to unspecified fields or how the variable is identified (via name) is provided.
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 a single, front-loaded sentence with no word waste, making it maximally concise. It does not, however, provide the depth needed for a complex tool with nested objects.
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 the tool's complexity—8 parameters including a nested graphical_function object, and an output schema—a one-sentence description is insufficient. It lacks information about update behavior, required context (model_id/workspace_id), and relationship to add_aux.
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 descriptions cover 100% of parameters, including detailed explanations for model_id and workspace_id. The description adds no additional parameter meaning, but the baseline of 3 applies due to high schema coverage.
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 'Update auxiliary variable fields' with a specific verb 'update' and resource 'auxiliary variable fields', clearly distinguishing from sibling tools like add_aux and update_flow. However, it does not explicitly mention that it modifies existing variables as opposed to creating them, leaving slight ambiguity.
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 description provides no guidance on when to use this tool versus alternatives like add_aux or update_stock. There is no mention of prerequisites, such as the variable existing, or the distinction between creating and updating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update flow fields while preserving structural stock links
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position | |
| y | No | Y position | |
| name | Yes | Flow name | |
| units | No | Units | |
| equation | No | Flow rate equation | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| non_negative | No | Prevent negative values | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| graphical_function | No | Graphical function (lookup table) definition |
| Name | Required | Description |
|---|---|---|
| flow | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds a behavioral guarantee—preservation of structural stock links—which is valuable extra context not present in the annotations.
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 a single, focused sentence that conveys the core purpose and a key constraint. No wasted words.
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 an update tool with a well-described schema and an output schema present, the description sufficiently covers the essential behavior. It could elaborate on prerequisites or side effects, but none are likely necessary given the annotations and schema.
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 input schema has 100% description coverage, so every parameter is already meaningfully described. The tool description itself does not add parameter-specific semantics, so it meets the baseline but does not exceed it.
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 clearly identifies the tool as updating flow fields, with a specific resource (flows) and action (update). The additional phrase 'while preserving structural stock links' adds distinguishing scope beyond mere naming.
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 description provides clear context: use when updating flow fields, with the caveat that structural stock links are preserved. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to differentiate from sibling tools like update_stock or update_aux.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update stock fields while preserving relationships
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position | |
| y | No | Y position | |
| name | Yes | Stock name | |
| units | No | Units | |
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| non_negative | No | Prevent negative values | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. | |
| initial_value | No | Initial value |
| Name | Required | Description |
|---|---|---|
| stock | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive. The description adds the useful behavioral guarantee that relationships are preserved, which is beyond the schema and annotations. However, it does not elaborate on what 'preserving relationships' entails (e.g., whether non-specified fields are unchanged, or how model_id/workspace_id affect behavior). With annotations covering the basic safety profile, this is adequate but not rich.
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 a single, front-loaded sentence with no wasted words. It conveys the core action and a key constraint in a compact form, making it easy to scan and understand.
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 that an output schema exists (covering return values) and the input schema fully describes parameters, the description is mostly complete. It could be improved by clarifying what fields are preserved and whether missing optional parameters are left unchanged. Still, the core operational context is sufficiently described for an agent to use the tool correctly.
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 input schema has 100% description coverage for all 8 parameters, so the description does not need to repeat parameter details. It adds no additional semantic meaning beyond the schema, such as how parameters interact or which fields are commonly updated together. Baseline 3 is appropriate given high schema coverage.
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 clearly states the verb ('Update'), the resource ('stock'), and a defining scope ('while preserving relationships'). This distinguishes it from sibling tools like add_stock (creation) and update_flow/update_aux (different target types), so the purpose is unmistakable.
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 description implies the tool is for modifying existing stock fields without breaking connections, but it does not explicitly say when to use it over alternatives like add_stock or update_flow. It provides clear context (updates on stocks) but lacks explicit exclusions or alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the current model for errors and warnings
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Session-scoped model ID. Optional; defaults to the current model for this session. | |
| workspace_id | No | Opaque application workspace handle. Required by MCP 2026-07-28 clients; supported legacy stdio clients may omit it to use the process-local compatibility workspace. |
| Name | Required | Description |
|---|---|---|
| issues | Yes | |
| passed | Yes | |
| model_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds that it surfaces errors and warnings. However, it does not disclose any additional behavioral traits like whether it may be expensive or how it interacts with unsaved changes; the read-only nature is covered by the annotation.
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?
Single sentence, directly states the action and outcome. Fully front-loaded with no filler.
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?
Tool has simple semantics, read-only annotation, and an output schema to document results. The description is sufficient but could benefit from a note on when validation is appropriate (e.g., before simulation).
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 covers 100% of parameter descriptions, including model_id defaulting to current model. The description's mention of 'current model' aligns with the schema but doesn't add new semantics beyond it.
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?
Description uses specific verb 'Validate' and resource 'model', clearly indicating it checks for errors and warnings. It is distinct from sibling tools like inspect_model or read_model, which focus on examination rather than validation.
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?
No guidance on when to use validate_model versus alternatives such as build_model or simulate. The description implies 'current model' context but does not state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clearly distinct purposes, but a few close pairs (create_model vs build_model, add_variables vs add_stock/add_flow/add_aux) could cause slight confusion. Descriptions help resolve these overlaps, so overall the set is mostly unambiguous.
Tool names consistently use lowercase snake_case with verb-first patterns (list_*, add_*, update_*, delete_*). A few longer names like sync_connectors_from_equations and auto_place_module_boxes deviate from the simple verb_noun form but remain predictable and readable.
At 44 tools, the server is significantly over-scoped for the domain. Many tools could be consolidated (e.g., update_stock/update_flow/update_aux into update_variable, add_stock/add_flow/add_aux into add_variable), and the count exceeds the recommended range even for a complex system dynamics editor.
The tool surface covers the full modeling lifecycle: workspace management, model creation/loading/saving, variable CRUD, connector manipulation, module organization, diagram rendering, templates, simulation, and analysis. Minor gaps exist (e.g., no explicit delete_connector or get_single_variable), but these are workable via existing tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Structured financial modeling for AI agents: build, version, audit models, export to Excel.
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Connect AI assistants to Stellary projects, boards, documents, and governed agent workflows.
Connect AI to Stelllink to organize, access, manage and share files, links, and digital workspaces.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bradleylab/stella-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
