Custom Tool JSON Schema

A custom tool JSON schema describes the inputs and outputs for each tool, providing the structure AI clients and NetSuite use to interact with your custom tools.

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 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 match the file path included in your SuiteCloud project (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.

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 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 match the file path included in your SuiteCloud project (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