OpenAI Agents SDK Duplicate Tool Names: Why the Later Tool Wins

OpenAI Agents SDK duplicate FunctionTool names can create ambiguous dispatch. Issue

Published · 2026-08-0310 min readXBSTACK
Evidence 7 cited sources
On this page

OpenAI Agents SDK Duplicate Tool Names: Why the Later Tool Wins

XBSTACK reproduced duplicate plain FunctionTool names in local registry/lookup fixtures on openai-agents 0.19.2 and 0.22.0. The fixtures show that Agent.get_all_tools() can return two lookup entries and that the bare lookup map keeps the later tool. They do not prove that Runner sends both definitions to the Provider.

The issue was filed in the official OpenAI Agents SDK repository on August 2, 2026 as issue #4116. It was closed through PR #4145, merged on August 4. The PR does not introduce RunConfig.tool_name_collision_policy; it applies the existing policy when reconciling queued function-tool and handoff calls after an approval interruption. The official policy defaults to warn, which logs a warning and exposes only the current dispatch winner; error raises UserError before the model call. The 0.22.0 fixture did not execute Runner or test either policy.

For an upgrade, use the exact version in your lockfile as the contract. Run both the application registry preflight and a Runner-level duplicate-name regression with tool_name_collision_policy="error" before removing safeguards. XBSTACK’s August 28 fixture only exercised 0.22.0 registry and lookup-map paths; it did not test Runner-level warn/error behavior or the current 0.24.0 release.

This page answers one narrow search problem:

Why can duplicate FunctionTool names enter an OpenAI Agents SDK Agent, why does local dispatch become last-wins, and how can a production service fail before sending a model request?

It is separate from the existing RunState approval resume guide. That article covers interruptions, approval, serialization, and cross-process recovery. This one covers tool-registry identity before the model call starts.

The smallest collision

The Python function names are different, but both public tool names are lookup:

from agents import function_tool


@function_tool(name_override="lookup")
def lookup_customers(query: str) -> str:
    """Look up customers."""
    return f"customer:{query}"


@function_tool(name_override="lookup")
def lookup_orders(query: str) -> str:
    """Look up orders."""
    return f"order:{query}"

The official tools documentation says @function_tool normally uses the Python function name and allows an explicit name_override. The identity that must be unique is the resulting FunctionTool.name, not the Python identifier.

This collision can emerge when:

  • CRM and order modules both export a generic lookup tool;
  • two plugins expose search;
  • an Agent.clone() flow appends the original tools again;
  • tenant or feature-flag logic adds tools dynamically;
  • sub-agents are converted to tools with repeated tool_name values;
  • multiple teams choose execute, query, or fetch as overrides;
  • an old and new implementation are registered during a migration.

Each module may be valid in isolation. The conflict appears only after the final registry is assembled.

Two OpenAI Agents SDK FunctionTools expose the same lookup name, both enter the Agent tool list, and local dispatch keeps only the later lookup_orders implementation

Offline test environment and version matrix

The fixtures avoid model behavior, API keys, network calls, and provider differences:

ComponentValue
Python3.10.2
OpenAI Agents SDK0.19.2 baseline and historical 0.22.0 local registry regression; not a current-release Runner test
API keyNot required
Model callNone
Verified pathsTool validation, Agent tool list, dispatch lookup map

The historical registry regression matrix is intentionally small and evidence-focused:

VersionValidatorAgent.get_all_tools()Bare lookup map
0.19.2accepts duplicate['lookup', 'lookup']later lookup_orders wins
0.22.0accepts duplicate['lookup', 'lookup']later lookup_orders wins

The second row was generated on August 28 with a fresh virtual environment and openai-agents==0.22.0. No API key or model request was used.

Files:

experiments/openai-agents-duplicate-tool-names-repro/
├── repro.py
├── verify_current_release.py
├── version-matrix.md
├── requirements.txt
├── results/verification.json
├── results/current-release.json
├── RESEARCH.md
└── README.md

Run it with:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python repro.py

Layer one: the SDK validator does not reject the conflict

The SDK contains a function with an explicit purpose:

validate_function_tool_lookup_configuration(tools)

Passing the duplicate tools returns normally:

result = validate_function_tool_lookup_configuration([
    lookup_customers,
    lookup_orders,
])

assert result is None

There is no UserError, warning, or deduplication.

Issue #4116 identifies the relevant branch: the validator detects an existing owner for the same qualified name, but when neither plain tool has an explicit namespace, it executes continue. The common collision is recognized and then ignored.

The issue also notes inconsistent handling across tool categories: duplicate names from MCP servers and Codex tools already have explicit checks, while plain FunctionTools do not receive the equivalent gate.

Layer two: Agent enumeration is not the Runner’s final request

After constructing the Agent, the local fixture reads its tool list:

from agents import Agent, RunContextWrapper

agent = Agent(
    name="Support",
    tools=[lookup_customers, lookup_orders],
)

tools = await agent.get_all_tools(
    RunContextWrapper(context=None),
)

print([tool.name for tool in tools])

The fixture prints:

['lookup', 'lookup']

This proves that Agent-level enumeration can contain both public names. It does not prove that Runner sends both definitions to the Provider. Runner applies RunConfig.tool_name_collision_policy before the model call: the default warn logs a warning and exposes the current dispatch winner; error raises UserError before the model is called. The local fixture did not exercise Runner with either policy.

The original upstream issue reported a provider-side 400 for duplicate function names on the older request path. Treat that as upstream-reported historical behavior, not as a result measured by the XBSTACK fixture on 0.22.0 or 0.24.0.

Layer three: local dispatch becomes last-wins

If a compatible provider accepts duplicate names and returns a tool call such as:

{
  "name": "lookup",
  "arguments": {"query": "A-100"}
}

then the SDK still needs to select a Python implementation.

The fixture builds the internal lookup map:

from agents._tool_identity import build_function_tool_lookup_map

lookup_map = build_function_tool_lookup_map([
    lookup_customers,
    lookup_orders,
])

Only one key remains:

('bare', 'lookup')

It points to the later tool:

selected = lookup_map[("bare", "lookup")]

assert selected is lookup_orders
assert selected is not lookup_customers

Verified output:

{
  "sdk_validator_returned_none": true,
  "advertised_tool_names": ["lookup", "lookup"],
  "dispatch_lookup_keys": [["bare", "lookup"]],
  "dispatch_selected_python_function": "lookup_orders",
  "first_tool_reachable_by_bare_name": false,
  "second_tool_reachable_by_bare_name": true
}

The later dictionary assignment replaces the earlier one.

Offline verification on openai-agents 0.19.2: the SDK validator does not fail, the Agent exposes two lookup tools, and local dispatch selects lookup_orders

Why silent last-wins is more dangerous than a 400

A provider 400 stops the request. It harms availability, but it does not execute the wrong operation. With the default warn policy, Runner logs a collision warning and exposes only the current dispatch winner; the model still cannot distinguish the original customer lookup from order lookup. Use error when ambiguous names must fail closed before the model call. A compatible Provider that accepts an older ambiguous payload may also expose the historical last-wins local dispatch risk.

Imagine that the two underlying implementations are:

lookup_customer_account
lookup_refund_order

If both are exposed as lookup, one tool may read customer data while the other initiates a refund, delete, message send, or database write. The identity collision becomes a side-effect risk.

The failure surface includes:

  • two indistinguishable schemas sent to the model;
  • provider request rejection;
  • incorrect local implementation selection;
  • audit logs that show only the ambiguous public name;
  • retries that repeat the deterministic configuration problem;
  • different failure behavior after switching providers.

Historical 0.22.0 registry fixture: Agent-level enumeration and local lookup only.

The offline fixture checks three local registry boundaries: explicit validation, Agent tool resolution, and lookup-map construction. On 0.22.0, validation returns normally, both names remain in the Agent tool list, and the later tool wins the bare lookup map. The fixture does not call Runner and therefore does not measure RunConfig collision policy.

Checkopenai-agents==0.22.0 result
Python3.10.2
Agent.get_all_tools()Two entries named lookup
Bare lookup-map winnerlookup_orders
Runner with warn/error policyNot tested
API/model call required by fixtureNo

The issue was closed through PR #4145. The RunConfig reference now documents warn as the default policy and error as a fail-before-model-call policy. The 0.22.0 fixture does not establish behavior for Runner or the current 0.24.0 release.

Configure the SDK collision policy

The official RunConfig reference documents tool_name_collision_policy. It controls collisions between unnamespaced function-tool and handoff names; strict validation for namespaced and deferred-loading tools remains separate. The default warn mode logs a warning and exposes the current dispatch winner; error raises UserError before the model call. For a fail-closed workflow, configure error explicitly:

from agents import Agent, RunConfig, Runner

agent = Agent(name="Support", tools=[...])

result = await Runner.run(
    agent,
    "Run a safe preflight task",
    run_config=RunConfig(tool_name_collision_policy="error"),
)

The application should still validate unique business tool names after all dynamic tools are assembled; warn is not a substitute for an explicit uniqueness contract.

Temporary fix: validate uniqueness before model dispatch

Even with the SDK policy, applications should validate the final registry after assembling static tools, plugins, MCP-derived tools, agent tools, and handoffs:

from collections import Counter
from collections.abc import Iterable

from agents import FunctionTool
from agents.exceptions import UserError


def find_duplicate_function_tool_names(
    tools: Iterable[object],
) -> list[str]:
    names = [
        tool.name
        for tool in tools
        if isinstance(tool, FunctionTool)
    ]

    return sorted(
        name
        for name, count in Counter(names).items()
        if count > 1
    )


def require_unique_function_tool_names(
    tools: Iterable[object],
) -> None:
    duplicates = find_duplicate_function_tool_names(tools)
    if duplicates:
        quoted = ", ".join(repr(name) for name in duplicates)
        raise UserError(
            "Duplicate FunctionTool names are not allowed: "
            f"{quoted}. Use a unique Python function name, "
            "name_override=, or a tool namespace."
        )

Apply it to the final set:

tools = load_static_tools()
tools += load_plugin_tools()
tools += await load_tenant_tools(tenant_id)

require_unique_function_tool_names(tools)

agent = Agent(
    name="Support",
    tools=tools,
)

The duplicate fixture now fails locally with an actionable message instead of waiting for a provider response:

Duplicate FunctionTool names are not allowed: 'lookup'.
Use a unique Python function name, name_override=, or a tool namespace.

Fix the public names

Give the second tool a distinct identity:

@function_tool(name_override="lookup_orders")
def lookup_orders(query: str) -> str:
    """Look up orders."""
    return f"order:{query}"

The resulting list is:

['lookup', 'lookup_orders']

Prefer business-specific names over numeric suffixes:

customer_lookup
order_lookup
invoice_lookup
knowledge_search
shipment_track

A good name helps the model distinguish capabilities as well as satisfying the uniqueness constraint.

Use namespaces for larger registries

The official tools documentation recommends namespaces where possible, especially when many related tools exist. A registry can expose clearer identities such as:

crm.lookup_customer
orders.lookup_order
billing.lookup_invoice

Namespaces reduce collisions on generic verbs such as lookup, search, and create, and give the model a better high-level surface.

They do not replace testing. CI should validate the actual assembled callable identities rather than only checking source-level function names.

Where the gate should run

Agent factory unit tests

def test_support_agent_tool_names_are_unique():
    tools = build_support_tools()
    require_unique_function_tool_names(tools)

Plugin registration

Validate after all plugins load. Per-plugin uniqueness cannot detect collisions between plugins.

Multi-tenant configuration

Different tenants can enable different combinations. Precompute valid combinations or validate and cache each final set at worker startup or request entry.

Clone and dynamic append paths

Cloning, list concatenation, feature flags, and A/B tests are common duplication sources. Validate the final list rather than the initial constant.

Release gates

CI can enumerate production factories:

for agent_name, tools in all_production_toolsets():
    try:
        require_unique_function_tool_names(tools)
    except UserError as exc:
        raise AssertionError(f"{agent_name}: {exc}") from exc

Mitigation and release gate for duplicate OpenAI Agents SDK tool names: assemble the final tool set, run a unique-name preflight, resolve collisions, and enforce factory and CI checks

Name uniqueness is only the first registry check

A production tool registry should also validate:

CheckFailure risk
Unique FunctionTool.nameProvider 400 or wrong dispatch
Stable tool schemaCache invalidation and argument drift
Distinct descriptionsUnstable model selection
Approval or guardrails for high-risk toolsUnauthorized side effects
Stable tool IDs in audit logsInability to identify implementation
Reproducible dynamic enablementDifferent workers expose different registries

For authorization and policy enforcement, continue with the AI Agent Tool Authorization Policy Gate. This page remains limited to naming identity.

Three approaches to avoid

Waiting for the provider 400

A deterministic local error is delayed until after network work, increasing latency, retry noise, and debugging cost. A provider change can convert the visible 400 into silent wrong dispatch.

Treating list order as configuration

Import order, plugin discovery, and configuration merging can change ordering. Last-wins is not an explicit or auditable routing policy.

Checking only __name__

Different Python functions can share the same public name through name_override. Validate FunctionTool.name.

Regression test after the upstream status change

Issue #4116 is closed through PR #4145. The PR applies the existing collision policy when reconciling queued function-tool and handoff calls after approval resume; it does not make the default warn policy fail closed. For a production release, explicitly configure tool_name_collision_policy="error" and keep an application-level uniqueness check after all static, plugin, MCP-derived, Agent-as-tool, and conditional tools have been assembled.

Test the deployed SDK through Runner, not only through the local validator or Agent.get_all_tools():

import pytest
from agents import Agent, RunConfig, Runner
from agents.exceptions import UserError


@pytest.mark.asyncio
async def test_runner_rejects_duplicate_bare_function_tools():
    agent = Agent(name="Support", tools=[lookup_customers, lookup_orders])
    with pytest.raises(UserError):
        await Runner.run(
            agent,
            "Run a safe preflight task",
            run_config=RunConfig(tool_name_collision_policy="error"),
        )

Also verify that:

  1. the configured error policy fails before a model request;
  2. the default warn policy logs and exposes only the documented dispatch winner;
  3. dynamic and static collisions are both detected after final registry assembly;
  4. approval-resume paths reconcile queued calls against the current enabled tool inventory;
  5. namespace, deferred-loading, MCP, and handoff collision rules match the deployed SDK version.

Relationship to the RunState article

The OpenAI Agents SDK RunState guide covers:

  • tool-approval interruptions;
  • RunState serialization;
  • cross-process resume;
  • redelivery and business idempotency;
  • context filtering and version governance.

This problem happens earlier. The tool registry is already ambiguous before the Agent sends a model request. A durable approval pipeline cannot make an ambiguous tool identity safe.

Conclusion

Duplicate FunctionTool names in OpenAI Agents SDK still reproduce locally on current 0.22.0, with the same two failure modes described by the original 0.19.2 investigation:

  • strict providers reject the duplicate function definitions;
  • tolerant providers allow the request, while local dispatch keeps the later implementation.

The offline XBSTACK fixtures verify on both 0.19.2 and 0.22.0:

SDK validator       -> no error
Agent tools          -> ['lookup', 'lookup']
Local dispatch map   -> later lookup_orders only
First tool reachable -> False

For the behavior reproduced here on both 0.19.2 and current 0.22.0—and for any later release that has not yet passed your own collision regression—production systems should:

  1. validate unique FunctionTool.name values after final registry assembly;
  2. use explicit business-specific names or name_override;
  3. organize larger tool sets with namespaces;
  4. run the check in factory tests, plugin registration, and release gates;
  5. keep a version-pinned regression test during SDK upgrades.

This configuration should fail at local startup, not through a provider 400 or an incorrect external side effect.

References

Topic path / AI Agents

Continue from one agent pattern to the complete production system

The AI Agent hub organizes architecture, memory, tool use, evaluation, security, deployment and multi-agent coordination into a single learning path.

Next step: continue the Agent system

Full decision path →

Choose the next architecture, tool, memory, evaluation, security, or production decision instead of starting over.

Continue with state and memoryOpenAI Agents SDK RunState: How to Resume Tool Approval Across ProcessesResume OpenAI Agents SDK Tool Approval with RunState across processes. Test to_json/from_json, approve/reject, redelivery, idempotency, and the v0.19.3 streaming fix.Continue with state and memoryImplementing AI Agent Memory Systems: A 3-Layer Architecture and Practical Code to Solve Agent 'Amnesia'Build AI Agent Memory with thread state, conversation context, cross-session facts, calibrated retrieval, tenant isolation, deletion, and storage tradeoffs.Refine the system architectureAutoGen Archived: AgentChat Teams and Agent Framework MigrationArchived AutoGen migration guide covering legacy AgentChat teams, termination, state and the move to Microsoft Agent Framework.
Comments & evidence

DISCUSSION

Questions, verification and corrections

Sign in to comment. Every new comment is reviewed before publication; while pending, it is visible only to you and the administrator.

Sign-in required Reviewed before public
Loading the discussion…