huggingface/smolagents · warning · FutureWarning

Parameter 'structured_output' was not specified. Currently i

Error message

Parameter 'structured_output' was not specified. Currently it defaults to False, but in version 1.25, the default will change to True. To suppress this warning, explicitly set structured_output=True (new behavior) or structured_output=False (legacy behavior). See documentation at https://huggingface.co/docs/smolagents/tutorials/tools#structured-output-and-output-schema-support for more details.

What it means

`ToolCollection.from_mcp(...)` (and `from_mcp` generally) is transitioning its `structured_output` parameter from defaulting to False to defaulting to True in smolagents 1.25. Structured output changes how tool results are returned (typed/schema-validated vs raw strings), so the default flip can break existing agents. The FutureWarning tells you to pin the behavior explicitly now.

Source

Thrown at src/smolagents/tools.py:1026

        ```

        Example with structured output enabled:
        ```py
        >>> with ToolCollection.from_mcp(server_parameters, trust_remote_code=True, structured_output=True) as tool_collection:
        >>>     agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True, model=model)
        >>>     agent.run("Please find a remedy for hangover.")
        ```

        Example with a Streamable HTTP MCP server:
        ```py
        >>> with ToolCollection.from_mcp({"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}, trust_remote_code=True) as tool_collection:
        >>>     agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True, model=model)
        >>>     agent.run("Please find a remedy for hangover.")
        ```
        """
        # Handle future warning for structured_output default value change
        if structured_output is None:
            warnings.warn(
                "Parameter 'structured_output' was not specified. "
                "Currently it defaults to False, but in version 1.25, the default will change to True. "
                "To suppress this warning, explicitly set structured_output=True (new behavior) or structured_output=False (legacy behavior). "
                "See documentation at https://huggingface.co/docs/smolagents/tutorials/tools#structured-output-and-output-schema-support for more details.",
                FutureWarning,
                stacklevel=2,
            )
            structured_output = False

        try:
            from mcpadapt.core import MCPAdapt
            from mcpadapt.smolagents_adapter import SmolAgentsAdapter
        except ImportError:
            raise ImportError(
                """Please install 'mcp' extra to use ToolCollection.from_mcp: `pip install 'smolagents[mcp]'`."""
            )
        if isinstance(server_parameters, dict):
            transport = server_parameters.get("transport")

View on GitHub (pinned to 30bb116109)

Solutions

Set `structured_output=False` now to keep current (legacy) behavior and silence the warning
Or set `structured_output=True` to opt into the new behavior early and update downstream result handling before 1.25
Pin your smolagents version (<1.25) if you cannot change code yet, then migrate deliberately

Example fix

# before
tools = ToolCollection.from_mcp({"url": "http://127.0.0.1:8000/mcp"})

# after
tools = ToolCollection.from_mcp({"url": "http://127.0.0.1:8000/mcp"}, structured_output=True)

Defensive patterns

Strategy: validation

Validate before calling

# before constructing, decide the behavior explicitly
EXPECTED_STRUCTURED = True  # flip to False for legacy behavior
tools = ToolCollection.from_mcp(server_params, structured_output=EXPECTED_STRUCTURED)

Prevention

Always pass structured_output explicitly to from_mcp
Pin smolagents version in requirements to control when the 1.25 default change lands
Run your MCP tool tests with warnings-as-errors to catch un-pinned defaults early

When it happens

Trigger: Calling `ToolCollection.from_mcp({...})` or `Tool.from_mcp(...)` without passing `structured_output`; the signature default is the sentinel `None`, which triggers the warning before falling back to legacy False behavior.

Common situations: Migrating to smolagents versions near 1.25; MCP-based agents whose tool-call parsing or answer formatting breaks after the default changes; CI logs filling with FutureWarnings from MCP integration tests.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/07087ddadab59629. Report an issue: GitHub.