diff --git a/packages/SwingSet/misc-tools/block-times.py b/packages/SwingSet/misc-tools/block-times.py
index 8c90c2481a7e..63169d7812d8 100644
--- a/packages/SwingSet/misc-tools/block-times.py
+++ b/packages/SwingSet/misc-tools/block-times.py
@@ -1,15 +1,15 @@
 #
-# given a slogfile on stdin, emit a CSV of (blockHeight, start,
-# elapsed) that measures the swingset time for each block (from
-# cosmic-swingset-end-block-start to
-# cosmic-swingset-end-block-finish), suitable for pasting into a
-# spreadsheet to make a graph
+# Given a slogfile on stdin, emit a CSV for every end-block:
+#   height,start,lag,swingset,deliveries,computrons,bridge_inbounds,consensus_time,block_time
+# "lag" is the duration between begin-block `blockTime` and `time`, "swingset"
+# is the duration of end-block, "deliveries" and "computrons" and
+# "bridge_inbounds" are counts, "consensus_time" is the duration from
+# after-commit-block to the next begin-block, "block_time" is the duration
+# between consecutive begin-blocks, and all durations are in seconds.
 
 import sys, json, statistics
 
 print("height,start,lag,swingset,deliveries,computrons,bridge_inbounds,consensus_time,block_time")
-# consensus_time is from cosmic-swingset-after-commit-block to cosmic-swingset-begin-block
-# block_time is from cosmic-swingset-end-block-start to cosmic-swingset-end-block-start
 
 lag = None # time - blockTime, how far was the node behind
 start = None # latest cosmic-swingset-end-block-start time