{"record":{"id":"2da55f0938cbd8c7","repo":"microsoft/autogen","slug":"unsupported-built-in-tool-type-tool-name","errorCode":null,"errorMessage":"Unsupported built-in tool type: {tool_name}","messagePattern":"Unsupported built-in tool type: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py","lineNumber":464,"sourceCode":"            # 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]:\n        \"\"\"Convert an OpenAIMessage to a Dict[str, Any].\"\"\"\n        return dict(message)\n\n    @property\n    def produced_message_types(\n        self: \"OpenAIAgent\",","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/agents/openai/_openai_agent.py#L446-L482","documentation":"OpenAIAgent._add_builtin_tool ends in a final else: any tool string that is not one of the known built-ins (web_search_preview, image_generation, local_shell, file_search, code_interpreter, computer_use_preview, mcp) is rejected. This catches typos and tool names the installed OpenAI API layer does not recognize as string-configurable.","triggerScenarios":"tools=[\"web_search\"] (the actual built-in is web_search_preview), tools=[\"code_executor\"], or any other unrecognized string.","commonSituations":"Typos and abbreviated names (web_search vs web_search_preview); using newer OpenAI built-in tool names not yet supported by the installed autogen-ext version; confusing autogen-core tool names with OpenAI built-in tool types.","solutions":["Correct the name to one of the supported built-ins: web_search_preview, image_generation, local_shell, file_search, code_interpreter, computer_use_preview, mcp.","For custom or function tools, register them through the model client / agent runtime rather than the built-in tools list.","If you believe the name is a valid newer OpenAI tool type, pass it as a dict with a \"type\" key, or upgrade autogen-ext to a version that whitelists it."],"exampleFix":"# before\nagent = OpenAIAgent(name=\"a\", model=\"gpt-4o\", client=client, tools=[\"web_search\"])\n\n# after\nagent = OpenAIAgent(name=\"a\", model=\"gpt-4o\", client=client, tools=[\"web_search_preview\"])","handlingStrategy":"validation","validationCode":"KNOWN_BUILTINS = {\"web_search_preview\", \"image_generation\", \"local_shell\",\n                   \"file_search\", \"code_interpreter\", \"computer_use_preview\", \"mcp\"}\nunknown = [t for t in tools if isinstance(t, str) and t not in KNOWN_BUILTINS]\nassert not unknown, f\"Unknown built-in tools: {unknown}\"","typeGuard":"def is_known_builtin(name: str) -> bool:\n    return name in {\"web_search_preview\", \"image_generation\", \"local_shell\",\n                    \"file_search\", \"code_interpreter\", \"computer_use_preview\", \"mcp\"}","tryCatchPattern":null,"preventionTips":["Use web_search_preview, not web_search.","Check the supported list for your autogen-ext version before adding new tool names.","Linter/CI check tool-name lists against a constant set."],"tags":["openai","tools","validation","typo"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}