›_ Claude Code Issues
Claude Code Issues / #12994

[BUG] Custom agents fail with "Tool names must be unique" error

Open 💬 4 comments Opened Dec 3, 2025 by wobrien-pronetx

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report (please file separate reports for different bugs)
  • [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: "Tool names must be unique" Error When Using Custom Agents

Summary

Unable to launch any custom agents via the Task tool - consistently receiving API error: "tools: Tool names must be unique"

Environment

  • Claude Code Version: Latest (as of 2025-12-03)
  • Platform: macOS (Darwin 25.2.0)
  • Model: claude-sonnet-4-5-20250929
  • Working Directory: /Users/bill/projects/spam-lambda

Steps to Reproduce

  1. Create custom agent files in .claude/agents/ directory (e.g., aws-lambda-expert.md, spam-email-detector.md)
  2. Agent files are properly formatted with frontmatter:

``markdown
---
name: aws-lambda-expert
description: Use this agent when...
model: sonnet
color: purple
---
[Agent prompt content]
``

  1. Attempt to launch any agent using the Task tool:

``
Task(
subagent_type: "aws-lambda-expert",
description: "Design Lambda architecture",
prompt: "..."
)
``

Expected Behavior

The agent should launch successfully and execute the task autonomously, returning results.

Actual Behavior

Immediately returns API error:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."},"request_id":"req_011CVkCDWnbJKjcZUkm6ucnW"}

Additional Context

Agent Files Created

  • aws-lambda-expert.md (5622 bytes)
  • spam-email-detector.md (7400 bytes)
  • unit-test-expert.md (6095 bytes)
  • unit-test-researcher.md (6038 bytes)
  • research-orchestrator.md (6152 bytes)
  • aws-deployment-expert.md (6626 bytes)
  • documentation-expert.md (5697 bytes)

Settings Configuration

.claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Bash(npm install)"
    ],
    "deny": [],
    "ask": []
  }
}

Error Consistency

  • Error occurs for ALL custom agents (tried multiple different agents)
  • Error occurs regardless of agent complexity or prompt length
  • Error occurs when launching agents sequentially or in parallel
  • Built-in subagent types (general-purpose, Explore, etc.) work correctly

Root Cause Analysis

The error "Tool names must be unique" suggests that when the Task tool sets up the agent subprocess environment, it's creating duplicate tool definitions. This is NOT caused by the agent configuration files themselves, as they contain no tool definitions - they only contain prompts and frontmatter.

Possible causes:

  1. Task tool is duplicating tool definitions when copying them to agent context
  2. Agent inheritance mechanism is causing tool name collisions
  3. Recent regression in how custom agents are initialized

Impact

  • Severity: High - Custom agents are completely non-functional
  • Workaround: None - cannot use custom agents at all
  • User Impact: Users cannot leverage specialized agent workflows they've configured

Reproduction Rate

100% - Error occurs every single time with any custom agent

Request IDs (for debugging)

  • req_011CVkCDWnbJKjcZUkm6ucnW
  • req_011CVkCDWVjM2c9XPwT77Nw5
  • req_011CVkCE2NaTE4wSdZTRREmH
  • req_011CVkCKdu8wJGNRqcyfkQ2P

Suggested Fix

Investigate the Task tool's agent initialization logic to ensure tool definitions are not being duplicated when setting up the agent subprocess environment.

What Should Happen?

Bug Report: "Tool names must be unique" Error When Using Custom Agents

Summary

Unable to launch any custom agents via the Task tool - consistently receiving API error: "tools: Tool names must be unique"

Environment

  • Claude Code Version: Latest (as of 2025-12-03)
  • Platform: macOS (Darwin 25.2.0)
  • Model: claude-sonnet-4-5-20250929
  • Working Directory: /Users/bill/projects/spam-lambda

Steps to Reproduce

  1. Create custom agent files in .claude/agents/ directory (e.g., aws-lambda-expert.md, spam-email-detector.md)
  2. Agent files are properly formatted with frontmatter:

``markdown
---
name: aws-lambda-expert
description: Use this agent when...
model: sonnet
color: purple
---
[Agent prompt content]
``

  1. Attempt to launch any agent using the Task tool:

``
Task(
subagent_type: "aws-lambda-expert",
description: "Design Lambda architecture",
prompt: "..."
)
``

Expected Behavior

The agent should launch successfully and execute the task autonomously, returning results.

Actual Behavior

Immediately returns API error:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."},"request_id":"req_011CVkCDWnbJKjcZUkm6ucnW"}

Additional Context

Agent Files Created

  • aws-lambda-expert.md (5622 bytes)
  • spam-email-detector.md (7400 bytes)
  • unit-test-expert.md (6095 bytes)
  • unit-test-researcher.md (6038 bytes)
  • research-orchestrator.md (6152 bytes)
  • aws-deployment-expert.md (6626 bytes)
  • documentation-expert.md (5697 bytes)

Settings Configuration

.claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Bash(npm install)"
    ],
    "deny": [],
    "ask": []
  }
}

Error Consistency

  • Error occurs for ALL custom agents (tried multiple different agents)
  • Error occurs regardless of agent complexity or prompt length
  • Error occurs when launching agents sequentially or in parallel
  • Built-in subagent types (general-purpose, Explore, etc.) work correctly

Root Cause Analysis

The error "Tool names must be unique" suggests that when the Task tool sets up the agent subprocess environment, it's creating duplicate tool definitions. This is NOT caused by the agent configuration files themselves, as they contain no tool definitions - they only contain prompts and frontmatter.

Possible causes:

  1. Task tool is duplicating tool definitions when copying them to agent context
  2. Agent inheritance mechanism is causing tool name collisions
  3. Recent regression in how custom agents are initialized

Impact

  • Severity: High - Custom agents are completely non-functional
  • Workaround: None - cannot use custom agents at all
  • User Impact: Users cannot leverage specialized agent workflows they've configured

Reproduction Rate

100% - Error occurs every single time with any custom agent

Request IDs (for debugging)

  • req_011CVkCDWnbJKjcZUkm6ucnW
  • req_011CVkCDWVjM2c9XPwT77Nw5
  • req_011CVkCE2NaTE4wSdZTRREmH
  • req_011CVkCKdu8wJGNRqcyfkQ2P

Suggested Fix

Investigate the Task tool's agent initialization logic to ensure tool definitions are not being duplicated when setting up the agent subprocess environment.

Error Messages/Logs

Steps to Reproduce

Bug Report: "Tool names must be unique" Error When Using Custom Agents

Summary

Unable to launch any custom agents via the Task tool - consistently receiving API error: "tools: Tool names must be unique"

Environment

  • Claude Code Version: Latest (as of 2025-12-03)
  • Platform: macOS (Darwin 25.2.0)
  • Model: claude-sonnet-4-5-20250929
  • Working Directory: /Users/bill/projects/spam-lambda

Steps to Reproduce

  1. Create custom agent files in .claude/agents/ directory (e.g., aws-lambda-expert.md, spam-email-detector.md)
  2. Agent files are properly formatted with frontmatter:

``markdown
---
name: aws-lambda-expert
description: Use this agent when...
model: sonnet
color: purple
---
[Agent prompt content]
``

  1. Attempt to launch any agent using the Task tool:

``
Task(
subagent_type: "aws-lambda-expert",
description: "Design Lambda architecture",
prompt: "..."
)
``

Expected Behavior

The agent should launch successfully and execute the task autonomously, returning results.

Actual Behavior

Immediately returns API error:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."},"request_id":"req_011CVkCDWnbJKjcZUkm6ucnW"}

Additional Context

Agent Files Created

  • aws-lambda-expert.md (5622 bytes)
  • spam-email-detector.md (7400 bytes)
  • unit-test-expert.md (6095 bytes)
  • unit-test-researcher.md (6038 bytes)
  • research-orchestrator.md (6152 bytes)
  • aws-deployment-expert.md (6626 bytes)
  • documentation-expert.md (5697 bytes)

Settings Configuration

.claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Bash(npm install)"
    ],
    "deny": [],
    "ask": []
  }
}

Error Consistency

  • Error occurs for ALL custom agents (tried multiple different agents)
  • Error occurs regardless of agent complexity or prompt length
  • Error occurs when launching agents sequentially or in parallel
  • Built-in subagent types (general-purpose, Explore, etc.) work correctly

Root Cause Analysis

The error "Tool names must be unique" suggests that when the Task tool sets up the agent subprocess environment, it's creating duplicate tool definitions. This is NOT caused by the agent configuration files themselves, as they contain no tool definitions - they only contain prompts and frontmatter.

Possible causes:

  1. Task tool is duplicating tool definitions when copying them to agent context
  2. Agent inheritance mechanism is causing tool name collisions
  3. Recent regression in how custom agents are initialized

Impact

  • Severity: High - Custom agents are completely non-functional
  • Workaround: None - cannot use custom agents at all
  • User Impact: Users cannot leverage specialized agent workflows they've configured

Reproduction Rate

100% - Error occurs every single time with any custom agent

Request IDs (for debugging)

  • req_011CVkCDWnbJKjcZUkm6ucnW
  • req_011CVkCDWVjM2c9XPwT77Nw5
  • req_011CVkCE2NaTE4wSdZTRREmH
  • req_011CVkCKdu8wJGNRqcyfkQ2P

Suggested Fix

Investigate the Task tool's agent initialization logic to ensure tool definitions are not being duplicated when setting up the agent subprocess environment.

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

Latest

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗