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, it’s important to understand the deployment requirements and be aware of any limitations that could affect your implementation. The following topics cover the essential information you’ll need when creating a custom tool:

Custom Tool Script Requirements

Creating your own custom tool requires the following:

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.

Important:
The N/http, N/https, and N/search modules are not supported in custom tool scripts.
Tool schema - A JSON file that defines all properties for the actions in your custom tool.
Custom Tool SDF Object - The SDF object where you can manage script deployment and configuration in NetSuite.

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

Property	Type	Description	Required
name	string	Method name as written in the script file.	Yes
description	string	Explains the tool's purpose. The AI client uses this to decide when to use the tool.	Yes
inputSchema	object	Details of the input parameters	Yes
inputSchema.type	string	The type of the input parameter.	Yes
inputSchema.properties	object	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" } }`	Yes
inputSchema.required	array<string>	Array of required parameters, as defined in inputSchema.properties.	Yes
annotations	object	Additional metadata for the tool.	Yes
annotations.title	string	Tool title	Yes
annotations.readOnlyHint	boolean	Set to true. This means the tool doesn’t change the system state.	Yes
annotations.idempotentHint	boolean	Set to true. Multiple identical calls will always give the same result.	Yes
annotations.openWorldHint	boolean	Set to false. Indicates if the tool can handle unknown or extra properties.	Yes

Property

Type

Description

Required

name

string

Method name as written in the script file.

Yes

description

string

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

Yes

inputSchema

object

Details of the input parameters

Yes

inputSchema.type

string

The type of the input parameter.

Yes

inputSchema.properties

object

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" }
}

Yes

inputSchema.required

array<string>

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

Yes

annotations

object

Additional metadata for the tool.

Yes

annotations.title

string

Tool title

Yes

annotations.readOnlyHint

boolean

Set to true. This means the tool doesn’t change the system state.

Yes

annotations.idempotentHint

boolean

Set to true. Multiple identical calls will always give the same result.

Yes

annotations.openWorldHint

boolean

Set to false. Indicates if the tool can handle unknown or extra properties.

Yes

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

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
There was an issue loading modules into the tool implementation, N/http and N/search can't be used within tool implementations.	This error occurs if you use blocked modules in your tool implementation. This error also happens if you use a custom module but provide the wrong path in your implementation.
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.
Tool execution failed	The tool doesn’t return a result properly.
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.
Invalid call, the following required properties are missing: [parameter1, parameter2]")	Some required parameters are missing.

Error Message

Description

There was an issue loading modules into the tool implementation, N/http and N/search can't be used within tool implementations.

This error occurs if you use blocked modules in your tool implementation. This error also happens if you use a custom module but provide the wrong path in your implementation.

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.

Tool execution failed

The tool doesn’t return a result properly.

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.

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

Some required parameters are missing.

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.

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.

General Notices