> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every Harwell tool: what it does, its parameters, what it returns and the scope it needs.

| Tool | Scope | Description |
| - | - | - |
| [`run_unit`](#run_unit) | `harwell:runs:write` | Compile and run a unit |
| [`submit`](#submit) | `harwell:runs:write` | Submit a job of a codebase |
| [`start`](#start) | `harwell:runs:write` | Start a transaction in a codebase's region |
| [`open_terminal`](#open_terminal) | `harwell:runs:write` | Open a screen a person drives by hand |
| [`read_terminal`](#read_terminal) | `harwell:runs:read` | Read what the person did at a terminal |
| [`sql`](#sql) | `harwell:runs:read` | Run a read-only SQL statement on a kept volume |
| [`list_datasets`](#list_datasets) | `harwell:runs:read` | List the data sets of a kept volume |
| [`read_dataset`](#read_dataset) | `harwell:runs:read` | Read a data set's records |
| [`systems`](#systems) | `harwell:systems:read` | List or describe your systems |
| [`checkpoint`](#checkpoint) | `harwell:systems:write` | Label a system's current state |
| [`restore`](#restore) | `harwell:systems:write` | Move a system back to a checkpoint |
| [`delete_system`](#delete_system) | `harwell:systems:write` | Forget a system |

A call that names a `system` also needs a [systems scope](#scopes).

Parameters ending in `_zip_b64` take a directory as a base64 zip (`cd dir && zip -qr - . | base64`). Hum packs a directory path for you.

## Scopes

Each tool needs one scope. Your [organization](https://docs.metaphi.ai/account/access.md) holds Harwell's scopes, and your client lists only the tools they reach.

| Scope | Reaches |
| - | - |
| `harwell:runs:write` | `run_unit`, `submit`, `start`, `open_terminal` |
| `harwell:runs:read` | `read_terminal`, `sql`, `list_datasets`, `read_dataset` |
| `harwell:systems:write` | `checkpoint`, `restore`, `delete_system`; `run_unit`, `submit`, `start` and `open_terminal` with `system`; `read_terminal` on a terminal that holds a system |
| `harwell:systems:read` | `systems`; `sql`, `list_datasets` and `read_dataset` with `system` |

A write scope includes the read scope of the same resource.

A call outside your scopes is a tool error:

```text theme={"dark"}
<tool> needs harwell:<scope>; this credential holds <scopes held, space separated>
```

For example, `checkpoint needs harwell:systems:write; this credential holds harwell:runs:read harwell:systems:read`. A credential with no Harwell scope lists no tools, and every call ends `this credential holds no Harwell scope`. To get a scope, [request access](https://docs.metaphi.ai/account/access.md).

## The run result

`run_unit`, `submit` and `start` return one result. A result whose `status` is not `ok` is a tool error.

**Text.** The verdict on the first line, then each compile error at `file:line` with the listing, the job log, each screen sent as 24 rows of 80 characters, what programs displayed, and, with an `ORACLE/`, `oracle: passed` or what missed.

**`structuredContent`:**

| Field | Type | Description |
| - | - | - |
| `status` | string | `ok`: everything ran and every check passed. `failed`: something did not. `error`: the call could not run |
| `verdict` | string | The first line of the text |
| `diagnostics` | array | One entry per compiler message, failed step, abend, negative SQLCODE or missed check: `{severity, file, line, message, code, source}`. `severity` is `error`, `warning` or `abend` |
| `jobs` | array | Each job with `name`, `status`, `rc`, and its `steps`: `name`, `pgm`, `status`, `rc`, and for a failed step `first_error` and the tail of its output |
| `artifacts` | array | Each linked file: `uri`, `name`, `mime`, `bytes` |
| `files` | array | The sources in your tree this result speaks for |
| `source` | object | `submit` and `start`: the repository, ref, commit and path, or the tree's digest |
| `work_id` | string | The kept volume, when `return_work` was set or the call ran on a system |
| `system` | object | `name`, `head` (its state now) and `from` (its state before), when the call ran on a system |
| `lifetime` | object | How long the state this call left lives. `kind` is `call` (discarded with the call), `kept` (the volume named by `work_id`) or `system` (the system's head, until `delete_system`) |
| `error` | string | When `status` is `error`: what to fix, in one sentence |

**Resource links.** `report.json`, every listing, every step's output and every spool file, at `harwell://runs/<run>/<name>`. Read one with `resources/read`. Only your organization reads them.

`run_unit`, `submit`, `start` and `open_terminal` can run as MCP tasks for clients that support the Tasks extension. The task's result is the same result.

## run\_unit

Compile and run a [unit](https://docs.metaphi.ai/harwell/unit-format.md): compile programs, submit jobs, run a chain, or start a transaction.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `unit_zip_b64` | string | yes | The unit directory |
| `work_id` | string | no | Start from a volume a previous call kept |
| `work_zip_b64` | string | no | Start from a volume you hold, as a zip |
| `return_work` | boolean | no | Keep this run's volume and return its `work_id`. Default `false` |
| `resume` | boolean | no | Restart a chain from the job that failed |
| `system` | string | no | Run on a [system](https://docs.metaphi.ai/harwell/guides/systems.md). Needs `harwell:systems:write` |

Give at most one of `work_id`, `work_zip_b64` and `system`. With none, the run starts on a fresh volume holding the unit's `CATALOG/` and `DB/seed.sql`, discarded when the call ends.

**Returns** [the run result](#the-run-result).

## submit

Submit a job of a [codebase](https://docs.metaphi.ai/harwell/guides/codebases.md) in place.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deck` | string | yes | The job: a member of the codebase's procedure libraries, or a path to a deck in the tree |
| `repo` | string | one of | GitHub `owner/name` or an https clone URL |
| `ref` | string | with `repo` | A branch, tag or commit |
| `path` | string | with `repo` | The directory that holds `harwell.toml`. `""` for the root |
| `codebase_zip_b64` | string | one of | The codebase directory, in place of `repo` |
| `step` | string | no | One step of the deck, named as `RESTART=` names it |
| `symbols` | object | no | Symbolic parameters: `{"NAME": "value"}` |
| `work_id` | string | no | Start from a kept volume |
| `work_zip_b64` | string | no | Start from a volume you hold |
| `snapshot_zip_b64` | string | no | A snapshot to lay down on an empty volume first. Not with a volume |
| `return_work` | boolean | no | Keep the volume and return its `work_id` |
| `system` | string | no | Run on a system. Needs `harwell:systems:write`. While a terminal holds the system, the job runs on the terminal's region |

With no volume, the job starts on a fresh volume holding the site data sets and tables `harwell.toml` declares.

**Returns** [the run result](#the-run-result).

## start

Start a transaction in a codebase's region.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `transid` | string | yes | The transaction ID, as typed at the terminal. `CEMT`, `CECI` and `CEDF` are in every region |
| `screens` | array | no | One entry per attention key: `{aid, map, mapset, fields}`, or `read_terminal`'s `screens` |
| `connections` | array | no | Inbound TCP connections for the CICS sockets listener, with `transid` `CSKL` |
| `repo`, `ref`, `path`, `codebase_zip_b64` | | | As for [`submit`](#submit) |
| `work_id`, `work_zip_b64`, `snapshot_zip_b64`, `return_work` | | | As for [`submit`](#submit) |
| `system` | string | no | Run on a system. Needs `harwell:systems:write`. Refused while a terminal holds it |

**Returns** [the run result](#the-run-result).

## open\_terminal

Open a browser page where a person drives a transaction by hand at a 24 by 80 screen.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `unit_zip_b64` | string | one of | A unit. Its region is the PCT its `run.json` declares |
| `repo`, `ref`, `path` | string | one of | A codebase by repository. Every transaction it installs |
| `codebase_zip_b64` | string | one of | A codebase as a tree |
| `replay` | boolean | no | A unit's own `screens` play first. Default `true` |
| `system` | string | no | Start on a system's state and hold it while the terminal is open. Needs `harwell:systems:write` |

**Returns**

| Field | Description |
| - | - |
| `terminal` | The terminal's ID, for `read_terminal` |
| `url` | The page. Give it to the person. The link is the whole credential |
| `expires_in_s` | Seconds until the link expires |
| `transactions` | The transactions the screen offers |
| `screen` | The opening screen |
| `lifetime` | How long the terminal's state lives. `kind` is `session` (until the terminal closes or its link expires, with `expires_in_s`) or `system` (the system's head) |

## read\_terminal

Read what the person did at a terminal: the keys they pressed, the turns they marked right, and their notes.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `terminal` | string | yes | The ID `open_terminal` returned. A terminal that holds a system needs `harwell:systems:write` |

**Returns**

| Field | Description |
| - | - |
| `status` | `closed` once the person is done |
| `screens` | Every key pressed, in `cics.screens` shape. Over a codebase, the `screens` for `start` |
| `oracle` | One entry per map sent, the fields of turns marked right, `null` elsewhere. Write it as `ORACLE/screens.json` |
| `findings` | Each turn's verdict, note and maps |
| `system` | When the terminal holds a system: its `name` and `head` |

Only your organization reads a terminal it opened.

## sql

Run one read-only SQL statement against the Db2 database of a kept volume or a system.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `statement` | string | yes | A `SELECT`, `WITH` or `VALUES` statement, in Db2's dialect |
| `work_id` | string | one of | A kept volume |
| `system` | string | one of | A system's current state. Needs `harwell:systems:read` |
| `limit` | integer | no | Rows returned. Default 100, at most 1000 |

**Returns** `{statement, columns, rows, more, sqlcode}`. `sqlcode` is `0` with rows and `100` with none. A failed statement returns `error`, `sqlcode` and `sqlstate`, such as `-204` for an unknown table.

## list\_datasets

List the data sets a kept volume or system catalogs, and its Db2 tables.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `work_id` | string | one of | A kept volume |
| `system` | string | one of | A system's current state. Needs `harwell:systems:read` |
| `pattern` | string | no | A data set name pattern: `*` within a qualifier, `**` across qualifiers, `%` one character. A name with no wildcard lists it and everything under it. Default: all |

**Returns** `{pattern, datasets, tables}`. Each data set has its name, organization, RECFM, LRECL, bytes and record count.

## read\_dataset

Read a data set's records, as text and hex or decoded through a copybook.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `dsn` | string | yes | The data set name, as `list_datasets` returns it |
| `work_id` | string | one of | A kept volume |
| `system` | string | one of | A system's current state. Needs `harwell:systems:read` |
| `copybook` | string | no | The copybook's source text |
| `record` | string | with `copybook` | The 01 record to decode through |
| `copybooks` | object | no | `{MEMBER: source}` for each `COPY` in the record |
| `start` | integer | no | The first record, from 0. Default 0 |
| `limit` | integer | no | Records returned. Default 20, at most 500 |

**Returns** `{framing, record_count, start, more, records}`. Each record is `{n, text, hex}`, or `{n, fields}` with a copybook, plus the layout's `fields`. A KSDS or RRDS is refused: `REPRO` it to a sequential data set in a job.

## systems

List your organization's systems, or describe one.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `system` | string | no | A system name. Default: list all |

**Returns** For a list, `{systems}`, each with `system`, `head`, `updated`, `volume_bytes`, `checkpoints`, `terminal` and `busy`. For one system, the same plus `created`, `lineage` (the last calls that moved it) and each checkpoint's run.

## checkpoint

Label a system's current state so `restore` can bring it back. A label used before moves to the current state.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `system` | string | yes | The system |
| `label` | string | yes | The checkpoint's name, such as `before-eod` |

**Returns** The system, as `systems` describes it, and `checkpoint`.

## restore

Move a system back to a checkpoint. The state it leaves stays in its lineage. Refused while a call runs on it or a terminal holds it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `system` | string | yes | The system |
| `label` | string | yes | One of its checkpoints |

**Returns** The system, as `systems` describes it, and `restored`.

## delete\_system

Forget a system and its checkpoints. Refused while a call runs on it or a terminal holds it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `system` | string | yes | The system |

**Returns** `{status, deleted}`.

## Resources

| URI | Description |
| - | - |
| `harwell://runs/{run}/{name}` | A file a result linked: `report.json`, a listing, a step's output or a spool file |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.