Why Does Using Enums in Function Parameters Cause Numbers to be Returned as Strings?

Below is some context on how function calling works with enums in the OpenAI API. The behavior you’re seeing is a consequence of how the JSON schema is defined rather than a bug:

What’s Happening

When you define a parameter with an enum, you’re constraining the model to only output values that exactly match one of the predefined options. In your example, if an enum is set—even if the prompt or external code describes numbers—the model will only return one of the enumerated strings.

Guidance from the Documentation

The official docs highlight using enums to help reduce hallucinations by limiting the set of possible values. For instance, in cases where you expect fixed string values (like T-shirt sizes), an enum is very useful. However, if the expected type is a number, adding an enum (which enforces string values) will force the model to output strings instead of actual numbers.

Recommendation

If you need the model to return numbers or integers:

• Do not add an enum to that parameter.
• Instead, define the JSON schema for that parameter with the type set to "number" or "integer".
• This ensures that the output follows the proper numeric format, avoiding any additional coercion into strings.

Here’s an example illustrating the difference:

JSONCopied
// For string enums (suitable for fixed string choices)
{
  "name": "pick_tshirt_size",
  "description": "Select a t-shirt size",
  "parameters": {
    "type": "object",
    "properties": {
      "size": {
        "type": "string",
        "enum": ["s", "m", "l"],
        "description": "The size of the t-shirt to order"
      }
    },
    "required": ["size"],
    "additionalProperties": false
  }
}

JSONCopied
// For numeric values (do NOT use an enum here)
{
  "name": "set_points",
  "description": "Sets the points for a user",
  "parameters": {
    "type": "object",
    "properties": {
      "points": {
        "type": "number",
        "description": "The number of points to assign"
      }
    },
    "required": ["points"],
    "additionalProperties": false
  }
}

By defining the parameter as a number without an enum, the model should return numeric output that your code can handle correctly.

Summary

The observed behavior is expected when an enum is present. To get numeric outputs, remove the enum and ensure your parameter type is set correctly in your function definition.