From 1c69a03e37d2af3a0c27823e31403f80a4e276e0 Mon Sep 17 00:00:00 2001 From: Logan Rosen Date: Thu, 30 Apr 2026 13:22:48 -0400 Subject: [PATCH] docs(python): clarify available_tools/excluded_tools filter all tools, not just built-ins 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> --- python/copilot/client.py | 22 ++++++++++++++++++---- python/copilot/session.py | 14 ++++++++++---- 2 files changed, 28 insertions(+), 8 deletions(-) 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.