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

• Custom Tool JSON Schema

• Custom Tool Script Impact on Other Customizations

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/email 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.

• Custom 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:

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 true. 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.

If you add a property that is not listed in this table, it will be ignored.

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 can't be used within tool implementations.	This error occurs if you use unsupported 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.

General Notices