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 catalog-approved Valdr action that is available to the workflow runtime. This turns eligible 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 reads the executable catalog installed with Valdr and shows the fields each supported action accepts. Eligible registered actions can join that catalog without requiring a new workflow step kind; actions outside the catalog are unavailable to workflows.

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`

Action-based tools use their normal action names. The aggregate Valdr adapter exposes registered actions, including pm_workflow actions, through the executable catalog. Each action retains its normal authorization and runtime restrictions. Health and ULID utilities are also absent from the workflow-step catalog. Git, GitHub, and Command use dedicated adapters because their evidence and side-effect contracts are different. The MCP reference is the canonical documentation for each Valdr tool’s actions and behavior; the Builder shows the executable fields available in your installed version.

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.

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"

Strict validation rejects unavailable actions, missing required inputs, and invalid expressions. The Builder offers contract-backed output suggestions where available; test arbitrary result selectors against a real run before relying on them. Each Valdr Tool card is derived from the same action catalog used by the runtime, so its executable fields stay aligned with the installed version.

Next step

Return to Workflow Steps, use Git for repository operations, GitHub for pull-request publication, Command for a trusted shell command, or continue with Session Steps to add agent work.

Git