docs(python): clarify available_tools/excluded_tools filter all tools, not just built-ins (#1180)

Update docstrings in client.py and inline comments in session.py to
accurately document that available_tools and excluded_tools apply to
the full merged tool catalog (built-in, MCP, and custom tools registered
via tools=), not just built-in tools.

Fixes #1179

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: loganrosen

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.
@@ -1531,8 +1538,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.

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.