pm_health & pm_generate_ulid

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

pm_health {}

Returns

{
  "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

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:

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

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 — uses clientRequestId for launches
• pm_review — reviewer launches need clientRequestId
• pm_audit — auditor launches need clientRequestId
• vmp — plan commits need idempotencyKey and txnId