1. SuiteCloud Platform
  2. SuiteScript
  3. SuiteScript 2.x
  4. SuiteScript 2.1 Script Types
  5. SuiteScript 2.1 Custom Tool Script Type
  6. SuiteScript 2.1 Custom Tool Script Type Reference
  7. Custom Tool JSON-RPC Schema

Custom Tool JSON-RPC Schema

A custom tool JSON-RPC schema defines one or more tools in your toolset. It also provides the information that AI clients use to invoke each tool through the NetSuite AI Connector Service. The inputSchema and outputSchema properties define the JSON schemas for a tool's input parameters and output.

Note:

When working with custom tool JSON-RPC schemas, ensure that the JSON-RPC schema file is valid JSON and uses only the properties documented in this section. Otherwise, deployment fails validation.

The following table describes the properties for each tool definition in the JSON-RPC schema:

Property

Type

Required or Optional

Description

name

string

Required

Method name as written in the script file.

Each tool name must be unique within the JSON-RPC schema.

description

string

Required

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

inputSchema

object

Required

Defines the input parameters.

inputSchema.type

string

Required

The type of the input parameter. Only accepts object type.

inputSchema.properties

object

Required

Key-value pairs for parameter names and their properties. Each parameter has a type and description. Supported types are string, number, and boolean.

For 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 nullable parameters, as defined in inputSchema.properties.

This parameter is ChatGPT-specific.

outputSchema

object

Required for ChatGPT, optional for other AI clients

Defines the expected output structure.

If specified, the tool returns a structured output.

outputSchema.type

string

Required for ChatGPT, optional for other AI clients

The type of the output parameter. Only accepts object type.

outputSchema.properties

object

Required

Key-value pairs for parameter names and their properties. Each parameter has a type and description. Supported types are string, number, boolean, and array.

If you use an array type, you also need to include an items property. For example:

                    "outputSchema": {
   "type": "object",
   "properties": {
      "results": {
         "type": "array",
         "description": "An array of values produced by splitting the input",
         "items": {
            "type": "object",
            "properties": {
               "value": {
                  "type": "string",
                  "description": "A value"
                  }
               }
            }
         }
      },
      "required": ["results"]
   }

outputSchema.required

array<string>

Required

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

outputSchema.nullable

array<string>

Required for ChatGPT

Array of nullable 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.

_meta.ui.resourceUri

string

Optional

Specifies the path of the bundled, self-contained HTML file that provides the interactive UI for the tool. This property is used only if the custom tool is implemented as an MCP App. The value must reference an .html file that exists in the File Cabinet and matches the file path included in your SuiteCloud project. For SuiteApp projects, the value must reference a file in the SuiteApps/<SuiteAppId>/ folder. For example, ui://SuiteApps/<SuiteAppId>/<folder>/mcp-app.html.

When defined, the AI client can load and display this UI in the chat experience for the tool. For information about MCP Apps, see Building MCP Apps (Interactive UI) with Custom Tools.

Related Topics

General Notices