Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

support preloaded custom tool schemas

Dhawal Upadhyaya2db64a1503c
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.py
index 154ae7dc5..b4664ec56 100644
--- a/python/composio/core/models/custom_tool.py
+++ b/python/composio/core/models/custom_tool.py
@@ -610,6 +610,7 @@ def build_custom_tools_map(
handle: CustomTool, final_slug: str, toolkit: t.Optional[str]
) -> None:
original_slug = handle.slug.upper()
+ final_slug_key = final_slug.upper()
if len(final_slug) > MAX_SLUG_LENGTH:
raise ValidationError(
@@ -617,7 +618,7 @@ def build_custom_tools_map(
f'"{final_slug}" which exceeds {MAX_SLUG_LENGTH} characters.'
)
- if final_slug in by_final_slug:
+ if final_slug_key in by_final_slug:
raise ValidationError(
f'Custom tool slug collision: "{final_slug}" is already registered.'
)
@@ -634,7 +635,7 @@ def build_custom_tools_map(
entry = CustomToolsMapEntry(
handle=handle, final_slug=final_slug, toolkit=toolkit
)
- by_final_slug[final_slug] = entry
+ by_final_slug[final_slug_key] = entry
by_original_slug[original_slug] = entry
# Process standalone tools
@@ -716,3 +717,42 @@ def build_custom_tools_map_from_response(
by_original_slug=by_original_slug,
toolkits=list(toolkits) if toolkits else None,
)
+
+
+def find_custom_tool_map_entry_by_final_slug(
+ custom_tools_map: t.Optional[CustomToolsMap],
+ slug: str,
+) -> t.Optional[CustomToolsMapEntry]:
+ """Find a custom tool entry by final slug only."""
+ if custom_tools_map is None:
+ return None
+ return custom_tools_map.by_final_slug.get(slug.upper())
+
+
+def get_preloaded_custom_tool_slugs(
+ tool_router_tools: t.Optional[t.Iterable[str]],
+ custom_tools_map: t.Optional[CustomToolsMap],
+) -> t.List[str]:
+ """Return final custom tool slugs selected by the backend for preload."""
+ if tool_router_tools is None or custom_tools_map is None:
+ return []
+
+ seen: t.Set[str] = set()
+ custom_tool_slugs: t.List[str] = []
+
+ for slug in tool_router_tools:
+ entry = find_custom_tool_map_entry_by_final_slug(
+ custom_tools_map,
+ str(slug),
+ )
+ if entry is None:
+ continue
+
+ final_slug_key = entry.final_slug.upper()
+ if final_slug_key in seen:
+ continue
+
+ seen.add(final_slug_key)
+ custom_tool_slugs.append(entry.final_slug)
+
+ return custom_tool_slugs
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index a460ed503..d8392d4e6 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -20,6 +20,7 @@ from composio.core.models.base import Resource
from composio.core.models.custom_tool import (
ExperimentalToolkit,
build_custom_tools_map_from_response,
+ get_preloaded_custom_tool_slugs,
serialize_custom_tools,
serialize_custom_toolkits,
)
@@ -51,6 +52,7 @@ ToolRouterTag = t.Literal[
# +----------+------+------+
# Defaults to "standard" server-side when omitted.
SandboxSize = t.Literal["standard", "medium", "large", "xlarge"]
+SessionPreset = t.Literal["direct_tools"]
class ToolRouterToolkitsEnableConfig(te.TypedDict, total=False):
@@ -217,7 +219,34 @@ class ToolRouterPreloadConfig(te.TypedDict, total=False):
tool lists without first calling search.
"""
- tools: t.List[str]
+ tools: t.Union[t.List[str], str]
+
+
+def _session_preload_config(session: t.Any) -> ToolRouterSessionPreloadConfig:
+ tools = session.config.preload.tools
+ return ToolRouterSessionPreloadConfig(
+ tools=tools if isinstance(tools, str) else list(tools or [])
+ )
+
+
+def _apply_session_preset_defaults(
+ session_preset: t.Optional[SessionPreset],
+ manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],
+ workbench: t.Optional[ToolRouterWorkbenchConfig],
+ preload: t.Optional[ToolRouterPreloadConfig],
+) -> t.Tuple[
+ t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],
+ t.Optional[ToolRouterWorkbenchConfig],
+ t.Optional[ToolRouterPreloadConfig],
+]:
+ if session_preset != "direct_tools":
+ return manage_connections, workbench, preload
+
+ return (
+ False if manage_connections is None else manage_connections,
+ {"enable": False} if workbench is None else workbench,
+ {"tools": "all"} if preload is None else preload,
+ )
class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):
@@ -497,6 +526,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
preload: t.Optional[ToolRouterPreloadConfig] = None,
+ session_preset: t.Optional[SessionPreset] = None,
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
) -> ToolRouterSession[TTool, TToolCollection]:
"""
@@ -553,8 +583,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
Example: {'github': 'ac_xxx', 'slack': 'ac_yyy'}
:param connected_accounts: Optional mapping of toolkit slug to connected account ID.
Example: {'github': 'ca_xxx', 'slack': 'ca_yyy'}
- :param workbench: Optional workbench configuration (ToolRouterWorkbenchConfig).
- Dict with:
+ :param workbench: Optional workbench configuration. Dict with:
- 'enable' (bool): Whether to enable the workbench entirely.
Defaults to True. When set to False, no code execution tools
(COMPOSIO_REMOTE_WORKBENCH, COMPOSIO_REMOTE_BASH_TOOL) are
@@ -579,9 +608,19 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
account selection when multiple accounts are connected.
Example: {'enable': True, 'max_accounts_per_toolkit': 3}
:param preload: Optional preload configuration. Dict with:
- - 'tools' (List[str]): Tool slugs to expose directly in
- session.tools() and MCP tool lists.
+ - 'tools' (List[str] | 'all'): Tool slugs to expose directly in
+ session.tools() and MCP tool lists. 'all' exposes every app
+ tool allowed by positive session filters such as toolkits,
+ tools, or tags; the backend validates and caps the final set.
Example: {'tools': ['GMAIL_FETCH_EMAILS']}
+ :param session_preset: Optional session preset. 'direct_tools' exposes all tools
+ allowed by the session filters directly in session.tools()
+ and the MCP tool list, and disables meta tools by default
+ (search, multi-execute, manage-connections, and workbench).
+ Use when all needed tools are known upfront and helper/meta
+ tools are not needed. Without this preset, ToolRouter uses
+ the default configuration with meta tools enabled. Loading
+ many tools can increase model context usage.
:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).
Note: These features are experimental and may change.
Dict with:
@@ -670,6 +709,14 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
```
"""
+ direct_tools_preset = session_preset == "direct_tools"
+ manage_connections, workbench, preload = _apply_session_preset_defaults(
+ session_preset=session_preset,
+ manage_connections=manage_connections,
+ workbench=workbench,
+ preload=preload,
+ )
+
# Parse manage_connections config
manage_connections = (
manage_connections if manage_connections is not None else True
@@ -795,6 +842,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
if preload is not None:
create_params["preload"] = preload
+ if direct_tools_preset:
+ create_params["search"] = {"enable": False}
+ create_params["execute"] = {"enable_multi_execute": False}
+
# Build experimental config
# Map SDK's experimental.assistive_prompt.user_timezone to API's
# experimental.assistive_prompt_config.user_timezone
@@ -845,6 +896,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
toolkits=custom_toolkits,
experimental=session.experimental,
)
+ preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(
+ getattr(session, "tool_router_tools", None),
+ custom_tools_map,
+ )
# Transform experimental response:
# API's assistive_prompt -> SDK's assistive_prompt
@@ -873,9 +928,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
experimental=experimental_response,
custom_tools_map=custom_tools_map,
user_id=user_id,
- preload=ToolRouterSessionPreloadConfig(
- tools=list(session.config.preload.tools)
- ),
+ preload=_session_preload_config(session),
+ preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,
)
def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
@@ -930,9 +984,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
url=session.mcp.url,
),
experimental=experimental_response,
- preload=ToolRouterSessionPreloadConfig(
- tools=list(session.config.preload.tools)
- ),
+ preload=_session_preload_config(session),
)
@@ -952,6 +1004,7 @@ __all__ = [
"ToolRouterManageConnectionsConfig",
"ToolRouterWorkbenchConfig",
"SandboxSize",
+ "SessionPreset",
"ToolRouterMultiAccountConfig",
"ToolRouterPreloadConfig",
"ToolRouterExperimentalConfig",
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index 720f89e5b..33b86603b 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -13,6 +13,12 @@ from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass
from composio_client import omit
+from composio.client.types import Tool
+from composio_client.types.tool_list_response import (
+ ItemDeprecated,
+ ItemDeprecatedToolkit,
+ ItemToolkit,
+)
from composio_client.types.tool_router.session_execute_response import (
SessionExecuteResponse,
)
@@ -25,6 +31,7 @@ from composio_client.types.tool_router.session_search_response import (
from composio.client import HttpClient
from composio.core.models.connected_accounts import ConnectionRequest
+from composio.core.models.custom_tool import find_custom_tool_map_entry_by_final_slug
from composio.core.models.custom_tool_execution import (
execute_custom_tool,
find_custom_tool,
@@ -48,6 +55,9 @@ if t.TYPE_CHECKING:
)
COMPOSIO_MULTI_EXECUTE_TOOL = "COMPOSIO_MULTI_EXECUTE_TOOL"
+DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX = (
+ "[Direct tool - call directly, no search or connection check needed beforehand.]"
+)
MAX_PARALLEL_WORKERS = 5
@@ -55,7 +65,7 @@ MAX_PARALLEL_WORKERS = 5
class ToolRouterSessionPreloadConfig:
"""Preloaded tools configured for a tool router session."""
- tools: t.List[str]
+ tools: t.Union[t.List[str], str]
class ToolRouterSession(t.Generic[TTool, TToolCollection]):
@@ -94,6 +104,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
custom_tools_map: t.Optional[CustomToolsMap] = None,
user_id: t.Optional[str] = None,
preload: t.Optional[ToolRouterSessionPreloadConfig] = None,
+ preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,
) -> None:
self._client = client
self._provider = provider
@@ -107,6 +118,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
self.preload = preload or ToolRouterSessionPreloadConfig(tools=[])
self._custom_tools_map = custom_tools_map
self._user_id = user_id
+ self._preloaded_custom_tool_slugs = preloaded_custom_tool_slugs or []
# Create singleton session context if custom tools are bound
self._session_context: t.Optional[SessionContextImpl] = None
@@ -168,6 +180,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
session_id=self.session_id,
modifiers=modifiers,
)
+ router_tools = self._add_preloaded_custom_tools(router_tools, modifiers)
for tool in router_tools:
tool.input_parameters = (
@@ -201,6 +214,95 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
),
)
+ def _add_preloaded_custom_tools(
+ self,
+ tools: t.List[Tool],
+ modifiers: t.Optional["Modifiers"],
+ ) -> t.List[Tool]:
+ custom_tools = self._get_preloaded_custom_tool_schemas(modifiers)
+ if not custom_tools:
+ return tools
+
+ existing_slugs = {tool.slug.upper() for tool in tools}
+ appended_tools = [
+ tool for tool in custom_tools if tool.slug.upper() not in existing_slugs
+ ]
+ if not appended_tools:
+ return tools
+
+ return [*tools, *appended_tools]
+
+ def _get_preloaded_custom_tool_schemas(
+ self,
+ modifiers: t.Optional["Modifiers"],
+ ) -> t.List[Tool]:
+ if not self._custom_tools_map or not self._preloaded_custom_tool_slugs:
+ return []
+
+ tools: t.List[Tool] = []
+ for slug in self._preloaded_custom_tool_slugs:
+ entry = find_custom_tool_map_entry_by_final_slug(
+ self._custom_tools_map,
+ slug,
+ )
+ if entry is None:
+ continue
+
+ tool = self._custom_tool_entry_to_tool(entry)
+ if modifiers is not None:
+ tool = t.cast(
+ Tool,
+ apply_modifier_by_type(
+ modifiers=modifiers,
+ toolkit=tool.toolkit.slug,
+ tool=tool.slug,
+ type="schema",
+ schema=tool,
+ ),
+ )
+ tools.append(tool)
+
+ return tools
+
+ def _custom_tool_entry_to_tool(self, entry: CustomToolsMapEntry) -> Tool:
+ toolkit_slug = entry.toolkit or "custom"
+ toolkit_name = (
+ self._custom_toolkit_name(toolkit_slug) or entry.toolkit or "Custom"
+ )
+
+ return Tool(
+ available_versions=[],
+ deprecated=ItemDeprecated(
+ available_versions=[],
+ displayName=entry.handle.name,
+ is_deprecated=False,
+ toolkit=ItemDeprecatedToolkit(logo=""),
+ version="latest",
+ ),
+ description=(
+ f"{DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX}\n{entry.handle.description}"
+ ),
+ input_parameters=entry.handle.input_schema,
+ is_deprecated=False,
+ name=entry.handle.name,
+ no_auth=entry.handle.extends_toolkit is None,
+ output_parameters=entry.handle.output_schema or {},
+ scopes=[],
+ slug=entry.final_slug,
+ tags=[],
+ toolkit=ItemToolkit(logo="", name=toolkit_name, slug=toolkit_slug),
+ version="latest",
+ )
+
+ def _custom_toolkit_name(self, toolkit_slug: str) -> t.Optional[str]:
+ if self._custom_tools_map is None:
+ return None
+
+ for toolkit in self._custom_tools_map.toolkits or []:
+ if toolkit.slug.lower() == toolkit_slug.lower():
+ return toolkit.name
+ return None
+
def _create_routing_execute_fn(
self,
tools_model: t.Any,
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index 36fa8d0bd..2cefdc4db 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -3,7 +3,9 @@
from unittest.mock import MagicMock, patch
import pytest
+from pydantic import BaseModel, Field
+from composio.core.models.custom_tool import ExperimentalAPI
from composio.core.models.tool_router import (
ToolkitConnectionsDetails,
ToolkitConnectionState,
@@ -16,6 +18,15 @@ from composio.core.models.tool_router import (
ToolRouterToolkitsDisableConfig,
ToolRouterToolkitsEnableConfig,
)
+from composio.core.models.tool_router_session import (
+ DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX,
+)
+
+experimental_api = ExperimentalAPI()
+
+
+class GrepInput(BaseModel):
+ pattern: str = Field(description="Pattern to search for")
@pytest.fixture
@@ -604,6 +615,63 @@ class TestToolRouter:
assert kwargs["preload"] == {"tools": ["GMAIL_FETCH_EMAILS"]}
assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]
+ def test_create_session_with_preload_all(self, tool_router, mock_client):
+ """preload tools='all' is forwarded and exposed on the session."""
+ mock_client.tool_router.session.create.return_value.config.preload.tools = "all"
+
+ session = tool_router.create(
+ user_id="user_123",
+ preload={"tools": "all"},
+ )
+
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
+ assert kwargs["preload"] == {"tools": "all"}
+ assert session.preload.tools == "all"
+
+ def test_create_session_with_direct_tools_preset(self, tool_router, mock_client):
+ """direct_tools applies SDK-side defaults for direct tool exposure."""
+ mock_client.tool_router.session.create.return_value.config.preload.tools = "all"
+
+ session = tool_router.create(
+ user_id="user_123",
+ session_preset="direct_tools",
+ toolkits=["github"],
+ )
+
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
+ assert kwargs["toolkits"] == {"enable": ["github"]}
+ assert kwargs["manage_connections"] == {"enable": False}
+ assert kwargs["workbench"] == {"enable": False}
+ assert kwargs["preload"] == {"tools": "all"}
+ assert kwargs["search"] == {"enable": False}
+ assert kwargs["execute"] == {"enable_multi_execute": False}
+ assert session.preload.tools == "all"
+
+ def test_create_session_with_direct_tools_preset_overrides(
+ self, tool_router, mock_client
+ ):
+ """Explicit user fields override direct_tools defaults."""
+ mock_client.tool_router.session.create.return_value.config.preload.tools = [
+ "GITHUB_CREATE_ISSUE"
+ ]
+
+ session = tool_router.create(
+ user_id="user_123",
+ session_preset="direct_tools",
+ toolkits=["github"],
+ manage_connections=True,
+ workbench={"enable": True},
+ preload={"tools": ["GITHUB_CREATE_ISSUE"]},
+ )
+
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
+ assert kwargs["manage_connections"] == {"enable": True}
+ assert kwargs["workbench"] == {"enable": True}
+ assert kwargs["preload"] == {"tools": ["GITHUB_CREATE_ISSUE"]}
+ assert kwargs["search"] == {"enable": False}
+ assert kwargs["execute"] == {"enable_multi_execute": False}
+ assert session.preload.tools == ["GITHUB_CREATE_ISSUE"]
+
def test_create_session_complex_config(self, tool_router, mock_client):
"""Test creating a session with complex configuration."""
session = tool_router.create(
@@ -1073,6 +1141,60 @@ class TestToolRouter:
assert [tool.slug for tool in wrapped_tools] == ["GMAIL_FETCH_EMAILS"]
assert result == "mocked-wrapped-tools"
+ @patch("composio.core.models.tools.Tools")
+ def test_tools_function_includes_preloaded_custom_tools(
+ self,
+ mock_tools_class,
+ tool_router,
+ mock_client,
+ mock_provider,
+ ):
+ """Custom tools preloaded by the create response are exposed locally."""
+
+ @experimental_api.tool(
+ slug="GREP",
+ name="Grep",
+ description="Search local text",
+ )
+ def grep(input: GrepInput, ctx):
+ return {"matches": []}
+
+ mock_response = mock_client.tool_router.session.create.return_value
+ mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS", "server_grep"]
+ mock_response.experimental = MagicMock()
+ mock_response.experimental.assistive_prompt = None
+ mock_response.experimental.custom_toolkits = []
+ mock_custom_tool = MagicMock()
+ mock_custom_tool.slug = "SERVER_GREP"
+ mock_custom_tool.original_slug = "GREP"
+ mock_custom_tool.extends_toolkit = None
+ mock_response.experimental.custom_tools = [mock_custom_tool]
+
+ mock_tools_instance = MagicMock()
+ mock_tool = MagicMock()
+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"
+ mock_tool.toolkit.slug = "composio"
+ mock_tool.input_parameters = {}
+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]
+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}
+ mock_tools_class.return_value = mock_tools_instance
+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"
+
+ session = tool_router.create(
+ user_id="user_123",
+ experimental={"custom_tools": [grep]},
+ )
+ result = session.tools()
+
+ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]
+ assert [tool.slug for tool in wrapped_tools] == [
+ "COMPOSIO_SEARCH_TOOLS",
+ "SERVER_GREP",
+ ]
+ assert DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX in wrapped_tools[1].description
+ assert wrapped_tools[1].toolkit.slug == "custom"
+ assert result == "mocked-custom-tools"
+
@patch("composio.core.models.tools.Tools")
def test_tools_function_with_modifiers(
self,
diff --git a/ts/packages/core/src/lib/toolRouterParams.ts b/ts/packages/core/src/lib/toolRouterParams.ts
index e82fda173..97b57be66 100644
--- a/ts/packages/core/src/lib/toolRouterParams.ts
+++ b/ts/packages/core/src/lib/toolRouterParams.ts
@@ -114,7 +114,7 @@ export const transformToolRouterManageConnectionsParams = (
export const transformToolRouterWorkbenchParams = (
params?: ToolRouterCreateSessionConfig['workbench']
): SessionCreateParams.Workbench | undefined => {
- if (!params) {
+ if (params === undefined) {
return undefined;
}
diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.ts
index 3b8d21852..58e602568 100644
--- a/ts/packages/core/src/models/CustomTool.ts
+++ b/ts/packages/core/src/models/CustomTool.ts
@@ -284,6 +284,7 @@ export function buildCustomToolsMap(
const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
const originalSlug = handle.slug.toUpperCase();
+ const finalSlugKey = finalSlug.toUpperCase();
// Length validated early in createCustomTool/createCustomToolkit, but check as safety net
if (finalSlug.length > MAX_SLUG_LENGTH) {
@@ -294,7 +295,7 @@ export function buildCustomToolsMap(
}
// Check cross-group collisions on final slug
- if (byFinalSlug.has(finalSlug)) {
+ if (byFinalSlug.has(finalSlugKey)) {
throw new ValidationError(
`Custom tool slug collision: "${finalSlug}" is already registered.`
);
@@ -309,7 +310,7 @@ export function buildCustomToolsMap(
}
const entry: CustomToolsMapEntry = { handle, finalSlug, toolkit };
- byFinalSlug.set(finalSlug, entry);
+ byFinalSlug.set(finalSlugKey, entry);
byOriginalSlug.set(originalSlug, entry);
};
@@ -415,7 +416,7 @@ export function buildCustomToolsMapFromResponse(
finalSlug,
toolkit: toolkit ?? match.toolkit,
};
- byFinalSlug.set(finalSlug, entry);
+ byFinalSlug.set(finalSlug.toUpperCase(), entry);
byOriginalSlug.set(originalSlug.toUpperCase(), entry);
};
@@ -437,3 +438,53 @@ export function buildCustomToolsMapFromResponse(
return { byFinalSlug, byOriginalSlug, toolkits };
}
+
+/**
+ * Find a custom tool entry by final slug only.
+ *
+ * @internal
+ */
+export function findCustomToolMapEntryByFinalSlug(
+ customToolsMap: CustomToolsMap | undefined,
+ slug: string
+): CustomToolsMapEntry | undefined {
+ return customToolsMap?.byFinalSlug.get(slug.toUpperCase());
+}
+
+/**
+ * Resolve custom tools that the backend selected for direct preload.
+ *
+ * The backend is the source of truth for preload expansion, including "all".
+ * The SDK only keeps the final custom slugs it can serve locally because
+ * the session tools endpoint only returns backend-managed tool schemas.
+ *
+ * @internal
+ */
+export function getPreloadedCustomToolSlugs(
+ toolRouterTools: readonly string[] | undefined,
+ customToolsMap: CustomToolsMap | undefined
+): string[] {
+ if (!toolRouterTools?.length || !customToolsMap) {
+ return [];
+ }
+
+ const seen = new Set<string>();
+ const customToolSlugs: string[] = [];
+
+ for (const slug of toolRouterTools) {
+ const entry = findCustomToolMapEntryByFinalSlug(customToolsMap, slug);
+ if (!entry) {
+ continue;
+ }
+
+ const finalSlugKey = entry.finalSlug.toUpperCase();
+ if (seen.has(finalSlugKey)) {
+ continue;
+ }
+
+ seen.add(finalSlugKey);
+ customToolSlugs.push(entry.finalSlug);
+ }
+
+ return customToolSlugs;
+}
diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.ts
index 0e3966a28..0cfe85f8e 100644
--- a/ts/packages/core/src/models/ToolRouter.ts
+++ b/ts/packages/core/src/models/ToolRouter.ts
@@ -46,6 +46,7 @@ import {
import { ToolRouterSession } from './ToolRouterSession';
import {
buildCustomToolsMapFromResponse,
+ getPreloadedCustomToolSlugs,
serializeCustomTools,
serializeCustomToolkits,
} from './CustomTool';
@@ -109,6 +110,13 @@ export class ToolRouter<
* customToolkits: [myToolkit],
* },
* });
+ *
+ * // Expose all tools allowed by filters directly, without meta/helper tools.
+ * // `preload.tools = "all"` requires a positive filter such as `toolkits`.
+ * const directSession = await composio.create('user_123', {
+ * sessionPreset: 'direct_tools',
+ * toolkits: ['github'],
+ * });
* ```
*/
async create(
@@ -116,6 +124,7 @@ export class ToolRouter<
config?: ToolRouterCreateSessionConfig
): Promise<Session<TToolCollection, TTool, TProvider>> {
const routerConfig = ToolRouterCreateSessionConfigSchema.parse(config ?? {});
+ const isDirectToolsPreset = routerConfig.sessionPreset === 'direct_tools';
// Extract custom tools/toolkits from experimental config
const customTools = routerConfig.experimental?.customTools;
@@ -152,6 +161,10 @@ export class ToolRouter<
workbench: transformToolRouterWorkbenchParams(routerConfig.workbench),
multi_account: multiAccountPayload,
preload: routerConfig.preload,
+ ...(isDirectToolsPreset && {
+ search: { enable: false },
+ execute: { enable_multi_execute: false },
+ }),
experimental: Object.keys(experimentalPayload).length > 0 ? experimentalPayload : undefined,
};
@@ -167,6 +180,13 @@ export class ToolRouter<
session.experimental
);
}
+ const metadata = {
+ ...getSessionMetadata(session),
+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(
+ session.tool_router_tools,
+ customToolsMap
+ ),
+ };
const assistivePrompt = session.experimental?.assistive_prompt;
@@ -178,7 +198,7 @@ export class ToolRouter<
{ assistivePrompt },
customToolsMap,
userId,
- getSessionMetadata(session)
+ metadata
);
}
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index c10e2375c..6231ff8f3 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -43,9 +43,12 @@ import type { SessionExecuteParams } from '@composio/client/resources/tool-route
import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
import { SessionContextImpl } from './SessionContext';
import { findCustomTool, executeCustomTool } from './customToolExecution';
+import { findCustomToolMapEntryByFinalSlug } from './CustomTool';
import { transformProxyParams } from './proxyParamsTransform';
const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
+export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
+ '[Direct tool - call directly, no search or connection check needed beforehand.]';
export class ToolRouterSession<
TToolCollection,
@@ -58,6 +61,7 @@ export class ToolRouterSession<
public readonly preload: ToolRouterSessionPreloadConfig;
public readonly configVersion?: number;
public readonly warnings: ToolRouterSessionWarning[];
+ private readonly preloadedCustomToolSlugs: string[];
/** Singleton session context — shared across all custom tool executions */
private readonly sessionContext?: SessionContext;
@@ -84,6 +88,7 @@ export class ToolRouterSession<
this.preload = metadata?.preload ?? { tools: [] };
this.configVersion = metadata?.configVersion;
this.warnings = metadata?.warnings ?? [];
+ this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];
// Create singleton session context if custom tools are bound
if (customToolsMap && userId) {
@@ -106,7 +111,8 @@ export class ToolRouterSession<
this.sessionId,
modifiers?.modifySchema ? { modifySchema: modifiers.modifySchema } : undefined
);
- const toolBySlug = new Map(tools.map(tool => [tool.slug.toUpperCase(), tool]));
+ const sessionTools = await this.addPreloadedCustomTools(tools, modifiers);
+ const toolBySlug = new Map(sessionTools.map(tool => [tool.slug.toUpperCase(), tool]));
if (this.hasCustomTools()) {
// Create an execute function that splits local/remote tools in COMPOSIO_MULTI_EXECUTE_TOOL
@@ -115,7 +121,7 @@ export class ToolRouterSession<
input: Record<string, unknown>
): Promise<ToolExecuteResponse> => {
if (toolSlug === COMPOSIO_MULTI_EXECUTE_TOOL) {
- return this.routeMultiExecute(input, ToolsModel, tools, modifiers);
+ return this.routeMultiExecute(input, ToolsModel, sessionTools, modifiers);
}
return ToolsModel.executeSessionTool(
toolSlug,
@@ -131,16 +137,84 @@ export class ToolRouterSession<
'Pass a provider in the Composio constructor.'
);
}
- return this.config.provider.wrapTools(tools, routingExecuteFn) as ReturnType<
+ return this.config.provider.wrapTools(sessionTools, routingExecuteFn) as ReturnType<
TProvider['wrapTools']
>;
}
// Standard path (no local tools)
- const wrappedTools = ToolsModel.wrapToolsForToolRouter(this.sessionId, tools, modifiers);
+ const wrappedTools = ToolsModel.wrapToolsForToolRouter(this.sessionId, sessionTools, modifiers);
return wrappedTools as ReturnType<TProvider['wrapTools']>;
}
+ private async addPreloadedCustomTools(
+ tools: Tool[],
+ modifiers?: SessionMetaToolOptions
+ ): Promise<Tool[]> {
+ const customTools = await this.getPreloadedCustomToolSchemas(modifiers);
+ if (!customTools.length) {
+ return tools;
+ }
+
+ const existingSlugs = new Set(tools.map(tool => tool.slug.toUpperCase()));
+ const appendedTools = customTools.filter(tool => !existingSlugs.has(tool.slug.toUpperCase()));
+ if (!appendedTools.length) {
+ return tools;
+ }
+
+ return [...tools, ...appendedTools];
+ }
+
+ private async getPreloadedCustomToolSchemas(modifiers?: SessionMetaToolOptions): Promise<Tool[]> {
+ if (!this.customToolsMap || !this.preloadedCustomToolSlugs.length) {
+ return [];
+ }
+
+ const tools: Tool[] = [];
+ for (const slug of this.preloadedCustomToolSlugs) {
+ const entry = findCustomToolMapEntryByFinalSlug(this.customToolsMap, slug);
+ if (!entry) {
+ continue;
+ }
+
+ let tool = this.customToolEntryToTool(entry);
+ if (modifiers?.modifySchema) {
+ tool = await modifiers.modifySchema({
+ toolSlug: tool.slug,
+ toolkitSlug: tool.toolkit?.slug ?? 'custom',
+ schema: tool,
+ });
+ }
+ tools.push(tool);
+ }
+ return tools;
+ }
+
+ private customToolEntryToTool(entry: CustomToolsMapEntry): Tool {
+ const toolkitSlug = entry.toolkit ?? 'custom';
+ const customToolkit = this.customToolsMap?.toolkits?.find(
+ toolkit => toolkit.slug.toLowerCase() === toolkitSlug.toLowerCase()
+ );
+ const toolkitName = customToolkit?.name ?? entry.toolkit ?? 'Custom';
+
+ return {
+ slug: entry.finalSlug,
+ name: entry.handle.name,
+ description: `${DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX}\n${entry.handle.description}`,
+ inputParameters: entry.handle.inputSchema as Tool['inputParameters'],
+ outputParameters: entry.handle.outputSchema as Tool['outputParameters'],
+ tags: [],
+ toolkit: {
+ slug: toolkitSlug,
+ name: toolkitName,
+ },
+ isDeprecated: false,
+ availableVersions: [],
+ scopes: [],
+ isNoAuth: !entry.handle.extendsToolkit,
+ };
+ }
+
/**
* List all custom tools registered in this session.
* Returns tools with their final slugs, schemas, and resolved toolkit.
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index 80e140bfd..988294859 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -169,8 +169,15 @@ export const ToolRouterConfigToolsSchema = z
});
export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;
-export const ToolRouterCreateSessionConfigSchema = z
+const ToolRouterCreateSessionConfigBaseSchema = z
.object({
+ sessionPreset: z
+ .literal('direct_tools')
+ .optional()
+ .describe(
+ 'Shortcut to expose every tool allowed by the session filters directly in session.tools() and the MCP tool list. This disables meta tools by default (search, multi-execute, manage-connections, and workbench). Use when all tools are known upfront and helper/meta tools are not needed. Without this preset, ToolRouter uses its default configuration with meta tools enabled.'
+ ),
+
tools: z
.record(z.string(), z.union([ToolRouterToolsParamSchema, ToolRouterConfigToolsSchema]))
.optional()
@@ -225,7 +232,7 @@ export const ToolRouterCreateSessionConfigSchema = z
'The auto offload threshold in characters for the tool execution to be moved into workbench'
),
sandboxSize: SandboxSizeSchema.optional().describe(
- 'Sandbox compute tier for the workbench. One of "standard" (1 vCPU / 1 GB), "medium" (2 vCPU / 2 GB), "large" (4 vCPU / 4 GB), or "xlarge" (8 vCPU / 8 GB). Defaults to "standard" server-side. Changing this on an existing session recreates the sandbox on next access; the session\'s in-memory FS is lost, but /mnt/files/ persists.'
+ 'Sandbox compute tier for the workbench. One of "standard" (1 vCPU / 1 GB), "medium" (2 vCPU / 2 GB), "large" (4 vCPU / 4 GB), or "xlarge" (8 vCPU / 8 GB). Defaults to "standard" server-side. Changing this on an existing session recreates the session\'s workbench sandbox on next access; the in-memory FS is lost, but /mnt/files/ persists.'
),
})
.optional()
@@ -258,10 +265,10 @@ export const ToolRouterCreateSessionConfigSchema = z
preload: z
.object({
tools: z
- .array(z.string())
+ .union([z.array(z.string()), z.literal('all')])
.optional()
.describe(
- 'Tool slugs to preload into session.tools() and the MCP tool list. The backend validates slugs against the session filters.'
+ 'Tool slugs to preload into session.tools() and the MCP tool list, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.'
),
})
.strict()
@@ -299,9 +306,32 @@ export const ToolRouterCreateSessionConfigSchema = z
})
.partial()
.describe('The config for the tool router session');
+
+const applyDirectToolsPresetDefaults = (value: unknown): unknown => {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
+ return value;
+ }
+
+ const config = value as Record<string, unknown>;
+ if (config.sessionPreset !== 'direct_tools') {
+ return value;
+ }
+
+ return {
+ ...config,
+ manageConnections: config.manageConnections === undefined ? false : config.manageConnections,
+ workbench: config.workbench === undefined ? { enable: false } : config.workbench,
+ preload: config.preload === undefined ? { tools: 'all' } : config.preload,
+ };
+};
+
+export const ToolRouterCreateSessionConfigSchema = z
+ .preprocess(applyDirectToolsPresetDefaults, ToolRouterCreateSessionConfigBaseSchema)
+ .describe('The config for the tool router session');
/**
* The config for the tool router session.
*
+ * @param {'direct_tools'} [sessionPreset] - Shortcut that exposes every tool allowed by the session filters directly in session.tools() and the MCP tool list. Disables search, multi-execute, manage-connections, and workbench by default; explicit overrides for supported fields still win. Without this preset, ToolRouter uses the default configuration with meta tools enabled.
* @param {ToolRouterToolkitsParamSchema | ToolRouterToolkitsDisabledConfigSchema | ToolRouterToolkitsEnabledConfigSchema} toolkits - The toolkits to use in the tool router session
* @param {Record<string, ToolRouterToolsParam | ToolRouterConfigTools>} tools - The tools to configure per toolkit (key is toolkit slug)
* @param {Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>} tags - Global tags to filter tools by behavior
@@ -320,7 +350,7 @@ export const ToolRouterCreateSessionConfigSchema = z
* @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
* @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
* @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
- * @param {string[]} [preload.tools] - Tool slugs to preload. Server-side validation ensures they exist and are allowed by the session filters.
+ * @param {string[] | 'all'} [preload.tools] - Tool slugs to preload, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.
*/
export type ToolRouterCreateSessionConfig = z.infer<typeof ToolRouterCreateSessionConfigSchema>;
@@ -544,6 +574,7 @@ export interface ToolRouterSessionMetadata {
preload?: ToolRouterSessionPreloadConfig;
configVersion?: number;
warnings?: ToolRouterSessionWarning[];
+ preloadedCustomToolSlugs?: string[];
}
export const SessionProxyExecuteParamsSchema = z.object({
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index 7d55e0a44..3569291e1 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -1,4 +1,5 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { z } from 'zod/v3';
import { ToolRouter } from '../../src/models/ToolRouter';
import ComposioClient from '@composio/client';
import { telemetry } from '../../src/telemetry/Telemetry';
@@ -6,6 +7,8 @@ import { MockProvider } from '../utils/mocks/provider.mock';
import { Tools } from '../../src/models/Tools';
import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';
import { ToolRouterCreateSessionConfig, Session } from '../../src/types/toolRouter.types';
+import { createCustomTool } from '../../src/models/CustomTool';
+import { DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX } from '../../src/models/ToolRouterSession';
// Mock dependencies
vi.mock('../../src/telemetry/Telemetry', () => ({
@@ -262,6 +265,106 @@ describe('ToolRouter', () => {
expect(session.configVersion).toBe(2);
});
+ it('should create a session with preload all', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ config: {
+ preload: { tools: 'all' },
+ },
+ config_version: 2,
+ });
+
+ const session = await toolRouter.create(userId, {
+ toolkits: ['github'],
+ preload: { tools: 'all' },
+ });
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
+ user_id: userId,
+ toolkits: {
+ enable: ['github'],
+ },
+ auth_configs: undefined,
+ connected_accounts: undefined,
+ tools: undefined,
+ tags: undefined,
+ manage_connections: createExpectedManageConnections(),
+ workbench: undefined,
+ preload: { tools: 'all' },
+ });
+
+ expect(session.preload.tools).toBe('all');
+ });
+
+ it('should apply the direct_tools session preset defaults', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ config: {
+ preload: { tools: 'all' },
+ },
+ });
+
+ const session = await toolRouter.create(userId, {
+ sessionPreset: 'direct_tools',
+ toolkits: ['github'],
+ });
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
+ user_id: userId,
+ toolkits: {
+ enable: ['github'],
+ },
+ auth_configs: undefined,
+ connected_accounts: undefined,
+ tools: undefined,
+ tags: undefined,
+ manage_connections: { enable: false },
+ workbench: { enable: false },
+ multi_account: undefined,
+ preload: { tools: 'all' },
+ search: { enable: false },
+ execute: { enable_multi_execute: false },
+ experimental: undefined,
+ });
+ expect(session.preload.tools).toBe('all');
+ });
+
+ it('should respect explicit overrides with the direct_tools session preset', async () => {
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ config: {
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
+ },
+ });
+
+ const session = await toolRouter.create(userId, {
+ sessionPreset: 'direct_tools',
+ toolkits: ['github'],
+ manageConnections: true,
+ workbench: { enable: true },
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
+ });
+
+ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
+ user_id: userId,
+ toolkits: {
+ enable: ['github'],
+ },
+ auth_configs: undefined,
+ connected_accounts: undefined,
+ tools: undefined,
+ tags: undefined,
+ manage_connections: { enable: true },
+ workbench: { enable: true },
+ multi_account: undefined,
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
+ search: { enable: false },
+ execute: { enable_multi_execute: false },
+ experimental: undefined,
+ });
+ expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);
+ });
+
it('should create a session with user ID only and verify MCP type transformation', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
@@ -2240,6 +2343,83 @@ describe('ToolRouter', () => {
expect(tools).toBe('mocked-wrapped-tools');
});
+ it('should include preloaded custom tools selected by the create response', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ inputParams: z.object({
+ pattern: z.string().describe('Pattern to search for'),
+ }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'server_grep'],
+ experimental: {
+ custom_tools: [
+ {
+ slug: 'SERVER_GREP',
+ original_slug: 'GREP',
+ extends_toolkit: null,
+ },
+ ],
+ },
+ });
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
+
+ const session = await toolRouter.create(userId, {
+ experimental: { customTools: [grepTool] },
+ });
+ const tools = await session.tools();
+
+ expect(mockProvider.wrapTools).toHaveBeenCalledTimes(1);
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{
+ slug: string;
+ description?: string;
+ toolkit?: { slug: string; name: string };
+ }>;
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'SERVER_GREP']);
+ expect(wrappedTools[1].description).toContain(DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX);
+ expect(wrappedTools[1].toolkit).toEqual({ slug: 'custom', name: 'Custom' });
+ expect(tools).toBe('mocked-custom-tools');
+ });
+
+ it('should not expose custom tools unless the backend preloaded them', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ inputParams: z.object({
+ pattern: z.string(),
+ }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
+ experimental: {
+ custom_tools: [
+ {
+ slug: 'LOCAL_GREP',
+ original_slug: 'GREP',
+ extends_toolkit: null,
+ },
+ ],
+ },
+ });
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
+
+ const session = await toolRouter.create(userId, {
+ preload: { tools: 'all' },
+ experimental: { customTools: [grepTool] },
+ });
+ await session.tools();
+
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);
+ });
+
it('should handle tools fetching errors', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);