fix: address critical Tool Search issues

- Fix unconditional bridge tool hijacking that broke user tools when disabled
- Resolve duplicate ToolSearchConfig classes by consolidating to tools module
- Add missing resolve_tool_search resolver function
- Fix hot path performance issues in BM25 scoring
- Add input validation for tool_call bridge args
- Fix cache metadata mismatches in chat_mixin
- Remove unnecessary f-string prefixes
- Strip __praisonai_deferrable__ from provider payloads
- Preserve tool_search config in clone_for_channel
- Improve type validation in agent constructor
- Fix overly broad MCP name heuristic

Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

Author: praisonai-triage-agent[bot]

src/praisonai-agents/praisonaiagents/__init__.py

@@ -384,6 +384,7 @@ def _get_lazy_cache():
     'MultiAgentExecutionConfig': ('praisonaiagents.config.feature_configs', 'MultiAgentExecutionConfig'),
     'MultiAgentPlanningConfig': ('praisonaiagents.config.feature_configs', 'MultiAgentPlanningConfig'),
     'MultiAgentMemoryConfig': ('praisonaiagents.config.feature_configs', 'MultiAgentMemoryConfig'),
+    'ToolSearchConfig': ('praisonaiagents.config.feature_configs', 'ToolSearchConfig'),
 
     # Parameter resolver
     'resolve': ('praisonaiagents.config.param_resolver', 'resolve'),

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -1458,8 +1458,14 @@ def __init__(
             from ..tools.tool_search import ToolSearchConfig as _ToolSearchConfig
             self._tool_search_config = _ToolSearchConfig(**tool_search)
         else:
-            # Assume ToolSearchConfig instance or similar
-            self._tool_search_config = tool_search
+            from ..tools.tool_search import ToolSearchConfig as _ToolSearchConfig
+            if isinstance(tool_search, _ToolSearchConfig):
+                self._tool_search_config = tool_search
+            else:
+                raise TypeError(
+                    "tool_search must be False/None, True, a mode string, "
+                    "a dict of ToolSearchConfig fields, or ToolSearchConfig"
+                )
 
         # ============================================================
         # END CONSOLIDATED PARAMS EXTRACTION
@@ -2057,6 +2063,7 @@ def clone_for_channel(self) -> "Agent":
             'skills': getattr(self, '_skills_config', None),
             'approval': getattr(self, '_approval_config', None),
             'learn': getattr(self, '_learn_config', None),
+            'tool_search': getattr(self, '_tool_search_config', None),
 
             # Tool configuration
             'tool_timeout': getattr(self, '_tool_timeout', None),

src/praisonai-agents/praisonaiagents/agent/chat_mixin.py

@@ -349,8 +349,10 @@ def _format_tools_for_completion(self, tools=None):
         tools_key = self._get_tools_cache_key(tools)
         tool_search_enabled = getattr(self, '_tool_search_config', None) is not None
         cache_key = f"{tools_key}:tool_search={tool_search_enabled}"
-        cached_tools = self._cache_get(self._formatted_tools_cache, cache_key)
-        if cached_tools is not None:
+        cached_entry = self._cache_get(self._formatted_tools_cache, cache_key)
+        if cached_entry is not None:
+            cached_tools, cached_metadata = cached_entry
+            self._tool_search_metadata = cached_metadata
             return cached_tools
 
         formatted_tools = []
@@ -424,9 +426,24 @@ def _format_tools_for_completion(self, tools=None):
                 # Tool search module not available, continue with original tools
                 logging.warning("Tool search requested but tool_search module not available")
 
-        # Cache the formatted tools with LRU eviction
-        self._cache_put(self._formatted_tools_cache, cache_key, formatted_tools)
-        return formatted_tools
+        # Strip __praisonai_deferrable__ from provider-facing tool payloads
+        # Keep the marker only for internal tool classification
+        cleaned_tools = []
+        for tool in formatted_tools:
+            if isinstance(tool, dict) and "__praisonai_deferrable__" in tool:
+                tool_copy = tool.copy()
+                tool_copy.pop("__praisonai_deferrable__", None)
+                cleaned_tools.append(tool_copy)
+            else:
+                cleaned_tools.append(tool)
+        
+        # Cache the formatted tools with LRU eviction, including tool search metadata
+        self._cache_put(
+            self._formatted_tools_cache,
+            cache_key,
+            (cleaned_tools, getattr(self, "_tool_search_metadata", None)),
+        )
+        return cleaned_tools
 
     def _build_multimodal_prompt(
         self, 

src/praisonai-agents/praisonaiagents/agent/tool_execution.py

@@ -136,7 +136,9 @@ def execute_tool(self, function_name: str, arguments: Dict[str, Any], tool_call_
         logging.debug(f"{self.name} executing tool {function_name} with arguments: {arguments}")
 
         # Handle bridge tool unwrapping BEFORE trace/stream/hooks (design invariant #6)
-        if function_name in ("tool_search", "tool_describe", "tool_call"):
+        # Only intercept when tool_search is active; otherwise fall through to real tool execution
+        if (getattr(self, '_tool_search_config', None) is not None and
+                function_name in ("tool_search", "tool_describe", "tool_call")):
             return self._handle_bridge_tool_call(function_name, arguments, tool_call_id)
 
         # NOTE: tool_call callback is triggered by display_tool_call in openai_client.py
@@ -976,13 +978,13 @@ def _handle_bridge_tool_call(self, function_name: str, arguments: Dict[str, Any]
         """
         # Ensure tool search metadata is available
         if not hasattr(self, '_tool_search_metadata') or self._tool_search_metadata is None:
-            return f"Tool search not available or not in bridge mode"
+            return "Tool search not available or not in bridge mode"
 
         metadata = self._tool_search_metadata
 
         # Check if we're in bridge mode
         if not metadata.get("bridge_mode", False):
-            return f"Tool search not in bridge mode"
+            return "Tool search not in bridge mode"
 
         # Get deferrable tools from metadata
         deferrable_tools = metadata.get("deferrable_tools", [])

src/praisonai-agents/praisonaiagents/config/feature_configs.py

@@ -1074,51 +1074,23 @@ def to_dict(self) -> Dict[str, Any]:
         }
 
 
-@dataclass
-class ToolSearchConfig:
-    """
-    Configuration for Tool Search feature - progressive MCP/plugin tool disclosure.
-    
-    When deferrable tool schemas would consume a large share of the model context window,
-    replace them with bridge tools (tool_search, tool_describe, tool_call) and load 
-    individual schemas on demand.
-    
-    Consolidates: tool_search parameter
-    
-    Usage:
-        # Simple enable (auto mode)
-        Agent(tool_search=True)
-        
-        # Auto mode with custom threshold
-        Agent(tool_search=ToolSearchConfig(enabled="auto", threshold_pct=15))
-        
-        # Always on mode
-        Agent(tool_search=ToolSearchConfig(enabled="on"))
-    """
-    # Control mode: "auto" | "on" | "off"  
-    enabled: Union[bool, str] = "auto"
-    
-    # Percentage of context window for deferral threshold (auto mode)
-    threshold_pct: float = 10.0
-    
-    # Default number of search results
-    search_default_limit: int = 5
-    
-    # Maximum search results allowed  
-    max_search_limit: int = 20
-    
-    # Override core tools set (advanced usage)
-    core_tools: Optional[FrozenSet[str]] = None
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary."""
-        return {
-            "enabled": self.enabled,
-            "threshold_pct": self.threshold_pct, 
-            "search_default_limit": self.search_default_limit,
-            "max_search_limit": self.max_search_limit,
-            "core_tools": list(self.core_tools) if self.core_tools else None,
-        }
+# Import ToolSearchConfig from tools module to avoid duplication
+def __get_tool_search_config():
+    try:
+        from ..tools.tool_search import ToolSearchConfig as _ToolSearchConfig
+        return _ToolSearchConfig
+    except ImportError:
+        # Fallback minimal config if tools module not available
+        @dataclass
+        class FallbackToolSearchConfig:
+            enabled: Union[bool, str] = "auto"
+            threshold_pct: float = 10.0
+            search_default_limit: int = 5
+            max_search_limit: int = 20
+            core_tools: Optional[FrozenSet[str]] = None
+        return FallbackToolSearchConfig
+
+ToolSearchConfig = __get_tool_search_config()
 
 
 class AutonomyLevel(str, Enum):
@@ -1393,6 +1365,21 @@ def resolve_autonomy(value: AutonomyParam) -> Optional[AutonomyConfig]:
     return value
 
 
+def resolve_tool_search(value: ToolSearchParam) -> Optional[ToolSearchConfig]:
+    """Resolve tool_search= parameter following precedence ladder."""
+    if value is None or value is False:
+        return None
+    if value is True:
+        return ToolSearchConfig()
+    if isinstance(value, str):
+        return ToolSearchConfig(enabled=value)
+    if isinstance(value, dict):
+        return ToolSearchConfig(**value)
+    if isinstance(value, ToolSearchConfig):
+        return value
+    return value
+
+
 __all__ = [
     # Enums
     "MemoryBackend",
@@ -1451,4 +1438,5 @@ def resolve_autonomy(value: AutonomyParam) -> Optional[AutonomyConfig]:
     "resolve_execution",
     "resolve_caching",
     "resolve_autonomy",
+    "resolve_tool_search",
 ]

src/praisonai-agents/praisonaiagents/tools/tool_search.py

@@ -139,9 +139,9 @@ def _is_tool_deferrable(tool_def: ToolDef) -> bool:
     if function_def.get("deferrable", False):
         return True
 
-    # Check tool name patterns for MCP tools
+    # Check tool name patterns for MCP tools (prefix only, to avoid false-positives)
     tool_name = function_def.get("name", "")
-    if tool_name.startswith("mcp_") or "mcp" in tool_name.lower():
+    if tool_name.startswith("mcp_"):
         return True
 
     return False
@@ -234,6 +234,7 @@ def _tokenize(self, text: str) -> List[str]:
 
     def _build_index(self):
         """Build BM25 index from catalog."""
+        total_length = 0
         # Calculate term frequencies for each document
         for item in self.catalog:
             doc_text = f"{item['name']} {item['description']}"
@@ -245,11 +246,15 @@ def _build_index(self):
                 tf[token] += 1
 
             self.term_frequencies.append(dict(tf))
+            total_length += len(tokens)
 
             # Document frequency (how many docs contain each term)
             unique_tokens = set(tokens)
             for token in unique_tokens:
                 self.doc_frequencies[token] += 1
+        
+        # Cache average document length to avoid O(n) recomputation in hot path
+        self._cached_avg_doc_length = total_length / len(self.catalog) if self.catalog else 0.0
 
     def search(self, query: str, limit: int = 5) -> List[Dict[str, str]]:
         """
@@ -269,7 +274,7 @@ def search(self, query: str, limit: int = 5) -> List[Dict[str, str]]:
         scores = []
         k1, b = 1.5, 0.75  # BM25 parameters
 
-        for i, (item, tf) in enumerate(zip(self.catalog, self.term_frequencies)):
+        for item, tf in zip(self.catalog, self.term_frequencies, strict=True):
             score = 0.0
             doc_length = sum(tf.values())
 
@@ -280,7 +285,7 @@ def search(self, query: str, limit: int = 5) -> List[Dict[str, str]]:
                                  (self.doc_frequencies[token] + 0.5))
                     term_freq = tf[token]
                     score += idf * (term_freq * (k1 + 1)) / (
-                        term_freq + k1 * (1 - b + b * (doc_length / self._avg_doc_length()))
+                        term_freq + k1 * (1 - b + b * (doc_length / self._cached_avg_doc_length))
                     )
 
             if score > 0:
@@ -290,12 +295,6 @@ def search(self, query: str, limit: int = 5) -> List[Dict[str, str]]:
         scores.sort(key=lambda x: x[0], reverse=True)
         return [item for _, item in scores[:limit]]
 
-    def _avg_doc_length(self) -> float:
-        """Calculate average document length."""
-        if not self.term_frequencies:
-            return 0.0
-        total_length = sum(sum(tf.values()) for tf in self.term_frequencies)
-        return total_length / len(self.term_frequencies)
 
 def search_catalog(
     deferrable_tools: ToolDefList, 
@@ -545,6 +544,13 @@ def resolve_underlying_call(tool_name: str, tool_args: Dict[str, Any]) -> Tuple[
         # Not a bridge call, return as-is
         return tool_name, tool_args
 
+    # Validate tool_args is a dict
+    if not isinstance(tool_args, dict):
+        raise TypeError(
+            f"tool_call expects a dictionary for tool_args, got {type(tool_args).__name__}. "
+            "Ensure the LLM output is properly formatted."
+        )
+    
     # Extract real tool call from bridge args
     real_tool_name = tool_args.get("tool_name", "")
     real_args = tool_args.get("tool_args", {})