›_ Claude Code Issues
Claude Code Issues / #10684

[BUG]

Resolved 💬 3 comments Opened Oct 31, 2025 by rayk Closed Nov 3, 2025

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?

Tool Problem

What Should Happen?

Agent invocations fail with API error "tools: Tool names must be unique" when the agent's global permissions include MCP
tools (mcp__brave-search__, mcp__firecrawl__). This occurs even when the agent file does not explicitly declare or
reference these tools.

Environment

  • Claude Code Version: Latest (as of 2025-10-31)
  • OS: macOS Darwin 24.6.0
  • Claude Model: claude-sonnet-4-5-20250929
  • Agent Type: Custom agent with model: inherit

Steps to Reproduce

  1. Configure global MCP tool permissions in .claude/settings.local.json:

{
"permissions": {
"allow": [
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape"
]
}
}

  1. Create agent file .claude/agents/ontologist.md with minimal YAML frontmatter:

---
name: ontologist
description: Schema alignment specialist
model: inherit
color: teal
---

  1. Invoke the agent:

Task({
subagent_type: "ontologist",
model: "haiku",
description: "Test agent",
prompt: "Return success status"
})

  1. Observe error:

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

Expected Behavior

Agent should invoke successfully, inheriting MCP tools from global permissions without duplication.

Actual Behavior

Agent fails immediately with "tools: Tool names must be unique" error, suggesting tool declarations are being duplicated
during agent loading.

Configuration Files

.claude/settings.local.json (relevant excerpt):
{
"permissions": {
"allow": [
"Read(/Users/rayk/lucid/lucid_knowledge/**)",
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape",
"WebFetch(domain:schema.org)",
"WebFetch(domain:legislation.nsw.gov.au)"
]
}
}

.claude/agents/ontologist.md (minimal version that fails):
---
name: ontologist
description: Multi-Schema Alignment specialist for LUON ontology
model: inherit
color: teal
---

# Agent documentation here
(No explicit tool declarations)

What Was Tried

Attempted fixes (all failed with same error):

  1. ✅ Removed MCP wildcard patterns from agent documentation
  2. ✅ Removed all bulleted tool lists from agent file
  3. ✅ Removed backticks from all path/tool references
  4. ✅ Condensed tool documentation to single prose paragraph
  5. ✅ Removed YAML frontmatter comments
  6. ✅ Restarted Claude Code CLI completely
  7. ✅ Verified no duplicate agent files exist

None of these changes resolved the error.

Hypothesis

Claude Code's agent loading mechanism appears to be:

  1. Loading MCP tools from global permissions
  2. Then parsing the agent markdown file
  3. Somehow treating documentation or metadata in the agent file as tool redeclarations
  4. Creating duplicate tool entries that trigger the uniqueness validation

This occurs even when the agent file contains no explicit tool declarations.

Impact

  • Severity: High - Blocks all usage of affected agents
  • Scope: Affects any custom agent when MCP tools are in global permissions
  • Workaround: Must remove MCP tools from global permissions (defeats purpose of global permissions)

Affected Agents

Confirmed failing with same error:

  • ontologist
  • strata-legislation-expert

Likely affects any agent that would use MCP tools from global permissions.

Additional Context

The error occurs during agent invocation, before the agent prompt is processed. This suggests the issue is in Claude
Code's agent initialization/tool resolution phase, not in the agent's runtime behavior.

Requested Fix

  1. Ensure agents inherit global MCP tool permissions without creating duplicates
  2. Clarify documentation on how tool inheritance works with MCP tools
  3. Add validation to detect and prevent duplicate tool declarations during agent loading

Error Messages/Logs

Agent invocations fail with API error "tools: Tool names must be unique" when the agent's global permissions include MCP
  tools (mcp__brave-search__*, mcp__firecrawl__*). This occurs even when the agent file does not explicitly declare or
  reference these tools.

  Environment

  - Claude Code Version: Latest (as of 2025-10-31)
  - OS: macOS Darwin 24.6.0
  - Claude Model: claude-sonnet-4-5-20250929
  - Agent Type: Custom agent with model: inherit

  Steps to Reproduce

  1. Configure global MCP tool permissions in .claude/settings.local.json:
  {
    "permissions": {
      "allow": [
        "mcp__brave-search__brave_web_search",
        "mcp__firecrawl__firecrawl_search",
        "mcp__firecrawl__firecrawl_scrape"
      ]
    }
  }

  2. Create agent file .claude/agents/ontologist.md with minimal YAML frontmatter:
  ---
  name: ontologist
  description: Schema alignment specialist
  model: inherit
  color: teal
  ---

  3. Invoke the agent:
  Task({
    subagent_type: "ontologist",
    model: "haiku",
    description: "Test agent",
    prompt: "Return success status"
  })

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

  Expected Behavior

  Agent should invoke successfully, inheriting MCP tools from global permissions without duplication.

  Actual Behavior

  Agent fails immediately with "tools: Tool names must be unique" error, suggesting tool declarations are being duplicated
  during agent loading.

  Configuration Files

  .claude/settings.local.json (relevant excerpt):
  {
    "permissions": {
      "allow": [
        "Read(/Users/rayk/lucid/lucid_knowledge/**)",
        "mcp__brave-search__brave_web_search",
        "mcp__firecrawl__firecrawl_search",
        "mcp__firecrawl__firecrawl_scrape",
        "WebFetch(domain:schema.org)",
        "WebFetch(domain:legislation.nsw.gov.au)"
      ]
    }
  }

  .claude/agents/ontologist.md (minimal version that fails):
  ---
  name: ontologist
  description: Multi-Schema Alignment specialist for LUON ontology
  model: inherit
  color: teal
  ---

  # Agent documentation here
  (No explicit tool declarations)

  What Was Tried

  Attempted fixes (all failed with same error):

  1. ✅ Removed MCP wildcard patterns from agent documentation
  2. ✅ Removed all bulleted tool lists from agent file
  3. ✅ Removed backticks from all path/tool references
  4. ✅ Condensed tool documentation to single prose paragraph
  5. ✅ Removed YAML frontmatter comments
  6. ✅ Restarted Claude Code CLI completely
  7. ✅ Verified no duplicate agent files exist

  None of these changes resolved the error.

  Hypothesis

  Claude Code's agent loading mechanism appears to be:
  1. Loading MCP tools from global permissions
  2. Then parsing the agent markdown file
  3. Somehow treating documentation or metadata in the agent file as tool redeclarations
  4. Creating duplicate tool entries that trigger the uniqueness validation

  This occurs even when the agent file contains no explicit tool declarations.

  Impact

  - Severity: High - Blocks all usage of affected agents
  - Scope: Affects any custom agent when MCP tools are in global permissions
  - Workaround: Must remove MCP tools from global permissions (defeats purpose of global permissions)

  Affected Agents

  Confirmed failing with same error:
  - ontologist
  - strata-legislation-expert

  Likely affects any agent that would use MCP tools from global permissions.

  Additional Context

  The error occurs during agent invocation, before the agent prompt is processed. This suggests the issue is in Claude
  Code's agent initialization/tool resolution phase, not in the agent's runtime behavior.

  Requested Fix

  1. Ensure agents inherit global MCP tool permissions without creating duplicates
  2. Clarify documentation on how tool inheritance works with MCP tools
  3. Add validation to detect and prevent duplicate tool declarations during agent loading

Steps to Reproduce

---
Bug Report for GitHub Issue

Repository: https://github.com/anthropics/claude-code/issues

Title: Agent invocation fails with "tools: Tool names must be unique" when MCP tools are in global permissions

Labels: bug, agents, mcp

---
Description

Agent invocations fail with API error "tools: Tool names must be unique" when the agent's global permissions include MCP
tools (mcp__brave-search__, mcp__firecrawl__). This occurs even when the agent file does not explicitly declare or
reference these tools.

Environment

  • Claude Code Version: Latest (as of 2025-10-31)
  • OS: macOS Darwin 24.6.0
  • Claude Model: claude-sonnet-4-5-20250929
  • Agent Type: Custom agent with model: inherit

Steps to Reproduce

  1. Configure global MCP tool permissions in .claude/settings.local.json:

{
"permissions": {
"allow": [
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape"
]
}
}

  1. Create agent file .claude/agents/ontologist.md with minimal YAML frontmatter:

---
name: ontologist
description: Schema alignment specialist
model: inherit
color: teal
---

  1. Invoke the agent:

Task({
subagent_type: "ontologist",
model: "haiku",
description: "Test agent",
prompt: "Return success status"
})

  1. Observe error:

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

Expected Behavior

Agent should invoke successfully, inheriting MCP tools from global permissions without duplication.

Actual Behavior

Agent fails immediately with "tools: Tool names must be unique" error, suggesting tool declarations are being duplicated
during agent loading.

Configuration Files

.claude/settings.local.json (relevant excerpt):
{
"permissions": {
"allow": [
"Read(/Users/rayk/lucid/lucid_knowledge/**)",
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape",
"WebFetch(domain:schema.org)",
"WebFetch(domain:legislation.nsw.gov.au)"
]
}
}

.claude/agents/ontologist.md (minimal version that fails):
---
name: ontologist
description: Multi-Schema Alignment specialist for LUON ontology
model: inherit
color: teal
---

# Agent documentation here
(No explicit tool declarations)

What Was Tried

Attempted fixes (all failed with same error):

  1. ✅ Removed MCP wildcard patterns from agent documentation
  2. ✅ Removed all bulleted tool lists from agent file
  3. ✅ Removed backticks from all path/tool references
  4. ✅ Condensed tool documentation to single prose paragraph
  5. ✅ Removed YAML frontmatter comments
  6. ✅ Restarted Claude Code CLI completely
  7. ✅ Verified no duplicate agent files exist

None of these changes resolved the error.

Hypothesis

Claude Code's agent loading mechanism appears to be:

  1. Loading MCP tools from global permissions
  2. Then parsing the agent markdown file
  3. Somehow treating documentation or metadata in the agent file as tool redeclarations
  4. Creating duplicate tool entries that trigger the uniqueness validation

This occurs even when the agent file contains no explicit tool declarations.

Impact

  • Severity: High - Blocks all usage of affected agents
  • Scope: Affects any custom agent when MCP tools are in global permissions
  • Workaround: Must remove MCP tools from global permissions (defeats purpose of global permissions)

Affected Agents

Confirmed failing with same error:

  • ontologist
  • strata-legislation-expert

Likely affects any agent that would use MCP tools from global permissions.

Additional Context

The error occurs during agent invocation, before the agent prompt is processed. This suggests the issue is in Claude
Code's agent initialization/tool resolution phase, not in the agent's runtime behavior.

Requested Fix

  1. Ensure agents inherit global MCP tool permissions without creating duplicates
  2. Clarify documentation on how tool inheritance works with MCP tools
  3. Add validation to detect and prevent duplicate tool declarations during agent loading

---
Copy this entire report and paste it into a new issue at: https://github.com/anthropics/claude-code/issues/new

Would you like me to help with anything else related to this issue?

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

Claude Code Version: Latest (as of 2025-10-31)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

---
Bug Report for GitHub Issue

Repository: https://github.com/anthropics/claude-code/issues

Title: Agent invocation fails with "tools: Tool names must be unique" when MCP tools are in global permissions

Labels: bug, agents, mcp

---
Description

Agent invocations fail with API error "tools: Tool names must be unique" when the agent's global permissions include MCP
tools (mcp__brave-search__, mcp__firecrawl__). This occurs even when the agent file does not explicitly declare or
reference these tools.

Environment

  • Claude Code Version: Latest (as of 2025-10-31)
  • OS: macOS Darwin 24.6.0
  • Claude Model: claude-sonnet-4-5-20250929
  • Agent Type: Custom agent with model: inherit

Steps to Reproduce

  1. Configure global MCP tool permissions in .claude/settings.local.json:

{
"permissions": {
"allow": [
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape"
]
}
}

  1. Create agent file .claude/agents/ontologist.md with minimal YAML frontmatter:

---
name: ontologist
description: Schema alignment specialist
model: inherit
color: teal
---

  1. Invoke the agent:

Task({
subagent_type: "ontologist",
model: "haiku",
description: "Test agent",
prompt: "Return success status"
})

  1. Observe error:

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

Expected Behavior

Agent should invoke successfully, inheriting MCP tools from global permissions without duplication.

Actual Behavior

Agent fails immediately with "tools: Tool names must be unique" error, suggesting tool declarations are being duplicated
during agent loading.

Configuration Files

.claude/settings.local.json (relevant excerpt):
{
"permissions": {
"allow": [
"Read(/Users/rayk/lucid/lucid_knowledge/**)",
"mcp__brave-search__brave_web_search",
"mcp__firecrawl__firecrawl_search",
"mcp__firecrawl__firecrawl_scrape",
"WebFetch(domain:schema.org)",
"WebFetch(domain:legislation.nsw.gov.au)"
]
}
}

.claude/agents/ontologist.md (minimal version that fails):
---
name: ontologist
description: Multi-Schema Alignment specialist for LUON ontology
model: inherit
color: teal
---

# Agent documentation here
(No explicit tool declarations)

What Was Tried

Attempted fixes (all failed with same error):

  1. ✅ Removed MCP wildcard patterns from agent documentation
  2. ✅ Removed all bulleted tool lists from agent file
  3. ✅ Removed backticks from all path/tool references
  4. ✅ Condensed tool documentation to single prose paragraph
  5. ✅ Removed YAML frontmatter comments
  6. ✅ Restarted Claude Code CLI completely
  7. ✅ Verified no duplicate agent files exist

None of these changes resolved the error.

Hypothesis

Claude Code's agent loading mechanism appears to be:

  1. Loading MCP tools from global permissions
  2. Then parsing the agent markdown file
  3. Somehow treating documentation or metadata in the agent file as tool redeclarations
  4. Creating duplicate tool entries that trigger the uniqueness validation

This occurs even when the agent file contains no explicit tool declarations.

Impact

  • Severity: High - Blocks all usage of affected agents
  • Scope: Affects any custom agent when MCP tools are in global permissions
  • Workaround: Must remove MCP tools from global permissions (defeats purpose of global permissions)

Affected Agents

Confirmed failing with same error:

  • ontologist
  • strata-legislation-expert

Likely affects any agent that would use MCP tools from global permissions.

Additional Context

The error occurs during agent invocation, before the agent prompt is processed. This suggests the issue is in Claude
Code's agent initialization/tool resolution phase, not in the agent's runtime behavior.

Requested Fix

  1. Ensure agents inherit global MCP tool permissions without creating duplicates
  2. Clarify documentation on how tool inheritance works with MCP tools
  3. Add validation to detect and prevent duplicate tool declarations during agent loading

---
Copy this entire report and paste it into a new issue at: https://github.com/anthropics/claude-code/issues/new

Would you like me to help with anything else related to this issue?

View original on GitHub ↗

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