tooluniverse 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

tooluniverse/execute_function.py

@@ -31,12 +31,26 @@ import random
 import string
 import os
 import time
+import hashlib
+import warnings
+from pathlib import Path
+from contextlib import nullcontext
+from typing import Any, Dict, List, Optional
 from .utils import read_json_list, evaluate_function_call, extract_function_call_json
+from .exceptions import (
+    ToolError,
+    ToolUnavailableError,
+    ToolValidationError,
+    ToolConfigError,
+    ToolServerError,
+)
 from .tool_registry import (
     auto_discover_tools,
     get_tool_registry,
     register_external_tool,
     get_tool_class_lazy,
+    get_tool_errors,
+    mark_tool_unavailable,
 )
 from .logging_config import (
     get_logger,
@@ -46,6 +60,7 @@ from .logging_config import (
     error,
     set_log_level,
 )
+from .cache.result_cache_manager import ResultCacheManager
 from .output_hook import HookManager
 from .default_config import default_tool_files, get_default_hook_config
 
@@ -81,6 +96,82 @@ for _tool_name, _tool_class in sorted(tool_type_mappings.items()):
     debug(f"  - {_tool_name}: {_tool_class.__name__}")
 
 
+class ToolCallable:
+    """
+    A callable wrapper for a tool that validates kwargs and calls run_one_function.
+
+    This class provides the dynamic function interface for tools, allowing
+    them to be called like regular Python functions with keyword arguments.
+    """
+
+    def __init__(self, engine: "ToolUniverse", tool_name: str):
+        self.engine = engine
+        self.tool_name = tool_name
+        self.schema = engine.all_tool_dict[tool_name]["parameter"]
+        self.__doc__ = engine.all_tool_dict[tool_name].get("description", tool_name)
+
+    def __call__(
+        self, *, stream_callback=None, use_cache=False, validate=True, **kwargs
+    ):
+        """
+        Execute the tool with the provided keyword arguments.
+
+        Args:
+            stream_callback: Optional callback for streaming responses
+            use_cache: Whether to use result caching
+            validate: Whether to validate parameters against schema
+            **kwargs: Tool-specific arguments
+
+        Returns:
+            Tool execution result
+        """
+        function_call = {"name": self.tool_name, "arguments": kwargs}
+        return self.engine.run_one_function(
+            function_call,
+            stream_callback=stream_callback,
+            use_cache=use_cache,
+            validate=validate,
+        )
+
+
+class ToolNamespace:
+    """
+    Dynamic namespace for accessing tools as callable functions.
+
+    This class provides the `tu.tools.tool_name(**kwargs)` interface,
+    dynamically creating ToolCallable instances for each available tool.
+    """
+
+    def __init__(self, engine: "ToolUniverse"):
+        self.engine = engine
+
+    def __getattr__(self, name: str) -> ToolCallable:
+        """Return a ToolCallable for the requested tool name."""
+        if name in self.engine.all_tool_dict:
+            return ToolCallable(self.engine, name)
+        raise AttributeError(f"Tool '{name}' not found")
+
+    def __len__(self) -> int:
+        """Return the number of available tools."""
+        return len(self.engine.all_tool_dict)
+
+    def __iter__(self):
+        """Iterate over tool names."""
+        return iter(self.engine.all_tool_dict.keys())
+
+    def __contains__(self, name: str) -> bool:
+        """Check if a tool exists."""
+        return name in self.engine.all_tool_dict
+
+    def refresh(self):
+        """Refresh tool discovery (re-discover MCP/remote tools)."""
+        self.engine.refresh_tools()
+
+    def eager_load(self, names: Optional[List[str]] = None):
+        """Pre-instantiate tools to reduce first-call latency."""
+        self.engine.eager_load_tools(names)
+
+
 class ToolUniverse:
     """
     A comprehensive tool management system for loading, organizing, and executing various scientific and data tools.
@@ -130,9 +221,9 @@ class ToolUniverse:
         self.logger = get_logger("ToolUniverse")
 
         # Initialize any necessary attributes here FIRST
-        self.all_tools = []
-        self.all_tool_dict = {}
-        self.tool_category_dicts = {}
+        self.all_tools: List[Dict[str, Any]] = []
+        self.all_tool_dict: Dict[str, Dict[str, Any]] = {}
+        self.tool_category_dicts: Dict[str, List[Dict[str, Any]]] = {}
         self.tool_finder = None
         if tool_files is None:
             tool_files = default_tool_files
@@ -172,6 +263,46 @@ class ToolUniverse:
             self.hook_manager = None
             self.logger.debug("Output hooks disabled")
 
+        # Initialize caching configuration
+        cache_enabled = os.getenv("TOOLUNIVERSE_CACHE_ENABLED", "true").lower() in (
+            "true",
+            "1",
+            "yes",
+        )
+        persistence_enabled = os.getenv(
+            "TOOLUNIVERSE_CACHE_PERSIST", "true"
+        ).lower() in ("true", "1", "yes")
+        memory_size = int(os.getenv("TOOLUNIVERSE_CACHE_MEMORY_SIZE", "256"))
+        default_ttl_env = os.getenv("TOOLUNIVERSE_CACHE_DEFAULT_TTL")
+        default_ttl = int(default_ttl_env) if default_ttl_env else None
+        singleflight_enabled = os.getenv(
+            "TOOLUNIVERSE_CACHE_SINGLEFLIGHT", "true"
+        ).lower() in ("true", "1", "yes")
+
+        cache_path = os.getenv("TOOLUNIVERSE_CACHE_PATH")
+        if not cache_path and persistence_enabled:
+            base_dir = os.getenv("TOOLUNIVERSE_CACHE_DIR")
+            if not base_dir:
+                base_dir = os.path.join(str(Path.home()), ".tooluniverse")
+            os.makedirs(base_dir, exist_ok=True)
+            cache_path = os.path.join(base_dir, "cache.sqlite")
+
+        self.cache_manager = ResultCacheManager(
+            memory_size=memory_size,
+            persistent_path=cache_path if persistence_enabled else None,
+            enabled=cache_enabled,
+            persistence_enabled=persistence_enabled,
+            singleflight=singleflight_enabled,
+            default_ttl=default_ttl,
+        )
+
+        self._strict_validation = os.getenv(
+            "TOOLUNIVERSE_STRICT_VALIDATION", "false"
+        ).lower() in ("true", "1", "yes")
+
+        # Initialize dynamic tools namespace
+        self.tools = ToolNamespace(self)
+
     def register_custom_tool(self, tool_class, tool_name=None, tool_config=None):
         """
         Register a custom tool class at runtime.
@@ -903,104 +1034,6 @@ class ToolUniverse:
         )
         self.logger.debug("_process_mcp_auto_loaders completed")
 
-    def select_tools(
-        self,
-        include_names=None,
-        exclude_names=None,
-        include_categories=None,
-        exclude_categories=None,
-    ):
-        """
-        Select tools based on tool names and/or categories (tool_files keys).
-
-        Args:
-            include_names (list, optional): List of tool names to include. If None, include all.
-            exclude_names (list, optional): List of tool names to exclude.
-            include_categories (list, optional): List of categories (tool_files keys) to include.
-                                               If None, include all.
-            exclude_categories (list, optional): List of categories (tool_files keys) to exclude.
-
-        Returns:
-            list: List of selected tool configurations.
-        """
-        selected_tools = []
-        # If categories are specified, use self.tool_category_dicts to filter
-        categories = set(self.tool_category_dicts.keys())
-        if include_categories is not None:
-            categories &= set(include_categories)
-        if exclude_categories is not None:
-            categories -= set(exclude_categories)
-        # Gather tools from selected categories
-        for cat in categories:
-            selected_tools.extend(self.tool_category_dicts[cat])
-        # Further filter by names if needed
-        if include_names is not None:
-            selected_tools = [
-                tool for tool in selected_tools if tool["name"] in include_names
-            ]
-        if exclude_names is not None:
-            selected_tools = [
-                tool for tool in selected_tools if tool["name"] not in exclude_names
-            ]
-        return selected_tools
-
-    def filter_tool_lists(
-        self,
-        tool_name_list,
-        tool_desc_list,
-        include_names=None,
-        exclude_names=None,
-        include_categories=None,
-        exclude_categories=None,
-    ):
-        """
-        Directly filter tool name and description lists based on names and/or categories.
-
-        This method takes existing tool name and description lists and filters them according
-        to the specified criteria using the select_tools method for category-based filtering.
-
-        Args:
-            tool_name_list (list): List of tool names to filter.
-            tool_desc_list (list): List of tool descriptions to filter (must correspond to tool_name_list).
-            include_names (list, optional): List of tool names to include.
-            exclude_names (list, optional): List of tool names to exclude.
-            include_categories (list, optional): List of categories to include.
-            exclude_categories (list, optional): List of categories to exclude.
-
-        Returns:
-            tuple: A tuple containing (filtered_tool_name_list, filtered_tool_desc_list).
-        """
-        # Build a set of allowed tool names using select_tools for category filtering
-        allowed_names = set()
-        if any([include_names, exclude_names, include_categories, exclude_categories]):
-            filtered_tools = self.select_tools(
-                include_names=include_names,
-                exclude_names=exclude_names,
-                include_categories=include_categories,
-                exclude_categories=exclude_categories,
-            )
-            allowed_names = set(tool["name"] for tool in filtered_tools)
-        else:
-            allowed_names = set(tool_name_list)
-
-        # Filter lists by allowed_names
-        filtered_tool_name_list = []
-        filtered_tool_desc_list = []
-        for name, desc in zip(tool_name_list, tool_desc_list):
-            if name in allowed_names:
-                filtered_tool_name_list.append(name)
-                filtered_tool_desc_list.append(desc)
-        return filtered_tool_name_list, filtered_tool_desc_list
-
-    def return_all_loaded_tools(self):
-        """
-        Return a deep copy of all loaded tools.
-
-        Returns:
-            list: A deep copy of the all_tools list to prevent external modification.
-        """
-        return copy.deepcopy(self.all_tools)
-
     def list_built_in_tools(self, mode="config", scan_all=False):
         """
         List all built-in tool categories and their statistics with different modes.
@@ -1041,9 +1074,14 @@ class ToolUniverse:
             - When scan_all=True, all JSON files in data/ and subdirectories are scanned
         """
         if mode not in ["config", "type", "list_name", "list_spec"]:
-            raise ValueError(
-                "Mode must be one of: 'config', 'type', 'list_name', 'list_spec'"
-            )
+            # Handle invalid modes gracefully
+            if mode is None:
+                mode = "config"  # Default to config mode
+            else:
+                # For invalid string modes, return error info instead of raising
+                return {
+                    "error": f"Invalid mode '{mode}'. Must be one of: 'config', 'type', 'list_name', 'list_spec'"
+                }
 
         # For list_name and list_spec modes, we can return early with just the data
         if mode in ["list_name", "list_spec"]:
@@ -1211,6 +1249,39 @@ class ToolUniverse:
 
         return result
 
+    def _read_tools_from_file(self, file_path):
+        """
+        Read tools from a single JSON file with error handling.
+
+        Args:
+            file_path (str): Path to the JSON file
+
+        Returns:
+            list: List of tool configurations from the file
+        """
+        try:
+            tools_in_file = read_json_list(file_path)
+
+            # Handle different data formats
+            if isinstance(tools_in_file, dict):
+                # Convert dict of tools to list of tools
+                tools_in_file = list(tools_in_file.values())
+            elif not isinstance(tools_in_file, list):
+                # Skip files that don't contain tool configurations
+                return []
+
+            # Validate tools have required fields
+            valid_tools = []
+            for tool in tools_in_file:
+                if isinstance(tool, dict) and "name" in tool:
+                    valid_tools.append(tool)
+
+            return valid_tools
+
+        except Exception as e:
+            warning(f"Warning: Could not read tools from {file_path}: {e}")
+            return []
+
     def _scan_predefined_files(self):
         """
         Scan predefined tool files (original behavior).
@@ -1223,39 +1294,23 @@ class ToolUniverse:
         all_tool_names = set()
 
         # Read tools from each category file
-        for category, file_path in self.tool_files.items():
-            try:
-                # Read the JSON file for this category
-                tools_in_category = read_json_list(file_path)
-                all_tools.extend(tools_in_category)
-                all_tool_names.update([tool["name"] for tool in tools_in_category])
-            except Exception as e:
-                warning(
-                    f"Warning: Could not read tools from {category} ({file_path}): {e}"
-                )
+        for _category, file_path in self.tool_files.items():
+            tools_in_category = self._read_tools_from_file(file_path)
+            all_tools.extend(tools_in_category)
+            all_tool_names.update([tool["name"] for tool in tools_in_category])
 
         # Also include remote tools
         try:
             remote_dir = os.path.join(current_dir, "data", "remote_tools")
             if os.path.isdir(remote_dir):
-                remote_tools = []
                 for fname in os.listdir(remote_dir):
                     if not fname.lower().endswith(".json"):
                         continue
                     fpath = os.path.join(remote_dir, fname)
-                    try:
-                        tools_in_file = read_json_list(fpath)
-                        if isinstance(tools_in_file, dict):
-                            tools_in_file = list(tools_in_file.values())
-                        if isinstance(tools_in_file, list):
-                            remote_tools.extend(tools_in_file)
-                    except Exception as e:
-                        warning(
-                            f"Warning: Could not read remote tools from {fpath}: {e}"
-                        )
-                if remote_tools:
-                    all_tools.extend(remote_tools)
-                    all_tool_names.update([tool["name"] for tool in remote_tools])
+                    remote_tools = self._read_tools_from_file(fpath)
+                    if remote_tools:
+                        all_tools.extend(remote_tools)
+                        all_tool_names.update([tool["name"] for tool in remote_tools])
         except Exception as e:
             warning(f"Warning: Failed to scan remote tools directory: {e}")
 
@@ -1288,31 +1343,14 @@ class ToolUniverse:
 
         self.logger.debug(f"Found {len(json_files)} JSON files to scan")
 
-        # Read tools from each JSON file
+        # Read tools from each JSON file using the common method
         for json_file in json_files:
-            try:
-                tools_in_file = read_json_list(json_file)
-
-                # Handle different data formats
-                if isinstance(tools_in_file, dict):
-                    # Convert dict of tools to list of tools
-                    tools_in_file = list(tools_in_file.values())
-                elif not isinstance(tools_in_file, list):
-                    # Skip files that don't contain tool configurations
-                    continue
-
-                # Add tools to our collection
-                for tool in tools_in_file:
-                    if isinstance(tool, dict) and "name" in tool:
-                        all_tools.append(tool)
-                        all_tool_names.add(tool["name"])
-
+            tools_in_file = self._read_tools_from_file(json_file)
+            if tools_in_file:
+                all_tools.extend(tools_in_file)
+                all_tool_names.update([tool["name"] for tool in tools_in_file])
                 self.logger.debug(f"Loaded {len(tools_in_file)} tools from {json_file}")
 
-            except Exception as e:
-                warning(f"Warning: Could not read tools from {json_file}: {e}")
-                continue
-
         self.logger.info(
             f"Scanned {len(json_files)} JSON files, found {len(all_tools)} tools"
         )
@@ -1387,63 +1425,42 @@ class ToolUniverse:
                 del tool[key]
         return tool
 
-    def prepare_tool_prompts(self, tool_list):
-        """
-        Prepare a list of tool configurations for prompt usage.
-
-        Args:
-            tool_list (list): List of tool configuration dictionaries.
-
-        Returns:
-            list: List of tool configurations with only essential keys for prompting.
-        """
-        copied_list = []
-        for tool in tool_list:
-            copied_list.append(self.prepare_one_tool_prompt(tool))
-        return copied_list
-
-    def remove_keys(self, tool_list, invalid_keys):
+    def prepare_tool_prompts(self, tool_list, mode="prompt", valid_keys=None):
         """
-        Remove specified keys from a list of tool configurations.
+        Prepare a list of tool configurations for different usage modes.
 
         Args:
             tool_list (list): List of tool configuration dictionaries.
-            invalid_keys (list): List of keys to remove from each tool configuration.
+            mode (str): Preparation mode. Options:
+                - 'prompt': Keep essential keys for prompting (name, description, parameter, required)
+                - 'example': Keep extended keys for examples (name, description, parameter, required, query_schema, fields, label, type)
+                - 'custom': Use custom valid_keys parameter
+            valid_keys (list, optional): Custom list of keys to keep when mode='custom'.
 
         Returns:
-            list: Deep copy of tool list with specified keys removed.
-        """
-        copied_list = copy.deepcopy(tool_list)
-        for tool in copied_list:
-            # Create a list of keys to avoid modifying the dictionary during iteration
-            for key in list(tool.keys()):
-                if key in invalid_keys:
-                    del tool[key]
-        return copied_list
-
-    def prepare_tool_examples(self, tool_list):
-        """
-        Prepare tool configurations for example usage by keeping extended set of keys.
-
-        This method is similar to prepare_tool_prompts but includes additional keys
-        useful for examples and documentation.
-
-        Args:
-            tool_list (list): List of tool configuration dictionaries.
+            list: List of tool configurations with only specified keys.
+        """
+        if mode == "prompt":
+            valid_keys = ["name", "description", "parameter", "required"]
+        elif mode == "example":
+            valid_keys = [
+                "name",
+                "description",
+                "parameter",
+                "required",
+                "query_schema",
+                "fields",
+                "label",
+                "type",
+            ]
+        elif mode == "custom":
+            if valid_keys is None:
+                raise ValueError("valid_keys must be provided when mode='custom'")
+        else:
+            raise ValueError(
+                f"Invalid mode: {mode}. Must be 'prompt', 'example', or 'custom'"
+            )
 
-        Returns:
-            list: Deep copy of tool list with only example-relevant keys.
-        """
-        valid_keys = [
-            "name",
-            "description",
-            "parameter",
-            "required",
-            "query_schema",
-            "fields",
-            "label",
-            "type",
-        ]
         copied_list = copy.deepcopy(tool_list)
         for tool in copied_list:
             # Create a list of keys to avoid modifying the dictionary during iteration
@@ -1472,21 +1489,6 @@ class ToolUniverse:
                 picked_tool_list.append(tool_spec)
         return picked_tool_list
 
-    def get_tool_by_name(self, tool_names, format="default"):
-        """
-        Retrieve tool configurations by their names.
-
-        Args:
-            tool_names (list): List of tool names to retrieve.
-            format (str, optional): Output format. Options: 'default', 'openai'.
-                                   If 'openai', returns OpenAI function calling format. Defaults to 'default'.
-
-        Returns:
-            list: List of tool configurations for the specified names.
-                 Tools not found will be reported but not included in the result.
-        """
-        return self.get_tool_specification_by_names(tool_names, format=format)
-
     def get_one_tool_by_one_name(self, tool_name, return_prompt=True):
         """
         Retrieve a single tool specification by name, optionally prepared for prompting.
@@ -1521,65 +1523,58 @@ class ToolUniverse:
         Returns:
             dict or None: Tool configuration if found, None otherwise.
         """
-        if tool_name in self.all_tool_dict:
-            tool_config = self.all_tool_dict[tool_name]
-
-            if format == "openai":
-                parameters = tool_config.get("parameter", {})
-                if isinstance(parameters, dict):
-                    # 修复 required 字段格式
-                    if "properties" in parameters:
-                        for _prop_name, prop_config in parameters["properties"].items():
-                            if (
-                                isinstance(prop_config, dict)
-                                and "required" in prop_config
-                            ):
-                                del prop_config["required"]
-
-                    if "required" in parameters and not isinstance(
-                        parameters["required"], list
-                    ):
-                        if parameters["required"] is True:
-                            required_list = []
-                            if "properties" in parameters:
-                                for prop_name, prop_config in parameters[
-                                    "properties"
-                                ].items():
-                                    if (
-                                        isinstance(prop_config, dict)
-                                        and prop_config.get("required") is True
-                                    ):
-                                        required_list.append(prop_name)
-                            parameters["required"] = required_list
-                        else:
-                            parameters["required"] = []
-
-                return {
-                    "name": tool_config["name"],
-                    "description": tool_config["description"],
-                    "parameters": parameters,
-                }
-            elif return_prompt:
-                return self.prepare_one_tool_prompt(tool_config)
-            else:
-                return tool_config
-        else:
+        if tool_name not in self.all_tool_dict:
             warning(f"Tool name {tool_name} not found in the loaded tools.")
             return None
 
-    def get_tool_description(self, tool_name):
-        """
-        Get the description of a tool by its name.
+        tool_config = self.all_tool_dict[tool_name]
 
-        This is a convenience method that calls get_one_tool_by_one_name.
+        if return_prompt:
+            return self.prepare_one_tool_prompt(tool_config)
 
-        Args:
-            tool_name (str): Name of the tool.
+        # Process parameter schema based on format
+        if "parameter" in tool_config and isinstance(tool_config["parameter"], dict):
+            import copy
 
-        Returns:
-            dict or None: Tool configuration if found, None otherwise.
-        """
-        return self.get_one_tool_by_one_name(tool_name)
+            processed_config = copy.deepcopy(tool_config)
+            parameter_schema = processed_config["parameter"]
+
+            if (
+                "properties" in parameter_schema
+                and parameter_schema["properties"] is not None
+            ):
+                required_properties = parameter_schema.get("required", [])
+
+                if format == "openai":
+                    # For OpenAI format: remove property-level required fields
+                    for _prop_name, prop_config in parameter_schema[
+                        "properties"
+                    ].items():
+                        if isinstance(prop_config, dict) and "required" in prop_config:
+                            del prop_config["required"]
+
+                    # Ensure required is a list
+                    if not isinstance(parameter_schema.get("required"), list):
+                        parameter_schema["required"] = (
+                            required_properties if required_properties else []
+                        )
+
+                    return {
+                        "name": processed_config["name"],
+                        "description": processed_config["description"],
+                        "parameters": parameter_schema,
+                    }
+                else:
+                    # For default format: add required fields to properties
+                    for prop_name, prop_config in parameter_schema[
+                        "properties"
+                    ].items():
+                        if isinstance(prop_config, dict):
+                            prop_config["required"] = prop_name in required_properties
+
+                    return processed_config
+
+        return tool_config
 
     def get_tool_type_by_name(self, tool_name):
         """
@@ -1596,6 +1591,15 @@ class ToolUniverse:
         """
         return self.all_tool_dict[tool_name]["type"]
 
+    def call_id_gen(self):
+        """
+        Generate a random call ID for function calls.
+
+        Returns:
+            str: A random 9-character string composed of letters and digits.
+        """
+        return "".join(random.choices(string.ascii_letters + string.digits, k=9))
+
     def tool_to_str(self, tool_list):
         """
         Convert a list of tool configurations to a formatted string.
@@ -1630,14 +1634,14 @@ class ToolUniverse:
             lst, return_message=return_message, verbose=verbose, format=format
         )
 
-    def call_id_gen(self):
+    def return_all_loaded_tools(self):
         """
-        Generate a random call ID for function calls.
+        Return a deep copy of all loaded tools.
 
         Returns:
-            str: A random 9-character string composed of letters and digits.
+            list: A deep copy of the all_tools list to prevent external modification.
         """
-        return "".join(random.choices(string.ascii_letters + string.digits, k=9))
+        return copy.deepcopy(self.all_tools)
 
     def run(
         self,
@@ -1708,7 +1712,9 @@ class ToolUniverse:
             error("Not a function call")
             return None
 
-    def run_one_function(self, function_call_json, stream_callback=None):
+    def run_one_function(
+        self, function_call_json, stream_callback=None, use_cache=False, validate=True
+    ):
         """
         Execute a single function call.
 
@@ -1718,67 +1724,155 @@ class ToolUniverse:
 
         Args:
             function_call_json (dict): Dictionary containing function name and arguments.
+            stream_callback (callable, optional): Callback for streaming responses.
+            use_cache (bool, optional): Whether to use result caching. Defaults to False.
+            validate (bool, optional): Whether to validate parameters against schema. Defaults to True.
 
         Returns:
             str or dict: Result from the tool execution, or error message if validation fails.
         """
-        check_status, check_message = self.check_function_call(function_call_json)
-        if check_status is False:
-            return (
-                "Invalid function call: " + check_message
-            )  # + "  You must correct your invalid function call!"
-        function_name = function_call_json["name"]
-        arguments = function_call_json["arguments"]
+        function_name = function_call_json.get("name", "")
+        arguments = function_call_json.get("arguments", {})
 
-        # Execute the tool
-        tool_instance = None
-        tool_arguments = arguments
-        if function_name in self.callable_functions:
-            tool_instance = self.callable_functions[function_name]
-            result, tool_arguments = self._execute_tool_with_stream(
-                tool_instance, arguments, stream_callback
-            )
-        else:
-            if function_name in self.all_tool_dict:
-                self.logger.debug(
-                    "Initiating callable_function from loaded tool dicts."
-                )
-                tool = self.init_tool(
-                    self.all_tool_dict[function_name], add_to_cache=True
+        # Handle malformed queries gracefully
+        if not function_name:
+            return {"error": "Missing or empty function name"}
+
+        if not isinstance(arguments, dict):
+            return {
+                "error": f"Arguments must be a dictionary, got {type(arguments).__name__}"
+            }
+
+        tool_instance = None
+        cache_namespace = None
+        cache_version = None
+        cache_key = None
+        composed_cache_key = None
+        cache_guard = nullcontext()
+
+        cache_enabled = (
+            use_cache and self.cache_manager is not None and self.cache_manager.enabled
+        )
+
+        if cache_enabled:
+            tool_instance = self._get_tool_instance(function_name, cache=True)
+            if tool_instance and tool_instance.supports_caching():
+                cache_namespace = tool_instance.get_cache_namespace()
+                cache_version = tool_instance.get_cache_version()
+                cache_key = self._make_cache_key(function_name, arguments)
+                composed_cache_key = self.cache_manager.compose_key(
+                    cache_namespace, cache_version, cache_key
                 )
-                tool_instance = tool
-                result, tool_arguments = self._execute_tool_with_stream(
-                    tool_instance, arguments, stream_callback
+                cached_value = self.cache_manager.get(
+                    namespace=cache_namespace,
+                    version=cache_version,
+                    cache_key=cache_key,
                 )
+                if cached_value is not None:
+                    self.logger.debug(f"Cache hit for {function_name}")
+                    return cached_value
+                cache_guard = self.cache_manager.singleflight_guard(composed_cache_key)
             else:
-                return f"Tool '{function_name}' not found"
-
-        # Apply output hooks if enabled
-        if self.hook_manager:
-            context = {
-                "tool_name": function_name,
-                "tool_type": (
-                    tool_instance.__class__.__name__
-                    if tool_instance is not None
-                    else "unknown"
-                ),
-                "execution_time": time.time(),
-                "arguments": tool_arguments,
-            }
-            result = self.hook_manager.apply_hooks(
-                result, function_name, tool_arguments, context
-            )
+                cache_enabled = False
+
+        with cache_guard:
+            if cache_enabled:
+                cached_value = self.cache_manager.get(
+                    namespace=cache_namespace,
+                    version=cache_version,
+                    cache_key=cache_key,
+                )
+                if cached_value is not None:
+                    self.logger.debug(
+                        f"Cache hit for {function_name} (after singleflight wait)"
+                    )
+                    return cached_value
+
+            # Validate parameters if requested
+            if validate:
+                validation_error = self._validate_parameters(function_name, arguments)
+                if validation_error:
+                    return self._create_dual_format_error(validation_error)
+
+            # Check function call format (existing validation)
+            check_status, check_message = self.check_function_call(function_call_json)
+            if check_status is False:
+                error_msg = "Invalid function call: " + check_message
+                return self._create_dual_format_error(
+                    ToolValidationError(
+                        error_msg, details={"check_message": check_message}
+                    )
+                )
 
-        return result
+            # Execute the tool
+            tool_arguments = arguments
+            try:
+                if tool_instance is None:
+                    tool_instance = self._get_tool_instance(function_name, cache=True)
+
+                if tool_instance:
+                    result, tool_arguments = self._execute_tool_with_stream(
+                        tool_instance, arguments, stream_callback, use_cache, validate
+                    )
+                else:
+                    error_msg = f"Tool '{function_name}' not found"
+                    return self._create_dual_format_error(
+                        ToolUnavailableError(
+                            error_msg,
+                            next_steps=[
+                                "Check tool name spelling",
+                                "Run tu.tools.refresh()",
+                            ],
+                        )
+                    )
+            except Exception as e:
+                # Classify and return structured error
+                classified_error = self._classify_exception(e, function_name, arguments)
+                return self._create_dual_format_error(classified_error)
+
+            # Apply output hooks if enabled
+            if self.hook_manager:
+                context = {
+                    "tool_name": function_name,
+                    "tool_type": (
+                        tool_instance.__class__.__name__
+                        if tool_instance is not None
+                        else "unknown"
+                    ),
+                    "execution_time": time.time(),
+                    "arguments": tool_arguments,
+                }
+                result = self.hook_manager.apply_hooks(
+                    result, function_name, tool_arguments, context
+                )
+
+            # Cache result if enabled
+            if cache_enabled and tool_instance and tool_instance.supports_caching():
+                if cache_key is None:
+                    cache_key = self._make_cache_key(function_name, arguments)
+                if cache_namespace is None:
+                    cache_namespace = tool_instance.get_cache_namespace()
+                if cache_version is None:
+                    cache_version = tool_instance.get_cache_version()
+                ttl = tool_instance.get_cache_ttl(result)
+                self.cache_manager.set(
+                    namespace=cache_namespace,
+                    version=cache_version,
+                    cache_key=cache_key,
+                    value=result,
+                    ttl=ttl,
+                )
 
-    def _execute_tool_with_stream(self, tool_instance, arguments, stream_callback):
-        """Invoke a tool, forwarding stream callbacks when supported."""
+            return result
+
+    def _execute_tool_with_stream(
+        self, tool_instance, arguments, stream_callback, use_cache=False, validate=True
+    ):
+        """Invoke a tool, forwarding stream callbacks and other parameters when supported."""
 
         tool_arguments = arguments
         stream_flag_key = (
-            getattr(tool_instance, "STREAM_FLAG_KEY", None)
-            if stream_callback
-            else None
+            getattr(tool_instance, "STREAM_FLAG_KEY", None) if stream_callback else None
         )
 
         if isinstance(arguments, dict):
@@ -1791,24 +1885,30 @@ class ToolUniverse:
             ):
                 tool_arguments[stream_flag_key] = True
 
-        if stream_callback is None:
-            return tool_instance.run(tool_arguments), tool_arguments
-
+        # Try to pass all available parameters to the tool
         try:
             signature = inspect.signature(tool_instance.run)
-            if "stream_callback" in signature.parameters:
-                return (
-                    tool_instance.run(
-                        tool_arguments, stream_callback=stream_callback
-                    ),
-                    tool_arguments,
-                )
-        except (ValueError, TypeError):
-            # If inspection fails, fall back to best-effort execution
-            pass
-
-        # Tool doesn't support streaming yet; execute normally
-        return tool_instance.run(tool_arguments), tool_arguments
+            params = signature.parameters
+
+            # Build kwargs based on what the tool accepts
+            kwargs = {}
+
+            # Always include arguments as first positional argument
+            if stream_callback is not None and "stream_callback" in params:
+                kwargs["stream_callback"] = stream_callback
+            if "use_cache" in params:
+                kwargs["use_cache"] = use_cache
+            if "validate" in params:
+                kwargs["validate"] = validate
+
+            # Call with all supported parameters
+            return tool_instance.run(tool_arguments, **kwargs), tool_arguments
+
+        except (ValueError, TypeError) as e:
+            # If inspection fails or tool doesn't accept extra params,
+            # fall back to simple execution with just arguments
+            self.logger.debug(f"Falling back to simple run() call: {e}")
+            return tool_instance.run(tool_arguments), tool_arguments
 
     def toggle_hooks(self, enabled: bool):
         """
@@ -1845,65 +1945,239 @@ class ToolUniverse:
             add_to_cache (bool, optional): Whether to cache the initialized tool. Defaults to True.
 
         Returns:
-            object: Initialized tool instance.
+            object: Initialized tool instance or None if initialization fails.
 
         Raises:
             KeyError: If the tool type is not found in tool_type_mappings.
         """
         global tool_type_mappings
 
-        if tool_name is not None:
-            # Use lazy loading to get the tool class
-            tool_class = get_tool_class_lazy(tool_name)
-            if tool_class is None:
-                raise KeyError(f"Tool type '{tool_name}' not found in registry")
-            new_tool = tool_class()
-        else:
-            tool_type = tool["type"]
-            tool_name = tool["name"]
-
-            # Use lazy loading to get the tool class
-            tool_class = get_tool_class_lazy(tool_type)
-            if tool_class is None:
-                # Fallback to old method if lazy loading fails
-                if tool_type not in tool_type_mappings:
-                    # Refresh registry and try again
-                    tool_type_mappings = get_tool_registry()
-                if tool_type not in tool_type_mappings:
-                    raise KeyError(f"Tool type '{tool_type}' not found in registry")
-                tool_class = tool_type_mappings[tool_type]
-
-            if "OpentargetToolDrugNameMatch" == tool_type:
-                if "FDADrugLabelGetDrugGenericNameTool" not in self.callable_functions:
-                    drug_tool_class = get_tool_class_lazy(
+        try:
+            if tool_name is not None:
+                # Use lazy loading to get the tool class
+                tool_class = get_tool_class_lazy(tool_name)
+                if tool_class is None:
+                    raise KeyError(f"Tool type '{tool_name}' not found in registry")
+                new_tool = tool_class()
+            else:
+                tool_type = tool["type"]
+                tool_name = tool["name"]
+
+                # Use lazy loading to get the tool class
+                tool_class = get_tool_class_lazy(tool_type)
+                if tool_class is None:
+                    # Fallback to old method if lazy loading fails
+                    if tool_type not in tool_type_mappings:
+                        # Refresh registry and try again
+                        tool_type_mappings = get_tool_registry()
+                    if tool_type not in tool_type_mappings:
+                        raise KeyError(f"Tool type '{tool_type}' not found in registry")
+                    tool_class = tool_type_mappings[tool_type]
+
+                if "OpentargetToolDrugNameMatch" == tool_type:
+                    if (
                         "FDADrugLabelGetDrugGenericNameTool"
-                    )
-                    if drug_tool_class is None:
-                        drug_tool_class = tool_type_mappings[
+                        not in self.callable_functions
+                    ):
+                        drug_tool_class = get_tool_class_lazy(
                             "FDADrugLabelGetDrugGenericNameTool"
-                        ]
-                    self.callable_functions["FDADrugLabelGetDrugGenericNameTool"] = (
-                        drug_tool_class()
+                        )
+                        if drug_tool_class is None:
+                            drug_tool_class = tool_type_mappings[
+                                "FDADrugLabelGetDrugGenericNameTool"
+                            ]
+                        self.callable_functions[
+                            "FDADrugLabelGetDrugGenericNameTool"
+                        ] = drug_tool_class()
+                    new_tool = tool_class(
+                        tool_config=tool,
+                        drug_generic_tool=self.callable_functions[
+                            "FDADrugLabelGetDrugGenericNameTool"
+                        ],
                     )
-                new_tool = tool_class(
-                    tool_config=tool,
-                    drug_generic_tool=self.callable_functions[
-                        "FDADrugLabelGetDrugGenericNameTool"
-                    ],
-                )
-            elif "ToolFinderEmbedding" == tool_type:
-                new_tool = tool_class(tool_config=tool, tooluniverse=self)
-            elif "ComposeTool" == tool_type:
-                new_tool = tool_class(tool_config=tool, tooluniverse=self)
-            elif "ToolFinderLLM" == tool_type:
-                new_tool = tool_class(tool_config=tool, tooluniverse=self)
-            elif "ToolFinderKeyword" == tool_type:
-                new_tool = tool_class(tool_config=tool, tooluniverse=self)
-            else:
-                new_tool = tool_class(tool_config=tool)
-        if add_to_cache:
-            self.callable_functions[tool_name] = new_tool
-        return new_tool
+                elif "ToolFinderEmbedding" == tool_type:
+                    new_tool = tool_class(tool_config=tool, tooluniverse=self)
+                elif "ComposeTool" == tool_type:
+                    new_tool = tool_class(tool_config=tool, tooluniverse=self)
+                elif "ToolFinderLLM" == tool_type:
+                    new_tool = tool_class(tool_config=tool, tooluniverse=self)
+                elif "ToolFinderKeyword" == tool_type:
+                    new_tool = tool_class(tool_config=tool, tooluniverse=self)
+                else:
+                    new_tool = tool_class(tool_config=tool)
+
+            if add_to_cache:
+                self.callable_functions[tool_name] = new_tool
+            return new_tool
+
+        except Exception as e:
+            tool_type = tool_name if tool_name else tool.get("type")
+            mark_tool_unavailable(tool_type, e)
+            self.logger.warning(f"Failed to initialize '{tool_type}': {e}")
+            return None  # Return None instead of raising
+
+    def _get_tool_instance(self, function_name: str, cache: bool = True):
+        """Get or create tool instance with optional caching."""
+        # Check cache first
+        if function_name in self.callable_functions:
+            return self.callable_functions[function_name]
+
+        # Check if known unavailable
+        tool_errors = get_tool_errors()
+        if function_name in tool_errors:
+            self.logger.debug(f"Tool {function_name} is unavailable")
+            return None
+
+        # Try to initialize
+        if function_name in self.all_tool_dict:
+            return self.init_tool(self.all_tool_dict[function_name], add_to_cache=cache)
+
+        return None
+
+    def _make_cache_key(self, function_name: str, arguments: dict) -> str:
+        """Generate cache key by delegating to BaseTool."""
+        tool_instance = self._get_tool_instance(function_name, cache=False)
+
+        if tool_instance:
+            return tool_instance.get_cache_key(arguments)
+
+        # Fallback: simple hash-based key
+        serialized = json.dumps(
+            {"name": function_name, "args": arguments}, sort_keys=True
+        )
+        return hashlib.md5(serialized.encode()).hexdigest()
+
+    def _validate_parameters(
+        self, function_name: str, arguments: dict
+    ) -> Optional[ToolError]:
+        """Validate parameters by delegating to BaseTool."""
+        if function_name not in self.all_tool_dict:
+            return ToolUnavailableError(f"Tool '{function_name}' not found")
+
+        tool_instance = self._get_tool_instance(function_name, cache=False)
+        if not tool_instance:
+            return ToolConfigError("Failed to initialize tool for validation")
+
+        # Check if tool has validate_parameters method (for backward compatibility)
+        if hasattr(tool_instance, "validate_parameters"):
+            return tool_instance.validate_parameters(arguments)
+        else:
+            # Fallback for old-style tools without validate_parameters
+            # Just return None (no validation) to maintain backward compatibility
+            return None
+
+    def _check_basic_type(self, value: Any, expected_type: str) -> bool:
+        """Check if value matches expected basic type."""
+        type_mapping = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "object": dict,
+            "array": list,
+        }
+
+        if expected_type not in type_mapping:
+            return True  # Unknown type, skip validation
+
+        expected_python_type = type_mapping[expected_type]
+        return isinstance(value, expected_python_type)
+
+    def _classify_exception(
+        self, exception: Exception, function_name: str, arguments: dict
+    ) -> ToolError:
+        """Classify exception by delegating to BaseTool."""
+        tool_instance = self._get_tool_instance(function_name, cache=False)
+
+        if tool_instance:
+            return tool_instance.handle_error(exception)
+
+        # Fallback for tool instance creation failure
+        return ToolServerError(f"Unexpected error calling {function_name}: {exception}")
+
+    def _create_dual_format_error(self, error: ToolError) -> dict:
+        """Create dual-format error response for backward compatibility."""
+        return {
+            "error": str(error),  # Backward compatible string
+            "error_details": error.to_dict(),  # New structured format
+        }
+
+    def refresh_tools(self):
+        """Refresh tool discovery (re-discover MCP/remote tools, reload configs)."""
+        # TODO: Implement MCP tool re-discovery
+        # For now, just reload tool configurations
+        self.logger.info("Refreshing tool configurations...")
+        # This could be extended to re-discover MCP tools, reload configs, etc.
+        self.logger.info("Tool refresh completed")
+
+    def eager_load_tools(self, names: Optional[List[str]] = None):
+        """Pre-instantiate tools to reduce first-call latency."""
+        tool_names = names or list(self.all_tool_dict.keys())
+        self.logger.info(f"Eager loading {len(tool_names)} tools...")
+
+        for tool_name in tool_names:
+            if (
+                tool_name in self.all_tool_dict
+                and tool_name not in self.callable_functions
+            ):
+                try:
+                    self.init_tool(self.all_tool_dict[tool_name], add_to_cache=True)
+                    self.logger.debug(f"Eager loaded: {tool_name}")
+                except Exception as e:
+                    self.logger.warning(f"Failed to eager load {tool_name}: {e}")
+
+        self.logger.info(
+            f"Eager loading completed. {len(self.callable_functions)} tools cached."
+        )
+
+    def clear_cache(self):
+        """Clear the result cache."""
+        if self.cache_manager:
+            self.cache_manager.clear()
+        self.logger.info("Result cache cleared")
+
+    def get_cache_stats(self) -> Dict[str, Any]:
+        """Return cache statistics."""
+        if not self.cache_manager:
+            return {"enabled": False}
+        return self.cache_manager.stats()
+
+    def dump_cache(self, namespace: Optional[str] = None):
+        """Iterate over cached entries (persistent layer only)."""
+        if not self.cache_manager:
+            return iter([])
+        return self.cache_manager.dump(namespace=namespace)
+
+    def close(self):
+        """Release resources."""
+        if self.cache_manager:
+            self.cache_manager.close()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def get_tool_health(self, tool_name: str = None) -> dict:
+        """Get health status for tool(s)."""
+        tool_errors = get_tool_errors()
+
+        if tool_name:
+            if tool_name in tool_errors:
+                return tool_errors[tool_name]
+            elif tool_name in self.all_tool_dict:
+                return {"available": True}
+            return {"available": False, "error": "Not found"}
+
+        # Summary for all tools
+        return {
+            "total": len(self.all_tool_dict),
+            "available": len(self.all_tool_dict) - len(tool_errors),
+            "unavailable": len(tool_errors),
+            "unavailable_list": list(tool_errors.keys()),
+            "details": tool_errors,
+        }
 
     def check_function_call(self, fcall_str, function_config=None, format="llama"):
         """
@@ -1986,6 +2260,66 @@ class ToolUniverse:
             self.logger.error(f"Error exporting tool names to {output_file}: {e}")
             return []
 
+    def filter_tools(
+        self,
+        include_tools=None,
+        exclude_tools=None,
+        include_tool_types=None,
+        exclude_tool_types=None,
+    ):
+        """
+        Filter tools based on inclusion/exclusion criteria.
+
+        Args:
+            include_tools (set, optional): Set of tool names to include
+            exclude_tools (set, optional): Set of tool names to exclude
+            include_tool_types (set, optional): Set of tool types to include
+            exclude_tool_types (set, optional): Set of tool types to exclude
+
+        Returns:
+            list: Filtered list of tool configurations
+        """
+        if not hasattr(self, "all_tools") or not self.all_tools:
+            self.logger.warning("No tools loaded. Call load_tools() first.")
+            return []
+
+        filtered_tools = []
+        for tool in self.all_tools:
+            tool_name = tool.get("name", "")
+            tool_type = tool.get("type", "")
+
+            # Check inclusion/exclusion criteria
+            if include_tools and tool_name not in include_tools:
+                continue
+            if exclude_tools and tool_name in exclude_tools:
+                continue
+            if include_tool_types and tool_type not in include_tool_types:
+                continue
+            if exclude_tool_types and tool_type in exclude_tool_types:
+                continue
+
+            filtered_tools.append(tool)
+
+        return filtered_tools
+
+    def get_required_parameters(self, tool_name):
+        """
+        Get required parameters for a specific tool.
+
+        Args:
+            tool_name (str): Name of the tool
+
+        Returns:
+            list: List of required parameter names
+        """
+        if tool_name not in self.all_tool_dict:
+            self.logger.warning(f"Tool '{tool_name}' not found")
+            return []
+
+        tool_config = self.all_tool_dict[tool_name]
+        parameter_schema = tool_config.get("parameter", {})
+        return parameter_schema.get("required", [])
+
     def get_available_tools(self, category_filter=None, name_only=True):
         """
         Get available tools, optionally filtered by category.
@@ -2031,6 +2365,10 @@ class ToolUniverse:
             self.logger.warning("No tools loaded. Call load_tools() first.")
             return []
 
+        # Handle None or empty pattern
+        if pattern is None or pattern == "":
+            return self.all_tools
+
         import re
 
         flags = 0 if case_sensitive else re.IGNORECASE
@@ -2057,10 +2395,209 @@ class ToolUniverse:
         )
         return matching_tools
 
+    # ============ DEPRECATED METHODS (Kept for backward compatibility) ============
+    # These methods are deprecated and will be removed in v2.0. Use the recommended
+    # alternatives instead. All methods below maintain backward compatibility but
+    # issue deprecation warnings when called.
+
+    def get_tool_by_name(self, tool_names, format="default"):
+        """
+        Retrieve tool configurations by their names.
+
+        DEPRECATED: Use tool_specification() instead.
+
+        Args:
+            tool_names (list): List of tool names to retrieve.
+            format (str, optional): Output format. Options: 'default', 'openai'.
+                                   If 'openai', returns OpenAI function calling format. Defaults to 'default'.
+
+        Returns:
+            list: List of tool configurations for the specified names.
+                 Tools not found will be reported but not included in the result.
+        """
+        warnings.warn(
+            "get_tool_by_name() is deprecated and will be removed in v2.0. "
+            "Use tool_specification() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_tool_specification_by_names(tool_names, format=format)
+
+    def get_tool_description(self, tool_name):
+        """
+        Get the description of a tool by its name.
+
+        DEPRECATED: Use tool_specification() instead.
+
+        Args:
+            tool_name (str): Name of the tool.
+
+        Returns:
+            dict or None: Tool configuration if found, None otherwise.
+        """
+        warnings.warn(
+            "get_tool_description() is deprecated and will be removed in v2.0. "
+            "Use tool_specification() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_one_tool_by_one_name(tool_name)
+
+    def remove_keys(self, tool_list, invalid_keys):
+        """
+        Remove specified keys from a list of tool configurations.
+
+        DEPRECATED: Use prepare_tool_prompts(mode='custom', valid_keys=...) instead.
+
+        Args:
+            tool_list (list): List of tool configuration dictionaries.
+            invalid_keys (list): List of keys to remove from each tool configuration.
+
+        Returns:
+            list: Deep copy of tool list with specified keys removed.
+        """
+        warnings.warn(
+            "remove_keys() is deprecated and will be removed in v2.0. "
+            "Use prepare_tool_prompts(mode='custom', valid_keys=...) instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        copied_list = copy.deepcopy(tool_list)
+        for tool in copied_list:
+            # Create a list of keys to avoid modifying the dictionary during iteration
+            for key in list(tool.keys()):
+                if key in invalid_keys:
+                    del tool[key]
+        return copied_list
+
+    def prepare_tool_examples(self, tool_list):
+        """
+        Prepare tool configurations for example usage by keeping extended set of keys.
+
+        DEPRECATED: Use prepare_tool_prompts(mode='example') instead.
+
+        Args:
+            tool_list (list): List of tool configuration dictionaries.
+
+        Returns:
+            list: Deep copy of tool list with only example-relevant keys.
+        """
+        warnings.warn(
+            "prepare_tool_examples() is deprecated and will be removed in v2.0. "
+            "Use prepare_tool_prompts(mode='example') instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.prepare_tool_prompts(tool_list, mode="example")
+
+    def select_tools(
+        self,
+        include_names=None,
+        exclude_names=None,
+        include_categories=None,
+        exclude_categories=None,
+    ):
+        """
+        Select tools based on tool names and/or categories (tool_files keys).
+
+        DEPRECATED: Use filter_tools() instead.
+
+        Args:
+            include_names (list, optional): List of tool names to include. If None, include all.
+            exclude_names (list, optional): List of tool names to exclude.
+            include_categories (list, optional): List of categories (tool_files keys) to include.
+                                               If None, include all.
+            exclude_categories (list, optional): List of categories (tool_files keys) to exclude.
+
+        Returns:
+            list: List of selected tool configurations.
+        """
+        warnings.warn(
+            "select_tools() is deprecated and will be removed in v2.0. "
+            "Use filter_tools() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        selected_tools = []
+        # If categories are specified, use self.tool_category_dicts to filter
+        categories = set(self.tool_category_dicts.keys())
+        if include_categories is not None:
+            categories &= set(include_categories)
+        if exclude_categories is not None:
+            categories -= set(exclude_categories)
+        # Gather tools from selected categories
+        for cat in categories:
+            selected_tools.extend(self.tool_category_dicts[cat])
+        # Further filter by names if needed
+        if include_names is not None:
+            selected_tools = [
+                tool for tool in selected_tools if tool["name"] in include_names
+            ]
+        if exclude_names is not None:
+            selected_tools = [
+                tool for tool in selected_tools if tool["name"] not in exclude_names
+            ]
+        return selected_tools
+
+    def filter_tool_lists(
+        self,
+        tool_name_list,
+        tool_desc_list,
+        include_names=None,
+        exclude_names=None,
+        include_categories=None,
+        exclude_categories=None,
+    ):
+        """
+        Directly filter tool name and description lists based on names and/or categories.
+
+        DEPRECATED: Use filter_tools() and manual list filtering instead.
+
+        Args:
+            tool_name_list (list): List of tool names to filter.
+            tool_desc_list (list): List of tool descriptions to filter (must correspond to tool_name_list).
+            include_names (list, optional): List of tool names to include.
+            exclude_names (list, optional): List of tool names to exclude.
+            include_categories (list, optional): List of categories to include.
+            exclude_categories (list, optional): List of categories to exclude.
+
+        Returns:
+            tuple: A tuple containing (filtered_tool_name_list, filtered_tool_desc_list).
+        """
+        warnings.warn(
+            "filter_tool_lists() is deprecated and will be removed in v2.0. "
+            "Use filter_tools() and manual list filtering instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # Build a set of allowed tool names using select_tools for category filtering
+        allowed_names = set()
+        if any([include_names, exclude_names, include_categories, exclude_categories]):
+            filtered_tools = self.select_tools(
+                include_names=include_names,
+                exclude_names=exclude_names,
+                include_categories=include_categories,
+                exclude_categories=exclude_categories,
+            )
+            allowed_names = set(tool["name"] for tool in filtered_tools)
+        else:
+            allowed_names = set(tool_name_list)
+
+        # Filter lists by allowed_names
+        filtered_tool_name_list = []
+        filtered_tool_desc_list = []
+        for name, desc in zip(tool_name_list, tool_desc_list):
+            if name in allowed_names:
+                filtered_tool_name_list.append(name)
+                filtered_tool_desc_list.append(desc)
+        return filtered_tool_name_list, filtered_tool_desc_list
+
     def load_tools_from_names_list(self, tool_names, clear_existing=True):
         """
         Load only specific tools by their names.
 
+        DEPRECATED: Use load_tools(include_tools=...) instead.
+
         Args:
             tool_names (list): List of tool names to load
             clear_existing (bool): Whether to clear existing tools first
@@ -2068,6 +2605,12 @@ class ToolUniverse:
         Returns:
             int: Number of tools successfully loaded
         """
+        warnings.warn(
+            "load_tools_from_names_list() is deprecated and will be removed in v2.0. "
+            "Use load_tools(include_tools=...) instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if clear_existing:
             self.all_tools = []
             self.all_tool_dict = {}