Building the OpenAI Tool Definition

You've created the convert_timezone() function that uses the OpenTimezone API to convert datetimes between timezones. Now you need to create a tool definition in OpenAI's format so the LLM can understand how to use this function. The tool definition acts as a manual for the model, describing the function's purpose, parameters, and requirements.

This exercise is part of the course

Working with the OpenAI Responses API

Exercise instructions

Define a "function" type tool called "convert_timezone".
Create definitions for each of the function's three parameters: "date_time", "from_timezone", and "to_timezone".
Ensure that all three of the parameters are marked as required by the tool.

Hands-on interactive exercise

Have a go at this exercise by completing this sample code.

tools = [
    {
        # Define a function tool called convert_timezone
        "type": "____",
        "name": "____",
        "description": "Convert a datetime from one timezone to another using the OpenTimezone API.",
        "parameters": {
            "type": "object",
            # Define the parameter names, types, and descriptions
            "properties": {
                "____": {
                    "type": "____",
                    "description": "The datetime string in ISO format (e.g., '2025-01-20T14:30:00')"
                },
                "____": {
                    "type": "____",
                    "description": "The source timezone (e.g., 'America/New_York', 'Asia/Tokyo')"
                },
                "____": {
                    "type": "____",
                    "description": "The target timezone (e.g., 'Europe/London', 'Australia/Sydney')"
                }
            },
            # Ensure that all three parameters are required
            "____": ["date_time", "from_timezone", "to_timezone"],
            "additionalProperties": False
        }
    }
]

Edit and Run Code

This exercise is part of the course

Working with the OpenAI Responses API

IntermediateSkill Level

5.0+

Start Course for Free

Building AI applications has never been easier with the Responses API! Learn how to prompt models using a simple interface, best practices for working with reasoning models, and how to build back-and-forth conversations with LLMs.

Exercise 1: The Responses API: a Developer's Best Friend Exercise 2: Your First Responses API Call Exercise 3: Adding Model Instructions Exercise 4: Extracting Information from the Response Exercise 5: Mastering Response Parameters Exercise 6: Experimenting with More Powerful Models Exercise 7: Reasoning About Reasoning Exercise 8: Conversation Chaining Exercise 9: From One Message to Another Exercise 10: Enabling Chat Conversations

LLMs are powerful, but they're even more powerful once tools are introduced! Learn how to integrate web search with your LLM systems with no additional API keys or credentials. Discover that tools can be, well... pretty much anything! Build your own tools for LLMs to call to go beyond the model's base capabilities.

Exercise 1: Response Items: The Building Blocks Exercise 2: Extracting Output Items and Their Contents Exercise 3: Using Items for Custom Handling Exercise 4: Web Search That Just Works Exercise 5: Combining LLMs and Web Search Exercise 6: Building Confidence with LLM Sources Exercise 7: Function-Calling Tools: Defining the Function Exercise 8: The Function-Calling Tool Workflow Exercise 9: Defining a Function for Converting Timezones Exercise 10: Function-Calling Tools: The Full Workflow Exercise 11: Building the OpenAI Tool Definition

Current Exercise

Exercise 12: Integrating Function-Calling Tools

Move your LLM systems from proof-of-concept to production with three key design paradigms. Learn how to generate consistent and reliable structured outputs, like JSON, using LLMs. You'll also use semantic events to stream updates to your users, creating interactive and enjoyable experiences. Finally, go multi-modal and learn how to combine text and images with OpenAI's GPT-5 models.

Exercise 1: Generating Structured Outputs Exercise 2: Consistent Outputs, Every Time!Exercise 3: Nesting Pydantic Classes Exercise 4: Streaming with Semantic Events Exercise 5: Streaming OpenAI Responses Exercise 6: Streaming Semantic Events Exercise 7: Streaming with Function Calls Exercise 8: Input Flexibility and Multimodality Exercise 9: Role-Based Inputs Exercise 10: Prompting with Images from URLs Exercise 11: Prompting with Local Image Files Exercise 12: Congratulations!