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.

These are the capabilities used inside the Phases agent. External MCP clients normally call only ask_phases; Phases selects and executes the internal tools. The previous direct-tool catalog remains available through an explicit deployment compatibility setting. 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#

Web chat and the delegated MCP agent share the engineering tool catalog below. The MCP entry point and internal lifecycle tools are listed at the end; only ask_phases is public by default.

Most of them can be switched off per workspace through the feature flag in the third 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 and Workspace limits and features.

What is actually switched on today#

Every flag in that table is on by default for every hosted workspace except two. feature.scientific_validation is off, with no workspace override anywhere in production, so inspect_validation_report and evaluate_validation_project are declared tools that no one can currently call. feature.structured_simulator_authoring is also off by default because it adds a dedicated model call; workspaces can opt in without changing their existing AI-authoring access. Both contracts are documented below because they are real and stable, not because every workspace can call them today.

Everything else is live: the four built-in simulators, Simulator Studio and the AI authoring tools, the RSW process-window compiler, engineering analysis, Python analysis and web search. If one of them refuses, the cause is almost always your role in the workspace or a missing confirmation, not the feature flag.

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.

Any of the four simulation tools, and run_simulator, can return a durable operation handle instead of a finished result. The handle survives a closed tab, a dropped connection and a new conversation. Long-running simulations explains what that handle is and how the result comes back.

Which tools a turn can see#

feature.route_control_plane is off in hosted Phases today, so the model currently sees the full feature- and role-filtered tool set on every turn. When that rollout flag is enabled, the server also narrows the tool list per turn. A conceptual question normally exposes no tools; a run comparison exposes only owned-run and deterministic-analysis tools; and a clear simulator request exposes only that simulator's preparation, execution and inspection tools. Ambiguous side-effecting requests and generic replies such as “yes” or “do it” expose no tools. Only an exact system-controlled confirmation format — the complete configuration posted by the RSW card or a server-issued custom-operation phrase — can expose its corresponding narrow tool. The execution boundary still verifies that configuration or checks the actor- and digest-bound receipt before execution. Workspace flags, your current role and confirmation gates can narrow that route further, and the server checks the same scope again immediately before a call. Text in a prompt, web page or artifact cannot widen it.

Disabling that flag is a rollback to the legacy monolithic/full-declaration path, which is what runs today. Feature, role, ownership, facade and confirmation checks still apply, but the model sees the broader feature-filtered tool set and there is no route-specific execution allowlist. It is therefore an availability fallback with a larger model-visible surface, not an equally strict security mode.

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).

There is no search, filter or pagination parameter on this tool. It returns the entire enabled built-in catalog — 2,059 grades in production — plus your workspace and session materials. That is why "list every material" is rarely the useful request. Above forty enabled grades the agent's own prompt stops carrying a full grade list and carries a material-type and family summary with counts and a handful of examples instead, so the way to reach a specific steel is to name it, name its number, or describe it. Finding your steel covers that, and Families and data sources covers what the families mean.

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.

A grade id and a composition can be supplied together, which is how "22MnB5 but with 0.30 % carbon" is loaded: the named grade is the base and your chemistry overrides it.

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.

Four things are checked before anything is calculated, and each of them ends the call. Providing no selector, or more than one, returns Provide exactly one material selector: material_id, tenant_material_id, or material_label + composition. Omitting material_source_kind returns This flow-stress material selection has no source provenance. Review and reselect the material before calculating. A value outside the three allowed ones is rejected on the enum, and a material_source_kind that does not match the selector you actually supplied returns The flow-stress material selector does not match its source provenance. The provenance is not decoration: it is how a session chemistry is prevented from being recorded as a catalog grade.

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.

All four normally return a durable operation handle rather than a finished result; see Long-running simulations.

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.

source names which definition the run is built from. Durable CCT accepts only active (the session's current material) and session; any other value fails with durable CCT requires an active immutable material. On the legacy in-process path the value is carried into the run metadata rather than enforced.

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.

case_name and description are not cosmetic. Both are fields of the strict durable admission schema, so they are part of the canonicalized input whose digest the approval is bound to. Changing either one after approval is a different request and needs another review.

Web chat always shows the rsw-params card first. On MCP, the server first expands defaults, templates, both plates and any inherited active material into one immutable effective request, then asks the host to show and approve that exact snapshot. The same snapshot is executed after acceptance. Supplying confirm_parameters=true yourself is not approval; rejected or unsupported elicitation, or any drift before acceptance, stops before the solver. See Parameter blocks.

RSW runs on a validated set of twenty bulk-property grades rather than the whole material catalog; Resistance spot welding lists them.

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.

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?".

Study orchestration is not another tool#

An explicit multi-trial request is routed into the typed study workflow rather than an extra chat tool. Generic studies cover HT, CCT, V-Gleeble and phase flow stress. A robust process-window proposal separates bounded control variables from uncertainty variables, declares constraints and a recommendation policy, and creates a deterministic Latin-hypercube sample within the 64-trial ceiling. Results rank sampled robust candidates and show Pareto and sensitivity summaries as derived evidence. Each candidate includes its coordinate-wise sampling cell, but its unsampled interior is explicitly not a certified continuous feasible region. Sensitivity here means association inside the sampled design, not causation or experimental validation.

How to actually ask for one, and how to read what comes back, is in Run a simulation study.

RSW is deliberately excluded from that generic optimizer. Its process-window foundation is a separate, maximum-32-evaluation policy compiler exposed through the two tools below.

RSW process-window tools#

These two are not authoring tools and not study tools. They compile and record an RSW policy, and they need simulator.rsw and feature.rsw_process_windows — both on for every workspace today.

Coarse screening declares electrical/thermal physics and carries only nugget-diameter or maximum-temperature criteria that thermal physics can evaluate. Refined and production-tolerance stages add mechanical and microstructure physics, so indentation-depth or expulsion-risk criteria are admitted only there. An optional experimental comparison is measurement-only and requires an exact dataset revision and digest. Every stage binds fidelity, mesh or measurement basis, physics, budget, exit criteria and immutable solver/configuration receipts. A proposal with no coarse thermal criterion, or a criterion unsupported by a stage's physics, is refused.

Proposing and approving compile and record policy only: neither action starts a simulation, experiment or generic study, and neither produces a feasible welding window. Actual RSW execution remains a separate workflow with its own exact parameter confirmation.

propose_rsw_process_window#

Compiles and persists one immutable staged RSW policy for review. Its required specification object binds the goal; exact tenant-owned upper and lower material-revision UUIDs and card digests; solver revision and physics-configuration digest; canonical parameter ranges in kA, ms and kN; exit criteria; deterministic seed; and a 6–32 evaluation ceiling. An optional measurement stage must bind one exact experimental-dataset revision and digest. The compiler checks stage ordering and admits each criterion only where the declared physics can evaluate it.

The response has needs_confirmation status and includes the complete plan, plan digest and an exact phrase of the form CONFIRM RSW PROCESS WINDOW <proposal UUID> DIGEST <SHA-256>. It has execution_started=false: persisting the proposal starts no solver, experiment or generic study.

approve_rsw_process_window#

Records approval for the exact immutable proposal selected by proposal_id and plan_sha256. In web chat, the user must send the proposal's byte-exact confirmation phrase on a later turn; yes, same-turn approval, a changed UUID or digest, and a phrase from another session fail closed. Hosted MCP requires accepted human approval from the host. The database rechecks the actor, session, workspace, current member/admin role, both feature flags, proposal ownership and digests before appending the one approval receipt.

Approval still returns execution_started=false. It records reviewed intent only and is not a solver receipt, a computed candidate set, a feasible welding window or a weld qualification. No execution adapter consumes this policy in this release.

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.

The whole idea is introduced in Custom simulators; running one someone else published is in Running a custom simulator.

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 definition so the agent can show what will run.

Returns the input schema, approved operator workflow, declared outputs, resource limits, manifest digest and authoritative trust status.

include_owned_draft is how you read back a draft you just created or edited, and it is the only way to do so through chat, because list_available_simulators lists published simulators only. It is an authoring mode: it requires the V2 authoring flags and it never reaches another user's draft.

Version 2 descriptions also assess study-schema readiness: only stable bounded numeric inputs can be candidate axes and only typed numeric metric outputs can be candidate metrics. A schema may be ready, but no generic custom-simulator study execution adapter is registered, so execution_ready_for_study and eligible remain false. The permitted study claim is exploratory. An author-declared evidence level — even experimentally_validated — is not a verified V&V certificate and cannot promote authoritative trust, eligibility or claim strength. Use the tool 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 nine 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 sit behind feature.simulator_studio and feature.ai_simulator_builder, both on by default today; 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. Custom simulators walks the same sequence as a conversation rather than as a parameter list.

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.

propose_simulator_design#

Proposes a reviewable design before any manifest exists. It takes a working name, the goal it answers, the approach including the governing physics, and optional governing_equations, inputs and outputs written as key (unit, range) — meaning lines, steps, assumptions, open_questions, and not_modelled. It writes nothing, pins no operator and compiles nothing. Web chat renders it as a review card so the physics can be corrected while correcting it is still cheap.

An optional runtime — composed, equation_model, transport_1d, generated_package, or the default undecided — selects which platform limits are quoted back alongside the design, so the boundary is stated where the decision is being made. Choosing generated_package warns immediately if this deployment cannot run generated Python, which is the cheap moment to learn it rather than after a bundle has been authored.

Leaving not_modelled empty is accepted, and answers with a warning: This design states no limits. Say what the model will not represent before building it.

author_simulator_draft#

Takes the approved design as name, goal, approach, optional runtime, inputs, outputs, and not_modelled. A dedicated schema-constrained model call generates the complete experimental V2 manifest, which is then validated, compiled, and checked against the approved design before it is saved. A manifest that drops declared inputs or outputs is rejected rather than silently simplified. The tool never publishes the draft or claims scientific validation. It requires feature.structured_simulator_authoring in addition to the two standard authoring flags; when that rollout flag is off, the existing create_simulator_draft path remains available.

create_simulator_draft#

Takes one complete manifest object with schema_version=2 and trust_status=experimental, or a from_template id from list_simulator_operators to seed the draft from a shipped worked example. 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. Prefer edit_simulator_draft for anything short of a bulk rewrite.

edit_simulator_draft#

Applies a small ordered batch of typed operations to an owned draft — add_input, update_input, remove_input, add_node, update_node, remove_node, add_output, update_output, remove_output, set_assumptions, set_resource_policy — instead of resending the whole manifest. One operation is roughly eighty bytes and two levels deep, which is far less for a model to corrupt than kilobytes of nested JSON, and a corrupted operation costs that operation rather than the model. The batch is validated as a complete manifest, so it is exactly as strict as a replacement. The response lists each applied edit in plain language, which is what makes an authoring transcript readable. There is deliberately no set_metadata: a draft manifest's name, description and classification must equal its definition row, so renaming is a definition-level operation rather than a manifest 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, in one of four modes.

Supplying none of the three runs the manifest's own default_inputs as a publication smoke test. corner_cases reports how each output moves across the corners, and returns early naming the corner that failed if one does — a placeholder value is invisible in a manifest and obvious here.

Where the answering node can sandbox in process, equation and generated-code nodes run synchronously under their declared limits. On the hosted API, which admits generated packages for a dedicated worker but never executes one itself, a test that carries an explicit input set is dispatched to that worker and the tool returns a durable operation (test_mode: true) to poll, exactly like a confirmed run. Only the modes that run without an explicit input set — run_validation_cases and corner_cases — need a sandbox-capable node; on the hosted API they come back with Validation cases of a generated package cannot be draft-tested from this node.

A draft containing a native-solver node refuses run_validation_cases and corner_cases outright with Native solver drafts require one complete default-parameter test through the durable execution path. Such a draft can still be tested with an explicit inputs object, or with no arguments at all so the manifest's default inputs are used; either way the test is dispatched as a durable operation and needs the durable runtime flags the draft's operators require.

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.

Engineering analysis tools#

These two tools read only runs owned by the current session and convert known outputs into bounded, unit-bearing engineering datasets. Both require feature.engineering_analysis, which is on for every workspace today; when it is absent or false, the declarations and application facade fail closed. They do not read arbitrary paths or accept storage URLs. Execution completion and a matching digest establish integrity, not physical validation: each result separately reports its source, execution status, scientific status, applicability and limitations. Compare and analyse runs shows both in use.

compare_runs#

Compares two owned runs with a versioned deterministic recipe.

Both runs must resolve to the same simulator type. A numerical delta is allowed only when quantity kind, unit and immutable scientific context are compatible. Known differences in material definition, solver revision, model revision or calibration revision produce an explicit incompatible result instead of a misleading delta. Exact curve axes are the default; linear interpolation must be requested and is limited to overlapping monotonic axes without categorical dimensions. The returned claims are deterministic derivations and never count as scientific validation.

run_analysis_recipe#

Runs one immutable recipe from the server allowlist over owned run data.

summary_statistics_v1 calculates finite minimum, maximum, mean, first and last values for selected quantities in one run. run_comparison_v1 performs the same governed comparison used by compare_runs for two runs. aligned_overlay_v1 returns plot-ready baseline and candidate series on an exact or explicitly interpolated shared axis, capped at 512 display points per metric with sampling disclosure. Recipe identity, version and digest travel with the output, so a standard calculation is reproducible without generated code. Use Python only when the required transformation cannot be expressed by this catalog.

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 canonical dataset snapshots from up to four explicitly selected owned runs, but its sandbox has no network access and cannot replace a physics simulator or validate a scientific model. Both flags ship off and are on for every hosted workspace today.

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.

data_json is a string of JSON text, not a JSON object: the default is the two-character string "{}", and it is forwarded to the sandbox unchanged.

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. Use either the legacy singular selector or the plural selector, never both. A shared simulator identity applies to every selected run; use the aligned identity array when runs come from different simulators. Every run is resolved through the same authenticated session before known owned artifacts are parsed into canonical quantities and units.

A singular request keeps the engineering-python-source/v1 value in inputs["source_run"]. A plural request receives an engineering-python-sources/v1 aggregate in inputs["source_runs"], with one per-run snapshot and receipt. Across all selected runs, the aggregate is capped at four runs, four datasets, 2,048 endpoint-preserving sampled rows, 64 quantities and 98,304 serialized bytes; each dataset is additionally capped at 512 rows and 16 quantities, and the builder reduces those limits deterministically when required. It includes evidence and scientific-context digests but never raw object-store paths, signed URLs or storage credentials. Per-run snapshots and the aggregate disclose source/included run, dataset, row, and quantity counts plus a truncated marker. If anything was sampled or omitted, peaks, extrema, integrals, and residual-style claims that need every source point are explicitly not qualified. The aggregate SHA-256 receipt and per-run receipts are persisted with the derived run provenance. Successful tool results retain a locator-free tuple of run version, simulator type, and snapshot SHA-256 for each source run, together with only the pinned sandbox image's SHA-256. One shared strict projector carries that evidence through live chat, saved transcripts, background replay, and admin/session history; a malformed, duplicate, oversized, or locator-bearing receipt set is discarded as a whole. 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; every source simulator run remains unchanged.

Every successful Python result is labeled origin=derived, scientific_status=not_assessed and applicable only to the supplied inputs and source datasets. Generated-code success cannot upgrade the scientific status of its inputs or outputs.

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.

Scientific validation tools#

These two tools are declared, documented and not currently enabled. feature.scientific_validation is off for every workspace, with no override anywhere in production, so a call to either one comes back saying the capability is disabled. The contract below is what would run if it were switched on; treat it as the shape of a planned capability, not as something you can use today. What Phases does validate, and how, is in How we validate.

Experimental datasets, server-generated prediction receipts, calibration projects and holdout assignments are created through the structured backend API; the agent cannot invent evidence, submit point predictions or use a successful solver run as a measurement. A prediction receipt extracts values from completed owner-scoped canonical run datasets and binds the exact run, subject, dataset, quantities, units and digests. Dataset, receipt, project, fit, model implementation and report digests bind every evaluation to exact immutable inputs. Calibration specimens cannot be reused as independent holdout evidence, including by copying them into another dataset identity.

inspect_validation_report#

Takes one required report_id UUID and reads that exact report in the active workspace. It returns a card-sized projection: model subject and implementation digest, aggregate error metrics, acceptance checks, holdout dataset identities, outcome, applicability warnings and the recommended trust status. Point-level observations, raw laboratory artifacts and internal storage details are not returned through chat. This is read-only and would be available to viewers, members and admins when the feature is enabled.

evaluate_validation_project#

Takes one required nested specification object using the public receipt-only scientific-validation request. The object names an existing project UUID, the exact project-specification and calibration-fit SHA-256 digests, one or more holdout_receipts containing an immutable prediction-receipt UUID and SHA-256, and explicit acceptance thresholds. It accepts no predicted values, point arrays or caller-authored prediction bindings.

The evaluation is an append-only member/admin action. Each receipt must belong to the active workspace, retain its original digest, match the calibration project's immutable subject, and bind evidence disjoint from the calibration specimens. It calculates holdout bias, MAE, RMSE, maximum absolute error, uncertainty coverage where evaluable, threshold checks and applicability extrapolation, then stores an immutable report. It never changes solver physics or promotes a model. A passing result is only a recommendation; a separate workspace-admin review through the backend API is required to create a trust decision.

The preparation API is deliberately separate. POST /scientific-validation/prediction-receipts takes an exact subject, experimental dataset UUID/digest, and one or more owned-run selectors naming the session, run version, simulator type, canonical dataset, axis and response keys. The server authorizes completed run ownership and subject/run identity, loads its canonical dataset, and aligns every experimental point under exact_coordinate_v1; no numerical prediction enters from the caller. GET /scientific-validation/prediction-receipts/{receipt_id} reads the immutable receipt in the active workspace. Calibration-project creation supplies calibration_receipts, and validation-report creation supplies holdout_receipts; both are UUID/SHA-256 references only.

MCP-only tools#

ask_phases is the default public tool. The four lifecycle tools remain internal or available to existing integrations using the direct-tool compatibility profile. They are not registered as tools in web chat.

ask_phases#

Delegates a request to the Phases metallurgy agent. Pass message and retain the returned product_session_id for every follow-up. turn_id identifies an exact message retry. To retrieve a durable simulation, pass operation_id with the same session and an empty message. The response includes the full answer, original results, figures, downloadable artifacts, and operations. MCP Apps hosts can display the answer and figures in the portable result viewer. Required approvals still use the host's explicit approval UI. See Use Phases from an MCP client for production and staging URLs, request examples, response fields and a connection test.

Omit product_session_id only to begin a new conversation. Operation retrieval uses an empty message and retains the existing session and operation handles. Temporary lookup outages preserve the retry delay; missing or inaccessible operations are explicit failures, not invitations to resubmit a simulation.

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. Direct-tool compatibility instructions tell the host to call it before simulation tools and skip trivial reads. Hosts using the default agent entry point call ask_phases instead.

reset_session#

Starts a fresh Phases session for an authenticated MCP caller with a resolved workspace. It has no tool-specific arguments; the MCP adapter accepts the usual product-session handle. Modern hosted callers must retain the new returned product_session_id and send it on subsequent requests. Legacy protocol-session callers also have their connection binding updated. The connection itself is not dropped. In the default agent profile, start over by omitting the old handle on a new ask_phases request; this direct lifecycle tool is not publicly exposed by default.

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, Known limits covers the cases where the honest answer is that the product will not do it, and Reporting a problem covers what to send us when neither of those fits.