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

MCPClient's structured_output parameter currently defaults to False (legacy behavior) but will default to True in smolagents 1.25. Passing structured_output=None (or omitting it) emits this FutureWarning explaining how to pin either behavior explicitly.

Source

Thrown at src/smolagents/mcp_client.py:93

        try:
            mcp_client = MCPClient(...)
            tools = mcp_client.get_tools()

            # use your tools here.
        finally:
            mcp_client.disconnect()
        ```
    """

    def __init__(
        self,
        server_parameters: "StdioServerParameters" | dict[str, Any] | list["StdioServerParameters" | dict[str, Any]],
        adapter_kwargs: dict[str, Any] | None = None,
        structured_output: bool | None = None,
    ):
        # 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 ModuleNotFoundError:
            raise ModuleNotFoundError("Please install 'mcp' extra to use MCPClient: `pip install 'smolagents[mcp]'`")
        if isinstance(server_parameters, dict):
            transport = server_parameters.get("transport")
            if transport is None:
                transport = "streamable-http"

View on GitHub (pinned to 30bb116109)

Solutions

Decide behavior explicitly: pass structured_output=True to get schema-parsed tool outputs now
Pass structured_output=False to keep legacy string outputs if your prompts expect them
Run your test suite both ways before 1.25 lands to detect breakage early

Example fix

# before
client = MCPClient(server_parameters)

# after
client = MCPClient(server_parameters, structured_output=True)

Defensive patterns

Strategy: validation

Validate before calling

client = MCPClient(server_parameters, structured_output=True)  # or False, but always explicit

Try / catch

import warnings
with warnings.catch_warnings():
    warnings.simplefilter('ignore', FutureWarning)
    client = MCPClient(server_parameters)

Prevention

Always pass structured_output explicitly
Test MCP tools against both True and False before 1.25
Subscribe to smolagents release notes for default flips

When it happens

Trigger: Creating MCPClient(server_parameters) without structured_output after upgrading; MCP tool outputs then default to plain strings, with a warning nudging explicit choice.

Common situations: Upgrading smolagents across the 1.25 boundary; MCP tools whose output schema parsing (structured dicts vs strings) changes subtly after the default flip breaks downstream parsing.

Related errors

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