Writing Tool Schemas for GPT-5

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.

/**
 * Sum two numbers and return the result.
 *
 * @param args - The input object containing a and b
 * @param args.a - First number to add
 * @param args.b - Second number to add
 * @returns The sum of a and b
 */
export function sumNumbers(args: { a: number, b: number }): number {
  return args.a + args.b;
}

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.