When designing API commands for Model Context Protocol (MCP), following proper naming conventions helps LLMs understand and effectively use your tools. Here are the key best practices:
Use short, descriptive names: Choose names that clearly indicate the function of the tool, making it easier for LLMs to select and use the right one[1]. Without explicit naming, auto-generated operation IDs might be cryptic (like "read_user_users__user_id__get"), making it harder for AI models to understand[4].
Be explicit: Always use explicit operation_id values that clearly indicate what the operation does[4]. This helps AI agents better understand when to use which tool.
Follow technical requirements:
- Must start with a letter
- Can include only letters, numbers, and underscores
- Avoid hyphens (not supported by some platforms like AWS Nova)[1]
Use consistent styling: Choose either camelCase or snake_case and apply it consistently across all tools[1]. This consistency makes your API more intuitive to use.
Ensure uniqueness: Each tool name should be unique and clearly indicate its function[1]. This prevents confusion when LLMs need to select the appropriate tool.
Adopt consistent parameter naming: Use similar naming conventions for parameters that serve similar functions across different endpoints[5]. This consistency helps AI models understand parameter relationships.
Use intuitive and clear parameter names: Choose names that are easy to understand for developers unfamiliar with your API[3].
Focus on meaning rather than implementation: Design tool names that reflect their conceptual purpose, not their technical implementation[2]. This approach improves resilience and adaptability.
Prioritize intention-based instructions: Create commands that communicate what needs to be accomplished rather than how it should be done technically[2].
By following these best practices, you can build more intuitive MCP tools that enhance the capabilities of LLM agents and improve the overall developer experience.
Citations: [1] https://github.com/tadata-org/fastapi_mcp/blob/main/docs/00_BEST_PRACTICES.md [2] https://docs.mcp.run/blog/2025/03/27/mcp-differential-for-modern-apis/ [3] https://blog.dreamfactory.com/best-practices-for-naming-rest-api-endpoints [4] https://huggingface.co/blog/lynn-mikami/fastapi-mcp-server [5] https://apidog.com/blog/fastapi-mcp/ [6] https://auth0.com/blog/an-introduction-to-mcp-and-authorization/ [7] https://www.philschmid.de/mcp-introduction [8] https://www.moesif.com/blog/technical/api-development/The-Ultimate-Guide-to-REST-API-Naming-Convention/ [9] https://www.speakeasy.com/open-source/mcp/optimizing-your-openapi-for-mcp [10] https://github.com/punkpeye/mcp-client/blob/main/README.md [11] https://modelcontextprotocol.io/docs/concepts/tools [12] https://github.com/awslabs/mcp/blob/main/DESIGN_GUIDELINES.md [13] https://block.github.io/goose/blog/2025/04/22/mcp-is-rewriting-the-rules-of-api-integration/ [14] https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-server-development-guide.md [15] https://news.ycombinator.com/item?id=43302297 [16] https://apidog.com/blog/mcp-supported-api-documentation/ [17] https://www.anthropic.com/news/model-context-protocol [18] https://dev.to/msnmongare/best-practices-for-naming-api-endpoints-2n5o/comments [19] https://www.linkedin.com/pulse/best-practices-mcp-servers-gaurang-desai-7ptqc [20] https://www.merge.dev/blog/mcp-best-practices
Answer from Perplexity: pplx.ai/share