# Valdr Tools
{{< tier level="sovereign" note="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

```yaml
- 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:

```yaml
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:

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

{{< callout type="info" >}}
**[Browse all Valdr MCP tools](/valdr/docs/valdr-mcp/)** — Open the complete tool catalog, action references, discovery guidance, and examples.
{{< /callout >}}

{{< callout type="info" >}}
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.
{{< /callout >}}

## Choose the dedicated step when one exists

Use:

- A [`session`](../session/) step to launch or continue an agent.
- A [`review`](../review/) step to launch an independent reviewer.
- A [`subworkflow`](../subworkflow/) step to run another workflow.

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

## Example: update task status

```yaml
- 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](../git/) for repository operations, [GitHub](../github/) for pull-request publication, [Command](../command/) for a trusted shell command, or continue with [Session Steps](../session/) to add agent work.