docs: improve comments to reason about sections of code

Co-authored-by: Michael Brooks <michael@michaelbrooks.ca>

Author: zimeg

ai/tools/dice.py

@@ -18,6 +18,8 @@ def roll_dice(sides: int = 6, count: int = 1) -> dict:
             "rolls": [],
             "total": 0,
         }
+
+    # Roll the dice and calculate the total
     rolls = [random.randint(1, sides) for _ in range(count)]
     total = sum(rolls)
 

listeners/assistant/message.py

@@ -41,6 +41,7 @@ def message(
         user_id = context.user_id
 
         # This first example shows a generated text response for the provided prompt
+        # displayed as a timeline.
         if message["text"] != "Wonder a few deep thoughts.":
             set_status(
                 status="thinking...",
@@ -74,6 +75,7 @@ def message(
             )
 
         # The second example shows detailed thinking steps similar to tool calls
+        # displayed as plan.
         else:
             streamer = client.chat_stream(
                 channel=channel_id,