tools: Document tools.toml

- So that it can be understood in isolation by ai.

eris/tools.toml

@@ -1,5 +1,6 @@
 
-
+# tools_for_extensions is a mapping that defines which tools are run on files of
+# certain types. The tools are defined below.
 tools_for_extensions = [
    [["py"], ["python_syntax", "python_unittests", "pytest", "pydoc", "mypy",
              "python_coverage", "pycodestyle", "pyflakes",
@@ -43,6 +44,17 @@ tools_for_extensions = [
    [["iso"], ["isoinfo"]],
    ]
 
+# Now define all the tools.
+#
+# Each section defines a tool by these attributes:
+#   dependencies: A list of debian packages that need to be installed for the tool to run.
+#   url: Where the tool is documented.
+#   command: The shell command to run the tool. All tools must produce a text report given a
+#            file in the codebase. The file's path is added to the end of the command.
+#            All reports are ideally in color. All tools should return an error code of 0 iff
+#            there are no issues with the file.
+#   has_color: Is true if the command's output is in color.
+#   timeout: Some commands have a timeout if they can't be trusted to finish in a reasonable time.
 
 [python_syntax]
   dependencies = []