N/llm Module: llm.createTool Lets Scripts Define Callable Tools for LLM Interactions

What changed

The N/llm module now exposes llm.createTool(options), allowing server-side SuiteScript 2.1 to define tool definitions that a large language model can request during a llm.generateText(options) or llm.generateTextStreamed(options) call. This follows the standard agentic tool-calling pattern: you describe what a tool does, what parameters it accepts, and the LLM decides at inference time whether to invoke it.

API surface

• Method: llm.createTool(options)
• Returns: llm.Tool
• Governance: None (creating the definition itself costs zero governance units; governance for the tool's own logic — e.g., SuiteQL queries — is still counted when you execute it)
• Script types: Server scripts only
• Module: N/llm (since 2025.2)

Required parameters

• options.name (string) — unique identifier the LLM uses when it emits a llm.ToolCall referencing this tool.
• options.description (string) — natural-language description that tells the LLM when to request the tool. Quality of this description directly affects whether the model invokes the tool at the right time.
• options.parameters (llm.ToolParameter[]) — array of parameter definitions created via llm.createToolParameter(options). Each parameter specifies a name, description, and type (e.g., llm.ToolParameterType.STRING).

Example skeleton

The following illustrates definition only (not execution):

const findUserIdTool = llm.createTool({
  name: "findUserId",
  description: "Looks up user ID based on user name",
  parameters: [
    llm.createToolParameter({
      name: "userName",
      description: "Name of the user",
      type: llm.ToolParameterType.STRING
    })
  ]
});

Once defined, pass one or more llm.Tool objects to llm.generateText({ tools: [findUserIdTool] }). The LLM may then return llm.ToolCall objects in its response, which your script must handle — execute the requested logic, feed the results back, and optionally continue the generation loop.

Key considerations

• Tool execution is your responsibility. createTool only declares the schema. When the LLM returns a llm.ToolCall, your script must match on toolCall.name, extract the arguments, run the operation (SuiteQL query, record load, REST call, etc.), and return the result. Oracle's documentation does not yet detail the exact response-looping mechanism — check the N/llm Module Script Samples page for the full round-trip pattern.
• Governance is indirect. The createTool call itself is free, but every SuiteScript API you call inside your tool handler (e.g., query.runSuiteQL, record.load) still counts its normal governance units. Plan your unit budget for the worst-case number of tool invocations per generation.
• Server scripts only. Client scripts, user-event scripts running client-side, and Suitelets with client-side entry points cannot use this API.
• Description quality matters. The LLM chooses tools based on options.description. Vague descriptions lead to missed or incorrect invocations. Be specific about what data the tool returns and under what conditions it should be called.

What to do

1. Review the full N/llm module documentation, especially llm.generateText, llm.generateTextStreamed, llm.createToolParameter, llm.ToolCall, and llm.ToolParameterType — these form the complete tool-calling lifecycle.
2. Start with a single tool per generation call to validate the round-trip before adding multi-tool orchestration.
3. Budget governance units for the SuiteScript operations inside your tool handlers, not just for the createTool call. If the LLM invokes a tool multiple times in one session, governance can add up quickly.
4. Write precise description strings. Include what data the tool returns, what entity it operates on, and any constraints. Treat these like API docstrings, not marketing copy.
5. Gate sensitive operations. Because the LLM decides when to invoke tools, ensure your tool handlers validate inputs and enforce permissions before executing record writes, workflow triggers, or external API calls.