Skip to content

feat: Add boolean option to disable default GitHub CLI tools #617

@Halcyonhal9

Description

@Halcyonhal9

Problem

When building SDK sessions that use MCP servers, the 14 default GitHub CLI tools are automatically included unless filtered out via available_tools or excluded_tools. Both existing approaches have friction:

  • available_tools (allowlist): Requires pre-expanding every MCP tool name at session creation time. MCP servers expose tools dynamically, so the caller must enumerate all tool names upfront before the session starts — defeating the point of dynamic tool discovery.
  • excluded_tools (blocklist): Requires hardcoding all 14 built-in tool names. This list is an implementation detail of the runtime and may change between versions, making it fragile.

Current workaround

# Sentinel to activate the filter but match nothing
config["available_tools"] = ["__none__"]

This is brittle and relies on the filter being applied when a non-empty list is provided, while hoping no tool is ever named __none__.

Proposal

Add a boolean session config option to disable all default built-in CLI tools:

# Python
config = {
    "model": "gpt-4.1",
    "include_default_tools": False,  # disables all 14 built-in CLI tools
    "mcp_servers": { ... },
    "tools": [my_custom_tool],
}
session = await client.create_session(config)
// TypeScript
const session = await client.createSession({
  model: "gpt-4.1",
  includeDefaultTools: false,
  mcpServers: { ... },
  tools: [myCustomTool],
});

Semantics

Setting Behavior
include_default_tools: True (default) Current behavior — all 14 CLI tools included
include_default_tools: False CLI built-ins excluded; user-registered tools + MCP tools still available

This is orthogonal to available_tools / excluded_tools and would be evaluated first: if include_default_tools is False, the built-in set is empty before any allow/blocklist filtering.

Motivation

  • MCP-heavy apps that provide their own file/search/git tools via MCP servers don't want the redundant CLI tools competing for the model's attention (and token budget).
  • Minimal-tool sessions (e.g. pure chat, or single-purpose agents) shouldn't need to enumerate tool names they never asked for.
  • The fix in Fix empty list handling for tool filters in session methods #487 (v0.1.29) resolved the empty-list truthy bug, but a boolean is still more ergonomic and intention-revealing than available_tools=[] + re-adding each desired tool by name.

Related

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions