Extending Agent Capabilities with Tools

Welcome back! In the last lesson, you learned how to manage multi-turn conversations with your agent, enabling your TypeScript applications to remember and build on previous exchanges. This is essential for creating natural, interactive experiences. Now, you’re ready to take the next step: extending your agent’s capabilities beyond just generating text.

In real-world applications, agents often need to do more than just chat — they might need to search the web, perform calculations, or interact with external systems. The OpenAI Agents SDK for TypeScript makes this possible by allowing you to add “tools” to your agents. Tools can be built-in (like web search) or custom function tools that you define yourself using the tool helper and Zod schemas for parameter validation. By the end of this lesson, you’ll know how to add both types of tools to your agent, making it much more powerful and useful.

The OpenAI Agents SDK for TypeScript comes with several built-in tools that you can add to your agent with just a few lines of code. One of the most useful is the webSearchTool(), which allows your agent to search the web for up-to-date information. This is especially helpful when your agent needs to answer questions about recent events or look up facts that are not part of its training data.

Let’s look at a simple example. Suppose you want to create an agent that can answer questions by searching the web. You can do this by adding the webSearchTool() to the tools array of your agent:

import { Agent, webSearchTool } from '@openai/agents';

const agent = new Agent({
  name: "Research Assistant",
  instructions: "You are a research assistant who can search the web to answer questions.",
  model: "gpt-5.6-terra",
  modelSettings: { providerData: { reasoning: { effort: "none" } } },
  tools: [webSearchTool()]
});

With this setup, your agent can now use the web search tool whenever it needs to find information. This is a big step up from a basic text-only agent, as it can now provide answers based on the latest information available online.

While built-in tools are powerful, sometimes you need your agent to perform a specific task that is unique to your application. This is where custom function tools come in. The OpenAI Agents SDK for TypeScript allows you to turn any function into a tool that your agent can use by defining it with the tool helper and specifying the expected input parameters using a Zod schema.

For example, suppose you want your agent to calculate the number of years between two historical events. You can define a custom function tool like this:

import { tool } from '@openai/agents';
import { z } from 'zod';

// Define a Zod schema for the input parameters
const calculateYearsBetween = tool({
  name: 'calculate_years_between',
  description: 'Calculate the absolute difference in years between two years',
  parameters: z.object({
    year1: z.number().describe('The first year'),
    year2: z.number().describe('The second year')
  }),
  async execute({ year1, year2 }) {
    return Math.abs(year2 - year1);
  }
});

Here, the Zod schema defines that the function expects an object with two numeric fields: year1 and year2. The tool helper registers the function as a tool, and the description provides a human-readable explanation that the agent can use to decide when and how to use the tool. By using Zod schemas, you ensure that the agent understands the required input structure, which is essential for reliable and accurate tool usage.

Now that you have both a built-in tool (webSearchTool()) and a custom function tool (calculateYearsBetween), you can combine them in a single agent. This allows your agent to use both tools as needed to answer user questions.

Here’s how you can create an agent with multiple tools:

import { Agent, webSearchTool } from '@openai/agents';

const agent = new Agent({
  name: 'Historical Calculator',
  instructions:
    'You are a helpful assistant that can calculate the number of years ' +
    'between two historical events. You should first search the web to find ' +
    'the years of the events, then use the calculation tool to find the ' +
    'difference.',
  model: 'gpt-5.6-terra',
  modelSettings: { providerData: { reasoning: { effort: 'none' } } },
  tools: [webSearchTool(), calculateYearsBetween]
});

In this example, the agent is given clear instructions on how to use its tools: first, search the web to find the years of the events, and then use the calculation tool to find the difference. By listing both tools in the tools array, you make them available for the agent to use during its reasoning process.

If you want to verify that the custom function tool you created is correctly set up for your agent to use, you can inspect the agent's list of tools and print out details for each one. This is especially useful for checking that your tool's name, description, and parameter schema are registered as expected.

To do this, you can iterate through the agent's tools array and print information for each tool:

for (const tool of agent.tools) {
  console.log(tool);
}

This will output details for each tool. For our example agent with both the web search tool and the custom calculation tool, you'll see output like this:

{
  type: 'hosted_tool',
  name: 'web_search_preview',
  providerData: {
    type: 'web_search',
    name: 'web_search_preview',
    userLocation: undefined,
    searchContextSize: 'medium'
  }
}
{
  type: 'function',
  name: 'calculate_years_between',
  description: 'Calculate the absolute difference in years between two years',
  parameters: {
    type: 'object',
    properties: { year1: [Object], year2: [Object] },
    required: [ 'year1', 'year2' ],
    additionalProperties: false,
    '$schema': 'http://json-schema.org/draft-07/schema#'
  },
  strict: true,
  invoke: [AsyncFunction: invoke],
  needsApproval: [AsyncFunction (anonymous)]
}

Notice how the agent sees each tool differently. The built-in web search tool appears as a hosted_tool with provider-specific configuration, while your custom function tool appears as a function type with the exact name and description you provided. Most importantly, the parameters field shows the JSON schema that was automatically generated from your Zod schema — this is what the agent uses to understand what arguments it needs to provide when calling your tool. The agent can read the description to understand when to use the tool and examine the parameters schema to know exactly what data structure to pass when invoking it.

Once your agent has its tools, you can run it just like before. The difference is that now, the agent can decide when to use each tool to answer the user's question. For example, if you ask, "How many years are there between Benjamin Franklin's discovery of electricity and ChatGPT?", the agent will first use the web search tool to find the years of each event, then use the calculation tool to compute the difference.

Here's how you can run the agent and see the result:

import { run } from '@openai/agents';

const result = await run(
  agent,
  "How many years between Benjamin Franklin's discovery of electricity and ChatGPT?"
);

// Print the result history
console.log(JSON.stringify(result.history, null, 2));

By inspecting the result.history, you can view a detailed, step-by-step breakdown of how the agent used its tools — including each tool invocation, the arguments passed, and the outputs returned. The history starts with the user's question:

[
  {
    "type": "message",
    "role": "user",
    "content": "How many years between Benjamin Franklin's discovery of electricity and ChatGPT?"
  },
  ...
]

Next, you'll see how the agent uses the web search tool to find information about the historical events:

  ...
  {
    "type": "hosted_tool_call",
    "id": "ws_686beb3e514c819b8a73112952aafd9c09afe8f7179c8b66",
    "name": "web_search_call",
    "status": "completed",
    "providerData": {
      "action": {
        "type": "search",
        "query": "What year did Benjamin Franklin discover electricity?"
      }
    }
  },
  ...

After the web search, the agent provides its findings with citations:

  ...
  {
    "type": "message",
    "id": "msg_686beb415c90819bb5e0989da817ccee09afe8f7179c8b66",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Benjamin Franklin conducted his famous kite experiment in June 1752, demonstrating that lightning is a form of electricity. ([en.wikipedia.org](https://en.wikipedia.org/wiki/Kite_experiment?utm_source=openai)) ChatGPT was launched by OpenAI in November 2022. ([qa.time.com](https://qa.time.com/6309022/sam-altman-ai/?utm_source=openai)) Therefore, there are 270 years between Franklin's experiment and the release of ChatGPT. ",
        "annotations": [
          {
            "type": "url_citation",
            "end_index": 209,
            "start_index": 124,
            "title": "Kite experiment",
            "url": "https://en.wikipedia.org/wiki/Kite_experiment?utm_source=openai"
          },
          {
            "type": "url_citation",
            "end_index": 336,
            "start_index": 259,
            "title": "Sam Altman",
            "url": "https://qa.time.com/6309022/sam-altman-ai/?utm_source=openai"
          }
        ],
        "logprobs": []
      }
    ],
    "status": "completed",
    "providerData": {}
  },
  ...

Finally, you can see how the agent uses your custom calculation tool to compute the exact difference:

  ...
  {
    "type": "function_call",
    "id": "fc_686beb43270c819bbc4058538dfeb7a109afe8f7179c8b66",
    "callId": "call_UezkPqPohuomIsk6X4e2Ic0O",
    "name": "calculate_years_between",
    "status": "completed",
    "arguments": "{\"year1\":1752,\"year2\":2022}",
    "providerData": {
      "type": "function_call"
    }
  },
  {
    "type": "function_call_result",
    "name": "calculate_years_between",
    "callId": "call_UezkPqPohuomIsk6X4e2Ic0O",
    "status": "completed",
    "output": {
      "type": "text",
      "text": "270"
    }
  }
]

This shows how the agent used both tools to answer the question, providing a clear and accurate response.

Integrating tools with different agentic systems can be difficult and time-consuming. Each platform often has its own way of defining and connecting tools, leading to duplicated work, inconsistent APIs, and maintenance headaches. As you add more tools or want to support multiple agent frameworks, these challenges multiply.

The Model Context Protocol (MCP) is a game changer. MCP is an open standard that lets you develop a tool once and make it available to any agentic system that supports the protocol. It standardizes how tools are described, discovered, and invoked, making integration much simpler and more reliable. With MCP, you can build tools that work across platforms, reduce integration effort, and improve security and governance.

In the next course, you’ll learn what MCP is, how it works, and how to develop and integrate your own MCP server—unlocking even more powerful and flexible agentic applications.

In this lesson, you learned how to extend your agent’s capabilities by adding both built-in and custom function tools using the OpenAI Agents SDK for TypeScript. You saw how to use the webSearchTool() for real-time information and how to create your own function tools with the tool helper and Zod schemas for clear input validation. You also learned how to combine multiple tools in a single agent, verify tool registration, and observe how agents use these tools step by step.

You also explored the broader challenges of integrating tools across different agentic systems and how the Model Context Protocol (MCP) is emerging as a solution to these problems. In the next course, you’ll dive deeper into MCP — learning what it is, how it works, and how to develop and integrate your own MCP server to make your tools universally accessible to any agentic platform.

Now, get ready to put your knowledge into practice with a set of hands-on exercises. These will help you reinforce what you’ve learned by building and using agents with both built-in and custom tools.