Welcome to your first lesson in developing GPT-5 agents with tool integration! In this lesson, you'll learn the foundational skill of preparing function schemas that enable GPT-5 to understand and request the use of your custom tools through a process called function calling.

By the end of this lesson, you'll understand how to write TypeScript functions and create JSON schemas that describe these functions to GPT-5. These schemas are the bridge that allows GPT-5 to understand what your functions do and how to call them, even though GPT-5 never sees your actual TypeScript code. This foundational step is essential before you can build a complete GPT-5 agent system that can execute tools and use their results.

Function calling is the mechanism that allows GPT-5 to use external tools and capabilities beyond text generation. Here's how the process works:

1. You provide GPT-5 with function schemas (JSON descriptions of your tools).
2. GPT-5 analyzes user requests and determines if any of your tools would be helpful.
3. If GPT-5 decides a tool is needed, it responds with a tool use request that includes the function name and specific parameters.
4. Your system receives this tool use request and executes the corresponding TypeScript function with the provided parameters.
5. Your system sends the function result back to GPT-5.
6. GPT-5 incorporates this result into its response to the user or decides to use additional tools if needed.

The key insight is that GPT-5 only sees the schemas (JSON descriptions), never your actual TypeScript code. The schemas must contain all the information GPT-5 needs to understand what each tool does and how to use it correctly. This separation means you can organize your TypeScript functions however you like — GPT-5 relies entirely on the schema descriptions to make decisions about tool usage.

When creating tool functions for GPT-5 agents, your TypeScript functions serve two purposes: they contain the actual logic that will be executed, and they provide the foundation for creating accurate schemas.

You might notice a specific pattern in how we define these functions: they accept a single object argument rather than multiple separate arguments.

Why use a single object argument?

This is a critical safety pattern for AI engineering. When GPT-5 decides to call a tool, it generates parameters as a JSON object (e.g., {"a": 10, "b": 5}). In the JSON specification, objects are technically unordered. This means GPT-5 might validly return {"b": 5, "a": 10}.

If your function relied on the order of arguments—like function(a, b)—and the parameters arrived in a different order than expected, you could end up with serious bugs (imagine a subtraction function calculating 5 - 10 instead of 10 - 5).

By defining your function to accept a single object (args), TypeScript maps values by their name (args.a, args.b) rather than their position. This ensures your tools always execute correctly, regardless of the order in which GPT-5 generates the parameters.

JSON schemas are the structured descriptions that tell GPT-5 exactly what each tool does and how to use it. These schemas are the only information GPT-5 receives about your tools, making them crucial for successful function calling.

Each schema contains several essential components that GPT-5 uses to understand your tool:

• The type field indicates this is a function schema.
• The name field identifies the tool and should be descriptive to help GPT-5 understand what the tool does and when to use it. While it doesn't necessarily need to match your TypeScript function name, keeping them consistent helps maintain clarity in your code.
• The description tells GPT-5 what the tool does and when to use it.
• The parameters section describes the function parameters using JSON Schema format. Notice how this structure perfectly matches our TypeScript function's single object argument.
• The required array lists which parameters are mandatory.
• The additionalProperties field ensures only the specified parameters are allowed.

GPT-5 uses this schema information to decide when to use your tool and what parameters to provide. If the descriptions are unclear or incomplete, GPT-5 may use the tool incorrectly or not at all.

Real GPT-5 agents typically have access to multiple tools, each described by its own schema. Let's create a second function and organize our functions in a dedicated file. In your functions.ts file, you can collect your tool functions:

Organizing your functions in a separate file keeps your code organized and makes it easy to import them when needed. Each function follows the same pattern with clear type annotations and detailed JSDoc comments, providing consistency across your tool collection. The export keyword makes these functions available for import in other modules.

Just as you organize your TypeScript functions in functions.ts, you can organize your corresponding schemas in a schemas.json file. This creates a clean separation between your implementation and the descriptions that GPT-5 will see:

When GPT-5 receives this array of schemas, it can analyze user requests and select the most appropriate tool. For example, if a user asks, "What's 5 plus 3?", GPT-5 would choose sum_numbers. If they ask, "What's 4 times 7?", GPT-5 would choose multiply_numbers. The clear descriptions in each schema help GPT-5 make these decisions accurately.

After organizing your functions in functions.ts and schemas in schemas.json, you need to load both and create a mapping that connects them. This creates two essential components: the schemas that you provide to GPT-5, and the mapping that you use to execute functions when GPT-5 requests them.

The toolSchemas variable contains the JSON array that you'll provide to GPT-5 — this is how GPT-5 learns about your available tools and their capabilities. The tools object is your internal mapping that you use to execute the correct TypeScript function when GPT-5 requests a tool by name. The Record<string, Function> type annotation indicates this is an object mapping string keys to function values.

This mapping must be precise — the keys in your tools object must exactly match the name fields in your schemas. If there's a mismatch, your system won't be able to execute the function when GPT-5 requests it.

For example, when GPT-5 analyzes a user request and decides to use the "sum_numbers" tool with parameters {"a": 10, "b": 5}, the process works like this:

1. GPT-5 references the toolSchemas to understand available tools.

Before using your tool schemas with GPT-5, it's important to verify they're structured correctly and contain all necessary information:

This displays your tool definitions in a formatted way, allowing you to review each schema's structure:

Review this output to ensure your schemas have clear descriptions, correct parameter types, and complete required field lists. These details are crucial since GPT-5 depends entirely on this schema information to use your tools correctly.

With your schemas verified and mapping in place, you can test that your system can successfully execute tools based on their names:

Running this code produces:

This confirms your function mapping works correctly and your system can execute tools by name. When GPT-5 requests tool usage through function calling, you'll receive the tool name and parameters from GPT-5, then use this mapping to look up and call the corresponding TypeScript function yourself before sending the result back to GPT-5.

You've now learned the essential process of preparing tools for GPT-5 agents through function calling. This involves writing well-structured TypeScript functions, creating detailed JSON schemas that describe these functions to GPT-5, and setting up a mapping system that connects schema names to actual function implementations.

Remember the key separation: GPT-5 only sees the schemas and uses them to make tool selection decisions and provide parameters. Your TypeScript functions and mapping system handle the actual execution. The quality of your schemas directly impacts how effectively GPT-5 can use your tools.

In the upcoming practice exercises, you'll apply these concepts to create your own tool functions and schemas, building toward the point where you can integrate these prepared tools with GPT-5 for powerful agent capabilities.