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

# Tools reference

> Every tool the Revilico MCP server offers for engines, files, runs, results, projects and your account, with the arguments and scope each one needs.

Each tool matches a REST endpoint and needs the same [scope](https://docs.revilico.bio/developers/authentication.md#scopes). An app only sees the tools for the permissions you allowed when you connected it, or for the scopes of its API key.

Tools return JSON in the same shape as the REST API, and errors in the same [format](https://docs.revilico.bio/developers/errors.md), so an app can read `error.code` and `error.message` and recover.

## Engines

### list\_engines

**List engines.** Lists the Revilico computational engines you can run (slug, name, family, description). Start here.

Read-only · Scope: `engines:read`

No arguments.

### get\_engine

**Describe an engine.** Describes one engine: its parameters as JSON Schema (with defaults), the input files it takes, limits, outputs and example requests. Read this before create\_run.

Read-only · Scope: `engines:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `engine` | string | Yes | Engine slug from list\_engines, e.g. "revenergy". |

### validate\_parameters

**Validate run parameters.** Checks parameters against the engine schema without running anything, and returns them with defaults filled in.

Read-only · Scope: `engines:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `engine` | string | Yes | Engine slug from list\_engines, e.g. "revenergy". |
| `parameters` | object | No | |

## Files

### upload\_file\_content

**Upload a small text file.** Uploads a text input file (e.g. SDF, MOL, XYZ or CSV of SMILES, up to 1 MB) and returns its file id for create\_run. The name must end with the format extension, e.g. "ligands.sdf".

Makes changes · Scope: `files:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | File name with extension. |
| `content` | string | Yes | The full file contents. |

### create\_upload

**Start a large file upload.** For files you can send over HTTP yourself: returns a file id and a pre-signed URL. PUT the bytes there with the returned headers within 15 minutes, then use the file id in create\_run.

Makes changes · Scope: `files:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | |
| `sizeBytes` | integer | Yes | |
| `contentType` | string | No | |

### get\_file

**Check an uploaded file.** Shows an uploaded file. Not found means the upload has not finished.

Read-only · Scope: `files:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `fileId` | string | Yes | A file\_… id. |

## Runs

### create\_run

**Start an engine run.** Starts a run and returns it with status "queued". Runs take minutes to hours and spend credits; check progress with get\_run. `parameters` must match the engine schema from get\_engine; `inputs` maps each input key to a file id. Pass projectId to add the run to a project.

Makes changes · Scope: `runs:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | A name for the run, shown in the web app. |
| `parameters` | object | No | Engine parameters, matching the engine's schema. |
| `inputs` | object | No | Input key → file id (`file_…`) from POST /v1/files. |
| `budget` | number | No | Most credits the run may spend; it is stopped beyond that. |
| `projectId` | string | No | Add the run to this project (`proj_…`); needs editor or owner on it. |
| `engine` | string | Yes | Engine slug, e.g. "revenergy". |

### get\_run

**Check a run.** Status (queued, running, succeeded, failed, cancelled), progress, timestamps, credits used and any error.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id from create\_run or list\_runs. |

### get\_run\_inputs

**Show what a run was given.** The parameters and input files a run was submitted with.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id from create\_run or list\_runs. |

### list\_runs

**List runs.** Your runs, newest first. Filter by engine and status; pass nextCursor back for more.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `engine` | string | No | Only runs of this engine slug. |
| `status` | `queued` \| `running` \| `succeeded` \| `failed` \| `cancelled` | No | Only runs with this status. |
| `limit` | integer | No | Runs per page. |
| `cursor` | string | No | `nextCursor` from the previous page. |

### cancel\_run

**Cancel a run.** Stops a queued or running run. This cannot be undone.

Makes changes · Scope: `runs:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id from create\_run or list\_runs. |

## Results and outputs

### get\_results

**Read run results.** Headline results of a succeeded run as JSON rows (one per molecule or chain), plus run-level facts. Per-atom data (charges, indices, sites) and structures are not in these rows: use get\_result\_detail with a row's index. Pass nextCursor back for more rows.

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | No | Rows per page. |
| `cursor` | string | No | `nextCursor` from the previous page. |
| `runId` | string | Yes | A run\_… id. |

### get\_result\_detail

**Read one result in full.** Everything the engine produced for one row of get\_results (the row's `index`): its full result document (e.g. atomic charges, spin densities, gradients), per-atom or per-site tables parsed from CSV, and the row's file paths for read\_run\_file.

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id. |
| `index` | integer | Yes | The row's index from get\_results (1-based). |

### list\_run\_files

**List all files of a run.** Every file the engine wrote for a run (reports, structures, per-molecule results…), with sizes and whether read\_run\_file can return the content inline. Narrow with prefix, e.g. "molecules/00001\_".

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `prefix` | string | No | Only files under this folder, e.g. `molecules/00001_water`. |
| `runId` | string | Yes | A run\_… id. |

### read\_run\_file

**Read a run file.** One file of a run by its path from list\_run\_files: the content of text files up to 256 KB (JSON, CSV, TXT, XYZ, SDF, PDB…), plus a download URL valid for 15 minutes for any file.

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id. |
| `path` | string | Yes | A path from list\_run\_files. |

### list\_outputs

**List output files.** The files a run produces and the formats each is available in.

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `runId` | string | Yes | A run\_… id. |

### get\_output

**Get a download link.** A pre-signed download URL for one output file, valid for 15 minutes.

Read-only · Scope: `data:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `format` | string | No | One of the output's formats; defaults to the first. |
| `runId` | string | Yes | A run\_… id. |
| `outputId` | string | Yes | An output id from list\_outputs. |

## Projects

### list\_projects

**List projects.** Projects (named groups of runs, also used as campaigns) you own or are a member of, with your role and run count.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `search` | string | No | Only projects whose name contains this. |
| `limit` | integer | No | Projects per page. |
| `cursor` | string | No | `nextCursor` from the previous page. |

### get\_project

**Show a project.** One project: name, description, your role, owner and run count.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | A proj\_… id from list\_projects. |

### list\_project\_runs

**List runs in a project.** Runs in a project, newest first, including other members' runs. Filter by engine and status.

Read-only · Scope: `runs:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `engine` | string | No | Only runs of this engine slug. |
| `status` | `queued` \| `running` \| `succeeded` \| `failed` \| `cancelled` | No | Only runs with this status. |
| `limit` | integer | No | Runs per page. |
| `cursor` | string | No | `nextCursor` from the previous page. |
| `projectId` | string | Yes | A proj\_… id from list\_projects. |

### create\_project

**Create a project.** Creates a project you own, to group related runs (a campaign). Pass its id as projectId to create\_run, or use add\_run\_to\_project.

Makes changes · Scope: `runs:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | |
| `description` | string | No | |

### add\_run\_to\_project

**Add a run to a project.** Adds one of your runs to a project where you are an editor or owner.

Makes changes · Scope: `runs:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | A proj\_… id from list\_projects. |
| `runId` | string | Yes | A run\_… id. |

### remove\_run\_from\_project

**Remove a run from a project.** Removes a run from a project (the run itself is kept). Needs editor or owner.

Makes changes · Scope: `runs:write`

| Argument | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | A proj\_… id from list\_projects. |
| `runId` | string | Yes | A run\_… id. |

## Account

### get\_credit\_balance

**Check credits.** The organization's credit pool: available, total and used. Credits are shared by everyone in the organization.

Read-only · Scope: `account:read`

No arguments.

### get\_usage

**Credit usage by run.** Credits used by your runs, one row per run, most recent first, with the total for the period. Filter by engine and by from/to (ISO dates; to is exclusive).

Read-only · Scope: `account:read`

| Argument | Type | Required | Description |
| - | - | - | - |
| `from` | string or string | No | Start of the period, an ISO date or date-time. |
| `to` | string or string | No | End of the period (exclusive), an ISO date or date-time. |
| `engine` | string | No | Only runs of this engine slug. |
| `limit` | integer | No | Rows per page. |
| `cursor` | string | No | `nextCursor` from the previous page. |


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