diff --git a/src/ci/docker/x86_64-gnu-tools/checkregression.py b/src/ci/docker/x86_64-gnu-tools/checkregression.py
index 72acb107405e5..4fbb8c4d20349 100755
--- a/src/ci/docker/x86_64-gnu-tools/checkregression.py
+++ b/src/ci/docker/x86_64-gnu-tools/checkregression.py
@@ -1,10 +1,16 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+## This script has two purposes: detect any tool that *regressed*, which is used
+## during the week before the beta branches to reject PRs; and detect any tool
+## that *changed* to see if we need to update the toolstate repo.
+
 import sys
 import json
 
-# Regressions for these tools do not cause failure.
+# Regressions for these tools during the beta cutoff week do not cause failure.
+# See `status_check` in `checktools.sh` for tools that have to pass on the
+# beta/stable branches.
 REGRESSION_OK = ["rustc-guide", "miri", "embedded-book"]
 
 if __name__ == '__main__':
diff --git a/src/ci/docker/x86_64-gnu-tools/checktools.sh b/src/ci/docker/x86_64-gnu-tools/checktools.sh
index 8df63c214e189..e0de51e2cb0ab 100755
--- a/src/ci/docker/x86_64-gnu-tools/checktools.sh
+++ b/src/ci/docker/x86_64-gnu-tools/checktools.sh
@@ -79,6 +79,9 @@ check_dispatch() {
 # List all tools here.
 # This function gets called with "submodule_changed" for each PR that changed a submodule,
 # and with "beta_required" for each PR that lands on beta/stable.
+# The purpose of this function is to *reject* PRs if a tool is not "test-pass" and
+# (a) the tool's submodule has been updated, or (b) we landed on beta/stable and the
+# tool has to "test-pass" on that branch.
 status_check() {
     check_dispatch $1 beta book src/doc/book
     check_dispatch $1 beta nomicon src/doc/nomicon
@@ -88,8 +91,10 @@ status_check() {
     check_dispatch $1 beta rls src/tools/rls
     check_dispatch $1 beta rustfmt src/tools/rustfmt
     check_dispatch $1 beta clippy-driver src/tools/clippy
-    # These tools are not required on the beta/stable branches.
-    # They will still cause failure during the beta cutoff week, see `checkregression.py` for that.
+    # These tools are not required on the beta/stable branches, but they *do* cause
+    # PRs to fail if a submodule update does not fix them.
+    # They will still cause failure during the beta cutoff week, unless `checkregression.py`
+    # exempts them from that.
     check_dispatch $1 nightly miri src/tools/miri
     check_dispatch $1 nightly embedded-book src/doc/embedded-book
 }
@@ -107,6 +112,7 @@ change_toolstate() {
         echo 'Toolstate is not changed. Not updating.'
     else
         if [ $SIX_WEEK_CYCLE -ge 35 ]; then
+            # Reject any regressions during the week before beta cutoff.
             python2.7 "$CHECK_NOT" "$OS" "$TOOLSTATE_FILE" "_data/latest.json" regressed
         fi
         sed -i "1 a\\
diff --git a/src/ci/docker/x86_64-gnu-tools/repo.sh b/src/ci/docker/x86_64-gnu-tools/repo.sh
index 35ab7e2b8c839..f06129551a464 100644
--- a/src/ci/docker/x86_64-gnu-tools/repo.sh
+++ b/src/ci/docker/x86_64-gnu-tools/repo.sh
@@ -62,10 +62,13 @@ commit_toolstate_change() {
     MESSAGE_FILE="$1"
     shift
     for RETRY_COUNT in 1 2 3 4 5; do
-        # Call the callback; this will in the end call `change_toolstate` from
-        # `checktools.sh` if we are in the `auto` branch (pre-landing) or
-        # `src/tools/publish_toolstate.py` if we are in the `master` branch
-        # (post-landing).
+        # Call the callback.
+        # - If we are in the `auto` branch (pre-landing), this is called from `checktools.sh` and
+        #   the callback is `change_toolstate` in that file. The purpose of this is to publish the
+        #   test results (the new commit-to-toolstate mapping) in the toolstate repo.
+        # - If we are in the `master` branch (post-landing), this is called by the CI pipeline
+        #   and the callback is `src/tools/publish_toolstate.py`. The purpose is to publish
+        #   the new "current" toolstate in the toolstate repo.
         "$@"
         # `git commit` failing means nothing to commit.
         FAILURE=0
diff --git a/src/tools/publish_toolstate.py b/src/tools/publish_toolstate.py
index 8f9061d7c1811..b8dcba3afc3a1 100755
--- a/src/tools/publish_toolstate.py
+++ b/src/tools/publish_toolstate.py
@@ -1,6 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+## This script publishes the new "current" toolstate in the toolstate repo (not to be
+## confused with publishing the test results, which happens in
+## `src/ci/docker/x86_64-gnu-tools/checktools.sh`).
+## It is set as callback for `src/ci/docker/x86_64-gnu-tools/repo.sh` by the CI scripts
+## when a new commit lands on `master` (i.e., after it passed all checks on `auto`).
+
 import sys
 import re
 import os