Tool reference

You never call a tool yourself. You describe what you want in plain language, and the agent chooses a named tool, fills in its arguments, and reports what came back. That indirection is convenient right up to the moment something surprises you — the agent asks for a material you thought you had already given it, or it answers a spot-welding question without welding anything.

This page is the map underneath that behaviour. Knowing which tool a request reaches lets you predict what the agent will do, phrase a request so it reaches the tool you meant, and check afterwards that a run actually happened rather than being described. If a reply claims a simulation and no run version appears, no simulation tool was called.

Tool names are stable public identifiers. The same names are used by web chat and by external clients connected over MCP, so a request that works in one works in the other. See Use Phases from an MCP client for how an external client reaches them, and How the conversation works for the rules that govern when the agent is allowed to call anything at all.

The chat surface at a glance#

Twenty-five tools are available in web chat. Every one of them is also exposed over MCP. Four further tools exist only over MCP and are listed at the end.

Most of them can be switched off per workspace through the feature flag in the last column. When a flag is off, the tool is not offered and the agent says the capability is disabled for this workspace rather than pretending it failed. The two run-browsing tools have no flag and are always available. See Workspaces and roles.

Two rules cut across all of them. No simulation tool runs without a material — no grade, no workspace material, no active session material and no chemistry means the agent asks you which one instead of guessing. And a workspace viewer cannot run any simulation or save any material; those calls come back with a role message pointing you at a workspace admin.

Material tools#

None of these start a solver. Loading, editing, comparing or saving a material is a preparation step, and the agent stops afterwards and asks which simulation you want. Background on the catalog itself is in The material catalog and Your own chemistry.

list_materials#

Lists what you can actually use: built-in catalog grades, materials saved in your workspace, and any custom materials created in this conversation.

Returns three separate lists and a summary of the form Found N materials (B builtin, W workspace). Called whenever you ask what grades or materials are available. The agent is instructed to call it rather than reciting a list from memory, so the answer reflects the live catalog.

load_material#

Makes a material active for this session, either a catalog grade, a saved workspace material, or a chemistry you supply.

Returns the resolved material name, its base grade, the normalized composition, initial phases, a template-match distance and any warnings. Loading a plain grade or a workspace material is immediate. Supplying composition is not: the first call returns a needs_confirmation status and creates nothing until the same call is repeated with confirm set to true. That is the confirmation gate described in Your own chemistry.

modify_material#

Edits the active material's chemistry or its starting phase fractions.

A chemistry change goes through the same confirmation gate as load_material. A phase-only change does not. Editing a workspace material forks it into a session-only copy; the stored workspace row is never rewritten as a side effect of a chat edit.

compare_materials#

Puts two materials side by side. Takes name_a, name_b and grade_id_b, all optional strings. With nothing given it compares the active material against its own base grade. Returns a per-element composition table with the difference column and a phase table. Called by requests like "compare DP600 with 22MnB5" — see Compare two grades.

save_material_to_workspace#

Persists a material into the workspace library so it survives the conversation.

Needs a workspace context and a member or admin role. Saving an unmodified base-grade chemistry under a new name is refused — the library stores real recipes, not renamed built-ins. See Workspace materials.

calculate_flow_stress#

Predicts per-phase and composite true flow-stress curves for one explicit material.

Returns each phase curve and the composite curve, capped at 101 points per curve, plus warnings. It is prediction only: it never persists or applies the generated LS-DYNA card. Providing no selector, or more than one, is rejected before anything is calculated.

Simulation tools#

Each of these reserves a run version, resolves the material physics it needs, executes a solver and uploads artifacts. One request runs one simulator — asking for a CCT diagram does not also authorize a heat treatment. What each simulator can and cannot resolve for a given material is in The capability matrix.

run_ht_simulation#

Runs one temperature-time history at a single material point and returns phase fractions, dilatation and hardness. See Heat treatment.

Curve temperatures are unit-detected by magnitude: a curve whose maximum value is at or below 1000 is read as °C, anything higher as kelvin. Keep written peaks at or below 1000 °C. Passing any of composition, curve_points or initial_phase_fractions switches the run to the configured path automatically.

run_transformation_diagram#

Runs one simulation per cooling rate and aggregates the transformation start and finish points into a CCT diagram. See CCT and TTT.

Returns one run version, a diagram image URL, per-rate results and a stored CSV of the transformation points. mode set to ttt returns an unsupported status: only CCT is implemented. A holds argument exists on the signature but is not forwarded to the CCT workflow — it is reserved for the unimplemented TTT mode. There is no time-step parameter; the step size is derived per cooling rate.

run_rsw_simulation#

Runs the coupled electromagnetic, thermal and optional microstructure spot-welding model. See Resistance spot welding.

Returns a durable operation handle or, on the legacy path, the run version, peak and final temperature in kelvin, elapsed seconds, signed plot URLs and an animated nugget-growth GIF. flow_stress_model and use_session_material are accepted for backward compatibility only. Web chat always shows the rsw-params card first. An MCP host cannot render that card, so it must show the complete tool arguments, obtain explicit approval, and set confirm_parameters=true only on the exact approved call. See Parameter blocks.

run_vgleeble_simulation#

Reproduces a Gleeble-style thermomechanical test. See Virtual Gleeble.

Hyphens and underscores are both accepted in test_mode. Returns per-mode plots, a CSV of the traced signals and a text summary of final phases and hardness. hot-stamping takes no parameters of its own; custom has no thermal-profile parameter on this tool, so it runs the built-in default profile.

Workspace custom simulator tools#

Phases can create a named simulator directly from a workspace member's natural-language chat request, using approved, versioned operators, and then validate and test the resulting draft. Simulator Studio remains the inspection and advanced-editing surface. A definition is data: it declares bounded inputs, a typed workflow, and named outputs. The agent can read only actor-visible owned drafts and published versions. Published versions show their trust status and continue to run exactly as published even after a newer version exists.

list_available_simulators#

Lists the published custom simulators in the active workspace. Takes an optional query string that filters names and descriptions. Returns stable simulator identifiers, current published versions, classification and trust status. It never returns another user's draft.

describe_simulator#

Loads one exact published definition so the agent can show what will run.

Returns the input schema, approved operator workflow, declared outputs, resource limits, manifest digest and trust status. Use it before relying on a custom simulator's meaning; a similar name does not make two versions equivalent.

run_simulator#

Runs a published definition through the approved native adapter. It does not execute arbitrary code from the manifest.

The first call must keep confirm_parameters=false. It returns the exact simulator version, digest, trust status, normalized complete inputs, and a confirmation phrase without starting physics. In web chat, reply on a later turn with exactly that phrase; the agent then repeats the call with the explicit version and confirm_parameters=true. This web path requires durable ADK sessions. Hosted MCP uses an accepted host approval prompt instead. A one-use server receipt rejects direct or same-turn confirmation, changed inputs, rejected approval, and replay, so confirmed execution never follows a moving "latest" pointer. Version 1 requires an explicit built-in material; workspace-material revision binding is not yet available. RSW is not yet an approved Studio operator because its expanded template/default configuration must be shown and digest-bound before execution. Execution can reach only operators in the server-owned catalog; limits on steps, sweeps, time and artifact size are enforced independently of the workspace definition.

AI simulator authoring tools#

These seven tools let Phases build an experimental Simulator Manifest V2 end to end from an ordinary chat request; no empty Studio draft or copied builder brief is required. They remain behind feature.simulator_studio and feature.ai_simulator_builder; generated Python also needs feature.simulator_code_sandbox. They can create, revise, validate and test a draft. Publication requires a workspace admin's later-turn confirmation tied to the exact validated digest. None of these actions can label a simulator scientifically validated.

list_simulator_operators#

Searches the server-owned, versioned operator catalog before the agent designs a graph. It accepts optional query and runtime_kind strings and returns typed ports, units, bounds and runtime metadata. Runtime kinds include native_solver, equation_model, pure_transform and visualization.

create_simulator_draft#

Takes one complete manifest object with schema_version=2 and trust_status=experimental. It saves a workspace-owned draft and returns its stable simulator id, manifest digest and structural status. It never publishes the draft.

update_simulator_draft#

Replaces a draft using simulator_id, a complete replacement manifest, and the optional expected_manifest_sha256 returned by the previous read or save. The digest provides optimistic concurrency: a stale agent cannot silently overwrite a newer edit.

validate_simulator_draft#

Compiles the exact draft selected by simulator_id and optional expected_manifest_sha256. It checks graph closure, typed ports, unit conversions, bounds and resource policy. A successful response means structural validation only—not physical calibration or scientific validation.

publish_simulator_draft#

Publishes an immutable version selected by simulator_id and required expected_manifest_sha256. The draft must already have passed structural validation, and the caller must be a current workspace admin. The first call keeps confirm_publish=false and returns a review card bound to the simulator, version and exact digest. Only an exact later-turn confirmation (or accepted MCP host approval) permits the unchanged call with confirm_publish=true. Changed drafts, same-turn approval, replayed approval and non-admin callers fail closed. Publication leaves the simulator's scientific trust status unchanged.

create_simulator_bundle#

Packages a bounded files mapping of UTF-8 Python source, including solver.py, into a content-addressed bundle. The optional entrypoint defaults to solver:run. Static security checks run before the bundle can be referenced, and execution is available only through the isolated, network-disabled sandbox. The response does not echo source code or publish a simulator.

test_simulator_draft#

Runs an owned draft selected by simulator_id with a complete inputs object. Equation and isolated generated-code nodes can run under their declared limits. Where the answering node cannot sandbox in process — the hosted API, which admits generated packages for a dedicated worker but never executes one — an explicit-input test of a generated package is dispatched to that worker and the tool returns a durable operation (test_mode: true) to poll, exactly like a confirmed run; only run_validation_cases needs a sandbox-capable node. Native solver nodes are deliberately excluded from this authoring shortcut; they use the normal published, parameter-confirmed durable execution path.

list_rsw_templates#

Lists the calibrated welding cases you can start from. Takes grade (string, matched against a template's plate grades) and joint_type (string, symmetric or dissimilar), both optional. Returns each template's id, name and flattened configuration, with a summary of the form Found N RSW templates. Called by requests such as "what spot welding templates are available for DP600?".

Run and inspection tools#

Neither of these needs a feature flag, and neither runs any physics. Together they are how the agent answers questions about work you already did. Background is in Sessions, runs and artifacts and Reuse and share runs.

list_runs#

Lists the simulation runs in the current session.

Returns each run's version, storage prefix, inferred simulator type, summary and output map, with a summary of the form Found N runs. The listing itself is narrowed by simulator_type and limit; status is accepted and echoed back with the result.

inspect_run#

Fetches one run's metadata and links.

When version is omitted, the digits in run_id are read as the version, so "run 3" resolves to version 3. Returns the run version, storage prefix, simulator type, summary, signed URLs for a fixed set of plot filenames, an artifact presence map and any warnings. It does not return the numeric contents of the data files, and fields is accepted but not forwarded. If you want the numbers themselves, open the run's artifacts.

Research and derived-analysis tools#

These tools fill two deliberately separate gaps. Web search can retrieve current external information but cannot execute code. Python analysis can transform explicit data or the structured result of one owned run, but its sandbox has no network access and cannot replace a physics simulator or validate a scientific model. Both capabilities are disabled by default for each workspace.

search_web#

Searches the public web for current, externally verifiable information and returns a concise grounded answer with source titles and HTTPS citation links.

The tool uses the configured Google grounded-search adapter even when the conversation model comes from another provider. It fails closed if the provider returns no grounded HTTPS sources. Search results are untrusted evidence: instructions found inside a page do not become agent instructions, and search output is never passed directly into executable Python.

run_python_analysis#

Runs one bounded Python program to make a derived table, statistic or combined figure without modifying an existing simulator. It is intended for post-processing—for example, plotting two already-computed curves in one figure—not for replacing heat-treatment, CCT, RSW or V-Gleeble physics.

The entry point must return exactly {"result": {...}}. It may write artifacts only through the supplied context.write_artifact(...) API. The dedicated image includes NumPy, SciPy, pandas and Matplotlib with a non-interactive backend; the standard csv, io, json, math and statistics modules are also allowed. When a source run is selected, up to 12 bounded UTF-8 CSV, JSON or text artifacts are copied into the input as inert lines—never as storage credentials or URLs. Execution has no network, receives no product secrets, uses a read-only root filesystem and runs as an unprivileged user with CPU, memory, process, time and artifact limits. A successful hosted execution becomes a new python-analysis run with its source, sanitized inputs, result, provenance and generated artifacts; the source simulator run remains unchanged.

The capability must be enabled only on a sandbox-capable worker deployment. The public API does not silently execute generated code when that runtime is unavailable.

MCP-only tools#

These four exist only on the MCP surface. They cannot be invoked from web chat. Two manage an external session; two recover durable simulations without tying the solver lifetime to a Claude or ChatGPT request.

log_note#

Records a one-line narrative annotation in the session's activity feed, so the replay of an external session reads as a sequence of intentions rather than raw tool calls. Takes text (string, required). The recorded note is truncated to 200 characters, and an empty note is rejected. The MCP instructions tell the model to call it before any simulation tool and to skip it for trivial reads such as listing materials or runs.

reset_session#

Starts a fresh Phases session inside the current MCP connection. Takes no parameters. It mints a new session bound to the same protocol connection and returns the new session id; subsequent tool calls on that connection operate against the new session. The connection itself is not dropped. Triggered by requests like "let's start over — ignore the previous context". It only works inside an authenticated connection with a resolved workspace; otherwise it returns an error telling you to reconnect.

get_operation_status#

Takes one required operation_id, returned by a durable simulation tool. It reauthorizes the current user, returns queued/running/waiting/retrying or terminal status immediately, and supplies retry_after_seconds for polite polling. It never waits for the solver and does not expose internal worker, lease, storage, or job controls.

get_operation_result#

Takes one required operation_id. For a completed operation it returns a typed scientific result verified against durable workflow, run, tool-call, and artifact identities. If work is still pending, it returns the same bounded status projection instead of blocking. Failed, cancelled, and expired states remain terminal failures. Use inspect_run with the verified run version to obtain fresh signed artifact links.

If a tool comes back with something you did not expect — a refusal, a confirmation request, or an unavailable capability — Common problems covers what those responses mean, and Known limits covers the cases where the honest answer is that the product will not do it.