# pm_user_tool
{{< tier level="sovereign" note="Let agents use your installed user tools directly, without creating a workflow." >}}

Your build helpers, reporting scripts, and CLI adapters can serve both workflows and everyday agent requests. With `pm_user_tool`, an agent finds an installed action, reads the inputs it needs, and runs it through the same Valdr MCP connection it already uses.

This guide covers finding an action, running it, and handling a repeat request. To write or install a tool first, start with [Build User Tools](/valdr/docs/workflows/user-tools/).

## Before you start

Import a user-tool pack and make sure its runtime or CLI is installed on the machine running Valdr. Your agent's MCP permissions must allow `pm_user_tool`; inspecting tools and running them can be permitted separately.

The examples below use the Node text summary from the [starter pack](/valdr/docs/workflows/user-tools/starters/). It counts text without reading files or accessing the network.

For the current call reference and examples:

```text
pm_user_tool { action: "help" }
```

If your MCP connection does not expose `pm_user_tool`, check your Valdr version, Sovereign access, and the tools enabled for that session.

## Find and inspect an action

Search by what you want to do:

```text
pm_user_tool { action: "search", query: "text summary" }
```

Omit `query` to browse. Use `toolId` to narrow the results to one installed tool, or pass the returned `nextOffset` as `offset` for the next page. Results identify the tool, action, selected revision, side effects, and whether the action is supported.

Read the action's inputs and outputs before running it:

```text
pm_user_tool {
  action: "describe",
  toolId: "valdr-tools.user.node",
  toolAction: "summarize"
}
```

`describe` returns the input and output schemas and execution limits. Searching and inspecting do not run the tool. A supported action still needs its runtime, credentials, and working directory available when you run it.

## Run it

Generate a fresh request ID with `pm_generate_ulid {}`, then supply the action's input and an existing absolute working directory on the Valdr host:

```text
pm_user_tool {
  action: "run",
  toolId: "valdr-tools.user.node",
  toolAction: "summarize",
  input: { text: "Hello Valdr" },
  cwd: "/absolute/path/to/your/project",
  clientRequestId: "<fresh ULID>"
}
```

Replace the directory and request ID before calling. `toolAction` selects the installed action; `input` contains that action's own fields. The result appears in `data.result`—here, the character, word, and line counts.

The call waits for the tool to finish. Optional `timeoutSeconds` can shorten its configured time limit, up to the host maximum of 300 seconds; it cannot extend that limit. Configure your MCP client's request timeout to allow the expected run time plus startup and cleanup.

Tools run as your user on the Valdr host, using their declared environment and that host's CLI sign-ins. Review an action's effects before running it. See [Requests and Execution](/valdr/docs/workflows/user-tools/runtime/) for environment setup and sensitive-output guidance.

## Choose a revision

By default, each call selects the most recently installed visible revision, rather than the highest version number. Pass an optional `revision` to `search`, `describe`, or `run` to select a particular installed version. Describe and run fail if that revision or action is missing, instead of falling back to an older one.

Use the revision returned by `describe` when you want the same version label for `run`. An approved pack overwrite can replace the contents under that label, so publish changed tools with a new revision.

## If a response is lost

Repeat the same call with the **same `clientRequestId`**. A recorded result is returned with `replayed: true`; changed input under that ID is rejected. Reusing the ID does not start the action again, and a removed tool may no longer be available to replay.

If the response says `outcome_unknown` or `needsAttention`, check what happened before making a new request. A timeout or cancellation cannot undo an external change. Use a fresh ID only when you deliberately intend a new invocation.

## Use it in a workflow

For a reusable process, add the installed tool directly from the Builder's **User tools** group. Workflow steps keep their selected revision and content hash. `pm_user_tool` is for direct agent calls and is not a workflow step; see [User Tool steps](/valdr/docs/workflows/steps/user-tool/).

## Try it with your agent

{{< prompts intro="With the starter pack imported, ask your agent:" >}}
Find the installed Node text summary tool, inspect its inputs, and summarize “Hello Valdr” using my project directory.
{{< /prompts >}}