Function Tool Parameter Schema

Overview

This page is a focused reference for the JSON-Schema-based parameters object on a function tool — the fields the model itself fills in at runtime — plus the strict and maxTokens fields that control validation and token allocation. For the broader walkthrough of creating and using custom function tools (transient vs. permanent, webhook setup, server config), see Custom Function Tools.

A function tool's function.parameters field is a standard JSON Schema object describing the inputs the model can populate from what the caller says. It always has this shape:

• type — always "object" at the top level
• properties — an object where each key is a parameter name, and each value defines that parameter's own type and description
• required — an array naming which of those parameters the model must supply

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name for the lookup"
    }
  },
  "required": ["city"]
}

required must be an array of parameter name strings — never a boolean and never an object. A common mistake is setting required: true at the property level; that isn't valid JSON Schema for this purpose. Instead, list every parameter name the model must supply in the top-level required array:

"required": ["contactId", "updates"]

Setting "strict": true on a function tool enables stricter schema validation, catching malformed tool calls before they reach your server rather than after. When troubleshooting a tool that seems to be receiving bad or missing data, check your call logs for a "Schema validation errors" entry — this is the surest sign the model's tool call didn't match the schema you defined.

The maxTokens field controls how many tokens are allocated to the tool's parameters and response. The default is only 100 tokens, which is frequently too low for tools with several parameters or verbose responses. If tool parameters or responses are getting cut off mid-value, raise this field — for example, to 500:

{
  "maxTokens": 500
}

Check your call logs for truncation-related warnings as a signal that maxTokens needs to go up.

{
  "type": "function",
  "name": "update_crm_contact",
  "description": "Update contact information in the CRM system",
  "parameters": {
    "type": "object",
    "properties": {
      "contactId": {
        "type": "string",
        "description": "CRM contact ID"
      },
      "updates": {
        "type": "object",
        "description": "Fields to update"
      }
    },
    "required": ["contactId", "updates"]
  },
  "strict": true,
  "maxTokens": 500
}

Defining a tool doesn't tell the assistant when to use it. Use the tool's exact name in the assistant's system prompt so the model reliably recognizes when to invoke it, for example: "When the caller asks to update their contact info, call update_crm_contact." A vague or mismatched description in the prompt is one of the most common reasons a correctly-configured tool never actually gets called.