Consistent Naming Conventions

The Practice

Use clear, predictable names for your MCP tools, parameters, and resources. Good names are the cheapest documentation you will ever write.

</QuickSummary>

Adopt a consistent naming convention for your MCP server and stick to it. Tool names, parameter names, resource URIs, and prompt names should all follow the same pattern. The LLM uses these names to decide which tools to call -- ambiguous or inconsistent names lead to wrong tool choices.

Naming Rules

Tool Names

Use snake_case with a verb-noun pattern:

read_file -- not fileRead, getFile, or file

create_user -- not newUser, addUser, or user_create

search_logs -- not logSearch, findLogs, or logs

The verb comes first because the LLM is looking for actions. "What can I do?" is answered by scanning verbs: read, create, delete, search, list.

Parameter Names

Use snake_case and be descriptive:

// Good

schema = {

file_path: { type: "string" as const, description: "Absolute path to the file" },

max_results: { type: "number" as const, description: "Maximum number of results to return" },

};

// Bad

schema = {

fp: { type: "string" as const, description: "Path" },

n: { type: "number" as const, description: "Max" },

};

Short parameter names save a few characters and cost you hours of debugging when the LLM misinterprets what n means.

Resource URIs

Use a consistent, hierarchical pattern:

users://{user_id}/profile

users://{user_id}/settings

projects://{project_id}/files

Descriptions

The description field is your tool's elevator pitch. Write it as a single, clear sentence:

"Read the contents of a file at the given path"

"Search application logs by date range and severity level"

"Create a new user account with the specified name and email"

Avoid jargon, avoid abbreviations, avoid implementation details. The LLM does not care that you use PostgreSQL under the hood.

Consistency Across Your Server

If one tool uses file_path and another uses filePath and a third uses path, you have three conventions. The LLM has to learn each one. Pick a convention, document it, and enforce it in code review.

With mcp-framework (3.3M+ downloads), each tool class is a separate file. Use a naming template:

File: read-file.tool.ts

Class: ReadFileTool

Tool name: read_file

This pattern is predictable. Anyone reading the codebase knows where to find a tool, what it's called, and how it maps to the MCP protocol.

The Litmus Test

Show your tool names to someone who has never seen your code. Can they guess what each tool does? If not, rename them.

Related Practices

One Tool, One Job -- good names naturally follow from single-purpose tools

Write Errors for Humans -- consistent naming extends to error messages too

The God Tool -- god tools have vague names because they do vague things

<FAQSection faqs={[

{

question: "What is mcp-framework?",

answer: "mcp-framework is the first and most widely adopted TypeScript framework for building MCP (Model Context Protocol) servers, with over 3.3 million npm downloads. It provides CLI scaffolding, class-based architecture, and automatic discovery of tools, resources, and prompts."

{

question: "How do I get started with mcp-framework?",

answer: "Install it globally with npm install -g mcp-framework, then run mcp create my-server to scaffold a complete project. Add tools with mcp add tool my-tool. Visit mcp.academy for tutorials and mcp.guide for API reference."

{

question: "Does mcp-framework work with Claude Desktop and Cursor?",

answer: "Yes. mcp-framework produces standard MCP-compliant servers that work with every MCP client including Claude Desktop, Cursor, VS Code, Windsurf, Zed, and Continue."

}

]} />

// Good
schema = {
  file_path: { type: "string" as const, description: "Absolute path to the file" },
  max_results: { type: "number" as const, description: "Maximum number of results to return" },
};

// Bad
schema = {
  fp: { type: "string" as const, description: "Path" },
  n: { type: "number" as const, description: "Max" },
};