itasca-mcp

Overview Schema Source Related Servers Discussions Admin

itasca_execute_task

Submit a Python script file for asynchronous execution in the Itasca engine; returns a task ID for background simulation runs and lifecycle polling.

Instructions

Submit a Python script file for asynchronous execution in the Itasca engine.

Returns a task_id immediately; the script runs in the background. Companion tools manage the lifecycle:

itasca_check_task_status: poll output, progress, and final status
itasca_interrupt_task: cancel a running task
itasca_list_tasks: browse task history For synchronous, inline execution, use itasca_execute_code instead.

While the task is cycling, itasca_execute_code shares the same main namespace in the engine's main thread, so you can inspect or modify simulation state live — probe progress, tune parameters mid-run, swap callbacks, or trigger early termination via a sentinel variable. Submit with reasonable starting values and refine as the task runs.

Console output from itasca.command() inside the script (table dumps, list output, command summaries) is captured into the task log alongside Python prints, visible through itasca_check_task_status.

Script-writing rules:

Multi-line itasca.command("""...""") batches are normalized to one engine call per command, keeping the task interruptible mid-batch. Normalization recognizes itasca.command through its import name; call it through that name directly — rebinding via intermediate variables (_it = itasca) bypasses it and logs a bridge warning.
Pass each FISH definition block (fish define / fish operator / legacy bare define, through its terminating standalone end) whole, in ONE itasca.command() string; feeding one line-by-line leaves the engine blocked in interactive FISH mode until completed manually in the GUI console. Per-line loops are fine for ordinary commands.
program call '<file>' (.p3dat / .p2dat / .dat / ...) is supported: the bridge runs the file inline, one command per engine call, so the bridge stays reachable, the task stays interruptible, and the file's output lands in the task log command by command.

Input Schema

Name	Required	Description	Default
`description`	Yes	Brief task purpose
`entry_script`	Yes	Absolute path to entry Python script in the Itasca engine workspace

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.5.1Oct 24, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so: it returns a task_id immediately, runs in the background, captures console and itasca.command() output into the task log, and stays interruptible. It further discloses the shared __main__ namespace with itasca_execute_code during cycling, and what happens on violating the FISH-block or program-call rules (engine blocked in interactive FISH mode, bridge warning).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, return behavior, and the sibling routing before the long script-writing rules, which is the right order. The scripting-rules section is dense and somewhat lengthy, but each bullet prevents a concrete failure mode rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be explained, and the description still covers the async contract, lifecycle routing, cross-tool concurrency, and script authoring constraints. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by constraining what entry_script may contain — FISH definition blocks must be passed whole in a single itasca.command() string, itasca.command must be called by its import name, and program call files are run one command per engine call. That is real added meaning for the primary parameter, though the description parameter itself is unaddressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Submit a Python script file') plus the execution mode ('asynchronous execution in the Itasca engine'), and later explicitly contrasts with itasca_execute_code for synchronous inline runs. An agent can distinguish it from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative explicitly ('For synchronous, inline execution, use itasca_execute_code instead') and maps the entire lifecycle to companion tools: check status, interrupt, list. The condition that selects each path is stated rather than inferred.

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

Deploy Server