diff --git a/frontend/src/components/tools/ToolLoadingFallback.tsx b/frontend/src/components/tools/ToolLoadingFallback.tsx
new file mode 100644
index 000000000..61138a9fd
--- /dev/null
+++ b/frontend/src/components/tools/ToolLoadingFallback.tsx
@@ -0,0 +1,12 @@
+import { Center, Stack, Loader, Text } from "@mantine/core";
+
+export default function ToolLoadingFallback({ toolName }: { toolName?: string }) {
+  return (
+    <Center h="100%" w="100%">
+      <Stack align="center" gap="md">
+        <Loader size="lg" />
+        <Text c="dimmed" size="sm">
+          {toolName ? `Loading ${toolName}...` : "Loading tool..."}
+        </Text>
+      </Stack>
+    </Center>
diff --git a/frontend/src/components/tools/ToolRenderer.tsx b/frontend/src/components/tools/ToolRenderer.tsx
index c27520a40..493470935 100644
--- a/frontend/src/components/tools/ToolRenderer.tsx
+++ b/frontend/src/components/tools/ToolRenderer.tsx
@@ -1,23 +1,12 @@
 import React, { Suspense } from "react";
-import { Loader, Center, Stack, Text } from "@mantine/core";
 import { useToolManagement } from "../../hooks/useToolManagement";
 import { BaseToolProps } from "../../types/tool";
+import ToolLoadingFallback from "./ToolLoadingFallback";
 
 interface ToolRendererProps extends BaseToolProps {
   selectedToolKey: string;
 }
 
-// Loading fallback component for lazy-loaded tools
-const ToolLoadingFallback = ({ toolName }: { toolName?: string }) => (
-  <Center h="100%" w="100%">
-    <Stack align="center" gap="md">
-      <Loader size="lg" />
-      <Text c="dimmed" size="sm">
-        {toolName ? `Loading ${toolName}...` : "Loading tool..."}
-      </Text>
-    </Stack>
-  </Center>
-);
 
 const ToolRenderer = ({
   selectedToolKey,
diff --git a/frontend/src/contexts/FileSelectionContext.tsx b/frontend/src/contexts/FileSelectionContext.tsx
index 68014f592..2c79882b2 100644
--- a/frontend/src/contexts/FileSelectionContext.tsx
+++ b/frontend/src/contexts/FileSelectionContext.tsx
@@ -1,10 +1,7 @@
 import React, { createContext, useContext, useState, useCallback, ReactNode } from 'react';
-import { 
-  MaxFiles, 
-  FileSelectionState, 
-  FileSelectionActions, 
-  FileSelectionComputed, 
-  FileSelectionContextValue 
+import {
+  MaxFiles,
+  FileSelectionContextValue
 } from '../types/tool';
 
 interface FileSelectionProviderProps {
@@ -48,6 +45,10 @@ export function FileSelectionProvider({ children }: FileSelectionProviderProps)
   );
 }
 
+/**
+ * Access the file selection context.
+ * Throws if used outside a <FileSelectionProvider>.
+ */
 export function useFileSelection(): FileSelectionContextValue {
   const context = useContext(FileSelectionContext);
   if (!context) {
@@ -56,21 +57,29 @@ export function useFileSelection(): FileSelectionContextValue {
   return context;
 }
 
+// Returns only the file selection values relevant for tools (e.g. merge, split, etc.)
+// Use this in tool panels/components that need to know which files are selected and selection limits.
 export function useToolFileSelection(): Pick<FileSelectionContextValue, 'selectedFiles' | 'maxFiles' | 'canSelectMore' | 'isAtLimit' | 'selectionCount'> {
   const { selectedFiles, maxFiles, canSelectMore, isAtLimit, selectionCount } = useFileSelection();
   return { selectedFiles, maxFiles, canSelectMore, isAtLimit, selectionCount };
 }
 
+// Returns actions for manipulating file selection state.
+// Use this in components that need to update the selection, clear it, or change selection mode.
 export function useFileSelectionActions(): Pick<FileSelectionContextValue, 'setSelectedFiles' | 'clearSelection' | 'setMaxFiles' | 'setIsToolMode'> {
   const { setSelectedFiles, clearSelection, setMaxFiles, setIsToolMode } = useFileSelection();
   return { setSelectedFiles, clearSelection, setMaxFiles, setIsToolMode };
 }
 
+// Returns the raw file selection state (selected files, max files, tool mode).
+// Use this for low-level state access, e.g. in context-aware UI.
 export function useFileSelectionState(): Pick<FileSelectionContextValue, 'selectedFiles' | 'maxFiles' | 'isToolMode'> {
   const { selectedFiles, maxFiles, isToolMode } = useFileSelection();
   return { selectedFiles, maxFiles, isToolMode };
 }
 
+// Returns computed values derived from file selection state.
+// Use this for file selection UI logic (e.g. disabling buttons when at limit).
 export function useFileSelectionComputed(): Pick<FileSelectionContextValue, 'canSelectMore' | 'isAtLimit' | 'selectionCount' | 'isMultiFileMode'> {
   const { canSelectMore, isAtLimit, selectionCount, isMultiFileMode } = useFileSelection();
   return { canSelectMore, isAtLimit, selectionCount, isMultiFileMode };