Custom Tool Script Best Practices
Following a few best practices can help you write custom tool scripts that are reliable and simple to maintain. The following list contains best practices for developing custom tools.
-
Use unique method names - Give each method a unique name to avoid conflicts and ensure clear mapping between your tool schema and script. This helps AI clients and developers find the right functionality.
-
Ensure tool descriptions are accurate - Write clear, precise descriptions for each tool. Accurate descriptions help AI clients and developers understand, maintain, and extend your tools.
-
Stringify objects before returning - Convert objects to JSON strings before returning them. This ensures compatibility with AI clients and avoids serialization issues. This also gives you a predictable data format for downstream processing.
-
Avoid semantic collision between tools - Ensure that no two tools perform similar or confusing actions. Overlap can cause unpredictable AI behavior and make maintenance harder.
-
Plan each operation for the AI-as-customer-agent model - The tool user is an AI acting for a customer. Make operations safe, auditable, and suitable for automation-not requiring human judgment.
-
Exclude data from untrusted sources in output - Only include information from trusted or verified sources in your tool's output. This keeps your data reliable, protects against security risks, and ensures that AI-driven actions are based on trusted information.
For additional best practices when building custom tools with interactive UI, see MCP App Best Practices.