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.
How to fix it
Use a plain verb and object, for example list_invoices.
- Replace generated or internal names (op_17, fn2, a hash) with verb_object names.
- Keep one convention across the server: snake_case verbs first (get_, list_, create_, update_, delete_).
- If names are generated from an API spec, map operationId to a readable name.
TypeScript SDK
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
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.
Related checks
- Tool names without promotional or comparative words
- Larger catalogs use a naming prefix
- Allowed characters in MCP tool names
- All checks in MCP tool names
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