Defining Function Schemas for the API
Write JSON Schema definitions for your functions, pass them in the tools parameter, and understand how the model decides when and how to call them.
Defining Function Schemas for the API is a free AI Engineering Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Engineering Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Is Function Calling?
OpenAI's function calling (now called tool calling) lets you describe Python functions to the model in a structured JSON Schema format. When the model determines a function should be called, instead of producing free-text it returns a structured JSON object with the function name and arguments — which your code then executes reliably.
The tools Parameter Structure
You pass your function definitions to the API in the tools parameter as a list of objects. Each object has a type of 'function' and a function key containing the name, description, and a JSON Schema defining the parameters.
from openai import OpenAI
client = OpenAI()
tools = [
{
'type': 'function',
'function': {
'name': 'get_current_weather',
'description': 'Get the current weather in a given location.',
'parameters': {
'type': 'object',
'properties': {
'location': {
'type': 'string',
'description': 'City and country, e.g. London, UK'
},
'unit': {
'type': 'string',
'enum': ['celsius', 'fahrenheit'],
'description': 'Temperature unit to use.'
}
},
'required': ['location']
}
}
}
]JSON Schema for Parameters
The parameters field follows the JSON Schema specification. Use type to specify string, number, integer, boolean, array, or object. Use description for each property to tell the model what the field means. List required fields in the required array — optional fields can be omitted from required.
# A more complex schema with multiple types
create_event_tool = {
'type': 'function',
'function': {
'name': 'create_calendar_event',
'description': 'Create a new calendar event. Use when the user wants to schedule a meeting or appointment.',
'parameters': {
'type': 'object',
'properties': {
'title': {'type': 'string', 'description': 'Event title.'},
'start_time': {'type': 'string', 'description': 'ISO 8601 datetime, e.g. 2024-03-15T14:00:00.'},
'duration_minutes': {'type': 'integer', 'description': 'Duration in minutes.', 'minimum': 5},
'attendees': {
'type': 'array',
'items': {'type': 'string'},
'description': 'List of email addresses of attendees.'
},
'location': {'type': 'string', 'description': 'Physical or virtual meeting location.'}
},
'required': ['title', 'start_time', 'duration_minutes']
}
}
}Making the API Call with Tools
Pass the tools list directly to chat.completions.create. The model may respond with a regular text message (if it can answer without a function), or it may respond with a tool_calls object instructing you to execute a function. Always check finish_reason to know which case you're in.
response = client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'user', 'content': 'What is the weather in Tokyo?'}
],
tools=tools
)
print('Finish reason:', response.choices[0].finish_reason)
# 'tool_calls' means the model wants to call a function
# 'stop' means the model gave a regular text response
choice = response.choices[0].message
if response.choices[0].finish_reason == 'tool_calls':
print('Model wants to call:', choice.tool_calls[0].function.name)Controlling Tool Selection with tool_choice
The tool_choice parameter controls whether the model must call a function or can choose freely. Setting it to 'auto' lets the model decide. Setting it to 'required' forces a tool call. Setting it to a specific function name forces exactly that function to be called — useful for extraction tasks where you always want structured output.
# Force the model to always call extract_contact
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Hi, I am John Smith, john@example.com, +1-555-0100.'}],
tools=[extract_contact_tool],
tool_choice={'type': 'function', 'function': {'name': 'extract_contact'}}
)
# With tool_choice forced, finish_reason will always be 'tool_calls'Enum Fields for Constrained Choices
Use the enum field in your JSON Schema whenever a parameter should be restricted to a fixed set of values. This dramatically improves reliability — the model is much less likely to invent an invalid option when it can see the exact allowed values listed in the schema.
classify_sentiment_tool = {
'type': 'function',
'function': {
'name': 'classify_sentiment',
'description': 'Classify the sentiment of a customer review.',
'parameters': {
'type': 'object',
'properties': {
'sentiment': {
'type': 'string',
'enum': ['positive', 'negative', 'neutral', 'mixed'],
'description': 'The sentiment classification.'
},
'confidence': {
'type': 'number',
'minimum': 0.0,
'maximum': 1.0,
'description': 'Model confidence from 0 to 1.'
}
},
'required': ['sentiment', 'confidence']
}
}
}Nested Object Schemas
JSON Schema supports nested objects. Use 'type': 'object' with its own properties to define complex hierarchical data structures. This is ideal for extracting structured data from unstructured text like emails or documents.
extract_order_tool = {
'type': 'function',
'function': {
'name': 'extract_order',
'description': 'Extract order details from a customer email.',
'parameters': {
'type': 'object',
'properties': {
'customer': {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'email': {'type': 'string', 'format': 'email'}
},
'required': ['name']
},
'items': {
'type': 'array',
'items': {
'type': 'object',
'properties': {
'product_id': {'type': 'string'},
'quantity': {'type': 'integer', 'minimum': 1}
},
'required': ['product_id', 'quantity']
}
}
},
'required': ['customer', 'items']
}
}
}Generating Schemas from Pydantic Models
Writing JSON Schemas by hand is tedious and error-prone. Instead, define your data structure as a Pydantic model and use .schema() to generate the JSON Schema automatically. This also gives you Python-level validation when you deserialize the model's response.
from pydantic import BaseModel, Field
from typing import Optional, List
class ContactInfo(BaseModel):
name: str = Field(description='Full name of the person.')
email: Optional[str] = Field(None, description='Email address.')
phone: Optional[str] = Field(None, description='Phone number in E.164 format.')
company: Optional[str] = Field(None, description='Company or organization.')
# Auto-generate the JSON Schema
schema = ContactInfo.schema()
# Build the tool definition
extract_contact_tool = {
'type': 'function',
'function': {
'name': 'extract_contact',
'description': 'Extract contact information from text.',
'parameters': schema
}
}Writing Effective Function Descriptions
The function description is the key signal the model uses to decide when to call a tool. A good description is specific about the use case, mentions when the function should and should not be called, and describes what the output will be. Vague descriptions cause the model to call the wrong function or miss opportunities to call the right one.
- Vague: 'Get weather data.'
- Good: 'Get the current weather conditions for a specific city. Use when the user explicitly asks about weather in a named location. Returns temperature, conditions, and humidity.'
Strict Mode for Guaranteed Schema Adherence
OpenAI's strict mode for structured outputs guarantees the model will produce JSON that exactly matches your schema — no extra fields, no missing required fields. Enable it by setting 'strict': true in the function definition. Note: strict mode requires additionalProperties: false in all schema objects.
strict_tool = {
'type': 'function',
'function': {
'name': 'classify_ticket',
'description': 'Classify a support ticket into category and priority.',
'strict': True, # Enable strict schema adherence
'parameters': {
'type': 'object',
'additionalProperties': False, # Required for strict mode
'properties': {
'category': {
'type': 'string',
'enum': ['billing', 'technical', 'account', 'other']
},
'priority': {
'type': 'string',
'enum': ['low', 'medium', 'high', 'urgent']
}
},
'required': ['category', 'priority']
}
}
}Testing Your Function Schemas
Before deploying, test each function schema with diverse inputs: normal cases, edge cases, and adversarial inputs. Verify the model calls the right function, produces valid argument types, handles optional fields correctly, and respects enum constraints. Use the OpenAI Playground to iterate quickly before writing production code.
Quick Check
Test your understanding of defining function schemas for the OpenAI API.
Lesson Recap
In this lesson you learned: function schemas use JSON Schema to define parameter types, descriptions, and constraints, tool_choice controls whether the model must call a function or chooses freely, and Pydantic models can auto-generate JSON Schema to reduce manual schema writing. Next up we learn to process tool calls in your application by detecting, executing, and sending results back.
Frequently asked questions
Is the “Defining Function Schemas for the API” lesson free?
Yes — the full text of “Defining Function Schemas for the API” is free to read here on the web, and the AI Engineering Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Engineering Academy course, upgrade to CoddyKit PRO.
What will I learn in “Defining Function Schemas for the API”?
Write JSON Schema definitions for your functions, pass them in the tools parameter, and understand how the model decides when and how to call them. You practise AI Engineering Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start AI Engineering Academy?
No prior experience is required. AI Engineering Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Defining Function Schemas for the API” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this AI Engineering Academy lesson?
Yes. Every AI Engineering Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Defining Function Schemas for the API
- Processing Tool Calls in Your Application
- Parallel Function Calling
- Building a Natural Language Database Interface