@juspay/neurolink 9.90.0 → 9.91.0

package/dist/lib/types/toolResolution.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool resolution types — the single tool-policy pipeline that decides which
+ * tools are sent to a provider for a given request.
+ *
+ * One policy object is resolved per request from (a) per-call legacy options
+ * (`toolFilter`, `excludeTools`, `enabledToolNames`, `disableTools`) and
+ * (b) the instance-level `tools` config, then applied at the single gate in
+ * `BaseProvider` that every generate/stream path passes through.
+ */
+import type { ToolConfig } from "./config.js";
+/**
+ * The resolved, merged tool policy for one request. Produced by
+ * `resolveToolPolicy()` (src/lib/tools/toolPolicy.ts) and consumed by
+ * `applyToolGate()` (src/lib/tools/toolGate.ts).
+ */
+export type ResolvedToolPolicy = {
+    /** false = no tools at all for this request (drops caller-supplied tools too). */
+    enabled: boolean;
+    /**
+     * Allowlist of tool-name patterns (exact names or `*` globs).
+     * `undefined` = all tools pass. An empty array means "no tools" — it can
+     * only come from the new `tools.include` config surface; legacy
+     * `toolFilter: []` is normalized to `undefined` (fail-open, preserving
+     * historical behavior) before it reaches here.
+     */
+    include?: string[];
+    /**
+     * Secondary allowlist clause ANDed with `include` — set when both a
+     * legacy per-call allowlist and the instance `tools.include` are present.
+     * Kept as a separate clause because two glob pattern lists cannot be
+     * losslessly pre-intersected into a single pattern array (a name must
+     * match BOTH lists to pass).
+     */
+    includeBound?: string[];
+    /** Denylist of tool-name patterns (exact names or `*` globs), applied after include. */
+    exclude: string[];
+    /** Defer external MCP tool schemas behind the search_tools meta-tool. */
+    discovery: boolean;
+    /** Which option/config sources contributed to this policy (telemetry/debugging). */
+    sources: string[];
+};
+/**
+ * Inputs to `resolveToolPolicy()`. Kept as a named type so the mapping is
+ * unit-testable as a pure function.
+ */
+export type ToolPolicyResolutionInput = {
+    /** Per-call options (the legacy per-call filtering surface). */
+    options: {
+        disableTools?: boolean;
+        toolFilter?: string[];
+        enabledToolNames?: string[];
+        excludeTools?: string[];
+    };
+    /** Instance-level `tools` config passed to the NeuroLink constructor. */
+    instanceConfig?: ToolConfig;
+    /**
+     * Names of the built-in (direct) tools of the calling provider — used to
+     * honor `tools.disableBuiltinTools` without this module importing the
+     * direct-tools registry.
+     */
+    builtinToolNames?: string[];
+};
+/**
+ * One entry in the deferred-tool catalog embedded in the `search_tools`
+ * meta-tool description when `tools.discovery` is enabled.
+ */
+export type DeferredToolIndexEntry = {
+    name: string;
+    /** One-line description (truncated) shown in the search_tools catalog. */
+    summary: string;
+    /** Originating MCP server id, when known. */
+    serverId?: string;
+};

package/dist/lib/types/toolResolution.js

@@ -0,0 +1,11 @@
+/**
+ * Tool resolution types — the single tool-policy pipeline that decides which
+ * tools are sent to a provider for a given request.
+ *
+ * One policy object is resolved per request from (a) per-call legacy options
+ * (`toolFilter`, `excludeTools`, `enabledToolNames`, `disableTools`) and
+ * (b) the instance-level `tools` config, then applied at the single gate in
+ * `BaseProvider` that every generate/stream path passes through.
+ */
+export {};
+//# sourceMappingURL=toolResolution.js.map

package/dist/mcp/toolRegistry.js

@@ -7,6 +7,7 @@ import { registryLogger } from "../utils/logger.js";
 import { randomUUID } from "crypto";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { directAgentTools } from "../agent/directTools.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
 import { ErrorFactory } from "../utils/errorHandling.js";
@@ -57,10 +58,14 @@ export class MCPToolRegistry extends MCPRegistry {
                 continue;
             }
             const toolId = `direct.${toolName}`;
+            // Register the tool's real parameter schema (converted from Zod) instead
+            // of a `{}` placeholder — token-budget accounting and tool listings read
+            // this ToolInfo, and an empty schema makes both under-count reality.
+            const inputSchema = convertZodToJsonSchema(toolDef.inputSchema);
             const toolInfo = {
                 name: toolName,
                 description: toolDef.description || `Direct tool: ${toolName}`,
-                inputSchema: {},
+                inputSchema,
                 serverId: "direct",
                 category: detectCategory({ isBuiltIn: true, serverId: "direct" }),
             };
@@ -98,7 +103,7 @@ export class MCPToolRegistry extends MCPRegistry {
                     }
                 },
                 description: toolDef.description,
-                inputSchema: {},
+                inputSchema,
             });
             registryLogger.debug(`Registered direct tool: ${toolName} as ${toolId}`);
         }

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,9 @@ export declare class NeuroLink {
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
     private toolDedupConfig?;
+    private toolsConfig?;
+    /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
+    private discoveryPins;
     private enableOrchestration;
     private authProvider?;
     private pendingAuthConfig?;
@@ -812,6 +815,11 @@ export declare class NeuroLink {
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a ToolInfo array.
      * Used to filter the tool list before building the system prompt.
+     *
+     * Resolves the SAME policy as the native gate (`BaseProvider`
+     * `applyToolFiltering`) — per-call options plus the instance-level `tools`
+     * config — so what the model is told about tools never diverges from the
+     * tools it can actually call.
      */
     private applyToolInfoFiltering;
     private createToolAwareSystemPrompt;
@@ -1194,6 +1202,28 @@ export declare class NeuroLink {
      * parameter through the full call stack.
      */
     getToolDedupConfig(): ToolDedupConfig | undefined;
+    /**
+     * Returns the instance-level `tools` config (master switch, include/exclude
+     * lists, discovery mode), or `undefined` when not provided at construction.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
+     * instance policy with per-call options on every generate/stream call.
+     */
+    getToolsConfig(): ToolConfig | undefined;
+    /**
+     * Tools discovered via `search_tools` for a session (`tools.discovery`
+     * mode). Pinned tools are sent in full on every subsequent call of that
+     * session instead of being deferred — discovery cost is paid once.
+     * Reading refreshes the session's recency (LRU), so active conversations
+     * are never the ones evicted at the session cap.
+     */
+    getDiscoveryPins(sessionKey: string): ReadonlySet<string>;
+    /**
+     * Pin discovered tools to a session (called by the `search_tools`
+     * meta-tool on hydration). Append-only within a session; the map is
+     * bounded by evicting the least-recently-used session past 1000 sessions.
+     */
+    pinDiscoveredTools(sessionKey: string, toolNames: string[]): void;
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *

package/dist/neurolink.js

@@ -83,7 +83,10 @@ import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
-import { isZodSchema } from "./utils/schemaConversion.js";
+import { isZodSchema, convertZodToJsonSchema, } from "./utils/schemaConversion.js";
+import { resolveToolPolicy } from "./tools/toolPolicy.js";
+import { applyToolGate } from "./tools/toolGate.js";
+import { directAgentTools } from "./agent/directTools.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Tool detection and execution imports
 // Transformation utilities
@@ -284,6 +287,30 @@ export function markStreamProviderEmittedGenerationEnd(options) {
  * survives minification AND doesn't rely on method-name stability.
  */
 export const NEUROLINK_BRAND = Symbol.for("@juspay/neurolink/sdk-brand");
+/**
+ * Providers whose native tool-calling support is model-dependent or absent —
+ * i.e. every provider that overrides `supportsTools()` and can return false
+ * (verified against src/lib/providers: ollama and openrouter are
+ * model-dependent; huggingface is deployment-dependent; the rest are
+ * image/embedding providers). Only these still receive the full tool listing
+ * in the system prompt on the generate path, where no provider instance
+ * exists yet to ask directly; every other provider gets tool definitions
+ * natively via its `tools` parameter, so repeating them in the prompt was
+ * pure token duplication. The stream path asks the provider instance
+ * (`provider.supportsTools()`) instead of this list. Keep in sync with
+ * `supportsTools()` overrides when adding providers.
+ */
+const PROMPT_ONLY_TOOL_PROVIDERS = new Set([
+    "ollama",
+    "huggingface",
+    "openrouter",
+    "ideogram",
+    "recraft",
+    "replicate",
+    "stability",
+    "jina",
+    "voyage",
+]);
 /**
  * Type-guard for opaque values that should be a {@link NeuroLink} instance.
  *
@@ -379,6 +406,9 @@ export class NeuroLink {
     toolRoutingVectorCache;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
+    toolsConfig;
+    /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
+    discoveryPins = new Map();
     // Add orchestration property
     enableOrchestration;
     // Authentication provider for secure access control
@@ -807,6 +837,11 @@ export class NeuroLink {
         if (config?.toolDedup) {
             this.toolDedupConfig = { ...config.toolDedup };
         }
+        if (config?.tools) {
+            // Shallow-clone so later caller mutations of the config object don't
+            // change this instance's tool policy mid-flight.
+            this.toolsConfig = { ...config.tools };
+        }
         // ModelPool: build one instance from config; null when not configured.
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
@@ -1108,10 +1143,15 @@ export class NeuroLink {
         // Use void to handle async registration without blocking constructor
         const registrations = Object.entries(fileTools).map(async ([toolName, toolDef]) => {
             const toolId = `direct.${toolName}`;
+            // Register the real parameter schema (converted from Zod) instead of a
+            // `{}` placeholder so tool listings and token-budget accounting see the
+            // schema that actually ships to providers.
+            const fileToolSchema = convertZodToJsonSchema((toolDef.inputSchema ??
+                toolDef.parameters));
             const toolInfo = {
                 name: toolName,
                 description: toolDef.description || `File tool: ${toolName}`,
-                inputSchema: {},
+                inputSchema: fileToolSchema,
                 serverId: "direct",
                 category: "built-in",
             };
@@ -5143,10 +5183,21 @@ Current user's request: ${currentInput}`;
         const circuitBreakerNote = unavailableTools.length > 0
             ? `\n\nNOTE: The following tools are temporarily unavailable due to repeated failures: ${unavailableTools.join(", ")}. Do not attempt to call these tools.`
             : "";
+        // Circuit-breaker-open tools are ENFORCED out of the native tool set via
+        // the per-call denylist — asking the model nicely (the note above) is
+        // informational, exclusion is the guarantee. Previously only the
+        // system-prompt listing was filtered; the native array still shipped them.
+        if (unavailableTools.length > 0) {
+            options.excludeTools = [
+                ...new Set([...(options.excludeTools ?? []), ...unavailableTools]),
+            ];
+        }
+        // Providers with native tool calling receive full definitions via their
+        // `tools` parameter; only prompt-based providers still get the listing.
+        const nativeToolSupport = !PROMPT_ONLY_TOOL_PROVIDERS.has(String(providerName).toLowerCase());
         const enhancedSystemPrompt = options.skipToolPromptInjection
             ? (options.systemPrompt || "") + circuitBreakerNote
-            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools) +
-                circuitBreakerNote;
+            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools, nativeToolSupport) + circuitBreakerNote;
         logger.debug("Tool-aware system prompt created", {
             requestId,
             originalPromptLength: options.systemPrompt?.length || 0,
@@ -5900,48 +5951,64 @@ Current user's request: ${currentInput}`;
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a ToolInfo array.
      * Used to filter the tool list before building the system prompt.
+     *
+     * Resolves the SAME policy as the native gate (`BaseProvider`
+     * `applyToolFiltering`) — per-call options plus the instance-level `tools`
+     * config — so what the model is told about tools never diverges from the
+     * tools it can actually call.
      */
     applyToolInfoFiltering(tools, options) {
-        // enabledToolNames is an additional whitelist — merged into toolFilter
-        const whitelist = [
-            ...(options.toolFilter ?? []),
-            ...(options.enabledToolNames ?? []),
-        ];
-        if (whitelist.length === 0 &&
-            (!options.excludeTools || options.excludeTools.length === 0)) {
-            return tools;
-        }
-        let filtered = tools;
-        if (whitelist.length > 0) {
-            const allowSet = new Set(whitelist);
-            filtered = filtered.filter((t) => allowSet.has(t.name));
-        }
-        if (options.excludeTools && options.excludeTools.length > 0) {
-            const denySet = new Set(options.excludeTools);
-            filtered = filtered.filter((t) => !denySet.has(t.name));
+        const policy = resolveToolPolicy({
+            options: {
+                disableTools: options.disableTools,
+                toolFilter: options.toolFilter,
+                enabledToolNames: options.enabledToolNames,
+                excludeTools: options.excludeTools,
+            },
+            instanceConfig: this.toolsConfig,
+            builtinToolNames: Object.keys(directAgentTools),
+        });
+        const record = {};
+        for (const tool of tools) {
+            if (!(tool.name in record)) {
+                record[tool.name] = tool;
+            }
         }
+        const gated = applyToolGate(record, policy);
+        const filtered = tools.filter((t) => t.name in gated);
         if (filtered.length !== tools.length) {
             logger.debug(`Tool info filtering applied for system prompt`, {
                 beforeCount: tools.length,
                 afterCount: filtered.length,
+                policySources: policy.sources,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
             });
         }
         return filtered;
     }
-    createToolAwareSystemPrompt(originalSystemPrompt, availableTools) {
+    createToolAwareSystemPrompt(originalSystemPrompt, availableTools, nativeToolSupport) {
         // AI prompt generation with tool analysis and structured logging
         const promptGenerationData = {
             originalPromptLength: originalSystemPrompt?.length || 0,
             availableToolsCount: availableTools.length,
             hasOriginalPrompt: !!originalSystemPrompt,
+            nativeToolSupport,
         };
         logger.debug("AI prompt generation with tool schemas", promptGenerationData);
         if (availableTools.length === 0) {
             logger.debug("No tools available - returning original prompt");
             return originalSystemPrompt || "";
         }
+        if (nativeToolSupport) {
+            // The provider receives full tool definitions natively via its `tools`
+            // parameter — repeating name/description/parameters here was pure
+            // duplication (~850 tokens on the default surface, tens of thousands
+            // with MCP servers attached). Keep only a short, static (cache-stable)
+            // damping line so models don't over-reach for tools.
+            return ((originalSystemPrompt || "") +
+                "\n\nTools are available via native tool calling. Use them only when they genuinely improve your response; for creative or conversational requests, respond naturally without tools.");
+        }
         const toolDescriptions = transformToolsToDescriptions(availableTools.map((t) => ({
             name: t.name,
             description: t.description ?? "",
@@ -7746,10 +7813,13 @@ Current user's request: ${currentInput}`;
         let availableTools = await this.getAllAvailableTools();
         // Apply per-call tool filtering for system prompt tool descriptions
         availableTools = this.applyToolInfoFiltering(availableTools, options);
-        // Skip tool prompt injection if skipToolPromptInjection is true
+        // Skip tool prompt injection if skipToolPromptInjection is true.
+        // For providers with native tool calling (instance truth via
+        // supportsTools()), the listing is skipped and only the short damping
+        // line is appended — full definitions ship natively via `tools`.
         const enhancedSystemPrompt = options.skipToolPromptInjection
             ? options.systemPrompt || ""
-            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
+            : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools, provider.supportsTools?.() ?? true);
         // Get conversation messages for context.
         // If the caller already supplied conversationMessages (e.g. proxy routes
         // forwarding a multi-turn Claude request), honour them — including an
@@ -8450,6 +8520,58 @@ Current user's request: ${currentInput}`;
     getToolDedupConfig() {
         return this.toolDedupConfig;
     }
+    /**
+     * Returns the instance-level `tools` config (master switch, include/exclude
+     * lists, discovery mode), or `undefined` when not provided at construction.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
+     * instance policy with per-call options on every generate/stream call.
+     */
+    getToolsConfig() {
+        return this.toolsConfig;
+    }
+    /**
+     * Tools discovered via `search_tools` for a session (`tools.discovery`
+     * mode). Pinned tools are sent in full on every subsequent call of that
+     * session instead of being deferred — discovery cost is paid once.
+     * Reading refreshes the session's recency (LRU), so active conversations
+     * are never the ones evicted at the session cap.
+     */
+    getDiscoveryPins(sessionKey) {
+        const pins = this.discoveryPins.get(sessionKey);
+        if (!pins) {
+            return new Set();
+        }
+        // Map iteration order is insertion order — re-inserting on access turns
+        // the eviction below into LRU rather than FIFO.
+        this.discoveryPins.delete(sessionKey);
+        this.discoveryPins.set(sessionKey, pins);
+        return pins;
+    }
+    /**
+     * Pin discovered tools to a session (called by the `search_tools`
+     * meta-tool on hydration). Append-only within a session; the map is
+     * bounded by evicting the least-recently-used session past 1000 sessions.
+     */
+    pinDiscoveredTools(sessionKey, toolNames) {
+        let pins = this.discoveryPins.get(sessionKey);
+        if (!pins) {
+            pins = new Set();
+        }
+        else {
+            this.discoveryPins.delete(sessionKey);
+        }
+        this.discoveryPins.set(sessionKey, pins);
+        for (const name of toolNames) {
+            pins.add(name);
+        }
+        if (this.discoveryPins.size > 1000) {
+            const oldest = this.discoveryPins.keys().next().value;
+            if (oldest !== undefined) {
+                this.discoveryPins.delete(oldest);
+            }
+        }
+    }
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *
@@ -9809,8 +9931,11 @@ Current user's request: ${currentInput}`;
                     }
                 }
             }
-            // Return canonical ToolInfo[]; defer presentation transforms to call sites
-            const tools = uniqueTools;
+            // Return canonical ToolInfo[]; defer presentation transforms to call sites.
+            // Name-sorted: external MCP discovery completes in parallel, so Map
+            // insertion order varies across restarts — downstream consumers (tool
+            // listings, prompt construction, budget accounting) need a stable order.
+            const tools = uniqueTools.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
             // Update the cache
             this.toolCache = {
                 tools,

package/dist/server/routes/agentRoutes.js

@@ -6,6 +6,27 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { ProviderFactory } from "../../factories/providerFactory.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Resolve `request.tools` (an array of tool NAMES shared by the execute and
+ * stream endpoints) into a `toolFilter` whitelist. The field was previously
+ * accepted and silently ignored, so entries are validated against registered
+ * names and the whole field fails open (undefined — keep all tools) when
+ * nothing matches: existing clients sending unknown names must not lose
+ * their tool set.
+ */
+async function resolveRequestToolFilter(ctx, requestedTools) {
+    if (!Array.isArray(requestedTools) || requestedTools.length === 0) {
+        return undefined;
+    }
+    const registered = new Set((await ctx.neurolink.getAllAvailableTools()).map((t) => t.name));
+    const known = requestedTools.filter((name) => typeof name === "string" && registered.has(name));
+    if (known.length > 0) {
+        return known;
+    }
+    logger.warn("[agentRoutes] Ignoring request.tools — no entries match registered tool names (legacy fail-open)", { requested: requestedTools });
+    return undefined;
+}
 import { createStreamRedactor } from "../utils/redaction.js";
 import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, SkillCreateRequestSchema, SkillUpdateRequestSchema, validateRequest, } from "../utils/validation.js";
 /**
@@ -65,6 +86,7 @@ export function createAgentRoutes(basePath = "/api") {
                         const input = typeof request.input === "string"
                             ? { text: request.input }
                             : request.input;
+                        const requestToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                         const result = await ctx.neurolink.generate({
                             input,
                             provider: request.provider,
@@ -72,8 +94,7 @@ export function createAgentRoutes(basePath = "/api") {
                             systemPrompt: request.systemPrompt,
                             temperature: request.temperature,
                             maxTokens: request.maxTokens,
-                            // Note: tools should be passed as Record<string, Tool> in generate options
-                            // If request.tools is an array of tool names, we skip them
+                            ...(requestToolFilter ? { toolFilter: requestToolFilter } : {}),
                             context: {
                                 // When an authenticated user context exists (set by auth middleware),
                                 // always use its IDs to prevent caller-supplied impersonation.
@@ -118,6 +139,7 @@ export function createAgentRoutes(basePath = "/api") {
                     const input = typeof request.input === "string"
                         ? { text: request.input }
                         : request.input;
+                    const streamToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                     const result = await ctx.neurolink.stream({
                         input,
                         provider: request.provider,
@@ -125,6 +147,7 @@ export function createAgentRoutes(basePath = "/api") {
                         systemPrompt: request.systemPrompt,
                         temperature: request.temperature,
                         maxTokens: request.maxTokens,
+                        ...(streamToolFilter ? { toolFilter: streamToolFilter } : {}),
                         context: {
                             // When an authenticated user context exists (set by auth middleware),
                             // always use its IDs to prevent caller-supplied impersonation.

package/dist/tools/toolDiscovery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * On-demand tool discovery (`tools.discovery: true`).
+ *
+ * Instead of sending every external MCP tool's full schema on every request,
+ * the model receives the hot set (built-in tools, per-call tools, explicitly
+ * requested tools, and previously discovered tools) plus ONE `search_tools`
+ * meta-tool whose description embeds a compact name+summary catalog of the
+ * deferred tools. Calling `search_tools` loads matching tools:
+ *  - immediately into the live tool record (providers that re-read the tools
+ *    record between agent-loop steps — the AI SDK path — can call them on the
+ *    very next step), and
+ *  - into the session pin set (all providers include them in full on every
+ *    subsequent call of the session).
+ *
+ * Evidence for this design: catalogs past ~30-50 tools measurably degrade
+ * tool-selection accuracy, and deferral+search both cuts definition tokens by
+ * ~85% and RAISES selection accuracy (Anthropic MCP-eval 49%→74% on Opus 4).
+ * The catalog construction (byte-stable, name-sorted, char-budgeted with a
+ * degradation ladder) mirrors the proven skills-index pattern in
+ * src/lib/skills/skillTools.ts.
+ */
+import type { Tool } from "../types/index.js";
+/**
+ * Above this many tools, a WARN suggests enabling `tools.discovery` when it
+ * is off. Chosen from the measured degradation range (30-50 tools).
+ */
+export declare const LARGE_CATALOG_WARN_THRESHOLD = 40;
+/** True when the value is a search_tools meta-tool generated by this module. */
+export declare function isDiscoveryMetaTool(tool: unknown): boolean;
+/**
+ * Partition a (post-gate) tools record for discovery: deferrable tools that
+ * are not pinned are removed from the record and replaced by one
+ * `search_tools` meta-tool. Returns the hot record; when nothing is
+ * deferrable the input record is returned unchanged.
+ *
+ * The returned record is mutated by search_tools on hydration (call-scoped —
+ * BaseProvider builds a fresh merged record per call), which is what makes
+ * discovered tools callable on subsequent steps of the same agent loop on
+ * providers that re-read the record between steps.
+ */
+export declare function partitionToolsForDiscovery(tools: Record<string, Tool>, args: {
+    /** External-tool names present in `tools` that are allowed to defer. */
+    deferrableNames: string[];
+    /** Session-pinned names (previously discovered) — never deferred. */
+    pinnedNames: ReadonlySet<string>;
+    /** Called with newly discovered names — persists session pins. */
+    onHydrate: (names: string[]) => void;
+}): Record<string, Tool>;