N/llm Module: createToolResult Method for Tool-Use Round-Trips

What changed

The N/llm module now exposes llm.createToolResult(options), completing the tool-use loop introduced alongside llm.generateText() and llm.generateTextStreamed() in 2025.2. When the LLM responds with a llm.ToolCall object (asking your script to execute an action such as a SuiteQL query or a record operation), you handle that action in your own code, then wrap the output in a llm.ToolResult and feed it back into the next generateText or generateTextStreamed call. The LLM incorporates those results to produce a more accurate final response.

Method signature

• Module: N/llm
• Method: llm.createToolResult(options)
• Returns: llm.ToolResult
• Governance: None
• Script types: Server scripts only (Scheduled, Map/Reduce, Suitelet, User Event, RESTlet, etc.)

Parameters

• options.call (llm.ToolCall, required) — The original tool-call request object returned by the LLM. This links the result back to the specific call.
• options.outputs (Object[], required) — An array of output objects. Each object should include a result property (or equivalent) containing the value to return to the LLM.

Typical flow

1. Define tools and call llm.generateText() or llm.generateTextStreamed().
2. Inspect the response for llm.ToolCall objects.
3. Execute the requested operation (e.g., run a N/query SuiteQL query, create or load a record via N/record).
4. Call llm.createToolResult({ call: toolCall, outputs: [{ result: handlerResult }] }).
5. Pass the ToolResult into a subsequent generateText / generateTextStreamed call so the LLM can incorporate it.

Example (non-functional, per Oracle docs)

const toolResult = llm.createToolResult({
  call: toolCall,
  outputs: [{ result: handlerResult }]
});

What to do

1. Review your existing N/llm integrations. If you are already calling llm.generateText() with tool definitions but were manually re-prompting the model with stringified results, switch to the formal createToolResult path for cleaner round-trips.
2. Structure outputs carefully. The outputs array accepts multiple objects — useful when a single tool call produces several discrete results. Each object should carry a result property with the data the LLM needs.
3. No governance cost. createToolResult itself consumes zero governance units. Governance is incurred only on the subsequent generateText/generateTextStreamed call that processes the result, so plan unit budgets around those calls, not this one.
4. Server scripts only. This method is unavailable in client scripts. If you need LLM tool-use from the browser, route through a Suitelet or RESTlet.
5. Consult the full samples. Oracle references N/llm Module Script Samples for a complete working example — review those for end-to-end patterns including error handling on tool execution failures.