# Tool names that say what the tool does

**OpenAI’s guidelines ask you to avoid internal jargon, unexplained acronyms and opaque identifiers in tool names; use a plain verb and object such as list_invoices.**

Check `openai-name-opaque` · OpenAI plugin directory · default severity: advice · rubric 2.1.0. Last verified against OpenAI plugin guidelines, section 6.1 on 2026-11-18.

## What fails

Names like op_17, fn2 or a hex id tell neither the model nor a reviewer what the tool does.

## The rule

> Avoid internal jargon, unexplained acronyms, and opaque identifiers.

Source: [OpenAI plugin guidelines, section 6.1](https://developers.openai.com/plugins/plugin-guidelines)

## How to fix it

Use a plain verb and object, for example list_invoices.

1. Replace generated or internal names (op_17, fn2, a hash) with verb_object names.
2. Keep one convention across the server: snake_case verbs first (get_, list_, create_, update_, delete_).
3. If names are generated from an API spec, map operationId to a readable name.

### TypeScript SDK

```ts
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'list_invoices',
  {
    title: 'List invoices',
    description: 'List invoices for a customer, newest first. Use when the user asks about bills or payments due.',
    inputSchema: z.strictObject({
      customer_id: z.string().describe('Customer ID, for example CUS-311'),
      limit: z.number().int().min(1).max(100).default(20).describe('Maximum invoices to return'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ customer_id, limit }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);
```

### Python SDK

```python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="List invoices",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_invoices(
    customer_id: Annotated[str, Field(description="Customer ID, for example CUS-311")],
    limit: Annotated[int, Field(description="Maximum invoices to return", ge=1, le=100)] = 20,
) -> str:
    """List invoices for a customer, newest first. Use when the user asks about bills or payments due."""
    return "Done"
```

## Questions

### What is a good MCP tool naming convention?

Verb then object in snake_case (get_issue, list_issues, create_issue), with a service prefix once the server has ten or more tools. Names stay under 64 characters and use only letters, digits, underscore and hyphen.

### Is camelCase allowed?

Yes, the specification allows it. Pick one style for the whole server so the model sees a pattern.

## Related checks

- [Tool names without promotional or comparative words](https://isokron.ai/mcp-check/checks/openai-name-promotional)
- [Larger catalogs use a naming prefix](https://isokron.ai/mcp-check/checks/design-namespace)
- [Allowed characters in MCP tool names](https://isokron.ai/mcp-check/checks/spec-name-charset)
- [MCP tool names](https://isokron.ai/mcp-check/checks/names)

## Further reading

- [Why MCP tool design matters for agent reliability](https://isokron.ai/research/why-mcp-tool-design-matters)

Counts toward: OpenAI plugin directory.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
