{"record":{"id":"ba612fe01750c958","repo":"microsoft/autogen","slug":"tool-tool-name-requires-specific-parameters-an","errorCode":null,"errorMessage":"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)}","messagePattern":"Tool '(.+?)' requires specific parameters and cannot be added using string format\\. Use dict configuration instead\\. Required parameters for (.+?): (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py","lineNumber":458,"sourceCode":"        # Only allow string format for tools that don't require parameters\n        if tool_name == \"web_search_preview\":\n            self._tools.append({\"type\": \"web_search_preview\"})\n        elif tool_name == \"image_generation\":\n            self._tools.append({\"type\": \"image_generation\"})\n        elif tool_name == \"local_shell\":\n            # Special handling for local_shell - very limited model support\n            if self._model != \"codex-mini-latest\":\n                raise ValueError(\n                    f\"Tool 'local_shell' is only supported with model 'codex-mini-latest', \"\n                    f\"but current model is '{self._model}'. \"\n                    f\"This tool is available exclusively through the Responses API and has severe limitations. \"\n                    f\"Consider using autogen_ext.tools.code_execution.PythonCodeExecutionTool with \"\n                    f\"autogen_ext.code_executors.local.LocalCommandLineCodeExecutor for shell execution instead.\"\n                )\n            self._tools.append({\"type\": \"local_shell\"})\n        elif tool_name in [\"file_search\", \"code_interpreter\", \"computer_use_preview\", \"mcp\"]:\n            # These tools require specific parameters and must use dict configuration\n            raise ValueError(\n                f\"Tool '{tool_name}' requires specific parameters and cannot be added using string format. \"\n                f\"Use dict configuration instead. Required parameters for {tool_name}: \"\n                f\"{self._get_required_params_help(tool_name)}\"\n            )\n        else:\n            raise ValueError(f\"Unsupported built-in tool type: {tool_name}\")\n\n    def _get_required_params_help(self, tool_name: str) -> str:\n        \"\"\"Get help text for required parameters of a tool.\"\"\"\n        help_text = {\n            \"file_search\": \"vector_store_ids (List[str])\",\n            \"code_interpreter\": \"container (str | dict)\",\n            \"computer_use_preview\": \"display_height (int), display_width (int), environment (str)\",\n            \"mcp\": \"server_label (str), server_url (str)\",\n        }\n        return help_text.get(tool_name, \"unknown parameters\")\n\n    def _convert_message_to_dict(self, message: OpenAIMessage) -> Dict[str, Any]:","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py#L440-L476","documentation":"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.","triggerScenarios":"tools=[\"file_search\"], tools=[\"code_interpreter\"], tools=[\"computer_use_preview\"], or tools=[\"mcp\"] passed as strings to OpenAIAgent.","commonSituations":"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.","solutions":["Switch to dict configuration with the parameters named in the message, e.g. {\"type\": \"file_search\", \"vector_store_ids\": [...]}.","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.","For MCP specifically, consider autogen-ext's dedicated MCP adapters (e.g. mcp_server adapters) which build Workbench tools for you."],"exampleFix":"# before\nagent = OpenAIAgent(name=\"a\", model=\"gpt-4o\", client=client, tools=[\"mcp\"])\n\n# after\nagent = OpenAIAgent(\n    name=\"a\",\n    model=\"gpt-4o\",\n    client=client,\n    tools=[{\"type\": \"mcp\", \"server_label\": \"fetch\", \"server_url\": \"https://mcp.example.com/sse\"}],\n)","handlingStrategy":"validation","validationCode":"NEEDS_DICT = {\"file_search\", \"code_interpreter\", \"computer_use_preview\", \"mcp\"}\nfor t in tools:\n    if isinstance(t, str) and t in NEEDS_DICT:\n        raise ConfigError(f\"tool '{t}' requires dict configuration with parameters\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only web_search_preview, image_generation (and local_shell on codex) work as bare strings.","Centralize tool configs as dicts with a 'type' key for parameterized built-ins.","Use the error's help text as the parameter checklist."],"tags":["openai","tools","validation","responses-api"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}