Skip to content
IsoKron

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

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

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

TypeScript
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"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

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.

Further reading

How this check is graded

It counts toward: OpenAI plugin directory. See the rubric.

Last verified against OpenAI plugin guidelines, section 6.1 on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere