Improve documentation for scan_keys and scan_all_keys functions

- Add clear warnings about partial results in scan_keys
- Include usage examples for better AI client understanding
- Add memory usage warning for scan_all_keys with large datasets
- Address maintainer feedback about potential client confusion

Author: SPRAGE

src/tools/misc.py

@@ -102,6 +102,10 @@ async def scan_keys(pattern: str = "*", count: int = 100, cursor: int = 0) -> di
     """
     Scan keys in the Redis database using the SCAN command (non-blocking, production-safe).
     
+    ⚠️  IMPORTANT: This returns PARTIAL results from one iteration. Use scan_all_keys() 
+    to get ALL matching keys, or call this function multiple times with the returned cursor
+    until cursor becomes 0.
+    
     The SCAN command iterates through the keyspace in small chunks, making it safe to use
     on large databases without blocking other operations.
 
@@ -111,13 +115,20 @@ async def scan_keys(pattern: str = "*", count: int = 100, cursor: int = 0) -> di
         count: Hint for the number of keys to return per iteration (default 100).
                Redis may return more or fewer keys than this hint.
         cursor: The cursor position to start scanning from (0 to start from beginning).
+                To continue scanning, use the cursor value returned from previous call.
 
     Returns:
         A dictionary containing:
         - 'cursor': Next cursor position (0 means scan is complete)
-        - 'keys': List of keys found in this iteration
+        - 'keys': List of keys found in this iteration (PARTIAL RESULTS)
         - 'total_scanned': Number of keys returned in this batch
+        - 'scan_complete': Boolean indicating if scan is finished
         Or an error message if something goes wrong.
+        
+    Example usage:
+        First call: scan_keys("user:*") -> returns cursor=1234, keys=[...], scan_complete=False
+        Next call: scan_keys("user:*", cursor=1234) -> continues from where it left off
+        Final call: returns cursor=0, scan_complete=True when done
     """
     try:
         r = RedisConnectionManager.get_connection()
@@ -143,6 +154,9 @@ async def scan_all_keys(pattern: str = "*", batch_size: int = 100) -> list:
     
     This function automatically handles the SCAN cursor iteration to collect all matching keys.
     It's safer than KEYS * for large databases but will still collect all results in memory.
+    
+    ⚠️  WARNING: With very large datasets (millions of keys), this may consume significant memory.
+    For large-scale operations, consider using scan_keys() with manual iteration instead.
 
     Args:
         pattern: Pattern to match keys against (default is "*" for all keys).