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

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": "<process-id>",
    "tools": ["pm_agent", "pm_task", "..."],
    "license": { "status": "valid", "tier": "<tier>" }
  }
}

If the compact call fails or returns a non-ok status, nothing else will work — the MCP server isn’t reachable or isn’t healthy.

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": "<process-id>",
    "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

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