openAIFunction

December 1, 2025 · View on GitHub

Use Function Calls from MATLAB®

Creation

Syntax

f = openAIFunction(name,description)

f = openAIFunction(mcpTool)

An openAIFunction object represents a tool that you have, such as a MATLAB function. It includes information about the name, syntax, and behavior of the tool. If you pass an openAIFunction object to a large language model (LLM), then the LLM can suggest calls to the tool in its generated output. The LLM does not execute the tool itself. However, you can write scripts that automate the tool calls suggested by the LLM.

If you have the MATLAB MCP HTTP Client add-on installed, then you can also use tools provided by external MCP servers.

Use openAIFunction objects to call tools using OpenAI® or Ollama™.

For example:

Diagram illustrating how to incorporate function calling in text generation.

f = openAIFunction(name,description) creates an openAIFunction object with a name name and description description.

f = openAIFunction(mcpTool) creates an openAIFunction object from one or more tools provided by an MCP server specified as a cell array of struct. For example, mcpTool = client.Tools for an mcpHTTPClient object client (requires the MATLAB MCP HTTP Client add-on).

Input Arguments

`name` — Function name

character vector | string scalar

Specify the function name and set the FunctionName property.

`description` — Function description

[] (default) | character vector | string scalar

Describe the function using natural language and set the Description property.

`mcpTool` — Tool provided by MCP server

cell array of struct

Tool provided by an external MCP server, specified as a cell array of struct (requires the MATLAB MCP HTTP Client add-on).

For example, if you have an mcpHTTPClient (MATLAB MCP HTTP Client) object client, then you can specify mcpTool as client.Tools.

Properties

`FunctionName` — Tool name

character vector | string scalar

This property is read-only.

The name of your tool. This does not have to be the same as the name of your openAIFunction object.

Set this property at construction using the name input argument.

`Description` — Tool description

[] (default) | character vector | string array

This property is read-only.

Natural language description of your function.

Set this property at construction using the description input argument.

`Parameters` — Function arguments

empty structure array (default) | structure array

Each field corresponds to an input argument, specified as another structure array. Add parameters one-by-one using the addParameter function. The fields of the nested structure array depend on the input you provide to the addParameter function.


Field name	Field description	Optional
required	Whether the input argument is required, specified as `true` or `false`.	No
type	Data type or types of the input argument, specified as JSON data type. The possible argument types and their corresponding MATLAB data types are: - `"string"` — character vector - `"number"` — scalar double - `"integer"` — scalar integer - `"object"` — scalar structure - `"boolean"` — scalar logical - `"null"` — `NaN` or empty double For more information on how to decode JSON-formatted data in MATLAB, see jsondecode.	Yes
description	Natural language description of the input argument, specified as a string or character array.	Yes
enum	List of all possible values of an input argument.	Yes

For example, the Parameters structure describing the input arguments for a function myFun(x) with optional input arguments animalSpecies and isMammal could look like this:

Diagram illustrating an example Parameters structure.

Object Functions

addParameter — Add information about an input argument

Examples

Compute Sine Using OpenAI Function Call

First, specify the OpenAI® API key as an environment variable and save it to a file called ".env". Next, load the environment file using the loadenv function.

loadenv(".env")

Create an openAIFunction object that represents the sind function. The sind function has a single input argument, x, representing the input angle in degrees.

f = openAIFunction("sind","Sine of argument in degrees");
f = addParameter(f,"x",type="number",description="Angle in degrees");

Connect to the OpenAI Chat Completion API. Pass the openAIFunction object f as an input argument.

model = openAIChat("You are a helpful assistant.",Tools=f);

Initialize the message history. Add a user message to the message history.

messages = messageHistory;
messages = addUserMessage(messages,"What is the sine of thirty?");

Generate a response based on the message history.

[~,completeOutput] = generate(model,messages)

completeOutput = struct with fields:
          role: 'assistant'
       content: []
    tool_calls: [1x1 struct]
       refusal: []

The model has not generated any text. Instead, it has detected a function call, completeOutput.tool_calls.

Add the response to the message history.

messages = addResponseMessage(messages,completeOutput);

Extract the tool call ID and the name of the called function.

toolCallID = string(completeOutput.tool_calls.id)

toolCallID = "call_K4zqC0oO6vA97BTvSSCY9FHL"

functionCalled = string(completeOutput.tool_calls.function.name)

functionCalled = "sind"

Make sure that the model is calling the correct function. Even with only a single function, large language models can hallucinate function calls to fictitious functions.

Extract the input argument values from the complete output using the jsondecode function. Compute the sine of the generated argument value and add the result to the message history using the addToolMessage function.

if functionCalled == "sind"
    args = jsondecode(completeOutput.tool_calls.function.arguments);
    result = sind(args.x)
    messages = addToolMessage(messages,toolCallID,functionCalled,"x="+result);
end

result = 0.5000

Finally, generate a natural language response.

generatedText = generate(model,messages)

generatedText = "The sine of thirty degrees is 0.5."