1. SuiteCloud Platform
  2. SuiteScript
  3. SuiteScript 2.x
  4. SuiteScript 2.x Script Types
  5. SuiteScript 2.1 Custom Tool Script Type
  6. SuiteScript 2.1 Custom Tool Script Type Reference

SuiteScript 2.1 Custom Tool Script Type Reference

Building a custom tool in NetSuite takes several key steps, from implementing your tool’s actions to defining how the external AI client should interact with it. As you develop your custom tool scripts, it’s important to understand the deployment requirements and be aware of any limitations that can affect your implementation. The following topics cover the essential information you’ll need when creating a custom tool script:

Custom Tool Script Requirements

Creating your own custom tool requires the following:

  • Custom Tool Script File – Contains the SuiteScript code for your tool. Each method in the script can be defined as a separate tool in the tool schema. For guidance on writing code and structuring your custom tool scripts effectively, see Custom Tool Script Best Practices.

    Important:

    The N/http and N/https modules are not supported in custom tool scripts.

  • Tool Schema – A JSON file that defines all properties for the actions in your custom tool. For information about the properties defined in the tool schema, see Custom Tool JSON Schema.

  • Tool SDF Object – The XML definition file for the custom tool. Custom tools are defined in SDF as tool SDF custom objects. For more information, see Custom Tool Scripts as XML Definitions.

For complete samples of each file, see SuiteScript 2.1 Custom Tool Script Type Code Samples.

Custom Tool JSON Schema

The following table describes the properties defined in the tool schema.

Note:

If you include a property that is not listed in the following table, it will be ignored.

Property

Type

Required or Optional

Description

name

string

Required

Method name as written in the script file.

description

string

Required

Explains the tool's purpose. The AI client uses this to decide when to use the tool.

inputSchema

object

Required

Details of the input parameters

inputSchema.type

object

Required

The type of the input parameter.

inputSchema.properties

object

Required

Key-value pairs for parameter names and their properties. Each parameter has a type and description.

Example:

                      { 
  "firstname": { "type": "string", "description": "First Name" },
  "lastname": { "type": "string", "description": "Last Name" }
}

inputSchema.required

array<string>

Required

Array of required parameters, as defined in inputSchema.properties.

inputSchema.nullable

array<string>

Required for ChatGPT

Array of required parameters, as defined in inputSchema.properties.

This parameter is ChatGPT specific.

outputSchema

object

Optional for all AI Clients, required for ChatGPT

Defines the expected output structure.

If specified, the tool returns a structured output.

outputSchema.type

object

Optional for all AI Clients, required for ChatGPT

The type of the output parameter.

outputSchema.properties

object

Required

Key-value pairs for parameter names and their properties. Each parameter has a type and description.

outputSchema.required

array<string>

Required

Array of required parameters, as defined in outputSchema.properties.

outputSchema.nullable

array<string>

Required for ChatGPT

Array of required parameters, as defined in outputSchema.properties.

This parameter is ChatGPT specific.

annotations

object

Optional

Additional metadata for the tool.

annotations.title

string

Optional

Tool title.

If not specified, the tool name will be used.

annotations.readOnlyHint

boolean

Optional

Default value is false.

If not specified, the default value will be used.

If true, the tool doesn't change its environment.

annotations.idempotentHint

boolean

Optional

Default value is false.

If not specified, the default value will be used.

If true, calling the tool repeatedly with the same arguments have no further effect on its environment.

This property applies only when readOnlyHint is set to false.

annotations.openWorldHint

boolean

Optional

Default value is false.

If not specified, the default value will be used.

If true, the tool can interact with external entities beyond its predefined domain. If false, the tool's interactions are limited to its defined scope.

annotations.destructiveHint

boolean

Optional

Default value is true.

If not specified, the default value will be used.

If true, the tool can remove or overwrite existing information in its environment. If false, the tool only adds new information and doesn't remove or change existing data.

This property applies only when readOnlyHint is set to false.

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.

Custom Tool Script Impact on Other Customizations

When external AI clients run custom tools, some scripts and customizations in NetSuite may also be triggered. The following table shows how these components are affected during execution.

Customization

Impact

User Event Scripts

Workflow Action Scripts

Run as the role configured for the NetSuite AI Connector Service.

Workflow

If not set to run as administrator, workflows are triggered as the role configured for the NetSuite AI Connector Service.

Custom Tool Script Error Messages

When working with custom tool scripts, you may encounter various error messages that can help identify and resolve issues during development or deployment. The following table provides common error messages along with their descriptions, so you can quickly understand what each message means and how it might affect your workflow.

Error Message

Description

Access denied.

The user's role does not have access to the File Cabinet folder where the tools are located. Verify that access to the File Cabinet folder is not restricted for the role. For more information, see Restricting Access to File Cabinet Folders.

Couldn’t load modules in the tool implementation. Make sure your custom tool script doesn’t use unsupported modules like N/http or N/https. If the issue persists, check your script for syntax errors or other problems.

Possible causes of this error include:

  • Using unsupported SuiteScript modules in the tool implementation

  • Providing the wrong path for a custom module

  • Syntax error or other problems in the tool implementation

Invalid call, the following required properties are missing: [parameter1, parameter2]")

Some required parameters are missing.

The script execution context creation failed due to the following issue: <error details>

A critical error occurred during preparation, so the tool couldn’t run.

This tool is not allowed

The tool needs a permission that the current session doesn’t have.

There was an unexpected error while executing the tool: <error details>

The tool runs but fails on a line or throws an exception.

Tool execution failed

The tool doesn’t return a result properly.

Related Topics

General Notices