deepset-ai/haystack · warning · FutureWarning

Combining Toolsets and Tools with '+' is deprecated and will

Error message

Combining Toolsets and Tools with '+' is deprecated and will be removed in Haystack 3.2.0. Pass them as a list wherever tools are accepted instead, e.g. Agent(tools=[toolset_a, toolset_b]).

What it means

Toolset.__add__ in haystack/tools/toolset.py unconditionally emits this FutureWarning because combining toolsets with the '+' operator is deprecated and will be removed in Haystack 3.2.0. Any use of toolset + tool, toolset + toolset, or toolset + list returns a _ToolsetWrapper but is now discouraged in favor of plain lists.

Source

Thrown at haystack/tools/toolset.py:281

            if not issubclass(tool_class, Tool):
                raise TypeError(f"Class '{tool_class}' is not a subclass of Tool")
            tools.append(tool_class.from_dict(tool_data))

        return cls(tools=tools)

    def __add__(self, other: "Tool | Toolset | list[Tool]") -> "Toolset":
        """
        Concatenate this Toolset with another Tool, Toolset, or list of Tools.

        Deprecated: will be removed in Haystack 3.2.0. Pass tools and Toolsets as a list wherever tools
        are accepted instead, e.g. `Agent(tools=[toolset_a, toolset_b])`.

        :param other: Another Tool, Toolset, or list of Tools to concatenate
        :returns: A new Toolset containing all tools
        :raises TypeError: If the other parameter is not a Tool, Toolset, or list of Tools
        :raises ValueError: If the combination would result in duplicate tool names
        """
        warnings.warn(
            "Combining Toolsets and Tools with '+' is deprecated and will be removed in Haystack 3.2.0. "
            "Pass them as a list wherever tools are accepted instead, e.g. Agent(tools=[toolset_a, toolset_b]).",
            FutureWarning,
            stacklevel=2,
        )
        if isinstance(other, Tool):
            return Toolset(tools=self.tools + [other])
        if isinstance(other, Toolset):
            return _ToolsetWrapper([self, other])
        if isinstance(other, list) and all(isinstance(item, Tool) for item in other):
            return Toolset(tools=self.tools + other)
        raise TypeError(f"Cannot add {type(other).__name__} to Toolset")

    def __len__(self) -> int:
        """
        Return the number of Tools in this Toolset.

        :returns: Number of Tools

View on GitHub (pinned to e318778c9b)

Solutions

Replace '+' expressions with a list of tools/toolsets passed where tools are accepted, e.g. Agent(tools=[toolset_a, toolset_b])
Mix tools and toolsets in one list: Agent(tools=[toolset_a, tool1, tool2])
If a single Toolset object is truly needed, construct it from a flat list of Tools instead of using +
Temporarily filter with warnings.filterwarnings('ignore', category=FutureWarning, module='haystack') until the 3.2.0 removal

Example fix

# before
combined = toolset_a + toolset_b
agent = Agent(chat_generator=gen, tools=[combined])
# after
agent = Agent(chat_generator=gen, tools=[toolset_a, toolset_b])
# or mixing tools:
agent = Agent(chat_generator=gen, tools=[toolset_a, tool1, tool2])

Defensive patterns

Strategy: type-guard

Validate before calling

from haystack.tools import Tool, Toolset, Toolset as TS

def normalize_tools(items) -> list:
    """Normalize tools/toolsets to a plain list, avoiding deprecated '+'."""
    if isinstance(items, Toolset):
        return [items]
    if isinstance(items, Tool):
        return [items]
    return list(items)

Type guard

from haystack.tools import Tool, Toolset

def can_use_plus(left, right) -> bool:
    # '+' on Toolset always warns; refuse to use it
    if isinstance(left, Toolset):
        return False
    return isinstance(left, (Tool, list))

Try / catch

import warnings

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", FutureWarning)
    combined = toolset_a + toolset_b
    if any(issubclass(w.category, FutureWarning) for w in caught):
        warnings.warn("Replace '+' with a list: Agent(tools=[toolset_a, toolset_b])", FutureWarning)

Prevention

Never use '+' to combine Toolsets; always build lists instead
Prefer plain list[Tool | Toolset] in your own APIs instead of combined Toolset objects
Run tests with -W error::FutureWarning to fail fast on deprecated operator use
Plan removal before Haystack 3.2.0 when the operator support is deleted

When it happens

Trigger: Any expression using '+' with a Toolset on the left: toolset_a + tool_b, toolset_a + toolset_b, toolset_a + [tool1, tool2], or chained forms like toolset_a + toolset_b + tool_c. The warning fires before the type of other is even inspected.

Common situations: Legacy code building tool collections with + operators; migration guides or snippets written for Haystack 2.x; code that will break when the operator support is deleted in 3.2.0.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/c407a91613fdd7f5. Report an issue: GitHub.