microsoft/autogen · error · ValueError

tool_choice references '{tool_name}' but it's not in the pro

Error message

tool_choice references '{tool_name}' but it's not in the provided tools

What it means

Thrown by OpenAIChatCompletionClient when tool_choice is a Tool instance whose schema name does not appear in the provided tools list. The client validates that the forced tool is actually available to the model before building the request, preventing an API-side rejection.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py:649

        converted_tools = convert_tools(tools)

        # Process tool_choice parameter
        if isinstance(tool_choice, Tool):
            if len(tools) == 0:
                raise ValueError("tool_choice specified but no tools provided")

            # Validate that the tool exists in the provided tools
            tool_names_available: List[str] = []
            for tool in tools:
                if isinstance(tool, Tool):
                    tool_names_available.append(tool.schema["name"])
                else:
                    tool_names_available.append(tool["name"])

            # tool_choice is a single Tool object
            tool_name = tool_choice.schema["name"]
            if tool_name not in tool_names_available:
                raise ValueError(f"tool_choice references '{tool_name}' but it's not in the provided tools")

        if len(converted_tools) > 0:
            # Convert to OpenAI format and add to create_args
            converted_tool_choice = convert_tool_choice(tool_choice)
            create_args["tool_choice"] = converted_tool_choice

        return CreateParams(
            messages=oai_messages,
            tools=converted_tools,
            response_format=response_format_value,
            create_args=create_args,
        )

    async def create(
        self,
        messages: Sequence[LLMMessage],
        *,
        tools: Sequence[Tool | ToolSchema] = [],

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Make sure the tool referenced by tool_choice is included in the tools list by that exact name
2. Check for naming drift between the Tool object used for tool_choice and the registered tools
3. Use tool_choice='auto' or 'required' if you do not need to force one specific tool

Example fix

# before
tool_a = Tool(get_weather, ...)  # name='get_weather'
await client.create([msg], tools=[tool_a], tool_choice=Tool(lookup_stock, ...))  # name='lookup_stock'

# after
await client.create([msg], tools=[tool_a], tool_choice=tool_a)

def tool_names(tools):
    return [t.schema["name"] if hasattr(t, "schema") else t["name"] for t in tools]

if isinstance(tool_choice, Tool):
    assert tool_choice.schema["name"] in tool_names(tools), "tool_choice name not in tools"

def tool_choice_resolves(tool_choice, tools) -> bool:
    if not isinstance(tool_choice, Tool):
        return True
    return tool_choice.schema["name"] in tool_names(tools)

try:
    result = await client.create(messages, tools=tools, tool_choice=tool_choice)
except ValueError as e:
    if "not in the provided tools" in str(e):
        result = await client.create(messages, tools=tools, tool_choice="required")
    else:
        raise

When it happens

Trigger: Calling create with tool_choice=Tool(name='X') while the tools list contains only tools named other than 'X' (or only ToolSchema dicts whose 'name' differs). The name comparison uses the schema's 'name' field for both Tool objects and raw dicts.

Common situations: Renaming a tool but not the tool_choice reference; constructing tool_choice from a different tool set than tools (e.g. copy-paste across agents); passing a workbench subset of tools while forcing a tool excluded by the filter.

Related errors

• tool_choice specified but no tools provided
• Unsupported tool type: {type(tool)}
• Tool '{tool_name}' requires specific parameters and cannot b
• Unsupported built-in tool type: {tool_name}
• Unsupported tool type: {type(tool)}

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