---
title: MCP tool reference
summary: The tools, resources and prompts the agent interface exposes, generated from the server definition.
section: reference
order: 4
level: 2
keywords: [MCP, tools, agents, reference]
---
<!-- gyre docs: expanded Markdown of reference/mcp-tools.md (generated tables, verification numbers and chart data are written out). Base level of this page: L2 Practice; passages at another level are bracketed by 'begin level N' / 'end level N' comments and start with [LN Name]. Built from revision ceb1f4b0be. -->

See the [Agent interface guide](../guide/agents.md) for connection and workflows.

### `gyre_info`

Identify this Gyre deployment: version, source commit, device, endpoints, uptime.

### `list_presets`

List built-in cases (name, description, size estimate) under `presets`. Start here.

### `get_case_schema`

JSON Schema of a case specification (mesh, flow, discretization, solver).

### `validate_case`

Dry-run a case without solving: resolved spec, element/DOF estimate, chosen device.

`case` is a preset name or a full CaseSpec object; `overrides` are dotted paths such as
{"flow.mach": 0.6, "discretization.order": 3, "mesh.params.n_surf": 48}.

| argument | type | required | default |
|---|---|---|---|
| `case` | string or mapping | yes |  |
| `overrides` | mapping or null | no |  |

### `submit_job`

Queue a steady flow analysis and return the job record.

Names are checked when the job is accepted: an unknown output or input in
`gradients_of`, `gradients_wrt`, `error_estimate` or `adapt_output` is refused at once
(UnknownName; the hint lists the valid names, as does `interface` of `validate_case`).
Also refused: a case above the deployment's size limit (CaseTooLarge) and a full queue
(QueueFull); `gyre_info` shows the limits.
Set `gradients_of` (e.g. ["cl","cd"]) and/or `gradients_wrt` (e.g. ["alpha","mach",
"x_surface"]) to also compute total derivatives by the discrete adjoint; `alpha_deg`
is accepted in `gradients_wrt` wherever `alpha` is (the derivative is then per degree).
Set `error_estimate` (e.g. ["cd"]) for adjoint-weighted-residual error estimates.
Set `adapt_output` (e.g. "cd") together with `adapt_tolerance` (absolute, e.g. 1e-4) to
let the solver choose the polynomial degree: it is raised from the case's
discretization.order up to `adapt_max_order` until the estimated error of that output
meets the tolerance; the result is that of the final degree and its `adaptation`
section says whether the tolerance was met.
`wait_seconds` (<= 300) long-polls for completion so short jobs return in one call.

| argument | type | required | default |
|---|---|---|---|
| `case` | string or mapping | yes |  |
| `overrides` | mapping or null | no |  |
| `gradients_of` | list of string or null | no |  |
| `gradients_wrt` | list of string or null | no |  |
| `error_estimate` | list of string or null | no |  |
| `device` | string | no | `"auto"` |
| `label` | string or null | no |  |
| `wait_seconds` | number | no | `0.0` |
| `adapt_output` | string or null | no |  |
| `adapt_tolerance` | number or null | no |  |
| `adapt_max_order` | integer | no | `5` |

### `get_job`

Job state (queued/running/succeeded/failed/cancelled), progress and result summary.

`wait_seconds` (<= 300) blocks until the job finishes or the time elapses.

| argument | type | required | default |
|---|---|---|---|
| `job_id` | string | yes |  |
| `wait_seconds` | number | no | `0.0` |

### `get_job_result`

Result of a finished job.

`sections` selects parts: outputs, gradients, error_estimate, adaptation, history,
surface, case, spec, timing, provenance (default: outputs, gradients, error_estimate,
adaptation, case, timing, provenance). Arrays are summarised unless `full_arrays` is
true. Values that are not finite (a diverged solve) are null.

| argument | type | required | default |
|---|---|---|---|
| `job_id` | string | yes |  |
| `sections` | list of string or null | no |  |
| `full_arrays` | boolean | no | `false` |

### `get_job_events`

Progress events of a job (nonlinear iterations etc.) starting at sequence `since`.

| argument | type | required | default |
|---|---|---|---|
| `job_id` | string | yes |  |
| `since` | integer | no | `0` |
| `limit` | integer | no | `40` |

### `list_jobs`

Recent jobs under `jobs`, newest first; optionally filter by state.

| argument | type | required | default |
|---|---|---|---|
| `state` | string or null | no |  |
| `limit` | integer | no | `20` |

### `cancel_job`

Cancel a queued or running job.

| argument | type | required | default |
|---|---|---|---|
| `job_id` | string | yes |  |

### `get_job_artifact`

Read a file a job produced.

`name` is one of result.json (complete result), events.jsonl (progress events),
request.json, error.txt (traceback of a failed job), field.json (sampled 2-D fields
for plotting), solution.npz (checkpoint of the converged state, binary) and flow.vtu
(VTK file for ParaView). Text files are returned under `content`, paged with `offset`
and `max_chars` (`truncated` says whether more follows). Binary and large files are
described instead: `bytes`, `sha256` and `download`, the REST path from which a
program fetches the file; set `max_base64_bytes` to also receive the content as base64
when the file is not larger than that.

| argument | type | required | default |
|---|---|---|---|
| `job_id` | string | yes |  |
| `name` | string | yes |  |
| `max_chars` | integer | no | `12000` |
| `offset` | integer | no | `0` |
| `max_base64_bytes` | integer | no | `0` |

### `open_session`

Open a warm analysis session (a dedicated solver process) for repeated evaluations.

Returns the session id and its interface: the available inputs and outputs. Use
sessions for parameter sweeps, design loops and coupled analyses; close them when done.

| argument | type | required | default |
|---|---|---|---|
| `case` | string or mapping | yes |  |
| `overrides` | mapping or null | no |  |
| `device` | string | no | `"auto"` |
| `label` | string or null | no |  |

### `session_evaluate`

Set inputs (e.g. {"alpha_deg": 3.0, "mach": 0.55}), converge the flow, return outputs.

Solves are warm-started from the previous state, so nearby evaluations are cheap.
If `converged` is false the outputs are those of the iterate the solve ended at; the
session keeps its last converged state, and gradients / error estimates are refused
until an evaluation converges again.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `inputs` | mapping or null | no |  |
| `outputs` | list of string or null | no |  |

### `session_gradients`

Exact total derivatives d(of)/d(wrt) at the session's current converged state.

`wrt` may contain flow parameters and "x_surface" (shape sensitivities at every
surface node, summarised unless `full_arrays`); `alpha_deg` is accepted wherever
`alpha` is and returns the derivative per degree. mode: auto | adjoint | direct.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `of` | list of string or null | no |  |
| `wrt` | list of string or null | no |  |
| `mode` | string | no | `"auto"` |
| `full_arrays` | boolean | no | `false` |

### `session_error_estimate`

Adjoint-weighted-residual discretization-error estimate for outputs `of`.

Returns the estimate, a corrected value and per-element indicators (summarised).

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `of` | list of string | yes |  |

### `session_adjoint`

Reverse (adjoint) total product at the session's converged state: the coupled-adjoint
building block.

Returns `derivatives[input] = (d outputs / d inputs)^T seeds` with one flow-adjoint
solve, whatever the number of seeded outputs. `seeds` maps output names to cotangents:
a number for a scalar output (e.g. {"cl": 1.0}) and, for the surface loads
`f_surface`, an array with one row per surface node (the shape is `interface.outputs.
f_surface.shape` of `open_session`; `session_surface` gives the nodes). `wrt` selects
inputs (default: all): flow parameters and `x_surface` (the result is then the
sensitivity with respect to every surface-node displacement, summarised unless
`full_arrays`); `alpha_deg` is accepted wherever `alpha` is. In a coupled
aero-structural adjoint the structural solver supplies the `f_surface` seed and
receives the `x_surface` product. Refused (RuntimeError) while the last evaluation did
not converge. `info` reports the linear solve (iterations, converged).

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `seeds` | mapping | yes |  |
| `wrt` | list of string or null | no |  |
| `full_arrays` | boolean | no | `false` |

### `session_surface`

Surface nodes of the session's case: `coordinates` (one row per node, the nodes
that the input `x_surface` displaces and on which `f_surface` acts), the current
`displacement` and `nodes`. Arrays are summarised unless `full_arrays`.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `full_arrays` | boolean | no | `false` |

### `session_state`

Current inputs of a session, whether a flow state exists (`solved`), whether the
last evaluation converged (`converged`) and the residual norm of the kept state.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |

### `get_session`

A session's case, device, counters and `interface` (inputs with shapes and current
values, outputs); `commands` lists what `session_command` accepts when the solver
process reports it.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |

### `session_command`

Run any command of the session's solver process (generic pass-through).

For commands without a dedicated tool: `distributions` (wall cp / cf), `field`, and
whatever else the session's solver process implements - residual evaluation at the
current or other inputs, forward (tangent) total products, state download and
upload, checkpoint and restore, reverting a failed evaluation (`commands` of
`get_session` lists them when the session reports them). `arguments` is the JSON
object of the command's keyword arguments. For a command that takes bytes (a state
or checkpoint to upload) pass them as `data_base64`; a command that returns bytes
is answered with `bytes` and `sha256`, plus `base64` when the result is not larger
than `max_base64_bytes`. An unknown command is refused with UnknownCommand. Arrays in
a JSON result are summarised unless `full_arrays`.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |
| `command` | string | yes |  |
| `arguments` | mapping or null | no |  |
| `data_base64` | string or null | no |  |
| `max_base64_bytes` | integer | no | `0` |
| `full_arrays` | boolean | no | `false` |

### `list_sessions`

Open sessions (under `sessions`) with their case, device, call counts and idle time.

### `close_session`

Close a session and free its solver process.

| argument | type | required | default |
|---|---|---|---|
| `session_id` | string | yes |  |

### `list_meshes`

Meshes in this deployment's mesh store, under `meshes`: name, size, element count,
geometry order, boundary groups (faces per group), bounding box, sha256.

### `upload_mesh`

Store a mesh file so that cases can use it; returns its summary.

`name` is a bare file name ending in .msh (Gmsh MSH 2.2 / 4.1 ASCII, quadrilaterals or
hexahedra, a named physical group on every boundary) or .npz (Gyre mesh). `content` is
the file: its text with encoding "text", or base64 with encoding "base64" (required
for .npz). The file is validated in full; an unusable file is refused (InvalidMesh,
with the reason) and not stored. Then use
mesh = {"generator": "file", "params": {"path": name}} in a case and give a boundary
condition for each group listed under `boundaries` in discretization.boundaries.

| argument | type | required | default |
|---|---|---|---|
| `name` | string | yes |  |
| `content` | string | yes |  |
| `encoding` | string | no | `"text"` |

### `inspect_mesh`

Summary of a stored mesh: bytes, sha256, dim, elements, geometry_order, nodes,
boundaries (faces per group), bounding_box and quality numbers.

| argument | type | required | default |
|---|---|---|---|
| `name` | string | yes |  |

### `delete_mesh`

Remove a mesh from the store (jobs still queued on it will fail).

| argument | type | required | default |
|---|---|---|---|
| `name` | string | yes |  |

### `list_pipelines`

Declarative pipelines of this deployment, under `pipelines`.

Each entry has name, description, parameters, stages and `runnable`. A pipeline with
`runnable: false` cannot be started through the service; its `reason` says why (e.g. it
contains shell stages, which only the operator may enable).

### `run_pipeline`

Start a pipeline run (a DAG of cached stages: solves, sweeps, gates, reports).

Returns the run id; poll `get_pipeline_run`, stop it with `cancel_pipeline_run`.
Unchanged stages are reused from the cache unless `force` is true. `params` override
the pipeline's parameters (`parameters` of `list_pipelines`; any other name is refused
with UnknownParameter); strings stay strings ("123" is not turned into a number). Only
pipelines that `list_pipelines` reports as `runnable` are started; runs of the same
pipeline execute one after another, and the deployment caps the number of active runs
(TooManyPipelineRuns).

| argument | type | required | default |
|---|---|---|---|
| `name` | string | yes |  |
| `params` | mapping or null | no |  |
| `force` | boolean | no | `false` |

### `get_pipeline_run`

Status and progress of a pipeline run.

`status` is running, succeeded, failed, cancelled or interrupted; `stages` maps every
stage to pending / running / succeeded / cached / failed / skipped / cancelled;
while it runs, `current_stage` and `stage_log_tail` show what the running stage is
doing (a solve logs each nonlinear step) and `phase` is "waiting" while another run of
the same pipeline holds the work directory. `record` has per-stage outputs and
timings. `wait_seconds` (<= 300) blocks until the run ends or the time elapses.

| argument | type | required | default |
|---|---|---|---|
| `run_id` | string | yes |  |
| `wait_seconds` | number | no | `0.0` |

### `list_pipeline_runs`

Recent pipeline runs under `runs`, newest first (id, pipeline, status, times).

| argument | type | required | default |
|---|---|---|---|
| `limit` | integer | no | `20` |

### `cancel_pipeline_run`

Cancel an active pipeline run (the engine and the stage it is running are
terminated); returns the run's status, `cancelled` once its processes have ended.
Stages that had completed stay in the stage cache. A finished run is returned as is.

| argument | type | required | default |
|---|---|---|---|
| `run_id` | string | yes |  |

### `get_pipeline_artifact`

Files a stage of a pipeline run produced.

Without `name`: the list of file names under `artifacts` (e.g. report.md and
report.json of a report stage; result.json, flow.vtu and solution.npz of a solve
stage; sweep.json; orders.json; stage.log). With `name`: the file; text is returned
under `content` (paged with `offset` / `max_chars`), binary files are described by
`bytes`, `sha256` and the REST path `download`. Available for stages that succeeded
(or were served from the cache) in this run, until a later run replaces their files.

| argument | type | required | default |
|---|---|---|---|
| `run_id` | string | yes |  |
| `stage` | string | yes |  |
| `name` | string or null | no |  |
| `max_chars` | integer | no | `12000` |
| `offset` | integer | no | `0` |

### `search_docs`

Full-text search of the Gyre documentation served with this deployment.

Returns ranked pages with title, section, depth level, summary and a path for
`read_doc`. Covers overview, user guide, examples, verification evidence, software
engineering and the mathematical / numerical methods.

| argument | type | required | default |
|---|---|---|---|
| `query` | string | yes |  |
| `limit` | integer | no | `6` |

### `read_doc`

Read a documentation page as Markdown (math in LaTeX). `path` comes from `search_docs`
(or use "llms.txt" for the site index). Long pages are paged with `offset`.

| argument | type | required | default |
|---|---|---|---|
| `path` | string | yes |  |
| `max_chars` | integer | no | `12000` |
| `offset` | integer | no | `0` |

## Resources

| URI | description |
|---|---|
| `gyre://presets` | Built-in case presets |
| `gyre://schema/case` | JSON Schema of the case specification |

## Prompts

| name | description |
|---|---|
| `analyze_case` | Run a case, check convergence, report outputs with error estimates. |
| `gradient_check` | Verify adjoint gradients against finite differences in a session. |