add best practices file

Author: shiraayal-tadata

BEST-PRACTICES.md

@@ -0,0 +1,52 @@
+# Best Practices for API to MCP Tool Conversion
+
+This guide outlines best practices for converting standard APIs into Model Context Protocol (MCP) tools for use with AI agents. Proper tool design helps ensure LLMs can understand and safely use your APIs.
+
+---
+
+## Tool Selection
+
+- **Be selective:**  
+  Avoid exposing every endpoint as a tool. LLM clients perform better with a limited number of well-defined tools, and providers often impose tool limits.
+
+- **Prioritize safety:**  
+  Do **not** expose `PUT` or `DELETE` endpoints unless absolutely necessary. LLMs are non-deterministic and could unintentionally alter or damage systems or databases.
+
+- **Focus on data retrieval:**  
+  Prefer `GET` endpoints that return data safely and predictably.
+
+- **Emphasize meaningful workflows:**  
+  Expose endpoints that reflect clear, goal-oriented tasks. Tools with focused actions are easier for agents to understand and use effectively.
+
+---
+
+## Tool Naming
+
+- **Use short, descriptive names:**  
+  Helps LLMs select and use the right tool. Know that some MCP clients restrict tool name length. 
+
+- **Follow naming constraints:**
+  - Must start with a letter
+  - Can include only letters, numbers, and underscores
+  - Avoid hyphens (e.g., AWS Nova does **not** support them)
+  - Use either `camelCase` or `snake_case` consistently across all tools
+
+- **Ensure uniqueness:**  
+  Each tool name should be unique and clearly indicate its function.
+
+---
+
+## Documentation
+
+- **Describe every tool meaningfully:**  
+  Provide a clear and concise summary of what each tool does.
+
+- **Include usage examples and parameter descriptions:**  
+  These help LLMs understand how to use the tool correctly.
+
+- **Standardize documentation across tools:**  
+  Keep formatting and structure consistent to maintain quality and readability.
+
+---
+
+By following these best practices, you can build safer, more intuitive MCP tools that enhance the capabilities of LLM agents.