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.

Neither tool accepts an action selector or has a help action.

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

Compact example

pm_health {}

Use the compact default as your first MCP call. It confirms the server is reachable, shows environment-specific runtime metadata, and returns the names of the registered tools.

Returns

{
  "status": "ok",
  "info": {
    "name": "pm-mcp",
    "version": "<version>",
    "startTs": "<iso-8601-start-time>",
    "runtimeId": "<runtime-id>",
    "cwd": "<working-directory>",
    "dataDir": "<valdr-data-directory>",
    "dbPath": "<valdr-database-path>",
    "pid": 12345,
    "tools": ["pm_agent", "pm_task", "..."],
    "license": { "status": "valid", "tier": "<tier>" }
  }
}

Check isError on the MCP result. A failure may be a connection, startup, or license error; it does not always mean the process is unreachable. Successful output is under structuredContent, with a readable summary in content.

Detailed example

pm_health { detail: true }

Use detailed mode when an agent needs to discover the live MCP tool surface before choosing its next call. The response includes the same runtime fields as the compact response, plus toolsDetailed.

{
  "status": "ok",
  "info": {
    "name": "pm-mcp",
    "version": "<version>",
    "startTs": "<iso-8601-start-time>",
    "runtimeId": "<runtime-id>",
    "cwd": "<working-directory>",
    "dataDir": "<valdr-data-directory>",
    "dbPath": "<valdr-database-path>",
    "pid": 12345,
    "tools": ["pm_agent", "pm_task", "..."],
    "license": { "status": "valid", "tier": "<tier>" },
    "toolsDetailed": [
      {
        "name": "pm_agent",
        "description": "Agent management (action: create|get|list|...)."
      },
      {
        "name": "pm_task",
        "description": "Task management (action: create|get|search|...)."
      }
    ]
  }
}

toolsDetailed is detail-mode-only. It is not returned by the compact pm_health {} call.

Response fields

Local runtime values such as paths, process IDs, runtime IDs, start times, versions, and license tiers are environment-specific. Use placeholders in reusable docs and prompts; read live output when an agent needs the actual values for diagnostics.

Discovery workflow

1. Call pm_health {} to confirm the server is reachable.
2. Call pm_health { detail: true } when you need the verbose live tool inventory.
3. Call an individual tool’s help action, such as pm_task { action: "help" }, for canonical action details, examples, cautions, and compatibility notes.

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

Example

pm_generate_ulid {}

The structured result is { "ulid": "<generated-id>" }. For a batch, pm_generate_ulid { count: 3 } returns ulid for the first ID plus an ulids array containing all three.

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

Use the returned value rather than the abbreviated sample ID. Keep it with the original arguments so an uncertain request can be retried consistently.

When to use

Generate new IDs for distinct operations, and reuse the original ID when retrying the same operation with unchanged arguments. Do not generate a new ID merely because a call timed out. For planner operations that require both idempotencyKey and txnId, generate and retain both values.

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