diff --git a/pkgs/clan-cli/clan_lib/ssh/remote.py b/pkgs/clan-cli/clan_lib/ssh/remote.py
index ec8c4e5d0..5356cf9ee 100644
--- a/pkgs/clan-cli/clan_lib/ssh/remote.py
+++ b/pkgs/clan-cli/clan_lib/ssh/remote.py
@@ -470,6 +470,22 @@ def check_machine_ssh_login(
 def check_machine_ssh_reachable(
     remote: Remote, opts: ConnectionOptions | None = None
 ) -> CheckResult:
+    """
+    Checks if a remote machine is reachable via SSH by attempting to open a TCP connection
+    to the specified address and port.
+    Args:
+        remote (Remote): The remote host to check for SSH reachability.
+        opts (ConnectionOptions, optional): Connection options such as timeout and number of retries.
+            If not provided, default values are used.
+    Returns:
+        CheckResult: An object indicating whether the SSH port is reachable (`ok=True`) or not (`ok=False`),
+        and a reason if the check failed.
+    Usage:
+        result = check_machine_ssh_reachable(remote)
+        if result.ok:
+            print("SSH port is reachable")
+            print(f"SSH port is not reachable: {result.reason}")
+    """
     if opts is None:
         opts = ConnectionOptions()