microsoft/autogen · error · ValueError

Tool '{tool_name}' requires specific parameters and cannot b

Error message

Tool '{tool_name}' requires specific parameters and cannot be added using string format. Use dict configuration instead. Required parameters for {tool_name}: {self._get_required_params_help(tool_name)}

What it means

In OpenAIAgent, the built-in tools file_search, code_interpreter, computer_use_preview, and mcp all require per-tool parameters (vector store IDs, container config, display dimensions, server label/URL). Because the plain-string form carries no parameters, the agent refuses it and tells you to use the dict form, listing the required parameters via _get_required_params_help.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py:458

        # Only allow string format for tools that don't require parameters
        if tool_name == "web_search_preview":
            self._tools.append({"type": "web_search_preview"})
        elif tool_name == "image_generation":
            self._tools.append({"type": "image_generation"})
        elif tool_name == "local_shell":
            # Special handling for local_shell - very limited model support
            if self._model != "codex-mini-latest":
                raise ValueError(
                    f"Tool 'local_shell' is only supported with model 'codex-mini-latest', "
                    f"but current model is '{self._model}'. "
                    f"This tool is available exclusively through the Responses API and has severe limitations. "
                    f"Consider using autogen_ext.tools.code_execution.PythonCodeExecutionTool with "
                    f"autogen_ext.code_executors.local.LocalCommandLineCodeExecutor for shell execution instead."
                )
            self._tools.append({"type": "local_shell"})
        elif tool_name in ["file_search", "code_interpreter", "computer_use_preview", "mcp"]:
            # These tools require specific parameters and must use dict configuration
            raise ValueError(
                f"Tool '{tool_name}' requires specific parameters and cannot be added using string format. "
                f"Use dict configuration instead. Required parameters for {tool_name}: "
                f"{self._get_required_params_help(tool_name)}"
            )
        else:
            raise ValueError(f"Unsupported built-in tool type: {tool_name}")

    def _get_required_params_help(self, tool_name: str) -> str:
        """Get help text for required parameters of a tool."""
        help_text = {
            "file_search": "vector_store_ids (List[str])",
            "code_interpreter": "container (str | dict)",
            "computer_use_preview": "display_height (int), display_width (int), environment (str)",
            "mcp": "server_label (str), server_url (str)",
        }
        return help_text.get(tool_name, "unknown parameters")

    def _convert_message_to_dict(self, message: OpenAIMessage) -> Dict[str, Any]:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Switch to dict configuration with the parameters named in the message, e.g. {"type": "file_search", "vector_store_ids": [...]}.
2. Use the error's help table: file_search needs vector_store_ids (List[str]); code_interpreter needs container (str|dict); computer_use_preview needs display_height, display_width, environment; mcp needs server_label and server_url.
3. For MCP specifically, consider autogen-ext's dedicated MCP adapters (e.g. mcp_server adapters) which build Workbench tools for you.

Example fix

# before
agent = OpenAIAgent(name="a", model="gpt-4o", client=client, tools=["mcp"])

# after
agent = OpenAIAgent(
    name="a",
    model="gpt-4o",
    client=client,
    tools=[{"type": "mcp", "server_label": "fetch", "server_url": "https://mcp.example.com/sse"}],
)

NEEDS_DICT = {"file_search", "code_interpreter", "computer_use_preview", "mcp"}
for t in tools:
    if isinstance(t, str) and t in NEEDS_DICT:
        raise ConfigError(f"tool '{t}' requires dict configuration with parameters")

When it happens

Trigger: tools=["file_search"], tools=["code_interpreter"], tools=["computer_use_preview"], or tools=["mcp"] passed as strings to OpenAIAgent.

Common situations: Treating all built-in tools like web_search_preview (which does work as a bare string); quickly enabling code interpreter during prototyping; copy-pasting tool names from OpenAI docs without their parameter payloads.

Related errors

• Unsupported tool type: {type(tool)}
• Unsupported built-in tool type: {tool_name}
• Unsupported tool type: {type(tool)}
• Model does not support function calling
• tool_choice specified but no tools provided

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/ba612fe01750c958. Report an issue: GitHub.