---
title: "DF0047: Agent Tool Wire-Name Collision"
description: "Agent tool \"{id}\" is hidden from the MCP surface: its wire name \"{name}\" collides with the tool \"{existing}\"."
canonical_url: "https://devfra.me/errors/df0047"
---
# DF0047: Agent Tool Wire-Name Collision

> Agent tool "\{id}" is hidden from the MCP surface: its wire name "\{name}" collides with the tool "\{existing}".

## Message

> Agent tool "`{id}`" is hidden from the MCP surface: its wire name "`{name}`" collides with the tool "`{existing}`".

## Cause

MCP clients constrain tool names to `^[a-zA-Z0-9_-]{1,128}$`, so the MCP adapter derives each tool's wire name from its id (runs of characters outside `[a-zA-Z0-9_-]` become a single `_`). Two registered ids sanitized to the same wire name, for example `demo:greet` and `demo_greet`. The first registration keeps the name; the later tool is hidden from `tools/list`.

## Example

```ts
ctx.agent.registerTool({ id: 'demo:greet', description: '…', handler })
ctx.agent.registerTool({ id: 'demo_greet', description: '…', handler }) // hidden: same wire name
```

## Fix

Rename one of the two ids so they sanitize to distinct wire names. Namespaced ids (`devframes:plugin:<slug>:<fn>`, `devframe:<area>:<fn>`) collide only when they differ solely in separator characters.

## Source

- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts): the `tools/list` handler reports this once per hidden tool when deduplicating wire names.


## Sitemap

See the full [sitemap](https://devfra.me/sitemap.md) for all pages.