# pm_health & pm_generate_ulid
{{< badge content="Vanguard" color="blue" class="tier-badge" >}}

Two utility tools every agent should know about: `pm_health` for runtime diagnostics, and `pm_generate_ulid` for producing stable identifiers used by idempotent operations.

## pm_health

Returns runtime details for the PM MCP server. Use this to verify connectivity, inspect the running tool inventory, and check license status.

### Parameters

None.

### Example

```text
pm_health {}
```

### Returns

```json
{
  "status": "ok",
  "info": {
    "name": "pm-mcp",
    "version": "0.0.0",
    "startTs": "2026-04-10T19:27:40.960Z",
    "runtimeId": "...",
    "cwd": "/path/to/working/directory",
    "dataDir": "/Users/you/.valdr/pm",
    "dbPath": "/Users/you/.valdr/pm/pm.db",
    "pid": 28844,
    "tools": ["pm_agent", "pm_audit", "pm_capability", ...],
    "toolsDetailed": [...],
    "license": { "status": "valid", "tier": "sovereign" }
  }
}
```

Use this as your very first MCP call in any agent workflow. If it fails or returns a non-`ok` status, nothing else will work — the MCP server isn't reachable or isn't healthy.

---

## pm_generate_ulid

Generate a ULID (Universally Unique Lexicographically Sortable Identifier). Use this whenever you need a `clientRequestId`, `idempotencyKey`, or any other unique identifier for PM MCP tool calls.

### Parameters

None.

### Example

```text
pm_generate_ulid {}
```

### Why this matters

Many PM MCP tools require a `clientRequestId` or `idempotencyKey` to prevent duplicate operations if an agent retries. Rather than generating ULIDs in your own code, agents should call `pm_generate_ulid` directly:

```text
// Step 1: Generate an idempotency key
pm_generate_ulid {}
// → { "ulid": "01HXYZABC123..." }

// Step 2: Use it in a launch
pm_session {
  action: "launch_task",
  clientRequestId: "01HXYZABC123...",
  actor: "@skadi",
  taskKey: "MYAPI-42",
  launcherConfigKey: "coder-claude"
}
```

This ensures the ID is in the correct format and guarantees uniqueness without the agent needing to know the ULID spec.

### When to use

| Operation | Needs ULID |
|-----------|------------|
| `pm_session.start` | `clientRequestId` |
| `pm_session.restart` | `clientRequestId` |
| `pm_session.launch_task` | `clientRequestId` |
| `pm_review.launch_reviewer` | `clientRequestId` |
| `pm_audit.launch` | `clientRequestId` |
| `vmp.write_plan` | `idempotencyKey`, `txnId` |
| `vmp.commit_bundle` | `idempotencyKey`, `txnId` |
| `vmp.commit_markdown` | `idempotencyKey` |

Call `pm_generate_ulid` once per operation, not once per agent run. Reusing the same ULID across different operations breaks idempotency guarantees.

## Related

- [pm_session](../sessions/) — uses `clientRequestId` for launches
- [pm_review](../reviews/) — reviewer launches need `clientRequestId`
- [pm_audit](../audits/) — auditor launches need `clientRequestId`
- [vmp](../planner/) — plan commits need `idempotencyKey` and `txnId`