diff --git a/pkgs/clan-cli/clan_lib/machines/actions.py b/pkgs/clan-cli/clan_lib/machines/actions.py
index 280c0aead..2c6012fbb 100644
--- a/pkgs/clan-cli/clan_lib/machines/actions.py
+++ b/pkgs/clan-cli/clan_lib/machines/actions.py
@@ -105,6 +105,18 @@ class Writeability(TypedDict):
 
 @API.register
 def get_machine_writeability(machine: Machine) -> dict[str, Writeability]:
+    """
+    Get writeability information for the fields of a machine.
+
+    This function checks which fields of the 'machine' resource are writable and provides a reason for each field's writability.
+
+    Args:
+        machine (Machine): The machine object for which to retrieve writeability.
+
+    Returns:
+        dict[str, Writeability]: A map from field-names to { 'writable' (bool) and 'reason' (str or None ) }
+    """
+
     inventory_store = InventoryStore(machine.flake)
     write_info = inventory_store.get_writeability_of(f"machines.{machine.name}")