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.

Document ToolRouter preloaded tools

Dhawal Upadhyaydda8684cc19f
diff --git a/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx b/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
new file mode 100644
index 000000000..e8e2bcf78
--- /dev/null
+++ b/docs/content/changelog/05-07-26-toolrouter-preload-direct-tools.mdx
@@ -0,0 +1,73 @@
+---
+title: "Sessions add preloaded tools and direct tools preset"
+description: "Sessions can now expose frequently used tools directly from session.tools(), and specialized agents can use a direct tools preset with selected meta tools enabled as needed."
+date: "2026-05-07"
+---
+
+Sessions now support preloading known tools into `session.tools()` and the
+session MCP tool list. This works for Composio-managed tools, while SDK custom
+tools can be exposed directly from `session.tools()` with `preload: true`.
+
+Use preloading for small, stable tool sets. Keep the preloaded set focused,
+generally fewer than 20 tools, to avoid context bloat.
+
+### SDK versions
+
+| SDK | Minimum version |
+| --- | --- |
+| TypeScript `@composio/core` | `TBD` |
+| Python `composio` | `TBD` |
+
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ preload: {
+ tools: [
+ "GRANOLA_MCP_LIST_MEETINGS",
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
+ ],
+ },
+});
+
+const tools = await session.tools();
+```
+
+### Direct tools preset
+
+Specialized agents with a narrow tool set can use the direct tools preset to
+load every tool allowed by session filters into the session's tool list and
+disable session meta tools by default.
+
+```typescript
+import { Composio, SessionPreset } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
+});
+```
+
+For agents that still need selected helper behavior, supported meta tool groups
+can be enabled alongside the preset:
+
+```typescript
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
+ manageConnections: {
+ enable: true,
+ },
+ workbench: {
+ enable: true,
+ },
+});
+```
+
+See [Preloading tools](/docs/configuring-sessions#preloading-tools),
+[Direct tools preset](/docs/configuring-sessions#direct-tools-preset), and
+[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools)
+for Python examples and full guidance.
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index f2fab5630..dba7d87df 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -89,6 +89,161 @@ const session = await composio.create("user_123", {
</Tab>
</Tabs>
+## Preloading tools
+
+By default, sessions expose [meta tools](/reference/meta-tools) that let the agent
+discover app tools at runtime. Use `preload.tools` when you already know the
+small set of tools that should be returned directly from `session.tools()` and
+the session MCP tool list.
+
+Preloading is useful for frequently used tools because the agent can call them
+without going through search each time. Keep the preloaded set small, generally
+fewer than 20 tools, to avoid context bloat.
+
+<Callout type="info">
+Requires `@composio/core` ≥ `TBD` (TypeScript) or `composio` ≥ `TBD`
+(Python). Older SDKs do not support `preload.tools`,
+`sessionPreset` / `session_preset`, or custom-tool `preload`.
+</Callout>
+
+<Callout type="info">
+`preload.tools` is not supported when `multiAccount.enable` is true. See
+[Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
+</Callout>
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits=["granola_mcp"],
+ preload={
+ "tools": [
+ "GRANOLA_MCP_LIST_MEETINGS",
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
+ ],
+ },
+)
+
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ preload: {
+ tools: [
+ "GRANOLA_MCP_LIST_MEETINGS",
+ "GRANOLA_MCP_QUERY_GRANOLA_MEETINGS",
+ ],
+ },
+});
+
+const tools = await session.tools();
+```
+</Tab>
+</Tabs>
+
+For SDK custom tools, set `preload: true` on the custom tool or custom toolkit
+instead of listing `LOCAL_*` slugs in `preload.tools`. See
+[Preloading custom tools](/docs/toolkits/custom-tools-and-toolkits#preloading-custom-tools).
+
+Use the `preload.tools = "all"` shortcut (`preload={"tools": "all"}` in Python,
+`preload: { tools: "all" }` in TypeScript) to preload every Composio-managed
+tool allowed by the session filters.
+
+### Direct tools preset
+
+The direct tools preset preloads every tool allowed by session filters into the
+session's tool list and disables session meta tools by default. This can be
+useful for specialized agents with a narrow tool set that do not need dynamic
+tool discovery, in-chat auth, or workbench helpers.
+
+This is not the default mode for broad agents. The default session behavior keeps
+meta tools available so the agent can search for relevant tools and avoid
+context bloat.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import SESSION_PRESET_DIRECT_TOOLS
+
+session = composio.create(
+ user_id="user_123",
+ toolkits=["granola_mcp"],
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
+)
+
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio, SessionPreset } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
+});
+
+const tools = await session.tools();
+```
+</Tab>
+</Tabs>
+
+**Enable selected meta tools**
+
+When using the direct tools preset, you can selectively re-enable supported meta
+tool groups that your agent still needs. For example, this session loads Granola
+tools upfront while keeping connection management and workbench support
+available:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import SESSION_PRESET_DIRECT_TOOLS
+
+session = composio.create(
+ user_id="user_123",
+ toolkits=["granola_mcp"],
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
+ manage_connections={
+ "enable": True,
+ },
+ workbench={
+ "enable": True,
+ },
+)
+
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio, SessionPreset } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["granola_mcp"],
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
+ manageConnections: {
+ enable: true,
+ },
+ workbench: {
+ enable: true,
+ },
+});
+
+const tools = await session.tools();
+```
+</Tab>
+</Tabs>
+
## Custom auth configs
Use your own OAuth credentials instead of Composio's defaults:
diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
index e4d57f87c..85d3738d4 100644
--- a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
@@ -393,7 +393,11 @@ A custom toolkit groups related standalone tools under a namespace. Tools inside
<Tab value="TypeScript">
```typescript
// @noErrors
-import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
+import {
+ Composio,
+ experimental_createTool,
+ experimental_createToolkit,
+} from "@composio/core";
import { z } from "zod/v3";
// ---cut---
@@ -491,6 +495,123 @@ tools = session.tools()
</IntegrationTabs>
+## Preloading custom tools
+
+Custom tools are searchable by default. Set `preload: true` / `preload=True` on a
+custom tool when it should be returned directly from `session.tools()`. For a
+custom toolkit, set preload on the toolkit to expose all of its tools, then use a
+tool-level `preload: false` / `preload=False` to opt out a specific tool.
+
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
+<Tab value="TypeScript">
+```typescript
+// @noErrors
+import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";
+import { z } from "zod/v3";
+
+const composio = new Composio({ apiKey: "your_api_key" });
+
+const lookupAccount = experimental_createTool("LOOKUP_ACCOUNT", {
+ name: "Lookup account",
+ description: "Look up an account by email",
+ preload: true,
+ inputParams: z.object({
+ email: z.string().describe("Customer email address"),
+ }),
+ execute: async ({ email }) => ({ email, status: "active" }),
+});
+
+const supportTools = experimental_createToolkit("SUPPORT_TOOLS", {
+ name: "Support tools",
+ description: "Internal support workflows",
+ preload: true,
+ tools: [
+ experimental_createTool("GET_TICKET", {
+ name: "Get ticket",
+ description: "Fetch an internal support ticket",
+ inputParams: z.object({
+ ticketId: z.string().describe("Ticket ID"),
+ }),
+ execute: async ({ ticketId }) => ({ ticketId, priority: "high" }),
+ }),
+ experimental_createTool("ARCHIVE_TICKET", {
+ name: "Archive ticket",
+ description: "Archive an internal support ticket",
+ preload: false,
+ inputParams: z.object({
+ ticketId: z.string().describe("Ticket ID"),
+ }),
+ execute: async ({ ticketId }) => ({ ticketId, archived: true }),
+ }),
+ ],
+});
+
+const session = await composio.create("user_1", {
+ experimental: {
+ customTools: [lookupAccount],
+ customToolkits: [supportTools],
+ },
+});
+
+const tools = await session.tools();
+```
+</Tab>
+<Tab value="Python">
+```python
+from pydantic import BaseModel, Field
+
+from composio import Composio
+
+composio = Composio(api_key="your_api_key")
+
+
+class EmailInput(BaseModel):
+ email: str = Field(description="Customer email address")
+
+
[email protected](preload=True)
+def lookup_account(input: EmailInput, ctx):
+ """Look up an account by email."""
+ return {"email": input.email, "status": "active"}
+
+
+support_tools = composio.experimental.Toolkit(
+ slug="SUPPORT_TOOLS",
+ name="Support tools",
+ description="Internal support workflows",
+ preload=True,
+)
+
+
+class TicketInput(BaseModel):
+ ticket_id: str = Field(description="Ticket ID")
+
+
+@support_tools.tool()
+def get_ticket(input: TicketInput, ctx):
+ """Fetch an internal support ticket."""
+ return {"ticket_id": input.ticket_id, "priority": "high"}
+
+
+@support_tools.tool(preload=False)
+def archive_ticket(input: TicketInput, ctx):
+ """Archive an internal support ticket."""
+ return {"ticket_id": input.ticket_id, "archived": True}
+
+
+session = composio.create(
+ user_id="user_1",
+ experimental={
+ "custom_tools": [lookup_account],
+ "custom_toolkits": [support_tools],
+ },
+)
+
+tools = session.tools()
+```
+</Tab>
+</Tabs>
+
## Meta tools integration
Custom tools work automatically with Composio's meta tools: