> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/ai/tool-inventory.md).

# Tool Inventory

The MCP tools the Pipekit server exposes, with their destructive-hint annotations.

Each tool is annotated with the standard MCP `readOnlyHint` and `destructiveHint` so compatible LLM clients (Claude Desktop, Cursor, Claude Code) can render appropriate warnings or apply approval policies.

The annotation rules are:

* **Read-only tools** (`list_*`, `get_*`, `version`) carry `readOnlyHint: true`. Safe by definition.
* **Additive tools** that only create new resources (`submit_workflow`, `restart_run`, `create_cron`, `trigger_cron`, `import_workflows`) carry `destructiveHint: false`. They do change state, but they don't overwrite or delete existing resources.
* **Mutating or deleting tools** carry `destructiveHint: true`. Clients that honor MCP annotations prompt before calling these.

`retry_run` also carries `destructiveHint: false`, but it does not follow the additive rule. It rewrites the existing Run's workflow and deletes the pods of the steps it resets. Take that into account when you write an approval policy from these hints.

## MCP tools

| Tool                | Hints                             | Purpose                                                               |
| ------------------- | --------------------------------- | --------------------------------------------------------------------- |
| `version`           | readOnly                          | Return the CLI / server version.                                      |
| `list_clusters`     | readOnly                          | List Clusters in the current Organization.                            |
| `list_pipes`        | readOnly                          | List Pipes on a Cluster (paginated, filterable).                      |
| `list_runs`         | readOnly                          | List Runs (paginated, filter by Pipe / status / cluster / namespace). |
| `get_run`           | readOnly                          | Fetch one Run by UUID or by `(cluster, namespace, workflow name)`.    |
| `get_workflow_node` | readOnly                          | Fetch one node inside a Run's workflow graph.                         |
| `get_run_logs`      | readOnly                          | Fetch a snapshot of container logs for a Run, with grep/head/tail.    |
| `submit_workflow`   | destructiveHint: false (additive) | Submit a Workflow YAML to a Cluster.                                  |
| `restart_run`       | destructiveHint: false (additive) | Resubmit a Run with the same parameters.                              |
| `retry_run`         | destructiveHint: false            | Rerun the failed steps of a finished Run, keeping successful steps.   |
| `stop_run`          | destructiveHint: true             | Gracefully stop a Run (exit handlers complete).                       |
| `terminate_run`     | destructiveHint: true             | Terminate a Run immediately (no exit handlers).                       |
| `update_cluster`    | destructiveHint: true             | Update a Cluster's name, description, or status.                      |
| `create_cron`       | destructiveHint: false (additive) | Create a CronWorkflow on a Cluster.                                   |
| `update_cron`       | destructiveHint: true             | Update an existing CronWorkflow.                                      |
| `delete_cron`       | destructiveHint: true             | Delete a CronWorkflow.                                                |
| `suspend_cron`      | destructiveHint: true             | Suspend a CronWorkflow (stops scheduling new Runs).                   |
| `resume_cron`       | destructiveHint: true             | Resume a suspended CronWorkflow.                                      |
| `trigger_cron`      | destructiveHint: false (additive) | Run a CronWorkflow immediately, regardless of schedule.               |
| `import_workflows`  | destructiveHint: false (additive) | Import workflows from an Argo Workflow Archive into Pipekit.          |

The live source of truth is the registry at [`tools/cli/cmd/mcp/tools/registry.go`](https://github.com/pipekit/pipeline-mono/blob/master/tools/cli/cmd/mcp/tools/registry.go). For the parameter schema of each tool, ask your MCP client to introspect the server (every MCP client has a way to list tools and their input schemas).

## Restart or retry

`restart_run` and `retry_run` are not interchangeable. `restart_run` builds a new workflow from the original spec and runs every step again, producing a new Run. `retry_run` keeps the steps that already succeeded, reruns only the failed ones, and puts the existing Run back into a running state.

| Input               | `restart_run` | `retry_run`                                                |
| ------------------- | ------------- | ---------------------------------------------------------- |
| Run identifier      | `runUUID`     | `runUUID`, or `clusterName` + `namespace` + `workflowName` |
| Node scope          | not supported | `nodeFieldSelector`, for example `id=5`                    |
| Rerun passing steps | not supported | `restartSuccessful`, with `nodeFieldSelector`              |
| Parameter overrides | not supported | `parameters`, as `KEY=VALUE` strings                       |

Pass either `runUUID` or the full cluster/namespace/workflow triple to `retry_run`, never both; the tool rejects a call that mixes them. Set `nodeFieldSelector` and `restartSuccessful` together to reset a node that already succeeded and everything downstream of it. Argo reads the selector only when `restartSuccessful` is set, so a call that omits `restartSuccessful` reruns the failed steps and ignores the selector:

```json
{"runUUID": "<uuid>", "nodeFieldSelector": "id=5", "restartSuccessful": true}
```

Retrying a workflow that finished successfully requires both of those fields.

`retry_run` returns a successful result before Pipekit Agent evaluates the request, so a rejected retry still looks like a success to the client. When the agent rejects a retry, it writes the reason to the Run's logs. See [Troubleshooting](https://docs.pipekit.io/ai/troubleshooting.md#retry_run-returns-a-result-but-no-steps-rerun) for the common causes, and [Reference > CLI > Commands](https://docs.pipekit.io/reference/cli/commands.md#choose-between-restart-and-retry) for the same choice from the CLI.

## MCP resources

In addition to tools, the server publishes a library of read-only resources the agent can list and fetch on demand:

* **Argo workflow schemas**: the `Workflow` and `CronWorkflow` JSON schemas.
* **Workflow examples**: small reference workflows the agent can crib from.
* **Pipekit how-to guides**: `pipekit://guides/{debugging-a-failed-run,workflow-authoring,parameters-and-artifacts,template-types,submitting-workflows,importing-workflows,cron-workflows,identifiers,offline-lint-templateref-footgun}`.

The guides are shipped with the CLI binary, not fetched from the network, so they're available even when the agent is offline relative to <https://pipekit.io>.
