diff --git a/src/ci/docker/x86_64-gnu-tools/checkregression.py b/src/ci/docker/x86_64-gnu-tools/checkregression.py
index 0cc0a6329e5bf..4fbb8c4d20349 100755
--- a/src/ci/docker/x86_64-gnu-tools/checkregression.py
+++ b/src/ci/docker/x86_64-gnu-tools/checkregression.py
@@ -1,9 +1,18 @@
 #!/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 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__':
     os_name = sys.argv[1]
     toolstate_file = sys.argv[2]
@@ -32,7 +41,8 @@
                 'The state of "{}" has {} from "{}" to "{}"'
                 .format(tool, verb, state, new_state)
             )
-            regressed = True
+            if not (verb == 'regressed' and tool in REGRESSION_OK):
+                regressed = True
 
     if regressed:
         sys.exit(1)
diff --git a/src/ci/docker/x86_64-gnu-tools/checktools.sh b/src/ci/docker/x86_64-gnu-tools/checktools.sh
index 2191d5d6e4680..4243effdf9b4b 100755
--- a/src/ci/docker/x86_64-gnu-tools/checktools.sh
+++ b/src/ci/docker/x86_64-gnu-tools/checktools.sh
@@ -25,6 +25,7 @@ python2.7 "$X_PY" test --no-fail-fast \
     src/doc/rust-by-example \
     src/doc/embedded-book \
     src/doc/edition-guide \
+    src/doc/rustc-guide \
     src/tools/clippy \
     src/tools/rls \
     src/tools/rustfmt \
@@ -41,7 +42,7 @@ check_tool_failed() {
 }
 
 # This function checks that if a tool's submodule changed, the tool's state must improve
-verify_status() {
+verify_submodule_changed() {
     echo "Verifying status of $1..."
     if echo "$CHANGED_FILES" | grep -q "^M[[:blank:]]$2$"; then
         echo "This PR updated '$2', verifying if status is 'test-pass'..."
@@ -66,7 +67,7 @@ verify_status() {
 check_dispatch() {
     if [ "$1" = submodule_changed ]; then
         # ignore $2 (branch id)
-        verify_status $3 $4
+        verify_submodule_changed $3 $4
     elif [ "$2" = beta ]; then
         echo "Requiring test passing for $3..."
         if check_tool_failed "$3"; then
@@ -75,7 +76,12 @@ check_dispatch() {
     fi
 }
 
-# list all tools here
+# 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
@@ -85,7 +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 for beta to successfully branch
+    # 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
     check_dispatch $1 nightly rustc-guide src/doc/rustc-guide
@@ -97,12 +106,14 @@ status_check() {
 status_check "submodule_changed"
 
 CHECK_NOT="$(readlink -f "$(dirname $0)/checkregression.py")"
+# This callback is called by `commit_toolstate_change`, see `repo.sh`.
 change_toolstate() {
     # only update the history
     if python2.7 "$CHECK_NOT" "$OS" "$TOOLSTATE_FILE" "_data/latest.json" changed; then
         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 56186a8b6a686..145f671a8cba5 100644
--- a/src/ci/docker/x86_64-gnu-tools/repo.sh
+++ b/src/ci/docker/x86_64-gnu-tools/repo.sh
@@ -42,6 +42,13 @@ commit_toolstate_change() {
     MESSAGE_FILE="$1"
     shift
     for RETRY_COUNT in 1 2 3 4 5; do
+        # 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