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

# Tools Reference

> Complete reference for all Orion MCP server tools

The Orion MCP server exposes 20 tools organized into read-only and action categories. Each tool includes annotations so your AI assistant knows which tools are safe to call without confirmation.

## Action Tools

These tools create, modify, or trigger operations in Orion.

### ask\_orion

Send a natural language question to Orion and get an AI-powered data analysis response. This is the primary tool for interacting with Orion.

| Parameter         | Type   | Required | Description                          |
| ----------------- | ------ | -------- | ------------------------------------ |
| `message`         | string | Yes      | The question or analysis request     |
| `user_id`         | string | Yes      | The user ID sending the message      |
| `project_id`      | string | No       | Project ID to scope the analysis     |
| `conversation_id` | string | No       | Existing conversation ID to continue |

<Note>
  Orion performs multi-step analyses that take 1-2 minutes. After calling `ask_orion`, use `get_conversation_history` to poll for the final response. Wait at least 30 seconds between polls.
</Note>

### create\_conversation

Start a new Orion conversation.

| Parameter    | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `user_id`    | string | Yes      | The user ID creating the conversation |
| `project_id` | string | No       | Project ID to scope the conversation  |
| `title`      | string | No       | Title for the conversation            |

### execute\_metric

Trigger execution of a metric to refresh its current value.

| Parameter   | Type   | Required | Description              |
| ----------- | ------ | -------- | ------------------------ |
| `metric_id` | string | Yes      | The metric ID to execute |

### run\_workflow

Trigger execution of a workflow (insight maker).

| Parameter     | Type   | Required | Description            |
| ------------- | ------ | -------- | ---------------------- |
| `workflow_id` | string | Yes      | The workflow ID to run |

### delete\_artifact

Delete a slide deck, dashboard, or report artifact. This is a destructive action.

| Parameter     | Type   | Required | Description               |
| ------------- | ------ | -------- | ------------------------- |
| `artifact_id` | string | Yes      | The artifact ID to delete |

## Read-Only Tools

These tools only read data and are safe to call without confirmation.

### list\_projects

List Orion projects the user has access to.

| Parameter | Type    | Required | Description                            |
| --------- | ------- | -------- | -------------------------------------- |
| `search`  | string  | No       | Search text to filter projects by name |
| `limit`   | integer | No       | Maximum results (default 20)           |

### list\_users

List all users in the Orion organization. Returns user ID, name, and role.

### list\_conversations

List chat conversations for a user.

| Parameter    | Type    | Required | Description                  |
| ------------ | ------- | -------- | ---------------------------- |
| `user_id`    | string  | Yes      | The user ID                  |
| `project_id` | string  | No       | Filter by project            |
| `limit`      | integer | No       | Maximum results (default 20) |

### get\_conversation\_history

Read messages from an existing Orion conversation. Use this to poll for results after calling `ask_orion`.

| Parameter         | Type    | Required | Description                   |
| ----------------- | ------- | -------- | ----------------------------- |
| `conversation_id` | string  | Yes      | The conversation ID           |
| `limit`           | integer | No       | Maximum messages (default 50) |

### list\_metrics

List metrics (KPIs) for a project.

| Parameter    | Type    | Required | Description                       |
| ------------ | ------- | -------- | --------------------------------- |
| `project_id` | string  | Yes      | The project ID                    |
| `pinned`     | boolean | No       | Filter to pinned/unpinned metrics |

### get\_metric

Get full metric detail including definition, Python code, data sources, and latest result.

| Parameter   | Type   | Required | Description   |
| ----------- | ------ | -------- | ------------- |
| `metric_id` | string | Yes      | The metric ID |

### get\_metric\_results

Get historical execution results for a metric.

| Parameter   | Type    | Required | Description                  |
| ----------- | ------- | -------- | ---------------------------- |
| `metric_id` | string  | Yes      | The metric ID                |
| `limit`     | integer | No       | Maximum results (default 20) |

### get\_metric\_insights

Get auto-detected metric insights showing significant changes and anomalies for a project.

| Parameter          | Type   | Required | Description                                         |
| ------------------ | ------ | -------- | --------------------------------------------------- |
| `project_id`       | string | Yes      | The project ID                                      |
| `change_threshold` | float  | No       | Minimum change to flag, 0.0-1.0 (default 0.2 = 20%) |

### list\_workflows

List workflows (insight makers) for a project.

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `project_id` | string | Yes      | The project ID |

### get\_workflow

Get workflow detail including notebook data, sources, and metric references.

| Parameter     | Type   | Required | Description     |
| ------------- | ------ | -------- | --------------- |
| `workflow_id` | string | Yes      | The workflow ID |

### get\_workflow\_results

Get execution results for a workflow.

| Parameter     | Type    | Required | Description                  |
| ------------- | ------- | -------- | ---------------------------- |
| `workflow_id` | string  | Yes      | The workflow ID              |
| `limit`       | integer | No       | Maximum results (default 20) |

### list\_artifacts

List slide decks, dashboards, or reports for a project.

| Parameter       | Type   | Required | Description                                                           |
| --------------- | ------ | -------- | --------------------------------------------------------------------- |
| `project_id`    | string | Yes      | The project ID                                                        |
| `artifact_type` | string | No       | Filter by type: `html_slides`, `html_dashboard`, or `markdown_report` |

### get\_artifact

Get the content of a slide deck, dashboard, or report as markdown.

| Parameter     | Type   | Required | Description     |
| ------------- | ------ | -------- | --------------- |
| `artifact_id` | string | Yes      | The artifact ID |

### search\_wiki

Search the Orion wiki/knowledge base.

| Parameter    | Type    | Required | Description                   |
| ------------ | ------- | -------- | ----------------------------- |
| `text`       | string  | Yes      | Search text                   |
| `project_id` | string  | No       | Scope the search to a project |
| `limit`      | integer | No       | Maximum results (default 20)  |

### list\_recommendations

Get AI-generated recommendations for a project with suggested analysis prompts.

| Parameter    | Type    | Required | Description                          |
| ------------ | ------- | -------- | ------------------------------------ |
| `project_id` | string  | Yes      | The project ID                       |
| `limit`      | integer | No       | Maximum recommendations (default 10) |