diff --git a/python/copilot/client.py b/python/copilot/client.py
index c800e2158..f4157b217 100644
--- a/python/copilot/client.py
+++ b/python/copilot/client.py
@@ -1238,8 +1238,15 @@ async def create_session(
             reasoning_effort: Reasoning effort level for the model.
             tools: Custom tools to register with the session.
             system_message: System message configuration.
-            available_tools: Allowlist of built-in tools to enable.
-            excluded_tools: List of built-in tools to disable.
+            available_tools: Allowlist of tools to enable. When specified, only
+                these tools will be available. Applies to the full merged tool
+                catalog including built-in tools, MCP tools, and custom tools
+                registered via ``tools=``. Custom tool names must be explicitly
+                included or they will be hidden from the model. Takes precedence
+                over ``excluded_tools``.
+            excluded_tools: List of tools to disable. Applies to all tools
+                including custom tools registered via ``tools=``. Ignored if
+                ``available_tools`` is set.
             on_user_input_request: Handler for user input requests.
             hooks: Lifecycle hooks for the session.
             working_directory: Working directory for the session.
@@ -1530,8 +1537,15 @@ async def resume_session(
             reasoning_effort: Reasoning effort level for the model.
             tools: Custom tools to register with the session.
             system_message: System message configuration.
-            available_tools: Allowlist of built-in tools to enable.
-            excluded_tools: List of built-in tools to disable.
+            available_tools: Allowlist of tools to enable. When specified, only
+                these tools will be available. Applies to the full merged tool
+                catalog including built-in tools, MCP tools, and custom tools
+                registered via ``tools=``. Custom tool names must be explicitly
+                included or they will be hidden from the model. Takes precedence
+                over ``excluded_tools``.
+            excluded_tools: List of tools to disable. Applies to all tools
+                including custom tools registered via ``tools=``. Ignored if
+                ``available_tools`` is set.
             on_user_input_request: Handler for user input requests.
             hooks: Lifecycle hooks for the session.
             working_directory: Working directory for the session.
diff --git a/python/copilot/session.py b/python/copilot/session.py
index 3e1d40931..38c5f1c37 100644
--- a/python/copilot/session.py
+++ b/python/copilot/session.py
@@ -847,9 +847,12 @@ class SessionConfig(TypedDict, total=False):
     reasoning_effort: ReasoningEffort
     tools: list[Tool]
     system_message: SystemMessageConfig  # System message configuration
-    # List of tool names to allow (takes precedence over excluded_tools)
+    # List of tool names to allow. When specified, only these tools will be available.
+    # Applies to the full merged tool catalog (built-in, MCP, and custom tools
+    # registered via tools=). Takes precedence over excluded_tools.
     available_tools: list[str]
-    # List of tool names to disable (ignored if available_tools is set)
+    # List of tool names to disable. Applies to all tools including custom tools
+    # registered via tools=. Ignored if available_tools is set.
     excluded_tools: list[str]
     # Handler for permission requests from the server
     on_permission_request: _PermissionHandlerFn
@@ -919,9 +922,12 @@ class ResumeSessionConfig(TypedDict, total=False):
     model: str
     tools: list[Tool]
     system_message: SystemMessageConfig  # System message configuration
-    # List of tool names to allow (takes precedence over excluded_tools)
+    # List of tool names to allow. When specified, only these tools will be available.
+    # Applies to the full merged tool catalog (built-in, MCP, and custom tools
+    # registered via tools=). Takes precedence over excluded_tools.
     available_tools: list[str]
-    # List of tool names to disable (ignored if available_tools is set)
+    # List of tool names to disable. Applies to all tools including custom tools
+    # registered via tools=. Ignored if available_tools is set.
     excluded_tools: list[str]
     provider: ProviderConfig
     # Reasoning effort level for models that support it.