@juspay/neurolink 9.74.0 → 9.76.0

package/dist/lib/core/toolDedup.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool-signature deduplication — pure module, no I/O, no side effects.
+ *
+ * ## Algorithm
+ *
+ * `computeToolSignature` builds a canonical, order-insensitive string from:
+ *   1. The tool's name (exact, case-preserved).
+ *   2. A normalised description: lowercased, all whitespace runs collapsed to a
+ *      single space, leading/trailing whitespace stripped.
+ *   3. A sorted, deduplicated list of JSON-schema property names (top-level
+ *      `properties` keys from `inputSchema`).  If the schema exposes a `type`
+ *      field on each property, that type string is appended as `name:type`.
+ *
+ * `dedupeTools` clusters tools by pairwise token-set Jaccard similarity:
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * where A and B are the _sets_ of whitespace-split tokens from each tool's
+ * canonical signature.  This is deterministic, symmetric, and independent of
+ * token ordering — making it robust to minor rewording while being fast (O(n²)
+ * in the number of tools, which is bounded in practice by provider limits).
+ *
+ * The first tool encountered in stable input-iteration order becomes the
+ * cluster representative; subsequent tools in the same cluster are dropped.
+ */
+import type { Tool } from "../types/index.js";
+import type { ToolDedupConfig, ToolDedupResult } from "../types/index.js";
+/**
+ * Build a canonical, order-insensitive signature string for a named tool.
+ *
+ * The signature is composed of:
+ *   - the tool's name
+ *   - a normalised description (lowercased, whitespace-collapsed)
+ *   - sorted parameter property names (with types when available)
+ *
+ * Stable regardless of property declaration order in the schema.
+ */
+export declare function computeToolSignature(name: string, tool: Tool): string;
+/**
+ * Collapse near-duplicate tools in a name→Tool record.
+ *
+ * When `options.enabled` is falsy (the default), returns the original record
+ * and an empty `removed` array — byte-for-byte unchanged behaviour.
+ *
+ * When enabled, tools whose token-set Jaccard similarity (over their canonical
+ * signatures) meets or exceeds `options.threshold` (default 0.9) are collapsed
+ * to a single representative (the first in stable iteration order).
+ *
+ * Any exception thrown internally returns the ORIGINAL tool set (fail-open).
+ */
+export declare function dedupeTools<T extends Tool>(tools: Record<string, T>, options: ToolDedupConfig): ToolDedupResult<Record<string, T>>;

package/dist/lib/core/toolDedup.js

@@ -0,0 +1,194 @@
+/**
+ * Tool-signature deduplication — pure module, no I/O, no side effects.
+ *
+ * ## Algorithm
+ *
+ * `computeToolSignature` builds a canonical, order-insensitive string from:
+ *   1. The tool's name (exact, case-preserved).
+ *   2. A normalised description: lowercased, all whitespace runs collapsed to a
+ *      single space, leading/trailing whitespace stripped.
+ *   3. A sorted, deduplicated list of JSON-schema property names (top-level
+ *      `properties` keys from `inputSchema`).  If the schema exposes a `type`
+ *      field on each property, that type string is appended as `name:type`.
+ *
+ * `dedupeTools` clusters tools by pairwise token-set Jaccard similarity:
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * where A and B are the _sets_ of whitespace-split tokens from each tool's
+ * canonical signature.  This is deterministic, symmetric, and independent of
+ * token ordering — making it robust to minor rewording while being fast (O(n²)
+ * in the number of tools, which is bounded in practice by provider limits).
+ *
+ * The first tool encountered in stable input-iteration order becomes the
+ * cluster representative; subsequent tools in the same cluster are dropped.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract top-level property names (and optionally their types) from a JSON
+ * Schema-shaped `inputSchema`.  Returns a sorted, stable list.
+ *
+ * The `inputSchema` on a `Tool` is typed as `FlexibleSchema<INPUT>` (opaque at
+ * runtime), so we access it via index to avoid casting.
+ */
+function extractSchemaTokens(inputSchema) {
+    if (!inputSchema) {
+        return [];
+    }
+    // FlexibleSchema may be a Zod schema, a jsonSchema() wrapper, or a plain
+    // JSON Schema object.  All three expose `jsonSchema` or fall through to the
+    // raw object.  We look for the plain JSON Schema `properties` key.
+    const schema = inputSchema;
+    // Vercel AI SDK wraps plain schemas in { jsonSchema: {...}, ... }
+    const rawSchema = schema["jsonSchema"] !== undefined
+        ? schema["jsonSchema"]
+        : schema;
+    const properties = rawSchema["properties"];
+    if (!properties || typeof properties !== "object" || properties === null) {
+        return [];
+    }
+    const tokens = [];
+    const props = properties;
+    for (const propName of Object.keys(props)) {
+        const propDef = props[propName];
+        if (propDef && typeof propDef === "object" && propDef !== null) {
+            const t = propDef["type"];
+            tokens.push(typeof t === "string" ? `${propName}:${t}` : propName);
+        }
+        else {
+            tokens.push(propName);
+        }
+    }
+    return tokens.sort();
+}
+/**
+ * Normalise a description string: lowercase, collapse whitespace, strip ends.
+ */
+function normaliseDescription(desc) {
+    if (!desc) {
+        return "";
+    }
+    return desc.toLowerCase().replace(/\s+/g, " ").trim();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a canonical, order-insensitive signature string for a named tool.
+ *
+ * The signature is composed of:
+ *   - the tool's name
+ *   - a normalised description (lowercased, whitespace-collapsed)
+ *   - sorted parameter property names (with types when available)
+ *
+ * Stable regardless of property declaration order in the schema.
+ */
+export function computeToolSignature(name, tool) {
+    const descPart = normaliseDescription(tool.description);
+    const schemaParts = extractSchemaTokens(tool.inputSchema);
+    // Pipe-separated sections keep tokens within each section unambiguous.
+    return [name, descPart, schemaParts.join(",")].join("|");
+}
+/**
+ * Compute the token-set Jaccard similarity between two signature strings.
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * Splits on whitespace and also on the pipe/comma delimiters used by
+ * `computeToolSignature` so that structural differences (e.g. a parameter
+ * missing from one tool) are properly reflected.
+ */
+function jaccardSimilarity(sigA, sigB) {
+    const tokenise = (s) => new Set(s.split(/[\s|,]+/).filter((t) => t.length > 0));
+    const setA = tokenise(sigA);
+    const setB = tokenise(sigB);
+    if (setA.size === 0 && setB.size === 0) {
+        return 1;
+    }
+    if (setA.size === 0 || setB.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of setA) {
+        if (setB.has(token)) {
+            intersection += 1;
+        }
+    }
+    const union = setA.size + setB.size - intersection;
+    return intersection / union;
+}
+/**
+ * Collapse near-duplicate tools in a name→Tool record.
+ *
+ * When `options.enabled` is falsy (the default), returns the original record
+ * and an empty `removed` array — byte-for-byte unchanged behaviour.
+ *
+ * When enabled, tools whose token-set Jaccard similarity (over their canonical
+ * signatures) meets or exceeds `options.threshold` (default 0.9) are collapsed
+ * to a single representative (the first in stable iteration order).
+ *
+ * Any exception thrown internally returns the ORIGINAL tool set (fail-open).
+ */
+export function dedupeTools(tools, options) {
+    const noOp = { tools, removed: [] };
+    if (!options.enabled) {
+        return noOp;
+    }
+    try {
+        const rawThreshold = options.threshold ?? 0.9;
+        const threshold = Math.min(1, Math.max(0, rawThreshold));
+        const entries = Object.entries(tools);
+        if (entries.length <= 1) {
+            return noOp;
+        }
+        // Pre-compute signatures once.
+        const signatures = new Map();
+        for (const [name, tool] of entries) {
+            signatures.set(name, computeToolSignature(name, tool));
+        }
+        // representative[toolName] = name of the cluster representative.
+        // Tools not yet assigned to a cluster act as their own representative.
+        const representativeOf = new Map();
+        for (const [nameA] of entries) {
+            if (representativeOf.has(nameA)) {
+                // Already absorbed into another cluster.
+                continue;
+            }
+            const sigA = signatures.get(nameA) ?? "";
+            for (const [nameB] of entries) {
+                if (nameA === nameB || representativeOf.has(nameB)) {
+                    continue;
+                }
+                const sigB = signatures.get(nameB) ?? "";
+                const sim = jaccardSimilarity(sigA, sigB);
+                if (sim >= threshold) {
+                    representativeOf.set(nameB, nameA);
+                }
+            }
+        }
+        if (representativeOf.size === 0) {
+            return noOp;
+        }
+        const dedupedTools = {};
+        const removed = [];
+        for (const [name, tool] of entries) {
+            const rep = representativeOf.get(name);
+            if (rep !== undefined) {
+                // Compute similarity again to include in the removed record.
+                const sim = jaccardSimilarity(signatures.get(name) ?? "", signatures.get(rep) ?? "");
+                removed.push({ name, duplicateOf: rep, similarity: sim });
+            }
+            else {
+                dedupedTools[name] = tool;
+            }
+        }
+        return { tools: dedupedTools, removed };
+    }
+    catch {
+        // Fail open — return the original set.
+        return noOp;
+    }
+}
+//# sourceMappingURL=toolDedup.js.map

package/dist/lib/index.d.ts

@@ -214,6 +214,7 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
  * ```
  */
 export { CircuitBreakerManager, calculateExpiresAt, createMCPServer, createOAuthProviderFromConfig, DEFAULT_HTTP_RETRY_CONFIG, DEFAULT_RATE_LIMIT_CONFIG, executeMCP, FileTokenStorage, getMCPStats, getServerInfo, globalCircuitBreakerManager, globalRateLimiterManager, HTTPRateLimiter, InMemoryTokenStorage, initializeMCPEcosystem, isRetryableHTTPError, isRetryableStatusCode, isTokenExpired, listMCPs, CircuitBreakerOpenError, MCPCircuitBreaker, mcpLogger, NeuroLinkOAuthProvider, RateLimiterManager, validateServerTools, validateTool as validateMCPTool, withHTTPRetry, MCPToolRegistry, ExternalServerManager, MCPClientFactory, ToolRouter, createToolRouter, DEFAULT_ROUTER_CONFIG, ToolCache, createToolCache, DEFAULT_CACHE_CONFIG, ToolResultCache, createToolResultCache, RequestBatcher, ToolCallBatcher, createRequestBatcher, createToolCallBatcher, DEFAULT_BATCH_CONFIG, inferAnnotations, createAnnotatedTool, validateAnnotations, filterToolsByAnnotations, mergeAnnotations, getAnnotationSummary, requiresConfirmation, isSafeToRetry, getToolSafetyLevel, ElicitationManager, globalElicitationManager, EnhancedToolDiscovery, MCPRegistryClient, globalMCPRegistryClient, getWellKnownServer, getAllWellKnownServers, MCPServerBase, MultiServerManager, globalMultiServerManager, AgentExposureManager, exposeAgentAsTool, exposeAgentsAsTools, exposeWorkflowAsTool, exposeWorkflowsAsTools, globalAgentExposureManager, ServerCapabilitiesManager, createTextResource, createJsonResource, createPrompt, neuroLinkToolToMCP, mcpToolToNeuroLink, batchConvertToMCP, batchConvertToNeuroLink, sanitizeToolName, validateToolName, createToolFromFunction, mcpProtocolToolToServerTool, serverToolToMCPProtocol, TOOL_COMPATIBILITY, ToolIntegrationManager, globalToolIntegrationManager, wrapToolWithElicitation, wrapToolsWithElicitation, createElicitationContext, confirmationMiddleware, validationMiddleware, loggingMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolMiddlewareChain, ElicitationProtocolAdapter, globalElicitationProtocol, isElicitationProtocolMessage, protocolMessageToElicitation, elicitationResponseToProtocol, createElicitationRequest, createElicitationResponse, createElicitationCancel, createTextInputRequest, createSelectRequest, createConfirmationRequest, createFormRequest, } from "./mcp/index.js";
+export { computeToolSignature, dedupeTools } from "./core/toolDedup.js";
 export { logger } from "./utils/logger.js";
 export { getPoolStats } from "./utils/redis.js";
 export { ToolRoutingCache } from "./core/toolRoutingCache.js";

package/dist/lib/index.js

@@ -354,6 +354,8 @@ neuroLinkToolToMCP, mcpToolToNeuroLink, batchConvertToMCP, batchConvertToNeuroLi
 ToolIntegrationManager, globalToolIntegrationManager, wrapToolWithElicitation, wrapToolsWithElicitation, createElicitationContext, confirmationMiddleware, validationMiddleware, loggingMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolMiddlewareChain, 
 // MCP Enhancements - Elicitation Protocol
 ElicitationProtocolAdapter, globalElicitationProtocol, isElicitationProtocolMessage, protocolMessageToElicitation, elicitationResponseToProtocol, createElicitationRequest, createElicitationResponse, createElicitationCancel, createTextInputRequest, createSelectRequest, createConfirmationRequest, createFormRequest, } from "./mcp/index.js";
+// Tool signature deduplication utilities (opt-in, fail-open)
+export { computeToolSignature, dedupeTools } from "./core/toolDedup.js";
 export { logger } from "./utils/logger.js";
 export { getPoolStats } from "./utils/redis.js";
 // Pre-call tool routing cache (ITEM C: LRU+TTL cache + session stickiness)

package/dist/lib/neurolink.d.ts

@@ -5,7 +5,7 @@
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
-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 } 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 { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -102,6 +102,7 @@ export declare class NeuroLink {
     private conversationMemoryConfig?;
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
+    private toolDedupConfig?;
     private enableOrchestration;
     private authProvider?;
     private pendingAuthConfig?;
@@ -1089,6 +1090,19 @@ export declare class NeuroLink {
      * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): TypedEventEmitter<NeuroLinkEvents>;
+    /**
+     * Returns the instance-level tool-dedup configuration, or `undefined` when
+     * toolDedup was not provided at construction time.
+     *
+     * The stored object is returned as-is whenever `toolDedup` was supplied,
+     * including when `enabled: false` — only the complete absence of a `toolDedup`
+     * option results in `undefined`.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the dedup pass uses the
+     * same config for every generate/stream call without threading an extra
+     * parameter through the full call stack.
+     */
+    getToolDedupConfig(): ToolDedupConfig | undefined;
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *

package/dist/lib/neurolink.js

@@ -445,6 +445,8 @@ export class NeuroLink {
     // Lazy-initialized routing decision cache (ITEM C). Created on first use so
     // instances that don't use routing pay no overhead.
     toolRoutingCacheInstance;
+    // Opt-in tool-signature deduplication config.
+    toolDedupConfig;
     // Add orchestration property
     enableOrchestration;
     // Authentication provider for secure access control
@@ -857,6 +859,9 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        if (config?.toolDedup) {
+            this.toolDedupConfig = { ...config.toolDedup };
+        }
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -7513,6 +7518,21 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Returns the instance-level tool-dedup configuration, or `undefined` when
+     * toolDedup was not provided at construction time.
+     *
+     * The stored object is returned as-is whenever `toolDedup` was supplied,
+     * including when `enabled: false` — only the complete absence of a `toolDedup`
+     * option results in `undefined`.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the dedup pass uses the
+     * same config for every generate/stream call without threading an extra
+     * parameter through the full call stack.
+     */
+    getToolDedupConfig() {
+        return this.toolDedupConfig;
+    }
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *

package/dist/lib/session/globalSessionState.d.ts

@@ -1,8 +1,10 @@
 import { NeuroLink } from "../neurolink.js";
-import type { ConversationMemoryConfig, LoopSessionState, SessionVariableValue } from "../types/index.js";
+import type { ConversationMemoryConfig, LoopSessionState, SessionVariableValue, ToolRoutingConfig } from "../types/index.js";
 export declare class GlobalSessionManager {
     private static instance;
     private loopSession;
+    /** Optional tool-routing config set by CLI handlers before SDK construction. */
+    private _toolRoutingConfig;
     static getInstance(): GlobalSessionManager;
     setLoopSession(config?: ConversationMemoryConfig): string;
     /**
@@ -33,6 +35,13 @@ export declare class GlobalSessionManager {
     updateSessionId(newSessionId: string): void;
     getLoopSession(): LoopSessionState | null;
     clearLoopSession(): void;
+    /**
+     * Store a tool-routing config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setToolRoutingConfig(config: ToolRoutingConfig): void;
     getOrCreateNeuroLink(): NeuroLink;
     getCurrentSessionId(): string | undefined;
     setSessionVariable(key: string, value: SessionVariableValue): void;

package/dist/lib/session/globalSessionState.js

@@ -31,6 +31,8 @@ function buildMcpOutputLimitsFromEnv() {
 export class GlobalSessionManager {
     static instance;
     loopSession = null;
+    /** Optional tool-routing config set by CLI handlers before SDK construction. */
+    _toolRoutingConfig = undefined;
     static getInstance() {
         if (!GlobalSessionManager.instance) {
             GlobalSessionManager.instance = new GlobalSessionManager();
@@ -127,6 +129,18 @@ export class GlobalSessionManager {
             this.loopSession = null;
         }
     }
+    /**
+     * Store a tool-routing config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setToolRoutingConfig(config) {
+        if (this.hasActiveSession()) {
+            return;
+        }
+        this._toolRoutingConfig = config;
+    }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
         if (session) {
@@ -142,6 +156,10 @@ export class GlobalSessionManager {
         if (mcpOutputLimits) {
             options.mcp = { outputLimits: mcpOutputLimits };
         }
+        if (this._toolRoutingConfig) {
+            options.toolRouting = this._toolRoutingConfig;
+            this._toolRoutingConfig = undefined;
+        }
         return new NeuroLink(Object.keys(options).length ? options : undefined);
     }
     getCurrentSessionId() {

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

@@ -45,7 +45,7 @@ export type BaseCommandArgs = {
 /**
  * Generate command arguments
  */
-export type GenerateCommandArgs = BaseCommandArgs & {
+export type GenerateCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
     /** Input text or prompt */
     input?: string;
     /** AI provider to use */
@@ -110,7 +110,7 @@ export type GenerateCommandArgs = BaseCommandArgs & {
 /**
  * Stream command arguments
  */
-export type StreamCommandArgs = BaseCommandArgs & {
+export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
     /** Input text or prompt */
     input?: string;
     /** AI provider to use */
@@ -137,7 +137,7 @@ export type StreamCommandArgs = BaseCommandArgs & {
 /**
  * Batch command arguments
  */
-export type BatchCommandArgs = BaseCommandArgs & {
+export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
     /** Input file path */
     file?: string;
     /** AI provider to use */
@@ -1500,3 +1500,29 @@ export type CliServeFlatRoute = {
     description?: string;
     group: string;
 };
+/**
+ * Raw CLI flag shape for the tool-routing family of options.
+ * Keys are camelCase as yargs delivers them after parsing kebab-case aliases.
+ */
+export type CliToolRoutingFlags = {
+    /** Master enable switch (--tool-routing). */
+    toolRouting?: boolean;
+    /** Router LLM hard timeout in ms (--tool-routing-timeout). */
+    toolRoutingTimeout?: number;
+    /** Router LLM provider override (--tool-routing-router-provider). */
+    toolRoutingRouterProvider?: string;
+    /** Router LLM model override (--tool-routing-router-model). */
+    toolRoutingRouterModel?: string;
+    /** Router LLM region override (--tool-routing-router-region). */
+    toolRoutingRouterRegion?: string;
+    /**
+     * Server ids that are always kept and never offered to the router
+     * (--tool-routing-always-include, repeatable).
+     */
+    toolRoutingAlwaysInclude?: string[];
+    /**
+     * Path to a JSON file OR inline JSON array of server descriptors
+     * (--tool-routing-servers).
+     */
+    toolRoutingServers?: string;
+};

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

@@ -9,7 +9,6 @@ import type { ConversationMemoryConfig } from "./conversation.js";
 import type { ObservabilityConfig } from "./observability.js";
 import type { AuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, BetterAuthConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, AuthenticatedContext } from "./auth.js";
 import type { NeurolinkCredentials } from "./providers.js";
-import type { ToolRoutingConfig } from "./toolRouting.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -74,6 +73,19 @@ export type NeurolinkConstructorConfig = {
      * any router failure. See {@link ToolRoutingConfig}.
      */
     toolRouting?: ToolRoutingConfig;
+    /**
+     * Opt-in tool-signature deduplication.  When enabled, tools whose
+     * canonical signatures are sufficiently similar (Jaccard ≥ threshold) are
+     * collapsed to a single representative before being sent to the model,
+     * reducing token cost and model confusion caused by near-identical tools.
+     *
+     * Disabled by default — enabling this changes nothing unless you
+     * explicitly set `enabled: true`.  Always fails open: any error in the
+     * dedup pass returns the original tool set unchanged.
+     *
+     * See {@link ToolDedupConfig}.
+     */
+    toolDedup?: ToolDedupConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.
@@ -338,7 +350,7 @@ export type ConfigUpdateOptions = {
  */
 export declare const DEFAULT_CONFIG: NeuroLinkConfig;
 import { TOOL_TIMEOUTS, BACKOFF_CONFIG, PERFORMANCE_PROFILES, PROVIDER_OPERATION_CONFIGS, MCP_OPERATION_CONFIGS } from "../constants/index.js";
-import type { ToolMiddleware, CacheStrategy, RoutingStrategy } from "./index.js";
+import type { ToolMiddleware, CacheStrategy, RoutingStrategy, ToolDedupConfig, ToolRoutingConfig } from "./index.js";
 import type { ModelAliasConfig } from "./generate.js";
 /** Timeout category keys from TOOL_TIMEOUTS. */
 export type TimeoutCategory = keyof typeof TOOL_TIMEOUTS;

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

@@ -50,6 +50,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolDedup.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";

package/dist/lib/types/index.js

@@ -51,6 +51,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolDedup.js";
 export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";

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

@@ -0,0 +1,45 @@
+/**
+ * Tool signature deduplication types.
+ *
+ * When many MCP servers are registered, it is common for tools from different
+ * servers to be functionally identical — same purpose, same parameters, only a
+ * slightly different name or description phrasing.  Sending all of them to the
+ * model wastes tokens and can confuse the model into picking the wrong variant.
+ *
+ * The dedup pass is OPT-IN and FAIL-OPEN.  When disabled (the default) the
+ * tool set is returned byte-for-byte unchanged.  Any error in the dedup logic
+ * also returns the original tool set.
+ */
+/** Configuration for the opt-in tool-signature deduplication pass. */
+export type ToolDedupConfig = {
+    /**
+     * Master switch.  Dedup runs only when `true`.
+     * Default: `false` (disabled — no change in behaviour).
+     */
+    enabled?: boolean;
+    /**
+     * Jaccard similarity threshold in [0, 1].  Pairs of tools whose token-set
+     * Jaccard similarity over their canonical signatures meets or exceeds this
+     * value are treated as near-duplicates; only one representative per cluster
+     * (the first in stable input order) is forwarded to the model.
+     *
+     * Default: `0.9`
+     */
+    threshold?: number;
+};
+/** Record produced for each tool collapsed by the dedup pass. */
+export type ToolDedupRemoved = {
+    /** Name of the tool that was collapsed. */
+    name: string;
+    /** Name of the representative tool that this one was collapsed into. */
+    duplicateOf: string;
+    /** Similarity score that triggered the collapse (in [0, 1]). */
+    similarity: number;
+};
+/** Return type of `dedupeTools()`. */
+export type ToolDedupResult<T extends Record<string, unknown>> = {
+    /** Deduplicated tool set (or original set when dedup is disabled/errored). */
+    tools: T;
+    /** Tools that were removed along with the reason. Empty when dedup is off. */
+    removed: ToolDedupRemoved[];
+};

package/dist/lib/types/toolDedup.js

@@ -0,0 +1,14 @@
+/**
+ * Tool signature deduplication types.
+ *
+ * When many MCP servers are registered, it is common for tools from different
+ * servers to be functionally identical — same purpose, same parameters, only a
+ * slightly different name or description phrasing.  Sending all of them to the
+ * model wastes tokens and can confuse the model into picking the wrong variant.
+ *
+ * The dedup pass is OPT-IN and FAIL-OPEN.  When disabled (the default) the
+ * tool set is returned byte-for-byte unchanged.  Any error in the dedup logic
+ * also returns the original tool set.
+ */
+export {};
+//# sourceMappingURL=toolDedup.js.map

package/dist/neurolink.d.ts

@@ -5,7 +5,7 @@
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
-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 } 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 { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -102,6 +102,7 @@ export declare class NeuroLink {
     private conversationMemoryConfig?;
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
+    private toolDedupConfig?;
     private enableOrchestration;
     private authProvider?;
     private pendingAuthConfig?;
@@ -1089,6 +1090,19 @@ export declare class NeuroLink {
      * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): TypedEventEmitter<NeuroLinkEvents>;
+    /**
+     * Returns the instance-level tool-dedup configuration, or `undefined` when
+     * toolDedup was not provided at construction time.
+     *
+     * The stored object is returned as-is whenever `toolDedup` was supplied,
+     * including when `enabled: false` — only the complete absence of a `toolDedup`
+     * option results in `undefined`.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the dedup pass uses the
+     * same config for every generate/stream call without threading an extra
+     * parameter through the full call stack.
+     */
+    getToolDedupConfig(): ToolDedupConfig | undefined;
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *

package/dist/neurolink.js

@@ -445,6 +445,8 @@ export class NeuroLink {
     // Lazy-initialized routing decision cache (ITEM C). Created on first use so
     // instances that don't use routing pay no overhead.
     toolRoutingCacheInstance;
+    // Opt-in tool-signature deduplication config.
+    toolDedupConfig;
     // Add orchestration property
     enableOrchestration;
     // Authentication provider for secure access control
@@ -857,6 +859,9 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        if (config?.toolDedup) {
+            this.toolDedupConfig = { ...config.toolDedup };
+        }
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -7513,6 +7518,21 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Returns the instance-level tool-dedup configuration, or `undefined` when
+     * toolDedup was not provided at construction time.
+     *
+     * The stored object is returned as-is whenever `toolDedup` was supplied,
+     * including when `enabled: false` — only the complete absence of a `toolDedup`
+     * option results in `undefined`.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the dedup pass uses the
+     * same config for every generate/stream call without threading an extra
+     * parameter through the full call stack.
+     */
+    getToolDedupConfig() {
+        return this.toolDedupConfig;
+    }
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *