name: list_windows

description:
List top-level windows. Each record includes z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one). To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order.

input_schema:
{
  "additionalProperties": false,
  "properties": {
    "on_screen_only": {
      "description": "When true, filter to visible windows only. Default false.",
      "type": "boolean"
    },
    "pid": {
      "type": "integer"
    }
  },
  "type": "object"
}