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

# MCP Tool Reference

> Complete reference for all Cloud.Red MCP tools available to AI assistants.

All tools are accessible via `crcli mcp`. The AI assistant discovers them automatically on connect — no manual configuration required.

<Tip>Every tool returns a JSON object. The AI uses the returned data to answer follow-up questions without additional calls.</Tip>

***

## 🔍 Identity & Context

<AccordionGroup>
  <Accordion title="get_context">
    Get the authenticated caller's identity and active account scope.

    Returns `is_admin` (bool), `account_id` (UUID), and `user_id` (UUID).

    **No parameters.** Call this first to confirm which account is in scope.
  </Accordion>

  <Accordion title="set_context  (crcli-injected)">
    Set the active tenant for all subsequent tool calls.

    | Parameter | Type   | Description                                                     |
    | --------- | ------ | --------------------------------------------------------------- |
    | `tenant`  | string | Tenant name (e.g. `acmecorp`). Empty string clears the context. |

    Injected by `crcli` — not a server-side tool. Only available when connecting via `crcli mcp`.
  </Accordion>
</AccordionGroup>

***

## 👥 Accounts

<Note>These tools are admin-only and not available to customer accounts.</Note>

<AccordionGroup>
  <Accordion title="list_accounts">
    List all active accounts.

    Returns `uuid`, `tenant` (name), and `display_name` for each account. Use the `uuid` with `account_id` parameters on other tools to scope calls to a specific tenant.

    **No parameters.**
  </Accordion>
</AccordionGroup>

***

## 🖥️ Device Groups

<AccordionGroup>
  <Accordion title="list_device_groups">
    List operational device groups for an account.

    Returns `uuid`, `name`, `agent`, `account`, `platform`, and `status` for each group. Only returns groups in an online, non-pending state.

    | Parameter    | Type   | Required                       | Description  |
    | ------------ | ------ | ------------------------------ | ------------ |
    | `account_id` | string | When no account context is set | Account UUID |
  </Accordion>

  <Accordion title="get_device_group">
    Get full details for a single device group.

    Returns `uuid`, `name`, `agent`, `account`, `platform`, `status`, and credential state (`locked`, `rotated`).

    | Parameter  | Type   | Required | Description       |
    | ---------- | ------ | -------- | ----------------- |
    | `group_id` | string | ✓        | Device group UUID |
  </Accordion>

  <Accordion title="list_devices_in_group">
    List all devices that belong to a device group.

    Returns `uuid`, `name`, `management_ip`, `platform`, `account`, `device_group`, `agent`, and `state` (software version + HA status). Use `state.status` to identify active vs standby before running scripts.

    | Parameter  | Type   | Required | Description       |
    | ---------- | ------ | -------- | ----------------- |
    | `group_id` | string | ✓        | Device group UUID |
  </Accordion>
</AccordionGroup>

***

## 📟 Devices

<AccordionGroup>
  <Accordion title="list_devices">
    List all online devices for an account.

    Returns `uuid`, `name`, `management_ip`, `platform`, `account`, `device_group`, `agent`, and `state`.

    | Parameter    | Type   | Required                       | Description  |
    | ------------ | ------ | ------------------------------ | ------------ |
    | `account_id` | string | When no account context is set | Account UUID |
  </Accordion>

  <Accordion title="get_device">
    Get full details for a single device, including software version and HA status (active / standby / standalone).

    | Parameter   | Type   | Required | Description |
    | ----------- | ------ | -------- | ----------- |
    | `device_id` | string | ✓        | Device UUID |
  </Accordion>

  <Accordion title="list_device_backups">
    List UCS backups for a device in reverse-chronological order.

    Returns `uuid`, `filename`, `status`, and `created_at` for each backup.

    | Parameter   | Type   | Required | Description                               |
    | ----------- | ------ | -------- | ----------------------------------------- |
    | `device_id` | string | ✓        | Device UUID                               |
    | `limit`     | number |          | Max results, 1–1000 (default: 25)         |
    | `status`    | string |          | Filter: `complete`, `error`, or `running` |
  </Accordion>

  <Accordion title="list_device_metrics">
    List the metric catalog for a device's platform (BIG-IP or F5OS).

    Returns metric names, descriptions, and units. Use the names with `pull_device_metric` or `query_device_metrics`.

    | Parameter   | Type   | Required | Description |
    | ----------- | ------ | -------- | ----------- |
    | `device_id` | string | ✓        | Device UUID |
  </Accordion>

  <Accordion title="pull_device_metric">
    Pull a single metric time series from a device. Defaults to the last hour.

    | Parameter     | Type   | Required | Description                            |
    | ------------- | ------ | -------- | -------------------------------------- |
    | `device_id`   | string | ✓        | Device UUID                            |
    | `metric_name` | string | ✓        | Metric name from `list_device_metrics` |
    | `start`       | string |          | RFC3339 start time                     |
    | `end`         | string |          | RFC3339 end time (default: now)        |

    <Tip>Use `query_device_metrics` to fetch multiple metrics in a single request.</Tip>
  </Accordion>

  <Accordion title="query_device_metrics">
    Fetch multiple metrics for a device in a single ClickHouse request. More efficient than multiple `pull_device_metric` calls.

    | Parameter      | Type   | Required | Description                           |
    | -------------- | ------ | -------- | ------------------------------------- |
    | `device_id`    | string | ✓        | Device UUID                           |
    | `metric_names` | array  | ✓        | Raw ClickHouse metric names (max 100) |
    | `start`        | string |          | RFC3339 start time                    |
    | `end`          | string |          | RFC3339 end time (default: now)       |
  </Accordion>
</AccordionGroup>

***

## ⚙️ Orchestration

<Warning>Orchestration tools require **Write** permission on the target device group.</Warning>

<AccordionGroup>
  <Accordion title="run_script">
    Run a script on a single device via SSH and return the output.

    | Parameter     | Type   | Required | Description                                 |
    | ------------- | ------ | -------- | ------------------------------------------- |
    | `device_id`   | string | ✓        | Device UUID                                 |
    | `script`      | string | ✓        | Script content to execute                   |
    | `interpreter` | string |          | `bash` (default), `python`, `node`, `tclsh` |
  </Accordion>

  <Accordion title="run_script_on_group">
    Run a script on all devices in a group and return per-device output.

    | Parameter     | Type    | Required | Description                                                     |
    | ------------- | ------- | -------- | --------------------------------------------------------------- |
    | `group_id`    | string  | ✓        | Device group UUID                                               |
    | `script`      | string  | ✓        | Script content to execute                                       |
    | `interpreter` | string  |          | `bash` (default), `python`, `node`, `tclsh`                     |
    | `all`         | boolean |          | If true, target all devices; default targets active device only |
  </Accordion>

  <Accordion title="push_file">
    Upload a file to a device via SCP.

    | Parameter   | Type   | Required | Description                         |
    | ----------- | ------ | -------- | ----------------------------------- |
    | `device_id` | string | ✓        | Device UUID                         |
    | `path`      | string | ✓        | Remote destination path             |
    | `content`   | string | ✓        | File content (plain text or base64) |
    | `encoding`  | string |          | `plain` (default) or `base64`       |
  </Accordion>

  <Accordion title="push_file_to_group">
    Upload a file to all devices in a group via SCP in parallel.

    | Parameter  | Type   | Required | Description                         |
    | ---------- | ------ | -------- | ----------------------------------- |
    | `group_id` | string | ✓        | Device group UUID                   |
    | `path`     | string | ✓        | Remote destination path             |
    | `content`  | string | ✓        | File content (plain text or base64) |
    | `encoding` | string |          | `plain` (default) or `base64`       |
  </Accordion>

  <Accordion title="pull_file">
    Download a file from a device via SCP.

    Returns file content as base64 (max 512 KB).

    | Parameter   | Type   | Required | Description      |
    | ----------- | ------ | -------- | ---------------- |
    | `device_id` | string | ✓        | Device UUID      |
    | `path`      | string | ✓        | Remote file path |
  </Accordion>
</AccordionGroup>

***

## 🔌 iControl REST

<Warning>iControl REST tools require **Write** permission on the target device group. Always call `delete_icontrol_session` when done.</Warning>

<AccordionGroup>
  <Accordion title="create_icontrol_session">
    Authenticate to a device's iControl REST API via the tunnel and return a session token.

    | Parameter   | Type   | Required | Description |
    | ----------- | ------ | -------- | ----------- |
    | `device_id` | string | ✓        | Device UUID |

    Returns `session_id` — pass this to `icontrol_request` and `delete_icontrol_session`.
  </Accordion>

  <Accordion title="icontrol_request">
    Make an iControl REST API request to a device directly via the tunnel.

    | Parameter    | Type   | Required | Description                                          |
    | ------------ | ------ | -------- | ---------------------------------------------------- |
    | `session_id` | string | ✓        | Session token from `create_icontrol_session`         |
    | `method`     | string | ✓        | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
    | `path`       | string | ✓        | iControl REST path (e.g. `/mgmt/tm/ltm/virtual`)     |
    | `body`       | object |          | Request body for POST/PUT/PATCH                      |
  </Accordion>

  <Accordion title="delete_icontrol_session">
    Invalidate an iControl session before it expires.

    Call this when done with `icontrol_request` to avoid leaving live credentials cached on the server.

    | Parameter    | Type   | Required | Description                 |
    | ------------ | ------ | -------- | --------------------------- |
    | `session_id` | string | ✓        | Session token to invalidate |
  </Accordion>
</AccordionGroup>

***

## 🔎 Log Search

<Note>Log search tools are only available when log search is configured for your account.</Note>

The AI follows a mandatory workflow when answering log-related questions:

<Steps>
  <Step title="list_logtypes">Discover available log sources</Step>
  <Step title="get_schema">Learn the table structure and query rules</Step>
  <Step title="get_logtype_doc">Get field names and value shapes for the target log type</Step>
  <Step title="query_logs">Execute the SQL query — each response includes a `query_id`</Step>
  <Step title="submit_session">Record the investigation — called exactly once after answering</Step>
</Steps>

<AccordionGroup>
  <Accordion title="list_logtypes">
    List all available F5 log types.

    Returns `namespace`, `name`, `source`, and `description` for each type.

    **No parameters.** Call this first to discover which log types exist before writing queries.
  </Accordion>

  <Accordion title="get_schema">
    Get the ClickHouse logs table schema, column reference, mandatory filter rules, time-window guidance, and common query patterns.

    **No parameters.** Read this before writing any SQL query.
  </Accordion>

  <Accordion title="get_logtype_doc">
    Get the field reference documentation for a specific log type — all `LogAttributes` keys, `ResourceAttributes` keys, `SeverityText` vocabulary, gotchas, and example queries.

    | Parameter   | Type   | Required | Description                            |
    | ----------- | ------ | -------- | -------------------------------------- |
    | `namespace` | string | ✓        | Log type namespace (e.g. `f5logs`)     |
    | `name`      | string | ✓        | Log type name (e.g. `f5.bigip.syslog`) |
  </Accordion>

  <Accordion title="get_log_keys">
    Discover which `LogAttribute` keys are present in your account's data for a log type, ranked by frequency over the past 7 days.

    | Parameter    | Type   | Required | Description                                            |
    | ------------ | ------ | -------- | ------------------------------------------------------ |
    | `namespace`  | string | ✓        | Log type namespace                                     |
    | `name`       | string | ✓        | Log type name                                          |
    | `account_id` | string |          | Account UUID (required when no account context is set) |
  </Accordion>

  <Accordion title="sample_logs">
    Fetch a small sample of recent log rows for a given log type, in descending timestamp order.

    | Parameter    | Type   | Required | Description                                            |
    | ------------ | ------ | -------- | ------------------------------------------------------ |
    | `namespace`  | string | ✓        | Log type namespace                                     |
    | `name`       | string | ✓        | Log type name                                          |
    | `account_id` | string |          | Account UUID (required when no account context is set) |
    | `limit`      | number |          | Rows to return (1–50, default: 5)                      |
  </Accordion>

  <Accordion title="query_logs">
    Execute a ClickHouse SELECT query against the F5 logs table.

    Returns rows as JSON with `context.query_id` — the AI records every `query_id` for `submit_session`.

    Rules enforced server-side: `ServiceNamespace` filter required, `ServiceName` filter required, bounded `Timestamp` window required, `LIMIT` required (max 10 000).

    | Parameter    | Type   | Required | Description                                            |
    | ------------ | ------ | -------- | ------------------------------------------------------ |
    | `sql`        | string | ✓        | A single SELECT statement targeting `logs_001`         |
    | `account_id` | string |          | Account UUID (required when no account context is set) |
  </Accordion>

  <Accordion title="submit_session">
    Record the completed log-search investigation for telemetry and quality improvement.

    Called exactly once after the AI answers (or fails to answer) a log-related question. Must include every `query_id` received from `query_logs`, `sample_logs`, or `get_log_keys`.

    | Parameter | Type   | Required | Description                                               |
    | --------- | ------ | -------- | --------------------------------------------------------- |
    | `ask`     | string | ✓        | The user's original question                              |
    | `intent`  | string | ✓        | Classified intent (e.g. `troubleshoot`, `audit`, `count`) |
    | `outcome` | string | ✓        | `answered`, `partial`, or `unanswered`                    |
    | `summary` | string | ✓        | One-sentence answer or reason it could not be answered    |
    | `queries` | array  |          | Array of `{query_id, description}` objects                |
  </Accordion>
</AccordionGroup>

***

## 🤖 Agents

<Note>Admin-only. Not available to customer accounts.</Note>

<AccordionGroup>
  <Accordion title="list_agents">
    List tunnel agents registered to an account.

    Returns `uuid`, `name`, and `account` for each online agent. Agents are the network proxies that relay SSH and iControl traffic to device groups.

    | Parameter    | Type   | Required                       | Description  |
    | ------------ | ------ | ------------------------------ | ------------ |
    | `account_id` | string | When no account context is set | Account UUID |
  </Accordion>
</AccordionGroup>