{
  "name": "list_nodes",
  "description": "List active cluster nodes with their metadata. By default only nodes with a fresh service-registry heartbeat (within 120s) are returned. Pass arbitrary `key=value` filters to narrow; all filters must match (AND). Pair with `target_node` on spawn_workstream to pin a child to a node that matches a capability. The 120s heartbeat is a sliding window, so a node returned here can drop out before a follow-up spawn lands — the race produces `\"No available node for routing\"`; omit `target_node` to let rendezvous pick from the still-healthy set, or retry after re-listing if a specific node is required. The `interfaces` key (container IPs, interface names) is stripped by default — routing should use capability/region tags, not IPs; pass `include_network_detail=true` only for debugging. Pass `include_inactive=true` to surface stale registrations (those nodes will reject `target_node` pinning).",
  "parameters": {
    "type": "object",
    "properties": {
      "filters": {
        "type": "object",
        "description": "Optional dict of key=value pairs to filter by. Pass values in their natural JSON type — string, integer, number, or boolean. Filter comparison is JSON-equal against the stored value (e.g. cpu_count=4 as int matches the stored integer, NOT the string \"4\"). Omit to list all nodes. Examples: {\"arch\": \"x86_64\"}, {\"capability\": \"gpu\", \"region\": \"us-west\"}, {\"cpu_count\": 4}.",
        "additionalProperties": {
          "type": ["string", "integer", "number", "boolean"]
        }
      },
      "limit": {
        "type": "integer",
        "description": "Max rows to return. Default 100, max 500."
      },
      "include_network_detail": {
        "type": "boolean",
        "description": "When true, include the auto-populated `interfaces` key (container IPs, interface names). Default false — routing decisions should use capability tags, not IPs, and including internal network detail trips the private-IP output guard."
      },
      "include_inactive": {
        "type": "boolean",
        "description": "When true, also return nodes whose service-registry heartbeat is stale (>120s old). Default false. Use only for debugging stale registrations; inactive nodes will reject `target_node` pinning and should not be used for `spawn_workstream` routing."
      }
    }
  },
  "coordinator": true,
  "auto_approve": true
}
