⏲️ feat: Defer Loading MCP Tools (#11270)

* WIP: code ptc

* refactor: tool classification and calling logic

* 🔧 fix: Update @librechat/agents dependency to version 3.0.68

* chore: import order and correct renamed tool name for tool search

* refactor: streamline tool classification logic for local and programmatic tools

* feat: add per-tool configuration options for agents, including deferred loading and allowed callers

- Introduced `tool_options` in agent forms to manage tool behavior.
- Updated tool classification logic to prioritize agent-level configurations.
- Enhanced UI components to support tool deferral functionality.
- Added localization strings for new tool options and actions.

* feat: enhance agent schema with per-tool options for configuration

- Added `tool_options` schema to support per-tool configurations, including `defer_loading` and `allowed_callers`.
- Updated agent data model to incorporate new tool options, ensuring flexibility in tool behavior management.
- Modified type definitions to reflect the new `tool_options` structure for agents.

* feat: add tool_options parameter to loadTools and initializeAgent for enhanced agent configuration

* chore: update @librechat/agents dependency to version 3.0.71 and enhance agent tool loading logic

- Updated the @librechat/agents package to version 3.0.71 across multiple files.
- Added support for handling deferred loading of tools in agent initialization and execution processes.
- Improved the extraction of discovered tools from message history to optimize tool loading behavior.

* chore: update @librechat/agents dependency to version 3.0.72

* chore: update @librechat/agents dependency to version 3.0.75

* refactor: simplify tool defer loading logic in MCPTool component

- Removed local state management for deferred tools, relying on form state instead.
- Updated related functions to directly use form values for checking and toggling defer loading.
- Cleaned up code by eliminating unnecessary optimistic updates and local state dependencies.

* chore: remove deprecated localization strings for tool deferral in translation.json

- Eliminated unused strings related to deferred loading descriptions in the English translation file.
- Streamlined localization to reflect recent changes in tool loading logic.

* refactor: improve tool defer loading handling in MCPTool component

- Enhanced the logic for managing deferred loading of tools by simplifying the update process for tool options.
- Ensured that the state reflects the correct loading behavior based on the new deferred loading conditions.
- Cleaned up the code to remove unnecessary complexity in handling tool options.

* refactor: update agent mocks in callbacks test to use actual implementations

- Modified the agent mocks in the callbacks test to include actual implementations from the @librechat/agents module.
- This change enhances the accuracy of the tests by ensuring they reflect the real behavior of the agent functions.

api/server/controllers/agents/__tests__/callbacks.spec.js

@@ -16,9 +16,7 @@ jest.mock('@librechat/data-schemas', () => ({
 }));
 
 jest.mock('@librechat/agents', () => ({
-  EnvVar: { CODE_API_KEY: 'CODE_API_KEY' },
+  ...jest.requireActual('@librechat/agents'),
-  Providers: { GOOGLE: 'google' },
-  GraphEvents: {},
   getMessageId: jest.fn(),
   ToolEndHandler: jest.fn(),
   handleToolCalls: jest.fn(),

api/server/controllers/agents/callbacks.js

@@ -1,6 +1,7 @@
 const { nanoid } = require('nanoid');
-const { sendEvent, GenerationJobManager } = require('@librechat/api');
+const { Constants } = require('@librechat/agents');
 const { logger } = require('@librechat/data-schemas');
+const { sendEvent, GenerationJobManager } = require('@librechat/api');
 const { Tools, StepTypes, FileContext, ErrorTypes } = require('librechat-data-provider');
 const {
   EnvVar,
@@ -441,10 +442,10 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })
       return;
     }
 
-    {
+    const isCodeTool =
-      if (output.name !== Tools.execute_code) {
+      output.name === Tools.execute_code || output.name === Constants.PROGRAMMATIC_TOOL_CALLING;
-        return;
+    if (!isCodeTool) {
-      }
+      return;
     }
 
     if (!output.artifact.files) {

api/server/controllers/agents/client.js

@@ -1012,6 +1012,7 @@ class AgentClient extends BaseClient {
 
         run = await createRun({
           agents,
+          messages,
           indexTokenCountMap,
           runId: this.responseMessageId,
           signal: abortController.signal,

api/server/services/Endpoints/agents/initialize.js

@@ -43,13 +43,23 @@ function createToolLoader(signal, streamId = null) {
    * @param {string} params.model
    * @param {AgentToolResources} params.tool_resources
    * @returns {Promise<{
-   * tools: StructuredTool[],
+   *   tools: StructuredTool[],
-   * toolContextMap: Record<string, unknown>,
+   *   toolContextMap: Record<string, unknown>,
-   * userMCPAuthMap?: Record<string, Record<string, string>>
+   *   userMCPAuthMap?: Record<string, Record<string, string>>,
+   *   toolRegistry?: import('@librechat/agents').LCToolRegistry
    * } | undefined>}
    */
-  return async function loadTools({ req, res, agentId, tools, provider, model, tool_resources }) {
+  return async function loadTools({
-    const agent = { id: agentId, tools, provider, model };
+    req,
+    res,
+    tools,
+    model,
+    agentId,
+    provider,
+    tool_options,
+    tool_resources,
+  }) {
+    const agent = { id: agentId, tools, provider, model, tool_options };
     try {
       return await loadAgentTools({
         req,

api/server/services/MCP.js

@@ -548,6 +548,7 @@ function createToolInstance({
   });
   toolInstance.mcp = true;
   toolInstance.mcpRawServerName = serverName;
+  toolInstance.mcpJsonSchema = parameters;
   return toolInstance;
 }
 

api/server/services/ToolService.js

@@ -6,6 +6,7 @@ const {
   hasCustomUserVars,
   getUserMCPAuthMap,
   isActionDomainAllowed,
+  buildToolClassification,
 } = require('@librechat/api');
 const {
   Tools,
@@ -36,6 +37,7 @@ const { recordUsage } = require('~/server/services/Threads');
 const { loadTools } = require('~/app/clients/tools/util');
 const { redactMessage } = require('~/config/parsers');
 const { findPluginAuthsByKeys } = require('~/models');
+const { loadAuthValues } = require('~/server/services/Tools/credentials');
 /**
  * Processes the required actions by calling the appropriate tools and returning the outputs.
  * @param {OpenAIClient} client - OpenAI or StreamRunManager Client.
@@ -367,7 +369,13 @@ async function processRequiredActions(client, requiredActions) {
  * @param {AbortSignal} params.signal
  * @param {Pick<Agent, 'id' | 'provider' | 'model' | 'tools'} params.agent - The agent to load tools for.
  * @param {string | undefined} [params.openAIApiKey] - The OpenAI API key.
- * @returns {Promise<{ tools?: StructuredTool[]; userMCPAuthMap?: Record<string, Record<string, string>> }>} The agent tools.
+ * @returns {Promise<{
+ *   tools?: StructuredTool[];
+ *   toolContextMap?: Record<string, unknown>;
+ *   userMCPAuthMap?: Record<string, Record<string, string>>;
+ *   toolRegistry?: Map<string, import('~/utils/toolClassification').LCTool>;
+ *   hasDeferredTools?: boolean;
+ * }>} The agent tools and registry.
  */
 async function loadAgentTools({
   req,
@@ -510,11 +518,23 @@ async function loadAgentTools({
     return map;
   }, {});
 
+  /** Build tool registry from MCP tools and create PTC/tool search tools if configured */
+  const { toolRegistry, additionalTools, hasDeferredTools } = await buildToolClassification({
+    loadedTools,
+    userId: req.user.id,
+    agentId: agent.id,
+    agentToolOptions: agent.tool_options,
+    loadAuthValues,
+  });
+  agentTools.push(...additionalTools);
+
   if (!checkCapability(AgentCapabilities.actions)) {
     return {
       tools: agentTools,
       userMCPAuthMap,
       toolContextMap,
+      toolRegistry,
+      hasDeferredTools,
     };
   }
 
@@ -527,6 +547,8 @@ async function loadAgentTools({
       tools: agentTools,
       userMCPAuthMap,
       toolContextMap,
+      toolRegistry,
+      hasDeferredTools,
     };
   }
 
@@ -654,6 +676,8 @@ async function loadAgentTools({
     tools: agentTools,
     toolContextMap,
     userMCPAuthMap,
+    toolRegistry,
+    hasDeferredTools,
   };
 }
 

client/src/common/agents-types.ts

@@ -1,6 +1,7 @@
 import { AgentCapabilities, ArtifactModes } from 'librechat-data-provider';
 import type {
   AgentModelParameters,
+  AgentToolOptions,
   SupportContact,
   AgentProvider,
   GraphEdge,
@@ -33,6 +34,8 @@ export type AgentForm = {
   model: string | null;
   model_parameters: AgentModelParameters;
   tools?: string[];
+  /** Per-tool configuration options (deferred loading, allowed callers, etc.) */
+  tool_options?: AgentToolOptions;
   provider?: AgentProvider | OptionWithIcon;
   /** @deprecated Use edges instead */
   agent_ids?: string[];

client/src/components/Chat/Messages/Content/Part.tsx

@@ -91,7 +91,11 @@ const Part = memo(
 
       const isToolCall =
         'args' in toolCall && (!toolCall.type || toolCall.type === ToolCallTypes.TOOL_CALL);
-      if (isToolCall && toolCall.name === Tools.execute_code) {
+      if (
+        isToolCall &&
+        (toolCall.name === Tools.execute_code ||
+          toolCall.name === Constants.PROGRAMMATIC_TOOL_CALLING)
+      ) {
         return (
           <ExecuteCode
             attachments={attachments}

client/src/components/Chat/Messages/Content/Parts/ExecuteCode.tsx

@@ -67,7 +67,7 @@ export default function ExecuteCode({
   const [contentHeight, setContentHeight] = useState<number | undefined>(0);
 
   const prevShowCodeRef = useRef<boolean>(showCode);
-  const { lang, code } = useParseArgs(args) ?? ({} as ParsedArgs);
+  const { lang = 'py', code } = useParseArgs(args) ?? ({} as ParsedArgs);
   const progress = useProgress(initialProgress);
 
   useEffect(() => {

client/src/components/SidePanel/Agents/AgentPanel.tsx

@@ -23,6 +23,7 @@ import {
 import { createProviderOption, getDefaultAgentFormValues } from '~/utils';
 import { useResourcePermissions } from '~/hooks/useResourcePermissions';
 import { useSelectAgent, useLocalize, useAuthContext } from '~/hooks';
+import type { TranslationKeys } from '~/hooks/useLocalize';
 import { useAgentPanelContext } from '~/Providers/AgentPanelContext';
 import AgentPanelSkeleton from './AgentPanelSkeleton';
 import AdvancedPanel from './Advanced/AdvancedPanel';
@@ -36,8 +37,8 @@ import ModelPanel from './ModelPanel';
 function getUpdateToastMessage(
   noVersionChange: boolean,
   avatarActionState: AgentForm['avatar_action'],
-  name: string | undefined,
+  name: string | null | undefined,
-  localize: (key: string, vars?: Record<string, unknown> | Array<string | number>) => string,
+  localize: (key: TranslationKeys, vars?: Record<string, unknown>) => string,
 ): string | null {
   // If only avatar upload is pending (separate endpoint), suppress the no-changes toast.
   if (noVersionChange && avatarActionState === 'upload') {
@@ -72,6 +73,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
     recursion_limit,
     category,
     support_contact,
+    tool_options,
     avatar_action: avatarActionState,
   } = data;
 
@@ -97,6 +99,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
       recursion_limit,
       category,
       support_contact,
+      tool_options,
       ...(shouldResetAvatar ? { avatar: null } : {}),
     },
     provider,
@@ -545,7 +548,7 @@ export default function AgentPanel() {
           <AgentFooter
             createMutation={create}
             updateMutation={update}
-            isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isPending}
+            isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isLoading}
             activePanel={activePanel}
             setActivePanel={setActivePanel}
             setCurrentAgentId={setCurrentAgentId}

client/src/components/SidePanel/Agents/AgentSelect.tsx

@@ -111,6 +111,11 @@ export default function AgentSelect({
           return;
         }
 
+        if (name === 'tool_options' && typeof value === 'object' && value !== null) {
+          formValues[name] = value;
+          return;
+        }
+
         if (!keys.has(name)) {
           return;
         }

client/src/components/SidePanel/Agents/MCPTool.tsx

@@ -1,8 +1,9 @@
-import React, { useState } from 'react';
+import React, { useState, useCallback } from 'react';
-import { ChevronDown } from 'lucide-react';
+import { ChevronDown, Clock } from 'lucide-react';
-import { useFormContext } from 'react-hook-form';
+import { useFormContext, useWatch } from 'react-hook-form';
 import { Constants } from 'librechat-data-provider';
 import * as AccordionPrimitive from '@radix-ui/react-accordion';
+import type { AgentToolOptions } from 'librechat-data-provider';
 import {
   Label,
   ESide,
@@ -10,6 +11,7 @@ import {
   OGDialog,
   Accordion,
   TrashIcon,
+  TooltipAnchor,
   InfoHoverCard,
   AccordionItem,
   OGDialogTrigger,
@@ -25,13 +27,82 @@ import { cn } from '~/utils';
 export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo }) {
   const localize = useLocalize();
   const { removeTool } = useRemoveMCPTool();
-  const { getValues, setValue } = useFormContext<AgentForm>();
+  const { getValues, setValue, control } = useFormContext<AgentForm>();
   const { getServerStatusIconProps, getConfigDialogProps } = useMCPServerManager();
 
   const [isFocused, setIsFocused] = useState(false);
   const [isHovering, setIsHovering] = useState(false);
   const [accordionValue, setAccordionValue] = useState<string>('');
 
+  const formToolOptions = useWatch({ control, name: 'tool_options' });
+
+  /** Check if a specific tool has defer_loading enabled */
+  const isToolDeferred = useCallback(
+    (toolId: string): boolean => formToolOptions?.[toolId]?.defer_loading === true,
+    [formToolOptions],
+  );
+
+  /** Toggle defer_loading for a specific tool */
+  const toggleToolDefer = useCallback(
+    (toolId: string) => {
+      const currentOptions = getValues('tool_options') || {};
+      const currentToolOptions = currentOptions[toolId] || {};
+      const newDeferred = !currentToolOptions.defer_loading;
+
+      const updatedOptions: AgentToolOptions = { ...currentOptions };
+
+      if (newDeferred) {
+        updatedOptions[toolId] = {
+          ...currentToolOptions,
+          defer_loading: true,
+        };
+      } else {
+        const { defer_loading: _, ...restOptions } = currentToolOptions;
+        if (Object.keys(restOptions).length === 0) {
+          delete updatedOptions[toolId];
+        } else {
+          updatedOptions[toolId] = restOptions;
+        }
+      }
+
+      setValue('tool_options', updatedOptions, { shouldDirty: true });
+    },
+    [getValues, setValue],
+  );
+
+  /** Check if all server tools are deferred */
+  const areAllToolsDeferred =
+    serverInfo?.tools &&
+    serverInfo.tools.length > 0 &&
+    serverInfo.tools.every((tool) => formToolOptions?.[tool.tool_id]?.defer_loading === true);
+
+  /** Toggle defer_loading for all tools from this server */
+  const toggleDeferAll = useCallback(() => {
+    if (!serverInfo?.tools) return;
+
+    const shouldDefer = !areAllToolsDeferred;
+    const currentOptions = getValues('tool_options') || {};
+    const updatedOptions: AgentToolOptions = { ...currentOptions };
+
+    for (const tool of serverInfo.tools) {
+      if (shouldDefer) {
+        updatedOptions[tool.tool_id] = {
+          ...(updatedOptions[tool.tool_id] || {}),
+          defer_loading: true,
+        };
+      } else {
+        if (updatedOptions[tool.tool_id]) {
+          delete updatedOptions[tool.tool_id].defer_loading;
+          if (Object.keys(updatedOptions[tool.tool_id]).length === 0) {
+            delete updatedOptions[tool.tool_id];
+          }
+        }
+      }
+    }
+
+    setValue('tool_options', updatedOptions, { shouldDirty: true });
+  }, [serverInfo?.tools, getValues, setValue, areAllToolsDeferred]);
+
   if (!serverInfo) {
     return null;
   }
@@ -170,6 +241,47 @@ export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo })
                           />
                         </div>
 
+                        {/* Defer All toggle - icon only with tooltip */}
+                        <TooltipAnchor
+                          description={
+                            areAllToolsDeferred
+                              ? localize('com_ui_mcp_undefer_all')
+                              : localize('com_ui_mcp_defer_all')
+                          }
+                          side="top"
+                          role="button"
+                          tabIndex={isExpanded ? 0 : -1}
+                          aria-label={
+                            areAllToolsDeferred
+                              ? localize('com_ui_mcp_undefer_all')
+                              : localize('com_ui_mcp_defer_all')
+                          }
+                          aria-pressed={areAllToolsDeferred}
+                          className={cn(
+                            'flex h-7 w-7 items-center justify-center rounded transition-colors duration-200',
+                            'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-1',
+                            isExpanded ? 'visible' : 'pointer-events-none invisible',
+                            areAllToolsDeferred
+                              ? 'bg-amber-500/20 text-amber-500 hover:bg-amber-500/30'
+                              : 'text-text-tertiary hover:bg-surface-hover hover:text-text-primary',
+                          )}
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            toggleDeferAll();
+                          }}
+                          onKeyDown={(e) => {
+                            if (e.key === 'Enter' || e.key === ' ') {
+                              e.preventDefault();
+                              e.stopPropagation();
+                              toggleDeferAll();
+                            }
+                          }}
+                        >
+                          <Clock
+                            className={cn('h-4 w-4', areAllToolsDeferred && 'fill-amber-500/30')}
+                          />
+                        </TooltipAnchor>
+
                         <div className="flex items-center gap-1">
                           {/* Caret button for accordion */}
                           <AccordionPrimitive.Trigger asChild>
@@ -230,52 +342,95 @@ export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo })
 
           <AccordionContent className="relative ml-1 pt-1 before:absolute before:bottom-2 before:left-0 before:top-0 before:w-0.5 before:bg-border-medium">
             <div className="space-y-1">
-              {serverInfo.tools?.map((subTool) => (
+              {serverInfo.tools?.map((subTool) => {
-                <label
+                const isDeferred = isToolDeferred(subTool.tool_id);
-                  key={subTool.tool_id}
+                return (
-                  htmlFor={subTool.tool_id}
+                  <label
-                  className={cn(
+                    key={subTool.tool_id}
-                    'group/item border-token-border-light hover:bg-token-surface-secondary flex cursor-pointer items-center rounded-lg border p-2',
+                    htmlFor={subTool.tool_id}
-                    'ml-2 mr-1 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background',
+                    className={cn(
-                  )}
+                      'group/item flex cursor-pointer items-center rounded-lg border p-2',
-                  onClick={(e) => e.stopPropagation()}
+                      'ml-2 mr-1 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background',
-                  onKeyDown={(e) => {
+                      isDeferred
-                    e.stopPropagation();
+                        ? 'border-amber-500/50 bg-amber-500/5 hover:bg-amber-500/10'
-                  }}
+                        : 'border-token-border-light hover:bg-token-surface-secondary',
-                >
+                    )}
-                  <Checkbox
+                    onClick={(e) => e.stopPropagation()}
-                    id={subTool.tool_id}
-                    checked={selectedTools.includes(subTool.tool_id)}
-                    onCheckedChange={(_checked) => {
-                      const newSelectedTools = selectedTools.includes(subTool.tool_id)
-                        ? selectedTools.filter((t) => t !== subTool.tool_id)
-                        : [...selectedTools, subTool.tool_id];
-                      updateFormTools(newSelectedTools);
-                    }}
                     onKeyDown={(e) => {
                       e.stopPropagation();
-                      if (e.key === 'Enter' || e.key === ' ') {
-                        e.preventDefault();
-                        const checkbox = e.currentTarget as HTMLButtonElement;
-                        checkbox.click();
-                      }
                     }}
-                    onClick={(e) => e.stopPropagation()}
+                  >
-                    className={cn(
+                    <Checkbox
-                      'relative float-left mr-2 inline-flex h-4 w-4 cursor-pointer rounded border border-border-medium transition-[border-color] duration-200 hover:border-border-heavy focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background',
+                      id={subTool.tool_id}
-                    )}
+                      checked={selectedTools.includes(subTool.tool_id)}
-                    aria-label={subTool.metadata.name}
+                      onCheckedChange={(_checked) => {
-                  />
+                        const newSelectedTools = selectedTools.includes(subTool.tool_id)
-                  <span className="text-token-text-primary select-none">
+                          ? selectedTools.filter((t) => t !== subTool.tool_id)
-                    {subTool.metadata.name}
+                          : [...selectedTools, subTool.tool_id];
-                  </span>
+                        updateFormTools(newSelectedTools);
-                  {subTool.metadata.description && (
+                      }}
-                    <div className="ml-auto flex items-center opacity-0 transition-opacity duration-200 group-focus-within/item:opacity-100 group-hover/item:opacity-100">
+                      onKeyDown={(e) => {
-                      <InfoHoverCard side={ESide.Left} text={subTool.metadata.description} />
+                        e.stopPropagation();
+                        if (e.key === 'Enter' || e.key === ' ') {
+                          e.preventDefault();
+                          const checkbox = e.currentTarget as HTMLButtonElement;
+                          checkbox.click();
+                        }
+                      }}
+                      onClick={(e) => e.stopPropagation()}
+                      className={cn(
+                        'relative float-left mr-2 inline-flex h-4 w-4 cursor-pointer rounded border border-border-medium transition-[border-color] duration-200 hover:border-border-heavy focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background',
+                      )}
+                      aria-label={subTool.metadata.name}
+                    />
+                    <span className="text-token-text-primary flex-1 select-none">
+                      {subTool.metadata.name}
+                    </span>
+                    <div className="ml-auto flex items-center gap-1">
+                      {/* Per-tool defer toggle - icon only */}
+                      <TooltipAnchor
+                        description={
+                          isDeferred
+                            ? localize('com_ui_mcp_click_to_undefer')
+                            : localize('com_ui_mcp_click_to_defer')
+                        }
+                        side="top"
+                        role="button"
+                        aria-label={
+                          isDeferred
+                            ? localize('com_ui_mcp_undefer')
+                            : localize('com_ui_mcp_defer_loading')
+                        }
+                        aria-pressed={isDeferred}
+                        className={cn(
+                          'flex h-6 w-6 items-center justify-center rounded transition-all duration-200',
+                          'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-1',
+                          isDeferred
+                            ? 'bg-amber-500/20 text-amber-500 hover:bg-amber-500/30'
+                            : 'text-text-tertiary opacity-0 hover:bg-surface-hover hover:text-text-primary group-focus-within/item:opacity-100 group-hover/item:opacity-100',
+                        )}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          e.preventDefault();
+                          toggleToolDefer(subTool.tool_id);
+                        }}
+                        onKeyDown={(e) => {
+                          e.stopPropagation();
+                          if (e.key === 'Enter' || e.key === ' ') {
+                            e.preventDefault();
+                            toggleToolDefer(subTool.tool_id);
+                          }
+                        }}
+                      >
+                        <Clock className={cn('h-3.5 w-3.5', isDeferred && 'fill-amber-500/30')} />
+                      </TooltipAnchor>
+                      {subTool.metadata.description && (
+                        <InfoHoverCard side={ESide.Left} text={subTool.metadata.description} />
+                      )}
                     </div>
-                  )}
+                  </label>
-                </label>
+                );
-              ))}
+              })}
             </div>
           </AccordionContent>
         </AccordionItem>

client/src/locales/en/translation.json

@@ -704,7 +704,7 @@
   "com_ui_agents_allow_use": "Allow using Agents",
   "com_ui_all": "all",
   "com_ui_all_proper": "All",
-  "com_ui_analyzing": "Analyzing",
+  "com_ui_analyzing": "Running tools with code",
   "com_ui_analyzing_finished": "Finished analyzing",
   "com_ui_api_key": "API Key",
   "com_ui_archive": "Archive",
@@ -1098,6 +1098,13 @@
   "com_ui_mcp_type_streamable_http": "Streamable HTTPS",
   "com_ui_mcp_update_var": "Update {{0}}",
   "com_ui_mcp_url": "MCP Server URL",
+  "com_ui_mcp_defer_loading": "Defer loading",
+  "com_ui_mcp_defer": "Defer",
+  "com_ui_mcp_defer_all": "Defer all tools",
+  "com_ui_mcp_undefer": "Undefer",
+  "com_ui_mcp_undefer_all": "Undefer all tools",
+  "com_ui_mcp_click_to_defer": "Click to defer - tool will be discoverable via search but not loaded until needed",
+  "com_ui_mcp_click_to_undefer": "Click to undefer - tool will be loaded immediately",
   "com_ui_medium": "Medium",
   "com_ui_memories": "Memories",
   "com_ui_memories_allow_create": "Allow creating Memories",

packages/api/src/agents/initialize.ts

@@ -10,14 +10,15 @@ import {
 } from 'librechat-data-provider';
 import type {
   AgentToolResources,
+  AgentToolOptions,
   TEndpointOption,
   TFile,
   Agent,
   TUser,
 } from 'librechat-data-provider';
+import type { GenericTool, LCToolRegistry, ToolMap } from '@librechat/agents';
 import type { Response as ServerResponse } from 'express';
 import type { IMongoFile } from '@librechat/data-schemas';
-import type { GenericTool } from '@librechat/agents';
 import type { InitializeResultBase, ServerRequest, EndpointDbMethods } from '~/types';
 import { getModelMaxTokens, extractLibreChatParams, optionalChainWithEmptyCheck } from '~/utils';
 import { filterFilesByEndpointConfig } from '~/files';
@@ -36,6 +37,12 @@ export type InitializedAgent = Agent & {
   useLegacyContent: boolean;
   resendFiles: boolean;
   userMCPAuthMap?: Record<string, Record<string, string>>;
+  /** Tool map for ToolNode to use when executing tools (required for PTC) */
+  toolMap?: ToolMap;
+  /** Tool registry for PTC and tool search (only present when MCP tools with env classification exist) */
+  toolRegistry?: LCToolRegistry;
+  /** Precomputed flag indicating if any tools have defer_loading enabled (for efficient runtime checks) */
+  hasDeferredTools?: boolean;
 };
 
 /**
@@ -61,11 +68,14 @@ export interface InitializeAgentParams {
     agentId: string;
     tools: string[];
     model: string | null;
+    tool_options: AgentToolOptions | undefined;
     tool_resources: AgentToolResources | undefined;
   }) => Promise<{
     tools: GenericTool[];
     toolContextMap: Record<string, unknown>;
     userMCPAuthMap?: Record<string, Record<string, string>>;
+    toolRegistry?: LCToolRegistry;
+    hasDeferredTools?: boolean;
   } | null>;
   /** Endpoint option (contains model_parameters and endpoint info) */
   endpointOption?: Partial<TEndpointOption>;
@@ -201,6 +211,8 @@ export async function initializeAgent(
     tools: structuredTools,
     toolContextMap,
     userMCPAuthMap,
+    toolRegistry,
+    hasDeferredTools,
   } = (await loadTools?.({
     req,
     res,
@@ -208,8 +220,15 @@ export async function initializeAgent(
     agentId: agent.id,
     tools: agent.tools ?? [],
     model: agent.model,
+    tool_options: agent.tool_options,
     tool_resources,
-  })) ?? { tools: [], toolContextMap: {}, userMCPAuthMap: undefined };
+  })) ?? {
+    tools: [],
+    toolContextMap: {},
+    userMCPAuthMap: undefined,
+    toolRegistry: undefined,
+    hasDeferredTools: false,
+  };
 
   const { getOptions, overrideProvider } = getProviderConfig({
     provider,
@@ -312,6 +331,8 @@ export async function initializeAgent(
     attachments: finalAttachments,
     resendFiles,
     userMCPAuthMap,
+    toolRegistry,
+    hasDeferredTools,
     toolContextMap: toolContextMap ?? {},
     useLegacyContent: !!options.useLegacyContent,
     maxContextTokens: Math.round((agentMaxContextNum - maxOutputTokensNum) * 0.9),

packages/api/src/agents/run.ts

@@ -1,9 +1,11 @@
 import { Run, Providers } from '@librechat/agents';
 import { providerEndpointMap, KnownEndpoints } from 'librechat-data-provider';
+import type { BaseMessage } from '@langchain/core/messages';
 import type {
   MultiAgentGraphConfig,
   OpenAIClientOptions,
   StandardGraphConfig,
+  LCToolRegistry,
   AgentInputs,
   GenericTool,
   RunConfig,
@@ -14,6 +16,121 @@ import type { Agent } from 'librechat-data-provider';
 import type * as t from '~/types';
 import { resolveHeaders, createSafeUser } from '~/utils/env';
 
+/** Tool search tool name constant */
+const TOOL_SEARCH_NAME = 'tool_search';
+
+/** Expected shape of JSON tool search results */
+interface ToolSearchJsonResult {
+  found?: number;
+  tools?: Array<{ name: string }>;
+}
+
+/**
+ * Parses tool names from JSON-formatted tool_search output.
+ * Format: { "found": N, "tools": [{ "name": "tool_name", ... }], ... }
+ *
+ * @param content - The JSON string content
+ * @param discoveredTools - Set to add discovered tool names to
+ * @returns true if parsing succeeded, false otherwise
+ */
+function parseToolSearchJson(content: string, discoveredTools: Set<string>): boolean {
+  try {
+    const parsed = JSON.parse(content) as ToolSearchJsonResult;
+    if (!parsed.tools || !Array.isArray(parsed.tools)) {
+      return false;
+    }
+    for (const tool of parsed.tools) {
+      if (tool.name && typeof tool.name === 'string') {
+        discoveredTools.add(tool.name);
+      }
+    }
+    return parsed.tools.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parses tool names from legacy text-formatted tool_search output.
+ * Format: "- tool_name (score: X.XX)"
+ *
+ * @param content - The text content
+ * @param discoveredTools - Set to add discovered tool names to
+ */
+function parseToolSearchLegacy(content: string, discoveredTools: Set<string>): void {
+  const toolNameRegex = /^- ([^\s(]+)\s*\(score:/gm;
+  let match: RegExpExecArray | null;
+  while ((match = toolNameRegex.exec(content)) !== null) {
+    const toolName = match[1];
+    if (toolName) {
+      discoveredTools.add(toolName);
+    }
+  }
+}
+
+/**
+ * Extracts discovered tool names from message history by parsing tool_search results.
+ * When the LLM calls tool_search, the result contains tool names that were discovered.
+ * These tools should have defer_loading overridden to false on subsequent turns.
+ *
+ * Supports both:
+ * - New JSON format: { "tools": [{ "name": "tool_name" }] }
+ * - Legacy text format: "- tool_name (score: X.XX)"
+ *
+ * @param messages - The conversation message history
+ * @returns Set of tool names that were discovered via tool_search
+ */
+export function extractDiscoveredToolsFromHistory(messages: BaseMessage[]): Set<string> {
+  const discoveredTools = new Set<string>();
+
+  for (const message of messages) {
+    const msgType = message._getType?.() ?? message.constructor?.name ?? '';
+    if (msgType !== 'tool') {
+      continue;
+    }
+
+    const name = (message as { name?: string }).name;
+    if (name !== TOOL_SEARCH_NAME) {
+      continue;
+    }
+
+    const content = message.content;
+    if (typeof content !== 'string') {
+      continue;
+    }
+
+    /** Try JSON format first (new), fall back to regex (legacy) */
+    if (!parseToolSearchJson(content, discoveredTools)) {
+      parseToolSearchLegacy(content, discoveredTools);
+    }
+  }
+
+  return discoveredTools;
+}
+
+/**
+ * Overrides defer_loading to false for tools that were already discovered via tool_search.
+ * This prevents the LLM from having to re-discover tools on every turn.
+ *
+ * @param toolRegistry - The tool registry to modify (mutated in place)
+ * @param discoveredTools - Set of tool names that were previously discovered
+ * @returns Number of tools that had defer_loading overridden
+ */
+export function overrideDeferLoadingForDiscoveredTools(
+  toolRegistry: LCToolRegistry,
+  discoveredTools: Set<string>,
+): number {
+  let overrideCount = 0;
+  for (const toolName of discoveredTools) {
+    const toolDef = toolRegistry.get(toolName);
+    if (toolDef && toolDef.defer_loading === true) {
+      toolDef.defer_loading = false;
+      overrideCount++;
+    }
+  }
+  return overrideCount;
+}
+
 const customProviders = new Set([
   Providers.XAI,
   Providers.DEEPSEEK,
@@ -48,6 +165,9 @@ type RunAgent = Omit<Agent, 'tools'> & {
   maxContextTokens?: number;
   useLegacyContent?: boolean;
   toolContextMap?: Record<string, string>;
+  toolRegistry?: LCToolRegistry;
+  /** Precomputed flag indicating if any tools have defer_loading enabled */
+  hasDeferredTools?: boolean;
 };
 
 /**
@@ -60,12 +180,16 @@ type RunAgent = Omit<Agent, 'tools'> & {
  * @param options.customHandlers - Custom event handlers.
  * @param options.streaming - Whether to use streaming.
  * @param options.streamUsage - Whether to stream usage information.
+ * @param options.messages - Optional message history to extract discovered tools from.
+ *   When provided, tools that were previously discovered via tool_search will have
+ *   their defer_loading overridden to false, preventing redundant re-discovery.
  * @returns {Promise<Run<IState>>} A promise that resolves to a new Run instance.
  */
 export async function createRun({
   runId,
   signal,
   agents,
+  messages,
   requestBody,
   user,
   tokenCounter,
@@ -81,9 +205,26 @@ export async function createRun({
   streamUsage?: boolean;
   requestBody?: t.RequestBody;
   user?: IUser;
+  /** Message history for extracting previously discovered tools */
+  messages?: BaseMessage[];
 } & Pick<RunConfig, 'tokenCounter' | 'customHandlers' | 'indexTokenCountMap'>): Promise<
   Run<IState>
 > {
+  /**
+   * Only extract discovered tools if:
+   * 1. We have message history to parse
+   * 2. At least one agent has deferred tools (using precomputed flag)
+   *
+   * This optimization avoids iterating through messages in the ~95% of cases
+   * where no agent uses deferred tool loading.
+   */
+  const hasAnyDeferredTools = agents.some((agent) => agent.hasDeferredTools === true);
+
+  const discoveredTools =
+    hasAnyDeferredTools && messages?.length
+      ? extractDiscoveredToolsFromHistory(messages)
+      : new Set<string>();
+
   const agentInputs: AgentInputs[] = [];
   const buildAgentContext = (agent: RunAgent) => {
     const provider =
@@ -135,6 +276,14 @@ export async function createRun({
       llmConfig.usage = true;
     }
 
+    /**
+     * Override defer_loading for tools that were discovered in previous turns.
+     * This prevents the LLM from having to re-discover tools via tool_search.
+     */
+    if (discoveredTools.size > 0 && agent.toolRegistry) {
+      overrideDeferLoadingForDiscoveredTools(agent.toolRegistry, discoveredTools);
+    }
+
     const reasoningKey = getReasoningKey(provider, llmConfig, agent.endpoint);
     const agentInput: AgentInputs = {
       provider,
@@ -144,6 +293,7 @@ export async function createRun({
       tools: agent.tools,
       clientOptions: llmConfig,
       instructions: systemContent,
+      toolRegistry: agent.toolRegistry,
       maxContextTokens: agent.maxContextTokens,
       useLegacyContent: agent.useLegacyContent ?? false,
     };

packages/api/src/agents/validation.ts

@@ -51,6 +51,15 @@ export const graphEdgeSchema = z.object({
   promptKey: z.string().optional(),
 });
 
+/** Per-tool options schema (defer_loading, allowed_callers) */
+export const toolOptionsSchema = z.object({
+  defer_loading: z.boolean().optional(),
+  allowed_callers: z.array(z.enum(['direct', 'code_execution'])).optional(),
+});
+
+/** Agent tool options - map of tool_id to tool options */
+export const agentToolOptionsSchema = z.record(z.string(), toolOptionsSchema).optional();
+
 /** Base agent schema with all common fields */
 export const agentBaseSchema = z.object({
   name: z.string().nullable().optional(),
@@ -68,6 +77,7 @@ export const agentBaseSchema = z.object({
   recursion_limit: z.number().optional(),
   conversation_starters: z.array(z.string()).optional(),
   tool_resources: agentToolResourcesSchema,
+  tool_options: agentToolOptionsSchema,
   support_contact: agentSupportContactSchema,
   category: z.string().optional(),
 });

packages/api/src/mcp/types/index.ts

@@ -17,7 +17,8 @@ import type {
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
 import type { SearchResultData, UIResource, TPlugin } from 'librechat-data-provider';
-import type { TokenMethods, JsonSchemaType, IUser } from '@librechat/data-schemas';
+import type { TokenMethods, IUser } from '@librechat/data-schemas';
+import type { LCTool } from '@librechat/agents';
 import type { FlowStateManager } from '~/flow/manager';
 import type { RequestBody } from '~/types/http';
 import type * as o from '~/mcp/oauth/types';
@@ -42,11 +43,6 @@ export interface MCPResource {
   description?: string;
   mimeType?: string;
 }
-export interface LCTool {
-  name: string;
-  description?: string;
-  parameters: JsonSchemaType;
-}
 
 export interface LCFunctionTool {
   type: 'function';

packages/api/src/tools/classification.ts

@@ -0,0 +1,491 @@
+/**
+ * @fileoverview Utility functions for building tool registries from environment variables.
+ * This is a temporary solution for tool classification until UI-based configuration is available.
+ *
+ * Environment Variables:
+ * - TOOL_PROGRAMMATIC_ONLY: Comma-separated tool names or server patterns (sys__all__sys_mcp_ServerName)
+ * - TOOL_PROGRAMMATIC_ONLY_EXCLUDE: Comma-separated tool names to exclude from programmatic only
+ * - TOOL_DUAL_CONTEXT: Comma-separated tool names or server patterns callable BOTH by LLM and PTC
+ * - TOOL_DUAL_CONTEXT_EXCLUDE: Comma-separated tool names to exclude from dual context
+ * - TOOL_DEFERRED: Comma-separated tool names or server patterns for deferred tools
+ * - TOOL_DEFERRED_EXCLUDE: Comma-separated tool names to exclude from deferred
+ * - TOOL_CLASSIFICATION_AGENT_IDS: Optional comma-separated agent IDs to restrict classification features
+ *
+ * Server patterns: Use `sys__all__sys_mcp_ServerName` to match all tools from an MCP server.
+ * Example: `sys__all__sys_mcp_Google-Workspace` matches all Google Workspace tools.
+ *
+ * Agent restriction: If TOOL_CLASSIFICATION_AGENT_IDS is set, only those agents will get
+ * PTC and tool search tools. If not set, all agents with matching tools get them.
+ *
+ * Smart enablement: PTC/tool search are only created if the agent has tools that actually
+ * match the classification patterns. An agent with no programmatic/deferred tools won't
+ * get PTC/tool search even if the env vars are set.
+ *
+ * @module packages/api/src/tools/classification
+ */
+
+import { logger } from '@librechat/data-schemas';
+import { Constants } from 'librechat-data-provider';
+import { EnvVar, createProgrammaticToolCallingTool, createToolSearch } from '@librechat/agents';
+import type { AgentToolOptions } from 'librechat-data-provider';
+import type {
+  LCToolRegistry,
+  JsonSchemaType,
+  AllowedCaller,
+  GenericTool,
+  LCTool,
+} from '@librechat/agents';
+
+export type { LCTool, LCToolRegistry, AllowedCaller, JsonSchemaType };
+
+/** Pattern prefix for matching all tools from an MCP server */
+const MCP_ALL_PATTERN = `${Constants.mcp_all}${Constants.mcp_delimiter}`;
+
+export interface ToolDefinition {
+  name: string;
+  description?: string;
+  parameters?: JsonSchemaType;
+}
+
+/**
+ * Parses a comma-separated tool list from an environment variable.
+ * @param envValue - The environment variable value
+ * @returns Set of tool names or server patterns
+ */
+export function parseToolList(envValue: string | undefined): Set<string> {
+  if (!envValue || envValue.trim() === '') {
+    return new Set();
+  }
+  return new Set(
+    envValue
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
+  );
+}
+
+/**
+ * Extracts the MCP server name from a tool name.
+ * Tool names follow the pattern: toolName_mcp_ServerName
+ * @param toolName - The full tool name
+ * @returns The server name or undefined if not an MCP tool
+ */
+export function getServerNameFromTool(toolName: string): string | undefined {
+  const parts = toolName.split(Constants.mcp_delimiter);
+  if (parts.length >= 2) {
+    return parts[parts.length - 1];
+  }
+  return undefined;
+}
+
+/**
+ * Checks if a tool matches a set of patterns (tool names or server patterns).
+ * Supports both exact tool name matches and server-wide patterns like `mcp_all_mcp_ServerName`.
+ *
+ * @param toolName - The tool name to check
+ * @param patterns - Set of patterns (tool names or mcp_all_mcp_ServerName patterns)
+ * @param excludes - Set of tool names to exclude (takes precedence over patterns)
+ * @returns Whether the tool matches any pattern and is not excluded
+ */
+export function toolMatchesPatterns(
+  toolName: string,
+  patterns: Set<string>,
+  excludes: Set<string>,
+): boolean {
+  if (excludes.has(toolName)) {
+    return false;
+  }
+
+  if (patterns.has(toolName)) {
+    return true;
+  }
+
+  const serverName = getServerNameFromTool(toolName);
+  if (serverName) {
+    const serverPattern = `${MCP_ALL_PATTERN}${serverName}`;
+    if (patterns.has(serverPattern)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Builds a tool registry from environment variables for the given tools.
+ * This is a temporary solution while UI-based configuration is being developed.
+ *
+ * Supports server-wide patterns using `mcp_all_mcp_ServerName` syntax.
+ * Exclusion env vars take precedence over inclusion patterns.
+ *
+ * Default behavior (if tool not listed in any env var):
+ * - allowed_callers: ['direct']
+ * - defer_loading: false
+ *
+ * @param tools - Array of tool definitions
+ * @returns Map of tool name to tool definition with classification
+ *
+ * @example
+ * // Environment for server-wide configuration:
+ * // TOOL_PROGRAMMATIC_ONLY=mcp_all_mcp_Google-Workspace
+ * // TOOL_DEFERRED=mcp_all_mcp_Google-Workspace
+ * // TOOL_DEFERRED_EXCLUDE=list_spreadsheets_mcp_Google-Workspace,read_sheet_values_mcp_Google-Workspace
+ *
+ * @example
+ * // Environment for individual tools:
+ * // TOOL_PROGRAMMATIC_ONLY=get_expenses,get_team_members
+ * // TOOL_DUAL_CONTEXT=get_weather
+ * // TOOL_DEFERRED=generate_report
+ */
+export function buildToolRegistryFromEnv(tools: ToolDefinition[]): LCToolRegistry {
+  const programmaticOnly = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY);
+  const programmaticOnlyExclude = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY_EXCLUDE);
+  const dualContext = parseToolList(process.env.TOOL_DUAL_CONTEXT);
+  const dualContextExclude = parseToolList(process.env.TOOL_DUAL_CONTEXT_EXCLUDE);
+  const deferred = parseToolList(process.env.TOOL_DEFERRED);
+  const deferredExclude = parseToolList(process.env.TOOL_DEFERRED_EXCLUDE);
+
+  const registry: LCToolRegistry = new Map();
+
+  for (const tool of tools) {
+    const { name, description, parameters } = tool;
+
+    let allowed_callers: AllowedCaller[];
+
+    if (toolMatchesPatterns(name, programmaticOnly, programmaticOnlyExclude)) {
+      allowed_callers = ['code_execution'];
+    } else if (toolMatchesPatterns(name, dualContext, dualContextExclude)) {
+      allowed_callers = ['direct', 'code_execution'];
+    } else {
+      // Default: direct only (LLM can call, PTC cannot)
+      allowed_callers = ['direct'];
+    }
+
+    const toolDef: LCTool = {
+      name,
+      allowed_callers,
+      defer_loading: toolMatchesPatterns(name, deferred, deferredExclude),
+    };
+
+    // Include description and parameters if available (needed for tool search and PTC stub generation)
+    if (description) {
+      toolDef.description = description;
+    }
+    if (parameters) {
+      toolDef.parameters = parameters;
+    }
+
+    registry.set(name, toolDef);
+  }
+
+  return registry;
+}
+
+/**
+ * Builds a tool registry from agent-level tool_options.
+ * This takes precedence over environment variable configuration when provided.
+ *
+ * @param tools - Array of tool definitions
+ * @param agentToolOptions - Per-tool configuration from the agent
+ * @returns Map of tool name to tool definition with classification
+ */
+export function buildToolRegistryFromAgentOptions(
+  tools: ToolDefinition[],
+  agentToolOptions: AgentToolOptions,
+): LCToolRegistry {
+  /** Fall back to env vars for tools not configured at agent level */
+  const programmaticOnly = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY);
+  const programmaticOnlyExclude = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY_EXCLUDE);
+  const dualContext = parseToolList(process.env.TOOL_DUAL_CONTEXT);
+  const dualContextExclude = parseToolList(process.env.TOOL_DUAL_CONTEXT_EXCLUDE);
+
+  const registry: LCToolRegistry = new Map();
+
+  for (const tool of tools) {
+    const { name, description, parameters } = tool;
+    const agentOptions = agentToolOptions[name];
+
+    /** Determine allowed_callers: agent options take precedence, then env vars, then default */
+    let allowed_callers: AllowedCaller[];
+    if (agentOptions?.allowed_callers && agentOptions.allowed_callers.length > 0) {
+      allowed_callers = agentOptions.allowed_callers;
+    } else if (toolMatchesPatterns(name, programmaticOnly, programmaticOnlyExclude)) {
+      allowed_callers = ['code_execution'];
+    } else if (toolMatchesPatterns(name, dualContext, dualContextExclude)) {
+      allowed_callers = ['direct', 'code_execution'];
+    } else {
+      allowed_callers = ['direct'];
+    }
+
+    /** Determine defer_loading: agent options take precedence (explicit true/false) */
+    const defer_loading = agentOptions?.defer_loading === true;
+
+    const toolDef: LCTool = {
+      name,
+      allowed_callers,
+      defer_loading,
+    };
+
+    if (description) {
+      toolDef.description = description;
+    }
+    if (parameters) {
+      toolDef.parameters = parameters;
+    }
+
+    registry.set(name, toolDef);
+  }
+
+  return registry;
+}
+
+/**
+ * Checks if PTC (Programmatic Tool Calling) should be enabled based on environment configuration.
+ * PTC is enabled if any tools or server patterns are configured for programmatic calling.
+ * @returns Whether PTC should be enabled
+ */
+export function shouldEnablePTC(): boolean {
+  const programmaticOnly = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY);
+  const dualContext = parseToolList(process.env.TOOL_DUAL_CONTEXT);
+  return programmaticOnly.size > 0 || dualContext.size > 0;
+}
+
+/**
+ * Checks if tool search should be enabled based on environment configuration.
+ * Tool search is enabled if any tools or server patterns are configured as deferred.
+ * @returns Whether tool search should be enabled
+ */
+export function shouldEnableToolSearch(): boolean {
+  const deferred = parseToolList(process.env.TOOL_DEFERRED);
+  return deferred.size > 0;
+}
+
+interface MCPToolInstance {
+  name: string;
+  description?: string;
+  mcp?: boolean;
+  /** Original JSON schema attached at MCP tool creation time */
+  mcpJsonSchema?: JsonSchemaType;
+}
+
+/**
+ * Extracts MCP tool definition from a loaded tool instance.
+ * MCP tools have the original JSON schema attached as `mcpJsonSchema` property.
+ *
+ * @param tool - The loaded tool instance
+ * @returns Tool definition
+ */
+export function extractMCPToolDefinition(tool: MCPToolInstance): ToolDefinition {
+  const def: ToolDefinition = { name: tool.name };
+
+  if (tool.description) {
+    def.description = tool.description;
+  }
+
+  if (tool.mcpJsonSchema) {
+    def.parameters = tool.mcpJsonSchema;
+  }
+
+  return def;
+}
+
+/**
+ * Checks if a tool is an MCP tool based on its properties.
+ * @param tool - The tool to check (can be any object with potential mcp property)
+ * @returns Whether the tool is an MCP tool
+ */
+export function isMCPTool(tool: unknown): tool is MCPToolInstance {
+  return typeof tool === 'object' && tool !== null && (tool as MCPToolInstance).mcp === true;
+}
+
+/**
+ * Cleans up the temporary mcpJsonSchema property from MCP tools after registry is populated.
+ * This property is only needed during registry building and can be safely removed afterward.
+ *
+ * @param tools - Array of tools to clean up
+ */
+export function cleanupMCPToolSchemas(tools: MCPToolInstance[]): void {
+  for (const tool of tools) {
+    if (tool.mcpJsonSchema !== undefined) {
+      delete tool.mcpJsonSchema;
+    }
+  }
+}
+
+/** Parameters for building tool classification and creating PTC/tool search tools */
+export interface BuildToolClassificationParams {
+  /** All loaded tools (will be filtered for MCP tools) */
+  loadedTools: GenericTool[];
+  /** User ID for auth lookup */
+  userId: string;
+  /** Agent ID (used to check if this agent should have classification features) */
+  agentId?: string;
+  /** Per-tool configuration from the agent (takes precedence over env vars) */
+  agentToolOptions?: AgentToolOptions;
+  /** Function to load auth values (dependency injection) */
+  loadAuthValues: (params: {
+    userId: string;
+    authFields: string[];
+  }) => Promise<Record<string, string>>;
+}
+
+/** Result from building tool classification */
+export interface BuildToolClassificationResult {
+  /** Tool registry built from MCP tools (undefined if no MCP tools) */
+  toolRegistry?: LCToolRegistry;
+  /** Additional tools created (PTC and/or tool search) */
+  additionalTools: GenericTool[];
+  /** Whether any tools have defer_loading enabled (precomputed for efficiency) */
+  hasDeferredTools: boolean;
+}
+
+/**
+ * Checks if an agent is allowed to have classification features based on TOOL_CLASSIFICATION_AGENT_IDS.
+ * If TOOL_CLASSIFICATION_AGENT_IDS is not set, all agents are allowed (including when no agentId).
+ * If set, requires agentId to be in the list.
+ * @param agentId - The agent ID to check
+ * @returns Whether the agent is allowed
+ */
+export function isAgentAllowedForClassification(agentId?: string): boolean {
+  const allowedAgentIds = parseToolList(process.env.TOOL_CLASSIFICATION_AGENT_IDS);
+  if (allowedAgentIds.size === 0) {
+    return true;
+  }
+  if (!agentId) {
+    return false;
+  }
+  return allowedAgentIds.has(agentId);
+}
+
+/**
+ * Checks if an agent's tools have any that match PTC patterns (programmatic only or dual context).
+ * @param toolRegistry - The tool registry to check
+ * @returns Whether any tools are configured for programmatic calling
+ */
+export function agentHasProgrammaticTools(toolRegistry: LCToolRegistry): boolean {
+  for (const toolDef of toolRegistry.values()) {
+    if (toolDef.allowed_callers?.includes('code_execution')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Checks if an agent's tools have any that are deferred.
+ * @param toolRegistry - The tool registry to check
+ * @returns Whether any tools are configured as deferred
+ */
+export function agentHasDeferredTools(toolRegistry: LCToolRegistry): boolean {
+  for (const toolDef of toolRegistry.values()) {
+    if (toolDef.defer_loading === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Builds the tool registry from MCP tools and conditionally creates PTC and tool search tools.
+ *
+ * This function:
+ * 1. Checks if the agent is allowed for classification features (via TOOL_CLASSIFICATION_AGENT_IDS)
+ * 2. Filters loaded tools for MCP tools
+ * 3. Extracts tool definitions and builds the registry
+ *    - Uses agent's tool_options if provided (UI-based configuration)
+ *    - Falls back to env vars for tools not configured at agent level
+ * 4. Cleans up temporary mcpJsonSchema properties
+ * 5. Creates PTC tool only if agent has tools configured for programmatic calling
+ * 6. Creates tool search tool only if agent has deferred tools
+ *
+ * @param params - Parameters including loaded tools, userId, agentId, agentToolOptions, and dependencies
+ * @returns Tool registry and any additional tools created
+ */
+export async function buildToolClassification(
+  params: BuildToolClassificationParams,
+): Promise<BuildToolClassificationResult> {
+  const { loadedTools, userId, agentId, agentToolOptions, loadAuthValues } = params;
+  const additionalTools: GenericTool[] = [];
+
+  /** Check if this agent is allowed to have classification features (requires agentId) */
+  if (!isAgentAllowedForClassification(agentId)) {
+    logger.debug(
+      `[buildToolClassification] Agent ${agentId ?? 'undefined'} not allowed for classification, skipping`,
+    );
+    return { toolRegistry: undefined, additionalTools, hasDeferredTools: false };
+  }
+
+  const mcpTools = loadedTools.filter(isMCPTool);
+  if (mcpTools.length === 0) {
+    return { toolRegistry: undefined, additionalTools, hasDeferredTools: false };
+  }
+
+  const mcpToolDefs = mcpTools.map(extractMCPToolDefinition);
+
+  /**
+   * Build registry from agent's tool_options if provided (UI config).
+   * Environment variable-based classification is only used as fallback
+   * when TOOL_CLASSIFICATION_FROM_ENV=true is explicitly set.
+   */
+  let toolRegistry: LCToolRegistry | undefined;
+
+  if (agentToolOptions && Object.keys(agentToolOptions).length > 0) {
+    toolRegistry = buildToolRegistryFromAgentOptions(mcpToolDefs, agentToolOptions);
+  } else if (process.env.TOOL_CLASSIFICATION_FROM_ENV === 'true') {
+    toolRegistry = buildToolRegistryFromEnv(mcpToolDefs);
+  } else {
+    /** No agent-level config and env-based classification not enabled */
+    return { toolRegistry: undefined, additionalTools, hasDeferredTools: false };
+  }
+
+  /** Clean up temporary mcpJsonSchema property from tools now that registry is populated */
+  cleanupMCPToolSchemas(mcpTools);
+
+  /**
+   * Check if this agent actually has tools that match the patterns.
+   * Only enable PTC if the agent has programmatic tools.
+   * Only enable tool search if the agent has deferred tools.
+   */
+  const hasProgrammaticTools = agentHasProgrammaticTools(toolRegistry);
+  const hasDeferredTools = agentHasDeferredTools(toolRegistry);
+
+  if (!hasProgrammaticTools && !hasDeferredTools) {
+    logger.debug(
+      `[buildToolClassification] Agent ${agentId} has no programmatic or deferred tools, skipping PTC/ToolSearch`,
+    );
+    return { toolRegistry, additionalTools, hasDeferredTools: false };
+  }
+
+  /** Tool search uses local mode (no API key needed) */
+  if (hasDeferredTools) {
+    const toolSearchTool = createToolSearch({
+      mode: 'local',
+      toolRegistry,
+    });
+    additionalTools.push(toolSearchTool);
+    logger.debug(`[buildToolClassification] Tool Search enabled for agent ${agentId}`);
+  }
+
+  /** PTC requires CODE_API_KEY for sandbox execution */
+  if (hasProgrammaticTools) {
+    try {
+      const authValues = await loadAuthValues({
+        userId,
+        authFields: [EnvVar.CODE_API_KEY],
+      });
+      const codeApiKey = authValues[EnvVar.CODE_API_KEY];
+
+      if (!codeApiKey) {
+        logger.warn('[buildToolClassification] PTC configured but CODE_API_KEY not available');
+      } else {
+        const ptcTool = createProgrammaticToolCallingTool({ apiKey: codeApiKey });
+        additionalTools.push(ptcTool);
+        logger.debug(`[buildToolClassification] PTC tool enabled for agent ${agentId}`);
+      }
+    } catch (error) {
+      logger.error('[buildToolClassification] Error creating PTC tool:', error);
+    }
+  }
+
+  return { toolRegistry, additionalTools, hasDeferredTools };
+}

packages/api/src/tools/index.ts

@@ -1,2 +1,3 @@
 export * from './format';
 export * from './toolkits';
+export * from './classification';

packages/data-provider/src/config.ts

@@ -1750,6 +1750,8 @@ export enum Constants {
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
   /** Placeholder Agent ID for Ephemeral Agents */
   EPHEMERAL_AGENT_ID = 'ephemeral',
+  /** Programmatic Tool Calling tool name */
+  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
 }
 
 export enum LocalStorageKeys {

packages/data-provider/src/schemas.ts

@@ -225,6 +225,7 @@ export const defaultAgentFormValues = {
   model: '',
   model_parameters: {},
   tools: [],
+  tool_options: {},
   provider: {},
   projectIds: [],
   edges: [],

packages/data-provider/src/types/assistants.ts

@@ -206,6 +206,38 @@ export type SupportContact = {
   email?: string;
 };
 
+/**
+ * Specifies who can invoke a tool.
+ * - 'direct': LLM can call directly
+ * - 'code_execution': Only callable via programmatic tool calling (PTC)
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+
+/**
+ * Per-tool configuration options stored at the agent level.
+ * Keyed by tool_id (e.g., "search_mcp_github").
+ */
+export type ToolOptions = {
+  /**
+   * If true, the tool uses deferred loading (discoverable via tool search).
+   * @default false
+   */
+  defer_loading?: boolean;
+  /**
+   * Specifies who can invoke this tool.
+   * - 'direct': LLM can call directly (default behavior)
+   * - 'code_execution': Only callable via PTC sandbox
+   * @default ['direct']
+   */
+  allowed_callers?: AllowedCaller[];
+};
+
+/**
+ * Map of tool_id to its configuration options.
+ * Used to customize tool behavior per agent.
+ */
+export type AgentToolOptions = Record<string, ToolOptions>;
+
 export type Agent = {
   _id?: string;
   id: string;
@@ -241,6 +273,8 @@ export type Agent = {
   version?: number;
   category?: string;
   support_contact?: SupportContact;
+  /** Per-tool configuration options (deferred loading, allowed callers, etc.) */
+  tool_options?: AgentToolOptions;
 };
 
 export type TAgentsMap = Record<string, Agent | undefined>;
@@ -265,6 +299,7 @@ export type AgentCreateParams = {
   | 'recursion_limit'
   | 'category'
   | 'support_contact'
+  | 'tool_options'
 >;
 
 export type AgentUpdateParams = {
@@ -291,6 +326,7 @@ export type AgentUpdateParams = {
   | 'recursion_limit'
   | 'category'
   | 'support_contact'
+  | 'tool_options'
 >;
 
 export type AgentListParams = {

packages/data-schemas/src/schema/agent.ts

@@ -118,6 +118,11 @@ const agentSchema = new Schema<IAgent>(
       default: [],
       index: true,
     },
+    /** Per-tool configuration (defer_loading, allowed_callers) */
+    tool_options: {
+      type: Schema.Types.Mixed,
+      default: undefined,
+    },
   },
   {
     timestamps: true,

packages/data-schemas/src/types/agent.ts

@@ -1,5 +1,5 @@
 import { Document, Types } from 'mongoose';
-import type { GraphEdge } from 'librechat-data-provider';
+import type { GraphEdge, AgentToolOptions } from 'librechat-data-provider';
 
 export interface ISupportContact {
   name?: string;
@@ -42,4 +42,6 @@ export interface IAgent extends Omit<Document, 'model'> {
   is_promoted?: boolean;
   /** MCP server names extracted from tools for efficient querying */
   mcpServerNames?: string[];
+  /** Per-tool configuration (defer_loading, allowed_callers) */
+  tool_options?: AgentToolOptions;
 }