pm_user_tool

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.

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. It counts text without reading files or accessing the network.

For the current call reference and examples:

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:

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:

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:

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 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.

Try it with your agent