Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxnew file mode 100644index 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.mdxindex 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 configsUse 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.mdxindex 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 integrationCustom tools work automatically with Composio's meta tools: