> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/mcp-tool-reference.md).

# MCP Tool Reference

Use the MCP tool catalog to find the operation for your task. Discover the connected server’s tools before making calls, because availability can depend on permissions and configuration.

![Call a discovered read-only tool](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FnwYFNwmTuUrz6pPFfUiK%2Fmcp-tool-reference.png?alt=media)

Confirm projects\_list is available through tools/list first. Read its returned projects and pagination information, then use a returned project ID in subsequent calls.

<details>

<summary>Copy the example</summary>

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "projects_list",
    "arguments": {"page_size": 10}
  }
}
```

</details>

## Before you begin

An authenticated MCP client and access to the target resources.

## MCP reference terminology

| Term           | Definition                                                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP server     | A server that exposes tools and other supported capabilities through Model Context Protocol. Discover the catalog available to the authenticated client.                  |
| Tool discovery | Retrieval of the available tool names, descriptions, and input schemas. Use the current discovered schema instead of guessing an operation name.                          |
| Tool argument  | A value supplied when calling a tool. It must match that tool’s exposed input schema and refer to accessible resources.                                                   |
| Tool result    | The returned data or error from a tool operation. The agent should base its report on this result rather than assuming the call succeeded.                                |
| Read-only mode | A server configuration that limits available operations to supported non-mutating capabilities. Discover the actual tool set; execution and mutation tools can be absent. |
| Dry run        | A supported preview or validation option that avoids applying the selected change. Its scope belongs to the specific operation; it is not a universal parameter.          |

## Find an MCP tool

1. Discover the server’s available tools.
2. Read the selected tool’s schema and provide its required arguments.
3. Inspect the tool result for success or error before continuing.

The client uses an available MCP operation with the correct argument contract.

## Behavior and limitations

This catalog describes supported tool contracts; the connected server’s discovery response determines current availability. Some tools run models or change external state. Do not assume a REST payload has the same field names as its MCP equivalent.

## Tool contracts

Discover tools on the connected server before using this catalog. Required permissions and current server configuration determine availability.

### `server_info`

Returns the server version, mode, and capability flags.

**Available in read-only mode:** Yes.

This tool has no arguments.

### `whoami`

Returns the authenticated user's profile, active organization, and paginated org memberships.

**Available in read-only mode:** Yes.

| Argument    | Required | Type        | Default |
| ----------- | -------- | ----------- | ------- |
| `cursor`    | No       | str \| None | None    |
| `page_size` | No       | int \| None | None    |

### `switch_org`

Sets the active organization for the session.

**Available in read-only mode:** Yes.

| Argument | Required | Type | Default |
| -------- | -------- | ---- | ------- |
| `org_id` | Yes      | str  | None    |

### `projects_list`

Lists projects accessible to the authenticated user in the active organization.

**Available in read-only mode:** Yes.

| Argument     | Required | Type         | Default |
| ------------ | -------- | ------------ | ------- |
| `cursor`     | No       | str \| None  | None    |
| `page_size`  | No       | int \| None  | None    |
| `owned_only` | No       | bool \| None | None    |

### `projects_run`

Executes a published project with the given inputs and returns the run output.

**Available in read-only mode:** No.

| Argument     | Required | Type               | Default |
| ------------ | -------- | ------------------ | ------- |
| `project_id` | Yes      | str                | None    |
| `inputs`     | Yes      | dict\[str, object] | None    |
| `version`    | No       | int \| None        | None    |
| `verbose`    | No       | bool \| None       | None    |

### `projects_create`

Creates and publishes a new project from a natural-language description.

**Available in read-only mode:** No.

| Argument      | Required | Type | Default |
| ------------- | -------- | ---- | ------- |
| `description` | Yes      | str  | None    |

### `connections_list`

Lists previously-authorized integration connections in the active org.

**Available in read-only mode:** Yes.

| Argument      | Required | Type        | Default |
| ------------- | -------- | ----------- | ------- |
| `provider_id` | No       | str \| None | None    |
| `cursor`      | No       | str \| None | None    |
| `page_size`   | No       | int \| None | None    |

### `catalog_list`

Lists StackAI integration providers, their actions, and their triggers.

**Available in read-only mode:** Yes.

| Argument             | Required | Type                      | Default |
| -------------------- | -------- | ------------------------- | ------- |
| `provider_id`        | No       | str \| list\[str] \| None | None    |
| `expand`             | No       | list\[str] \| None        | None    |
| `include_deprecated` | No       | bool \| None              | None    |

### `projects_edit`

Edits an existing project's draft via natural language or a structured patch.

**Available in read-only mode:** No.

| Argument       | Required | Type                  | Default |
| -------------- | -------- | --------------------- | ------- |
| `project_id`   | Yes      | str                   | None    |
| `publish`      | No       | bool \| None          | None    |
| `description`  | No       | str \| None           | None    |
| `direct_patch` | No       | list\[NodeOp] \| None | None    |
| `dry_run`      | No       | bool \| None          | None    |

### `files_upload`

Uploads a file inline (base64) and returns a signed URL usable in project inputs.

**Available in read-only mode:** No.

| Argument         | Required | Type                | Default |
| ---------------- | -------- | ------------------- | ------- |
| `filename`       | Yes      | str                 | None    |
| `content_base64` | Yes      | str                 | None    |
| `purpose`        | No       | FilePurpose \| None | None    |
| `mime_type`      | No       | str \| None         | None    |

### `files_create_upload_url`

Requests a presigned PUT URL so the client can upload large files out of band.

**Available in read-only mode:** No.

| Argument       | Required | Type                         | Default |
| -------------- | -------- | ---------------------------- | ------- |
| `filename`     | Yes      | str                          | None    |
| `byte_length`  | Yes      | int                          | None    |
| `content_hash` | Yes      | str                          | None    |
| `purpose`      | No       | PresignedFilePurpose \| None | None    |
| `mime_type`    | No       | str \| None                  | None    |

### `files_finalize_upload`

Finalizes a presigned upload and returns a projects\_run-ready signed URL.

**Available in read-only mode:** No.

| Argument  | Required | Type | Default |
| --------- | -------- | ---- | ------- |
| `file_id` | Yes      | str  | None    |

### `projects_import`

Creates a new draft project from an exported workflow JSON.

**Available in read-only mode:** No.

| Argument        | Required | Type               | Default |
| --------------- | -------- | ------------------ | ------- |
| `workflow_json` | Yes      | dict\[str, object] | None    |
| `project_name`  | No       | str \| None        | None    |
| `folder_id`     | No       | str \| None        | None    |

### `projects_edit_ui`

Patches a project's UI options without modifying the flow graph.

**Available in read-only mode:** No.

| Argument     | Required | Type               | Default |
| ------------ | -------- | ------------------ | ------- |
| `project_id` | Yes      | str                | None    |
| `updates`    | Yes      | dict\[str, object] | None    |
| `publish`    | No       | bool \| None       | None    |

### `projects_get`

Fetches a project's flow as a node-centric, paginated subgraph.

**Available in read-only mode:** Yes.

| Argument     | Required | Type                                   | Default |
| ------------ | -------- | -------------------------------------- | ------- |
| `project_id` | Yes      | str                                    | None    |
| `version`    | No       | Literal\['published', 'draft'] \| None | None    |
| `cursor`     | No       | str \| None                            | None    |
| `page_size`  | No       | int \| None                            | None    |
| `verbose`    | No       | bool \| None                           | None    |

### `projects_get_corrections`

Re-validates a project's draft and returns every action-parameter correction, paginated.

**Available in read-only mode:** Yes.

| Argument     | Required | Type        | Default |
| ------------ | -------- | ----------- | ------- |
| `project_id` | Yes      | str         | None    |
| `cursor`     | No       | str \| None | None    |
| `page_size`  | No       | int \| None | None    |

### `projects_validate`

Runs every pre-flight check against a project's draft and returns paginated findings.

**Available in read-only mode:** Yes.

| Argument          | Required | Type                                    | Default |
| ----------------- | -------- | --------------------------------------- | ------- |
| `project_id`      | Yes      | str                                     | None    |
| `severity_filter` | No       | Literal\['all', 'errors\_only'] \| None | None    |
| `cursor`          | No       | str \| None                             | None    |
| `page_size`       | No       | int \| None                             | None    |

### `projects_validate_flow_json`

Runs the project validators against a raw flow JSON payload without saving it.

**Available in read-only mode:** Yes.

| Argument          | Required | Type                                    | Default |
| ----------------- | -------- | --------------------------------------- | ------- |
| `flow_json`       | Yes      | dict\[str, object]                      | None    |
| `severity_filter` | No       | Literal\['all', 'errors\_only'] \| None | None    |
| `cursor`          | No       | str \| None                             | None    |
| `page_size`       | No       | int \| None                             | None    |

### `runs_get`

Fetches the per-node execution trace for a single project run.

**Available in read-only mode:** Yes.

| Argument          | Required | Type                                                          | Default |
| ----------------- | -------- | ------------------------------------------------------------- | ------- |
| `project_id`      | Yes      | str                                                           | None    |
| `run_id`          | Yes      | str                                                           | None    |
| `verbose`         | No       | bool \| None                                                  | None    |
| `severity_filter` | No       | Literal\['failed\_or\_slow', 'failed', 'slow', 'all'] \| None | None    |
| `expand`          | No       | list\[str] \| None                                            | None    |
| `cursor`          | No       | str \| None                                                   | None    |
| `page_size`       | No       | int \| None                                                   | None    |

### `runs_list`

Lists a project's run history, paginated.

**Available in read-only mode:** Yes.

| Argument     | Required | Type        | Default |
| ------------ | -------- | ----------- | ------- |
| `project_id` | Yes      | str         | None    |
| `cursor`     | No       | str \| None | None    |
| `page_size`  | No       | int \| None | None    |

### `skills_list`

Lists the skills visible to the authenticated user, builtins first.

**Available in read-only mode:** Yes.

| Argument    | Required | Type        | Default |
| ----------- | -------- | ----------- | ------- |
| `cursor`    | No       | str \| None | None    |
| `page_size` | No       | int \| None | None    |

### `skills_get`

Fetches one skill's full detail: instructions, frontmatter, actions, and file manifest.

**Available in read-only mode:** Yes.

| Argument   | Required | Type | Default |
| ---------- | -------- | ---- | ------- |
| `skill_id` | Yes      | str  | None    |

### `skills_create`

Creates a new skill (version 1) from text fields OR a file bundle.

**Available in read-only mode:** No.

| Argument       | Required | Type                           | Default |
| -------------- | -------- | ------------------------------ | ------- |
| `name`         | No       | str \| None                    | None    |
| `description`  | No       | str \| None                    | None    |
| `instructions` | No       | str \| None                    | None    |
| `actions`      | No       | list\[str] \| None             | None    |
| `files`        | No       | list\[SkillFileUpload] \| None | None    |

### `skills_update`

Publishes a new version of a skill - a FULL replacement, from text or files.

**Available in read-only mode:** No.

| Argument       | Required | Type                           | Default |
| -------------- | -------- | ------------------------------ | ------- |
| `skill_id`     | Yes      | str                            | None    |
| `name`         | No       | str \| None                    | None    |
| `description`  | No       | str \| None                    | None    |
| `instructions` | No       | str \| None                    | None    |
| `actions`      | No       | list\[str] \| None             | None    |
| `files`        | No       | list\[SkillFileUpload] \| None | None    |

### `skills_versions_list`

Lists a skill's full version history, newest first.

**Available in read-only mode:** Yes.

| Argument   | Required | Type | Default |
| ---------- | -------- | ---- | ------- |
| `skill_id` | Yes      | str  | None    |

### `skills_version_get`

Fetches one historical version's full detail: instructions, frontmatter, actions, file manifest.

**Available in read-only mode:** Yes.

| Argument   | Required | Type | Default |
| ---------- | -------- | ---- | ------- |
| `skill_id` | Yes      | str  | None    |
| `version`  | Yes      | int  | None    |

### `skills_rollback`

Restores a prior version's content by publishing it as a NEW latest version.

**Available in read-only mode:** No.

| Argument   | Required | Type | Default |
| ---------- | -------- | ---- | ------- |
| `skill_id` | Yes      | str  | None    |
| `version`  | Yes      | int  | None    |

### `skills_validate`

Validates a proposed skill bundle offline and previews normalization - the pre-flight for file-mode writes.

**Available in read-only mode:** Yes.

| Argument  | Required | Type                   | Default |
| --------- | -------- | ---------------------- | ------- |
| `files`   | Yes      | list\[SkillFileUpload] | None    |
| `actions` | No       | list\[str] \| None     | None    |

### `kb_list`

Lists knowledge bases available to the authenticated user.

**Available in read-only mode:** Yes.

| Argument    | Required | Type         | Default |
| ----------- | -------- | ------------ | ------- |
| `cursor`    | No       | str \| None  | None    |
| `page_size` | No       | int \| None  | None    |
| `verbose`   | No       | bool \| None | None    |

### `kb_search`

Searches a knowledge base by semantic, keyword, or hybrid retrieval and returns matching chunks.

**Available in read-only mode:** Yes.

| Argument         | Required | Type                  | Default |
| ---------------- | -------- | --------------------- | ------- |
| `kb_id`          | Yes      | str                   | None    |
| `query`          | Yes      | str                   | None    |
| `top_k`          | No       | int \| None           | None    |
| `query_strategy` | No       | QueryStrategy \| None | None    |
| `expand`         | No       | list\[str] \| None    | None    |

### `project_triggers_list`

Lists the triggers (cron schedules, polling jobs, webhook bindings) configured on a project.

**Available in read-only mode:** Yes.

| Argument     | Required | Type         | Default |
| ------------ | -------- | ------------ | ------- |
| `project_id` | Yes      | str          | None    |
| `verbose`    | No       | bool \| None | None    |

### `audit_logs_list`

Lists the active org's audit trail (who did what, when), paginated.

**Available in read-only mode:** Yes.

| Argument         | Required | Type        | Default |
| ---------------- | -------- | ----------- | ------- |
| `user_id`        | No       | str \| None | None    |
| `action`         | No       | str \| None | None    |
| `resource_type`  | No       | str \| None | None    |
| `permission_key` | No       | str \| None | None    |
| `decision`       | No       | str \| None | None    |
| `date_from`      | No       | str \| None | None    |
| `date_to`        | No       | str \| None | None    |
| `search`         | No       | str \| None | None    |
| `cursor`         | No       | str \| None | None    |
| `page_size`      | No       | int \| None | None    |

### `evals_datasets_list`

List datasets with complete continuation metadata. Requires project\_id. Search is optional. Pass pagination.next\_cursor to continue; page\_size defaults to 25 and caps at 100.

**Available in read-only mode:** Yes.

| Argument     | Required | Type        | Default |
| ------------ | -------- | ----------- | ------- |
| `project_id` | Yes      | str         | None    |
| `search`     | No       | str \| None | None    |
| `cursor`     | No       | str \| None | None    |
| `page_size`  | No       | int \| None | None    |

### `evals_evaluators_list`

List evaluators with complete continuation metadata. Requires project\_id. Search and either compatible\_with\_dataset\_id or compatible\_with\_experiment\_id are optional; use at most one compatibility filter. Use compatibility filtering before running or scoring. Continue using pagination.next\_cursor.

**Available in read-only mode:** Yes.

| Argument                        | Required | Type        | Default |
| ------------------------------- | -------- | ----------- | ------- |
| `project_id`                    | Yes      | str         | None    |
| `search`                        | No       | str \| None | None    |
| `compatible_with_dataset_id`    | No       | str \| None | None    |
| `compatible_with_experiment_id` | No       | str \| None | None    |
| `cursor`                        | No       | str \| None | None    |
| `page_size`                     | No       | int \| None | None    |

### `evals_experiments_list`

List experiments with complete continuation metadata. Requires project\_id; optional dataset\_id filters to one dataset. Returns experiments with aggregates and pagination. Continue with pagination.next\_cursor.

**Available in read-only mode:** Yes.

| Argument     | Required | Type        | Default |
| ------------ | -------- | ----------- | ------- |
| `project_id` | Yes      | str         | None    |
| `dataset_id` | No       | str \| None | None    |
| `cursor`     | No       | str \| None | None    |
| `page_size`  | No       | int \| None | None    |

### `evals_monitors_list`

List monitors with complete continuation metadata. Requires project\_id. Returns monitor health, recent scores and cursor pagination; page\_size defaults to 25 and caps at 100.

**Available in read-only mode:** Yes.

| Argument     | Required | Type        | Default |
| ------------ | -------- | ----------- | ------- |
| `project_id` | Yes      | str         | None    |
| `cursor`     | No       | str \| None | None    |
| `page_size`  | No       | int \| None | None    |

### `evals_datasets_get`

Read a dataset, optionally expanding one explicit row page. Returns dataset metadata. Use expand=\['rows'] to fetch one row page (25 by default, cap 100); continue with rows\_cursor=rows\_pagination.next\_cursor. Row cursor/size require the rows expansion. Never assume the first page is complete.

**Available in read-only mode:** Yes.

| Argument         | Required | Type                            | Default |
| ---------------- | -------- | ------------------------------- | ------- |
| `dataset_id`     | Yes      | str                             | None    |
| `expand`         | No       | list\[Literal\['rows']] \| None | None    |
| `rows_cursor`    | No       | str \| None                     | None    |
| `rows_page_size` | No       | int \| None                     | None    |

### `evals_experiments_get`

Read an experiment, optionally expanding one explicit row page. Returns experiment detail and aggregates. Use expand=\['rows'] for one row page including each row's scores. Continue using rows\_cursor=rows\_pagination.next\_cursor with the same experiment\_id and expansion. Defaults to 25 rows, cap 100.

**Available in read-only mode:** Yes.

| Argument         | Required | Type                            | Default |
| ---------------- | -------- | ------------------------------- | ------- |
| `experiment_id`  | Yes      | str                             | None    |
| `expand`         | No       | list\[Literal\['rows']] \| None | None    |
| `rows_cursor`    | No       | str \| None                     | None    |
| `rows_page_size` | No       | int \| None                     | None    |

### `evals_datasets_create`

Create a dataset, preserving its ID if optional row insertion fails. Requires project\_id, name and node\_contract={input\_kind,input\_keys,output\_node\_ids}. Optional rows are validated before creation. If row insertion fails, the error contains dataset\_id and dataset\_created=true: inspect all existing rows before repairing. Do not repeat dataset creation or blindly retry rows.

**Available in read-only mode:** No.

| Argument        | Required | Type                               | Default |
| --------------- | -------- | ---------------------------------- | ------- |
| `project_id`    | Yes      | str                                | None    |
| `name`          | Yes      | str                                | None    |
| `node_contract` | Yes      | EvalNodeContractInput              | None    |
| `description`   | No       | str \| None                        | None    |
| `rows`          | No       | list\[EvalDatasetRowDraft] \| None | None    |

### `evals_dataset_rows_add`

Append rows once; a lost response must be inspected before retrying. Requires dataset\_id and nonempty rows containing inputs and optional expected\_output/source\_run\_id. Adds at most 100 rows. This append is not idempotent; inspect existing rows after an uncertain result before retrying.

**Available in read-only mode:** No.

| Argument     | Required | Type                       | Default |
| ------------ | -------- | -------------------------- | ------- |
| `dataset_id` | Yes      | str                        | None    |
| `rows`       | Yes      | list\[EvalDatasetRowDraft] | None    |

### `evals_evaluators_get`

Read evaluator configuration and its required node contract. Returns evaluator\_type, config, node\_contract, score\_kind and reference-output requirements. Read this before choosing evaluators for a dataset, experiment or live run.

**Available in read-only mode:** Yes.

| Argument       | Required | Type | Default |
| -------------- | -------- | ---- | ------- |
| `evaluator_id` | Yes      | str  | None    |

### `evals_evaluators_create`

Create an evaluator with its explicit input/output contract. Requires project\_id, name, evaluator\_type (builtin\_rule or llm\_judge), config and node\_contract. Optional description, judge\_provider and judge\_model\_id are forwarded. Start with evals\_evaluator\_templates\_list to obtain valid configuration.

**Available in read-only mode:** No.

| Argument         | Required | Type                  | Default |
| ---------------- | -------- | --------------------- | ------- |
| `project_id`     | Yes      | str                   | None    |
| `name`           | Yes      | str                   | None    |
| `evaluator_type` | Yes      | EvaluatorType         | None    |
| `config`         | Yes      | dict\[str, object]    | None    |
| `node_contract`  | Yes      | EvalNodeContractInput | None    |
| `description`    | No       | str \| None           | None    |
| `judge_provider` | No       | str \| None           | None    |
| `judge_model_id` | No       | str \| None           | None    |

### `evals_evaluators_preview`

Dry-run an evaluator configuration on 1 to 3 samples before saving it. Requires project\_id, evaluator\_type (builtin\_rule or llm\_judge), config and samples, each with generated\_output and optional inputs and expected\_output. Optional judge\_provider and judge\_model\_id are forwarded. Nothing is persisted; llm\_judge previews spend judge tokens. Returns one verdict per sample with score, choice\_label, feedback, status and error. Fix the config until every verdict is scored, then call evals\_evaluators\_create.

**Available in read-only mode:** No.

| Argument         | Required | Type                          | Default |
| ---------------- | -------- | ----------------------------- | ------- |
| `project_id`     | Yes      | str                           | None    |
| `evaluator_type` | Yes      | EvaluatorType                 | None    |
| `config`         | Yes      | dict\[str, object]            | None    |
| `samples`        | Yes      | list\[EvalPreviewSampleInput] | None    |
| `judge_provider` | No       | str \| None                   | None    |
| `judge_model_id` | No       | str \| None                   | None    |

### `evals_evaluator_templates_list`

Discover evaluator templates before configuring a new evaluator. Returns evaluator template IDs, types and configuration starting points. Customize config and supply the node\_contract when calling evals\_evaluators\_create.

**Available in read-only mode:** Yes.

This tool has no arguments.

### `evals_experiments_create`

Freeze dataset rows into an experiment using a project version. Requires dataset\_id and project\_version\_id (a nonnegative published version or draft). Freezes dataset rows. Optional evaluator\_ids configure the experiment, but must be supplied again explicitly during generate/score. Returns experiment and warnings, including draft\_version when the editable draft is selected.

**Available in read-only mode:** No.

| Argument             | Required | Type                  | Default |
| -------------------- | -------- | --------------------- | ------- |
| `dataset_id`         | Yes      | str                   | None    |
| `project_version_id` | Yes      | EvalProjectVersionRef | None    |
| `evaluator_ids`      | No       | list\[str] \| None    | None    |
| `name`               | No       | str \| None           | None    |
| `notes`              | No       | str \| None           | None    |

### `evals_experiments_run`

Generate outputs or score existing outputs with explicit evaluator IDs. Requires experiment\_id. mode='generate' generates outputs, and evaluator\_ids defaults to \[] (generation only). mode='score' reuses generated outputs and requires a nonempty evaluator\_ids list. Creation-time evaluators are never implicitly reused. Returns accepted, job\_id, status\_url and a next\_action to poll that exact job. May execute workflow side effects or paid judges; do not retry blindly.

**Available in read-only mode:** No.

| Argument        | Required | Type                                  | Default |
| --------------- | -------- | ------------------------------------- | ------- |
| `experiment_id` | Yes      | str                                   | None    |
| `mode`          | No       | Literal\['generate', 'score'] \| None | None    |
| `evaluator_ids` | No       | list\[str] \| None                    | None    |

### `evals_experiments_status`

Poll one accepted job with its experiment\_id and job\_id from evals\_experiments\_run, or omit job\_id to inspect the experiment's latest job with cumulative row counts and aggregate cards. Returns that job's lifecycle, public terminal error and next\_action. No job returns status=null. Unavailable job health returns job\_status\_available=false and status=null, or a 503 for exact-job reads: retry the status read, never the run POST. Poll only queued/running states, keeping both IDs unchanged for exact-job polling. completed, completed\_with\_failures, failed and cancelled are terminal; inspect errors and all row pages before another job. Row counts never establish job completion.

**Available in read-only mode:** Yes.

| Argument        | Required | Type        | Default |
| --------------- | -------- | ----------- | ------- |
| `experiment_id` | Yes      | str         | None    |
| `job_id`        | No       | str \| None | None    |

### `evals_monitors_get`

Read a monitor with optional score statistics and alert configuration. Requires monitor\_id. Optional expand=\['stats','alert'] fetches score statistics and alert configuration; window is 24h, 7d (default), 30d or all.

**Available in read-only mode:** Yes.

| Argument     | Required | Type                                      | Default |
| ------------ | -------- | ----------------------------------------- | ------- |
| `monitor_id` | Yes      | str                                       | None    |
| `expand`     | No       | list\[Literal\['stats', 'alert']] \| None | None    |
| `window`     | No       | EvalMonitorWindow \| None                 | None    |

### `evals_monitors_create`

Create a monitor that samples future project runs for one evaluator. Requires project\_id and evaluator\_id. Optional name, sampling\_rate, max\_runs\_daily and notifications\_enabled override upstream defaults. Creates continuous evaluation of sampled future runs and may incur judge costs.

**Available in read-only mode:** No.

| Argument                | Required | Type          | Default |
| ----------------------- | -------- | ------------- | ------- |
| `project_id`            | Yes      | str           | None    |
| `evaluator_id`          | Yes      | str           | None    |
| `name`                  | No       | str \| None   | None    |
| `sampling_rate`         | No       | float \| None | None    |
| `max_runs_daily`        | No       | int \| None   | None    |
| `notifications_enabled` | No       | bool \| None  | None    |

### `evals_run_scores_list`

Read paginated score history, preserving the upstream opaque cursor. Requires run\_id. Returns appended score history, including re-evaluations. Pass pagination.next\_cursor unchanged; the upstream cursor is opaque and no total is available. Page size defaults to 25, cap 100.

**Available in read-only mode:** Yes.

| Argument    | Required | Type        | Default |
| ----------- | -------- | ----------- | ------- |
| `run_id`    | Yes      | str         | None    |
| `cursor`    | No       | str \| None | None    |
| `page_size` | No       | int \| None | None    |

### `evals_run_scores_create`

Append one evaluator score for an existing project run. Requires run\_id and evaluator\_id. Scores one existing run with a compatible evaluator that does not require an expected output. Each call appends another score and may incur judge costs; this operation is not idempotent.

**Available in read-only mode:** No.

| Argument       | Required | Type | Default |
| -------------- | -------- | ---- | ------- |
| `run_id`       | Yes      | str  | None    |
| `evaluator_id` | Yes      | str  | None    |

## Related resources

[API Versions and Compatibility](https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/mcp-tool-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
