# Tool names follow verb_noun or verb-noun convention with no collisions

- **Pattern:** `ab-001826` (`mcp-server.tool-definitions.tool-naming`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001826
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001826)

## Why it matters

Tool names are the primary routing signal for any AI client selecting between dozens of tools from multiple connected MCP servers. A name like `run` or `do` gives the model nothing to distinguish your tool from a similarly-named one in another server. Mixed conventions — some `snake_case`, some `camelCase`, some `kebab-case` — force the model to pattern-match without a consistent rule, increasing mistaken invocations. When tool selection fails silently, the correct action is never taken and the user sees wrong or missing output with no explanation.

## Severity rationale

High because inconsistent or vague names cause the AI to select the wrong tool, especially in multi-server sessions where name collisions produce unpredictable routing behavior.

## Remediation

Rename every tool to `verb_noun` snake_case with a descriptive noun that scopes the action. No single-word names.

```ts
// src/tools/index.ts
// Before: 'run', 'createIssue', 'do-deploy'
// After:
server.tool('run_command', ...)
server.tool('create_github_issue', ...)
server.tool('deploy_to_vercel', ...)
```

If two tools have the same verb, make the noun more specific: `read_file` vs. `read_database_row`. Confirm no duplicate names by listing all registered tools at startup.

## Detection

- **ID:** `tool-naming`
- **Severity:** `high`
- **What to look for:** Count all tool names. Enumerate which follow snake_case convention and are descriptive vs. which use abbreviations or unclear names. List all registered tool names. Check that names follow a consistent convention — `verb_noun` (e.g., `search_files`, `create_issue`) or `verb-noun` (e.g., `search-files`, `create-issue`). Check for name collisions (duplicate names). Check for vague names (`run`, `do`, `process`) that don't describe what the tool does. Check that names are descriptive enough for an AI to select the right tool from a list of many tools.
- **Pass criteria:** All tool names follow a consistent naming convention. Names are descriptive (an AI reading only the name could guess what the tool does). No duplicate names. No single-word generic names. 100% of tool names must use snake_case with no more than 40 characters each.
- **Fail criteria:** Mixed naming conventions (some snake_case, some camelCase, some kebab-case), or duplicate tool names, or vague single-word names, or names that don't describe the action.
- **Skip (N/A) when:** The server registers no tools. All checks skip when no MCP server is detected.

- **Cross-reference:** For tool descriptions, see `tool-descriptions`. For naming in resource URIs, see `resource-uris`.
- **Detail on fail:** `"Mixed naming: 'search_files' (snake_case) but 'createIssue' (camelCase) and 'deploy' (single-word, vague)"` or `"Tool name 'run' is too generic — when multiple MCP servers are connected, the AI cannot distinguish this from other 'run' tools"`
- **Remediation:** Tool names are the primary signal an AI uses to decide which tool to call. Make them specific and consistent:

  ```ts
  // src/tools/index.ts — well-named tools
  { name: "get_user_profile" }  // Good: snake_case, descriptive
  // Avoid: { name: "gup" } or { name: "getUserProfile" }
  ```

  ```ts
  // Good — consistent snake_case, descriptive verb_noun
  server.tool('search_files', ...)
  server.tool('read_file', ...)
  server.tool('create_issue', ...)
  server.tool('list_branches', ...)

  // Bad — inconsistent, vague
  server.tool('search', ...)        // search what?
  server.tool('createIssue', ...)   // mixed convention
  server.tool('do-deploy', ...)     // mixed convention
  ```

## External references

- external mcp-spec-tool-naming — https://modelcontextprotocol.io/docs/concepts/tools

Taxons: inference-contract

HTML version: https://auditbuffet.com/patterns/ab-001826