Valdr Tools

Sovereign

Sovereign tier required. Valdr Tool steps make the action-based Valdr MCP surface reusable inside workflows.

Use a Valdr Tool step to call a supported Valdr action. This turns operations for projects, tasks, sprints, sessions, reviews, planning, knowledge, providers, and workflows into reusable steps with explicit inputs, dependencies, and recorded outcomes.

The Workflow Builder shows the supported actions and the fields each accepts in your installed version of Valdr.

Configuration

- key: load_task
  name: Load Task
  kind: tool
  tool:
    id: pm_task
    action: get
  inputs:
    taskKey: "${workflow.inputs.taskKey}"
  outputs:
    status: "$.normalized.task.status"

Field	Required	Purpose
`tool.id`	Yes	Valdr MCP tool, such as `pm_task` or `pm_workflow`
`tool.action`	Yes	Supported action, such as `get` or `change_status`
`inputs`	Depends on action	Values sent to the selected action
`outputs`	No	Named results made available to later steps

Put the action under tool, not inside inputs.

Inputs

Inputs can use literals, workflow inputs, prior step outputs, and runtime values:

inputs:
  taskKey: "${workflow.inputs.taskKey}"
  to: in_review
  reason: "Implementation and review preparation completed."
  actorHandle: "${runtime.actor}"

Author every action-specific required value. Valdr supplies run-owned values when the action supports them.

Outputs

Declare only the results the workflow needs later:

outputs:
  taskStatus: "$.normalized.task.status"
  assigneeHandle: "$.normalized.task.assigneeHandle"

Downstream steps read ${steps.load_task.outputs.taskStatus}. The builder’s result picker is the easiest way to choose a supported result path.

The Valdr action surface

Valdr Tools include the action-based Valdr MCP tools available to the workflow runtime:

Area	Tools
Work and planning	`pm_project`, `pm_task`, `pm_sprint`, `vmp`
Agents and evidence	`pm_agent`, `pm_session`, `pm_review`, `pm_audit`, `pm_provider`
Reusable context	`pm_prompt`, `pm_capability`, `pm_knowledge`
Workflow operations	`pm_workflow`

Tools use their normal action names and permissions. Health and ULID utilities are unavailable as workflow steps. Use the separate Git, GitHub, and Command steps for those operations. The MCP reference documents each Valdr tool’s actions and behavior; the Builder shows the fields available in your installed version.

A tool available to your agent is not automatically available as a workflow step. To use an external MCP server, run an agent session configured with that server. To call your own local program or CLI, package it as a User Tool. In a workflow, select the installed user tool’s own ID and complete pin; do not put the direct-call gateway pm_user_tool in tool.id.

Browse all Valdr MCP tools — Open the complete tool catalog, action references, discovery guidance, and examples.

Valdr records the selected tool, action, inputs, attempt, and available outputs with the run. A Valdr Tool step does not make a destructive action harmless—choose side effects deliberately and route unexpected outcomes to a block or failure policy.

For code you own or an installed CLI adapter, use User Tools. Those actions carry their own schemas, exact revision and content hash. Imported tools are immediately available in the Builder; running the workflow executes their programs on the host.

Choose the dedicated step when one exists

Use:

A session step to launch or continue an agent.
A review step to launch an independent reviewer.
A subworkflow step to run another workflow.

Those step kinds provide clearer configuration and make the workflow graph easier to understand.

Example: update task status

- key: mark_in_review
  name: Mark Task In Review
  kind: tool
  needs: [await_executor]
  tool:
    id: pm_task
    action: change_status
  inputs:
    taskKey: "${workflow.inputs.taskKey}"
    to: in_review
    actorHandle: "${runtime.actor}"
  outputs:
    status: "$.normalized.task.status"

Validation rejects unavailable actions, missing required inputs, and invalid expressions. The Builder offers output suggestions where available; test custom result selectors against a real run before relying on them.

List actions return collections. An empty pm_review/list result is a successful read with $.normalized.reviews: [] and $.normalized.review: null; it is not a failed workflow step. pm_workflow/list_runs exposes $.normalized.runs and $.normalized.page. Check whether a collection has the data your process needs before selecting an item, and map only the fields you use.

Next step

Continue with Command to run a trusted shell command, then User Tools when you need a reusable, typed local action. For other step kinds, return to Workflow Steps.

Command