diff --git a/polaris/polaris_nodes_debug.sh b/polaris/polaris_nodes_debug.sh
index 9f0f405e04b0b1dfb9040b5b69dca9b3f767f762..3b72553d3aa7956cd49cdc2e0ae5c596ad17ff71 100755
--- a/polaris/polaris_nodes_debug.sh
+++ b/polaris/polaris_nodes_debug.sh
@@ -1,3 +1,7 @@
 #! /bin/bash
 
+# goal: show state of debug nodes excluded from prod queue
+# include: nodes marked as debug
+# output: hostname, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.debug=="True") | [.resources_available.host,.state] | @tsv'
diff --git a/polaris/polaris_nodes_demand.sh b/polaris/polaris_nodes_demand.sh
index b77131a215605058d73c53da61a6971f6490ec4e..9dd3b302b5bf3da1b46f58add58d8bdc0e6c4c55 100755
--- a/polaris/polaris_nodes_demand.sh
+++ b/polaris/polaris_nodes_demand.sh
@@ -1,3 +1,7 @@
 #! /bin/bash
 
+# goal: show state of demand nodes excluded from prod queue
+# include: nodes marked as demand
+# output: hostname, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.demand=="True") | [.resources_available.host,.state] | @tsv'
diff --git a/polaris/polaris_nodes_prod.sh b/polaris/polaris_nodes_prod.sh
index da743f1371b40180c2ed46f22749895f7a0b72ff..3360ff419fe20d49e0da10f7a429ac87c6a9735e 100755
--- a/polaris/polaris_nodes_prod.sh
+++ b/polaris/polaris_nodes_prod.sh
@@ -1,3 +1,10 @@
 #! /bin/bash
 
+# goal: determine the max job size that could run in prod queue in near future
+# example: ./polaris_nodes_prod.sh | wc -l
+# include: nodes in "free" or "job-exclusive" state
+# exclude: nodes marked as "debug" or "demand"
+# output: hostname, state
+# issues: unsure how state relates to reservations on polaris
+
 pbsnodes -a -F json | jq -r '.nodes[] | select( (.state=="free" or .state=="job-exclusive") and .resources_available.debug!="True" and .resources_available.demand!="True") | [.resources_available.host,.state] | @tsv'
diff --git a/polaris/polaris_nodes_resv.sh b/polaris/polaris_nodes_resv.sh
index 6ceaa4aa0e375de22ff68a14bdd2f65f253db221..e8d7eed5ef8bd21c611b8a1caf6263b2a59eaf1c 100755
--- a/polaris/polaris_nodes_resv.sh
+++ b/polaris/polaris_nodes_resv.sh
@@ -1,3 +1,7 @@
 #! /bin/bash
 
+# goal: show state of nodes currently under reservation
+# include: nodes with non-null resv attribute
+# output: hostname, resv attribute value, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resv!=null) | [.resources_available.host,.resv,.state] | @tsv'
diff --git a/polaris/polaris_nodes_states.sh b/polaris/polaris_nodes_states.sh
index 030199877133bc6512468a78b7eebb618bb4e565..fbe019e35702a109b16912c4ed6084b9ca35e591 100755
--- a/polaris/polaris_nodes_states.sh
+++ b/polaris/polaris_nodes_states.sh
@@ -1,3 +1,5 @@
 #! /bin/bash
 
+# goal: print list of current unique values for node state
+
 pbsnodes -a -F json | jq '[.nodes[].state] | unique'