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

# MCP tool catalogue

> Task-oriented Towbar tools for discovery, deployment, diagnostics, backups, servers, previews, and secrets.

Towbar exposes 53 purpose-built tools. Names follow `towbar_<entity>_<action>`; they are independent of REST routes. Discovery filters this catalogue by your key and workspace role.

Use [MCP setup](/docs/api/mcp) for connection details and worked examples. Mutation tools carry risk annotations; client approval is still required for consequential actions. Successful calls return structured `result` data with a matching JSON text fallback. Failures set `isError`.

Inventory and history tools return bounded pages with continuation fields. Histories backed by live inventories are best-effort pages, not snapshot cursors; concurrent changes can shift offsets.

## Scout Alerts

<AccordionGroup>
  <Accordion title="Inspect Scout alerts and incidents">
    `towbar_alerts_inspect`

    Inspect configured rules, latest evaluations, HTTP check results, destination IDs, and a page of incidents. An active incident is not proof that its notification was delivered. Use returned rule IDs before configuration; use the incident cursor to read older history.

    Read-only operation. Required permissions: `alert.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "state": {
          "default": "active",
          "type": "string",
          "enum": ["active", "resolved", "all"]
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 50
        },
        "before": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
        },
        "beforeId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "ruleId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "deployableId": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            {
              "type": "string",
              "const": "server"
            }
          ]
        }
      },
      "required": ["serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Create or update a Scout alert">
    `towbar_alerts_configure`

    Configure a host/workload metric alert or a public HTTP uptime check. Omit ruleId to create; supply an inspected ruleId to replace its settings. Read current settings before updating and preserve settings the user did not request changing. HTTP checks send recurring public requests. Alerts notify all destinations configured on the server on the first qualifying reading, once per incident, and recover when the condition clears. Creating a rule does not send an immediate test.

    Edit access required. Required permissions: `alert.configure`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "enabled": {
          "default": true,
          "type": "boolean"
        },
        "severity": {
          "default": "warning",
          "type": "string",
          "enum": ["warning", "critical"]
        },
        "deployableId": {
          "default": null,
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            {
              "type": "null"
            }
          ]
        },
        "condition": {
          "type": "object",
          "properties": {
            "metric": {
              "type": "string",
              "enum": [
                "cpuPercent",
                "cpuCores",
                "cpuLimitCores",
                "memoryUsedBytes",
                "memoryTotalBytes",
                "memoryLimitBytes",
                "memoryPercent",
                "swapUsedBytes",
                "swapTotalBytes",
                "diskTotalBytes",
                "diskUsedBytes",
                "diskPercent",
                "dockerDiskTotalBytes",
                "dockerDiskUsedBytes",
                "dockerDiskPercent",
                "diskReadBytesPerSecond",
                "diskWriteBytesPerSecond",
                "networkRxBytesPerSecond",
                "networkTxBytesPerSecond",
                "uptimeSeconds",
                "load1",
                "load5",
                "load15",
                "restarts",
                "missingReports",
                "httpAvailability"
              ]
            },
            "http": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "maxLength": 2048,
                  "format": "uri"
                },
                "method": {
                  "default": "GET",
                  "type": "string",
                  "enum": ["GET", "HEAD"]
                },
                "intervalSeconds": {
                  "default": 60,
                  "type": "integer",
                  "minimum": 30,
                  "maximum": 300,
                  "multipleOf": 30
                },
                "timeoutSeconds": {
                  "default": 5,
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 10
                },
                "expectedStatusMin": {
                  "default": 200,
                  "type": "integer",
                  "minimum": 100,
                  "maximum": 599
                },
                "expectedStatusMax": {
                  "default": 299,
                  "type": "integer",
                  "minimum": 100,
                  "maximum": 599
                },
                "maxRedirects": {
                  "default": 0,
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 3
                }
              },
              "required": ["url"],
              "additionalProperties": false
            },
            "operator": {
              "default": "above",
              "type": "string",
              "enum": ["above", "below"]
            },
            "threshold": {
              "type": "number",
              "minimum": 0,
              "maximum": 1000000000000000000
            },
            "windowSeconds": {
              "default": 300,
              "type": "integer",
              "minimum": 60,
              "maximum": 3600
            },
            "aggregation": {
              "default": "average",
              "type": "string",
              "enum": ["average", "peak"]
            }
          },
          "required": ["metric", "threshold"],
          "additionalProperties": false
        },
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "ruleId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Scout alert rule UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["name", "condition", "serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Remove a Scout alert rule">
    `towbar_alerts_remove`

    Delete an inspected Scout rule, stop its checks/evaluation and close active incidents without claiming recovery. Resolved incident history remains until retention expires. Confirm the user's intended rule before removal.

    Edit access required. Required permissions: `alert.configure`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "ruleId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Scout alert rule UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["serverId", "ruleId"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Deployments

<AccordionGroup>
  <Accordion title="Compare performance between deployments">
    `towbar_deployment_compare`

    First call with workloadId only to discover successful deployment IDs. Then supply baselineId and candidateId from the same workload and production/preview environment to compare equal post-readiness windows. Reports coverage, usage deltas, restarts and caveats; insufficient data cannot establish a regression and traffic may differ. Defaults to summaries; includePoints returns at most 24 representative points per side.

    Read-only operation. Required permissions: `alert.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "baselineId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Baseline deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "candidateId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Compared deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "windowMinutes": {
          "default": 30,
          "type": "integer",
          "minimum": 5,
          "maximum": 1440
        },
        "warmupMinutes": {
          "default": 2,
          "type": "integer",
          "minimum": 0,
          "maximum": 60
        },
        "regressionPercent": {
          "default": 0,
          "type": "number",
          "minimum": 0,
          "maximum": 500
        },
        "minimumCoveragePercent": {
          "default": 0,
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "statistic": {
          "default": "average",
          "type": "string",
          "enum": ["average", "peak"]
        },
        "cpuFloorCores": {
          "default": 0,
          "type": "number",
          "minimum": 0,
          "maximum": 1024
        },
        "memoryFloorMiB": {
          "default": 0,
          "type": "number",
          "minimum": 0,
          "maximum": 1048576
        },
        "includePoints": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": ["workloadId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="List deployment history">
    `towbar_deployment_list`

    Find deployment IDs and outcomes across the workspace with server-side pagination. Use towbar\_deployment\_inspect for build steps and logs.

    Read-only operation. Required permissions: `deployment.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "page": {
          "default": 1,
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Inspect deployment progress and logs">
    `towbar_deployment_inspect`

    Diagnose one deployment: returns state, build steps, a bounded log page, and optional vulnerability findings. Poll using nextAfter, including after terminal state if hasMoreLogs. Only succeeded, succeeded\_with\_warnings, failed, cancelled, or skipped are terminal; accepted/queued is not success.

    Read-only operation. Required permissions: `deployment.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "deploymentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "after": {
          "default": -1,
          "type": "integer",
          "minimum": -1,
          "maximum": 9007199254740991
        },
        "logLimit": {
          "default": 50,
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        },
        "includeFindings": {
          "default": false,
          "type": "boolean"
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["deploymentId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Cancel deployment">
    `towbar_deployment_cancel`

    Request cancellation of a running deployment. Poll towbar\_deployment\_inspect until terminal; a cancellation request can race completion.

    Edit access required. Required permissions: `deployment.cancel`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "deploymentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["deploymentId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Retry deployment">
    `towbar_deployment_retry`

    Create a new attempt for an eligible failed deployment. Use a fresh idempotencyKey for this retry, then inspect the returned deployment ID.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "deploymentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["deploymentId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Rescan deployed image">
    `towbar_deployment_rescan`

    Request a vulnerability scan for a deployment image. Read findings and scan state using towbar\_deployment\_inspect with includeFindings afterward.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "deploymentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Deployment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["deploymentId"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Integrations

<AccordionGroup>
  <Accordion title="List available integrations">
    `towbar_integration_list`

    List integrations enabled by the Towbar runtime environment. Configuration and secret values are never returned.

    Read-only operation. Required permissions: `integration.manage`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Disconnect GitHub integration">
    `towbar_github_disconnect`

    Disconnect the workspace GitHub integration, affecting repository sync and deployments. Confirm this workspace-wide change with the user.

    Edit access required. Required permissions: `integration.manage`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Retry preview reporting">
    `towbar_github_retry_reporting`

    Retry failed GitHub preview status/comment reporting. This retries reporting, not deployment; inspect preview/deployment state separately.

    Edit access required. Required permissions: `integration.manage`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Workspace

<AccordionGroup>
  <Accordion title="Inspect workspace">
    `towbar_workspace_inspect`

    Identify the current team, actor, and permitted actions. Use first to understand the authenticated context.

    Read-only operation. Required permissions: `identity.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Refresh control-plane health">
    `towbar_workspace_check`

    Run system health checks, then use towbar\_workspace\_inspect to review the latest results.

    Edit access required. Required permissions: `system.manage`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Discovery

<AccordionGroup>
  <Accordion title="Find apps, resources, sources, or servers">
    `towbar_inventory_search`

    Find entity UUIDs by name, repository, or IP before taking action. Returns a compact page and nextOffset. An optional sourceId or serverId limits app/resource discovery; do not supply both. Use the matching inspect tool for details.

    Read-only operation. Required permissions: `repository.read`, `workload.read`, `resource.read`, `server.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource", "source", "server"]
        },
        "search": {
          "default": "",
          "type": "string",
          "maxLength": 255
        },
        "sourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["kind"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Find available GitHub or GitLab repositories">
    `towbar_repository_search`

    Find a repository connection and provider-specific identifier for towbar\_source\_connect. GitHub uses its installation connection; GitLab uses its workspace provider configuration and supports cloud or self-managed instances.

    Read-only operation. Required permissions: `githubInstallation.read`, `integration.manage`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "provider": {
          "default": "github",
          "type": "string",
          "enum": ["github", "gitlab"]
        },
        "integration": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "search": {
          "default": "",
          "type": "string",
          "maxLength": 255
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Repositories

<AccordionGroup>
  <Accordion title="Inspect source and environments">
    `towbar_source_inspect`

    Inspect a connected repository, its environment branch mappings, auto-deploy control and server capacity. Supply an environmentId to include the immutable manifest snapshot from its latest successful sync. Find IDs with towbar\_inventory\_search and the returned environment list.

    Read-only operation. Required permissions: `repository.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "environmentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source environment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["sourceId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Connect repository">
    `towbar_source_connect`

    Connect a repository after discovery, mapping its selected environments to branches. Initial sync does not deploy. Inspect each returned environment sync outcome.

    Edit access required. Required permissions: `repository.connect`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "repositoryOwner": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "repositoryName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "environments": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "environment": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9-]{0,62}$"
                  },
                  "branch": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  }
                },
                "required": ["environment", "branch"],
                "additionalProperties": false
              }
            },
            "provider": {
              "default": "github",
              "type": "string",
              "const": "github"
            },
            "githubInstallationId": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          },
          "required": [
            "repositoryOwner",
            "repositoryName",
            "environments",
            "githubInstallationId"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "repositoryOwner": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "repositoryName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "environments": {
              "minItems": 1,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "environment": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9-]{0,62}$"
                  },
                  "branch": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  }
                },
                "required": ["environment", "branch"],
                "additionalProperties": false
              }
            },
            "provider": {
              "type": "string",
              "const": "gitlab"
            },
            "providerRepositoryId": {
              "type": "string",
              "pattern": "^[1-9]\\d{0,19}$"
            },
            "integration": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
            }
          },
          "required": [
            "repositoryOwner",
            "repositoryName",
            "environments",
            "provider",
            "providerRepositoryId",
            "integration"
          ],
          "additionalProperties": false
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Disconnect source">
    `towbar_source_disconnect`

    Remove a source from Towbar. Inspect the source and confirm the target with the user first; this changes which repository Towbar manages.

    Edit access required. Required permissions: `repository.disconnect`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["sourceId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Discover repository environments">
    `towbar_source_discover`

    Read towbar.yml on a discovery branch to find declared environments before connecting. Does not create a source or deploy.

    Edit access required. Required permissions: `repository.connect`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "repositoryOwner": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "repositoryName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "discoveryBranch": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "provider": {
              "default": "github",
              "type": "string",
              "const": "github"
            },
            "githubInstallationId": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          },
          "required": [
            "repositoryOwner",
            "repositoryName",
            "discoveryBranch",
            "githubInstallationId"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "repositoryOwner": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "repositoryName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "discoveryBranch": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "provider": {
              "type": "string",
              "const": "gitlab"
            },
            "providerRepositoryId": {
              "type": "string",
              "pattern": "^[1-9]\\d{0,19}$"
            },
            "integration": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
            }
          },
          "required": [
            "repositoryOwner",
            "repositoryName",
            "discoveryBranch",
            "provider",
            "providerRepositoryId",
            "integration"
          ],
          "additionalProperties": false
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Sync connected environments">
    `towbar_source_sync`

    Sync one environment when environmentId is supplied, or all connected environments otherwise. Uses mapped branches. Member sync updates inventory without deploying. Inspect each returned sync ID for completion.

    Edit access required. Required permissions: `repository.sync`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "environmentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Environment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["sourceId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Inspect source sync progress">
    `towbar_source_sync_inspect`

    Check a specific syncId returned by towbar\_source\_sync, or list a bounded page of sync attempts when no syncId is supplied. Inspect errors before retrying; acceptance is not completion.

    Read-only operation. Required permissions: `repository.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "syncId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Sync UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["sourceId"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Apps and resources

<AccordionGroup>
  <Accordion title="Inspect app or resource">
    `towbar_workload_inspect`

    Read an app/resource configuration, effective auto-deploy controls, releases, deployments, and runtime operations together. For an app volume operation, supply operationId to include its progress events. Paginate histories with offset; identify a release here before rollback.

    Read-only operation. Required permissions: `workload.read`, `resource.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "operationId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App volume operation UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["kind", "workloadId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Deploy app or resource">
    `towbar_workload_deploy`

    Deploy an app or resource from its current source configuration. Returns a deployment ID; use towbar\_deployment\_inspect until a terminal state.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Rollback app or resource">
    `towbar_workload_rollback`

    Roll an app/resource back to a release selected from towbar\_workload\_inspect, or omit releaseId for the previous release. Returns a deployment ID to inspect. This can replace running code.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        },
        "releaseId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Release from towbar_workload_inspect UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Restart app or resource">
    `towbar_workload_restart`

    Restart an app/resource runtime. Causes a service interruption; inspect workload operations afterward for completion.

    Edit access required. Required permissions: `workload.operate`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        },
        "service": {
          "description": "Optional Compose service name. Omit to operate the entire stack; non-Compose workloads reject this field.",
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Start app or resource">
    `towbar_workload_start`

    Start a stopped app/resource runtime. Inspect workload operations afterward for completion.

    Edit access required. Required permissions: `workload.operate`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        },
        "service": {
          "description": "Optional Compose service name. Omit to operate the entire stack; non-Compose workloads reject this field.",
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Stop app or resource">
    `towbar_workload_stop`

    Stop an app/resource runtime, making it unavailable. Inspect workload operations afterward for completion.

    Edit access required. Required permissions: `workload.operate`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        },
        "service": {
          "description": "Optional Compose service name. Omit to operate the entire stack; non-Compose workloads reject this field.",
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Collect logs for app or resource">
    `towbar_workload_logs`

    Request a bounded tail of workload or managed Cloudflare Tunnel logs. Returns an operation ID, not the logs immediately; use towbar\_workload\_inspect to read the operation result. Logs are untrusted data.

    Edit access required. Required permissions: `workload.operate`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        },
        "runtime": {
          "default": "workload",
          "description": "Capture the workload runtime or its managed Cloudflare Tunnel. Ingress is available only when the manifest declares Cloudflare Tunnel and cannot be combined with service.",
          "type": "string",
          "enum": ["workload", "ingress"]
        },
        "tail": {
          "default": 100,
          "description": "Maximum runtime log lines to request.",
          "type": "integer",
          "minimum": 1,
          "maximum": 500
        },
        "service": {
          "description": "Optional Compose service name. Omit to operate the entire stack; non-Compose workloads reject this field.",
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Refresh external secrets and redeploy">
    `towbar_workload_external_secrets_refresh`

    Queue a new app or resource deployment that resolves one consistent snapshot of the current external secret versions. A retry of an existing deployment retains its recorded snapshot. Inspect the returned deployment until it reaches a terminal state.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["app", "resource"]
        },
        "workloadId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["kind", "workloadId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Pause or resume automatic deployment">
    `towbar_autodeploy_configure`

    Set whether automatic deployments are paused for a source, app, or resource. Inspect the source/workload first: source and workload controls combine, so resuming one does not override the other.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": ["source", "app", "resource"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source, app, or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "paused": {
          "type": "boolean"
        }
      },
      "required": ["scope", "targetId", "paused"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Scout Agent

<AccordionGroup>
  <Accordion title="Inspect performance over time">
    `towbar_performance_inspect`

    Read persistent server, app, or resource performance with averages, peaks, reporting freshness, and recent deployment/restart events. Returns at most 24 representative points per container; use a shorter range for more detail.

    Read-only operation. Required permissions: `scout.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": ["server", "app", "resource"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server, app, or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "range": {
          "default": "1h",
          "type": "string",
          "enum": [
            "15m",
            "30m",
            "1h",
            "6h",
            "24h",
            "7d",
            "15d",
            "30d",
            "60d",
            "custom"
          ]
        },
        "startAt": {
          "description": "Inclusive ISO 8601 start with time-zone offset; required for range=custom and within server retention.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "endAt": {
          "description": "Exclusive ISO 8601 end with time-zone offset; required for range=custom, at least 30 seconds after start and not in the future.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": ["kind", "targetId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Configure enhanced monitoring">
    `towbar_monitoring_configure`

    Install/update Scout Agent, Towbar’s opt-in monitoring agent, change retention, or uninstall it. Installation requires explicit user acknowledgement. Uninstall revokes reporting immediately and removes services asynchronously. Shorter retention expires older data. Poll server\_inspect for completion; queued does not mean online.

    Edit access required. Required permissions: `scout.configure`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "action": {
          "type": "string",
          "enum": ["install", "uninstall", "retention"]
        },
        "retentionDays": {
          "anyOf": [
            {
              "type": "number",
              "const": 7
            },
            {
              "type": "number",
              "const": 15
            },
            {
              "type": "number",
              "const": 30
            },
            {
              "type": "number",
              "const": 60
            }
          ]
        },
        "acknowledge": {
          "type": "boolean",
          "const": true
        }
      },
      "required": ["serverId", "action"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Servers

<AccordionGroup>
  <Accordion title="Inspect server readiness and capacity">
    `towbar_server_inspect`

    Read server settings, capacity, recent checks, preparation attempts, monitoring, and orphan inventory together. Use before preparation or cleanup. No private credential values are returned.

    Read-only operation. Required permissions: `server.read`, `scout.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Register server">
    `towbar_server_register`

    Register a workspace server by IP and SSH configuration. Then configure credentials, independently verify/trust its SSH host key, and prepare it. Registration alone does not make the server ready.

    Edit access required. Required permissions: `server.update`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "buildConcurrency": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16
        },
        "previewBuildConcurrency": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4
        },
        "ip": {
          "type": "string"
        },
        "ssh": {
          "type": "object",
          "properties": {
            "host": {
              "type": "string"
            },
            "username": {
              "type": "string",
              "pattern": "^[a-z_][a-z0-9_-]{0,31}$"
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            }
          },
          "required": ["username"],
          "additionalProperties": false
        },
        "proxy": {
          "type": "object",
          "properties": {
            "cloudflare": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "const": true
                }
              },
              "required": ["enabled"],
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "required": ["ip", "ssh"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Remove server from Towbar">
    `towbar_server_remove`

    Stop managing a server and forget stored credentials and host trust. Uninstalls monitoring before forgetting SSH access; this may return pending. Does not terminate the machine or delete running services, Docker objects, or data. Assigned workloads and active operations block removal. Inspect and clean selected orphans first if desired.

    Edit access required. Required permissions: `server.remove`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Configure server">
    `towbar_server_configure`

    Update server IP, SSH settings, proxy options, and build concurrency. Inspect current settings first; changing connectivity can disrupt deployments.

    Edit access required. Required permissions: `server.update`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "buildConcurrency": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16
        },
        "previewBuildConcurrency": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4
        },
        "ip": {
          "type": "string"
        },
        "ssh": {
          "type": "object",
          "properties": {
            "host": {
              "type": "string"
            },
            "username": {
              "type": "string",
              "pattern": "^[a-z_][a-z0-9_-]{0,31}$"
            },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            }
          },
          "required": ["username"],
          "additionalProperties": false
        },
        "proxy": {
          "type": "object",
          "properties": {
            "cloudflare": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "const": true
                }
              },
              "required": ["enabled"],
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "required": ["serverId", "ip", "ssh"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Update server credentials">
    `towbar_server_credentials_update`

    Set or delete SSH/Cloudflare credentials with the revision from towbar\_server\_inspect. Values are never returned. Preserve expectedRevision to avoid overwriting concurrent changes.

    Edit access required. Required permissions: `server.credentials`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "expectedRevision": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            {
              "type": "null"
            }
          ]
        },
        "set": {
          "default": {},
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 65536
          }
        },
        "delete": {
          "default": [],
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          }
        }
      },
      "required": ["serverId", "expectedRevision"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Trust SSH host key">
    `towbar_server_trust_host`

    Trust a server host key only after the user independently verifies its fingerprint. Never auto-trust a fingerprint simply because the server reported it.

    Edit access required. Required permissions: `server.credentials`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "algorithm": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9@._+-]{0,79}$"
        },
        "fingerprint": {
          "type": "string",
          "maxLength": 255,
          "pattern": "^SHA256:.*"
        },
        "publicKey": {
          "type": "string",
          "minLength": 32,
          "maxLength": 16384
        },
        "replaceExisting": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": ["serverId", "algorithm", "fingerprint", "publicKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Revoke trusted SSH key">
    `towbar_server_revoke_host`

    Remove a previously trusted server host key. This can prevent subsequent SSH connections; identify hostKeyId in towbar\_server\_inspect first.

    Edit access required. Required permissions: `server.credentials`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "hostKeyId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Trusted host key UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["serverId", "hostKeyId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Prepare server for workloads">
    `towbar_server_prepare`

    Install or validate server prerequisites after credentials and host trust are configured. Follow preparation attempts in towbar\_server\_inspect until ready or failed.

    Edit access required. Required permissions: `server.prepare`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Refresh server health">
    `towbar_server_check`

    Request a new health/capacity check. Inspect server checks afterward to distinguish a queued request from a completed check.

    Edit access required. Required permissions: `server.update`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["serverId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Clean selected orphaned objects">
    `towbar_server_cleanup`

    Delete only explicitly selected orphan containers, images, or volumes from towbar\_server\_inspect. Volumes may contain data; confirm the exact inventory with the user before cleanup.

    Edit access required. Required permissions: `server.remove`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Server UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "items": {
          "minItems": 1,
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["container", "image", "volume"]
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              }
            },
            "required": ["kind", "name"],
            "additionalProperties": false
          }
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["serverId", "items", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Secrets

<AccordionGroup>
  <Accordion title="Inspect secret names and revisions">
    `towbar_secrets_inspect`

    Read secret bindings, inheritance, and revision metadata for a workspace, source, app, or resource. Never returns plaintext values. Read before towbar\_secrets\_update; use the correct environment and slot revision.

    Read-only operation. Required permissions: `secret.list`, `sharedSecret.list`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": ["workspace", "source", "app", "resource"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Secret owner; omit for workspace scope UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "environment": {
          "type": "string",
          "maxLength": 80,
          "pattern": "^(?:preview:)?[a-z][a-z0-9-]{0,62}$"
        }
      },
      "required": ["scope"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Update environment secrets">
    `towbar_secrets_update`

    Set/delete named secrets in one environment and lifecycle stage. Use expectedRevision from towbar\_secrets\_inspect (null only for an empty slot). A conflict requires rereading and reconciling changes. Never returns plaintext values.

    Edit access required. Required permissions: `secret.update`, `sharedSecret.update`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": ["workspace", "source", "app", "resource"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Secret owner; omit for workspace scope UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "environment": {
          "type": "string",
          "maxLength": 80,
          "pattern": "^(?:preview:)?[a-z][a-z0-9-]{0,62}$"
        },
        "stage": {
          "type": "string",
          "enum": ["build", "deployment", "pre_deploy", "post_deploy"]
        },
        "expectedRevision": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            {
              "type": "null"
            }
          ]
        },
        "set": {
          "default": {},
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 65536
          }
        },
        "delete": {
          "default": [],
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          }
        }
      },
      "required": ["scope", "environment", "stage", "expectedRevision"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Backups and restores

<AccordionGroup>
  <Accordion title="Inspect backups and restore progress">
    `towbar_backup_inspect`

    For a source, page through available backups. For a resource, inspect backup assurance and operations; supply operationId to include its restore events. Use before restore and to check backup/restore completion.

    Read-only operation. Required permissions: `repository.read`, `resource.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": ["source", "resource"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Source or resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "operationId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Resource operation UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["scope", "targetId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Back up resource">
    `towbar_backup_create`

    Request a database/resource backup. Follow the operation in towbar\_backup\_inspect; acceptance does not mean a recoverable backup exists.

    Edit access required. Required permissions: `resource.backup`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["resourceId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Restore resource backup">
    `towbar_backup_restore`

    Restore a selected backup to a resource. This can overwrite database contents. Inspect backup assurance and the target first; obtain the exact confirmation and a reason from the user. Follow progress with towbar\_backup\_inspect.

    Edit access required. Required permissions: `resource.restore`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "backupId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "confirmation": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "reason": {
          "type": "string",
          "minLength": 10,
          "maxLength": 1000
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": [
        "resourceId",
        "backupId",
        "confirmation",
        "reason",
        "idempotencyKey"
      ],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Clean up completed restore">
    `towbar_restore_cleanup`

    Request cleanup for a specific restore after reviewing its outcome. This removes retained restore artifacts; use towbar\_backup\_inspect to verify completion.

    Edit access required. Required permissions: `resource.restore`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "restoreId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "idempotencyKey": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Unique identifier for this intended action. Reuse exactly this value when retrying an uncertain response; use a new value for a new action."
        }
      },
      "required": ["resourceId", "restoreId", "idempotencyKey"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Cancel restore">
    `towbar_restore_cancel`

    Request cancellation of an eligible resource restore. Inspect the operation with towbar\_backup\_inspect afterward; acceptance is not proof that the restore stopped.

    Edit access required. Required permissions: `resource.restore`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "resourceId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Resource UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "operationId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Restore operation UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["resourceId", "operationId"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Preview environments

<AccordionGroup>
  <Accordion title="Find pull request previews">
    `towbar_preview_list`

    List preview environments for an app or source, including IDs, URLs, and lifecycle state. Use IDs from this list for deploy/cleanup, and poll it afterward to verify the outcome.

    Read-only operation. Required permissions: `workload.read`, `repository.read`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": ["app", "source"]
        },
        "targetId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "App or source UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        },
        "offset": {
          "default": 0,
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 20,
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": ["scope", "targetId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Deploy pull request preview">
    `towbar_preview_deploy`

    Request a deployment for a preview environment found by towbar\_preview\_list. Inspect the returned deployment ID and preview lifecycle afterward.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "previewEnvironmentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Preview environment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["previewEnvironmentId"],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Remove pull request preview">
    `towbar_preview_cleanup`

    Request removal of a preview environment and its runtime. Confirm the selected preview; poll towbar\_preview\_list afterward until cleanup completes or fails.

    Edit access required. Required permissions: `deployment.create`.

    **Arguments**

    ```json theme={"system"}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "previewEnvironmentId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Preview environment UUID returned by a Towbar discovery or inspection tool. Do not guess IDs."
        }
      },
      "required": ["previewEnvironmentId"],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>