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 a clear mapping between your JSON-RPC schema and script. Use a common prefix for tools delivered in the same SuiteApp or under the same publisher ID to reduce the risk of collisions. 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.