OpenAI Agents SDK Duplicate Tool Names: Why the Later Tool Wins
OpenAI Agents SDK duplicate FunctionTool names can create ambiguous dispatch. Issue
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
lookuptool; - 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_namevalues; - multiple teams choose
execute,query, orfetchas 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.

Offline test environment and version matrix
The fixtures avoid model behavior, API keys, network calls, and provider differences:
| Component | Value |
|---|---|
| Python | 3.10.2 |
| OpenAI Agents SDK | 0.19.2 baseline and historical 0.22.0 local registry regression; not a current-release Runner test |
| API key | Not required |
| Model call | None |
| Verified paths | Tool validation, Agent tool list, dispatch lookup map |
The historical registry regression matrix is intentionally small and evidence-focused:
| Version | Validator | Agent.get_all_tools() | Bare lookup map |
|---|---|---|---|
0.19.2 | accepts duplicate | ['lookup', 'lookup'] | later lookup_orders wins |
0.22.0 | accepts 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.

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.
| Check | openai-agents==0.22.0 result |
|---|---|
| Python | 3.10.2 |
| Agent.get_all_tools() | Two entries named lookup |
| Bare lookup-map winner | lookup_orders |
| Runner with warn/error policy | Not tested |
| API/model call required by fixture | No |
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

Name uniqueness is only the first registry check
A production tool registry should also validate:
| Check | Failure risk |
|---|---|
Unique FunctionTool.name | Provider 400 or wrong dispatch |
| Stable tool schema | Cache invalidation and argument drift |
| Distinct descriptions | Unstable model selection |
| Approval or guardrails for high-risk tools | Unauthorized side effects |
| Stable tool IDs in audit logs | Inability to identify implementation |
| Reproducible dynamic enablement | Different 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:
- the configured
errorpolicy fails before a model request; - the default
warnpolicy logs and exposes only the documented dispatch winner; - dynamic and static collisions are both detected after final registry assembly;
- approval-resume paths reconcile queued calls against the current enabled tool inventory;
- 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:
- validate unique
FunctionTool.namevalues after final registry assembly; - use explicit business-specific names or
name_override; - organize larger tool sets with namespaces;
- run the check in factory tests, plugin registration, and release gates;
- 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
- OpenAI Agents SDK issue #4116: Reject duplicate function tool names
- OpenAI Agents SDK: Tools
- OpenAI Agents SDK: 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.
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.