Tools: File Search, MCP and Functions

Hosted tools, MCP servers and your own functions

Agents act through tools. Typical options include hosted tools such as file search over uploaded documents and web search, MCP servers that expose your systems through the Model Context Protocol, and in code your own function tools. The model decides when to call a tool based on its name, description and parameter schema, so write them like documentation: what it does, when to use it, what each parameter means. Give each agent only the tools it needs; every extra tool is another way to go wrong.

A function tool and its generated schema, run

I ran this with Python 3, the openai-agents package 0.22.3 and pydantic 2.13.5, without any API key: it only builds definitions and schemas, no model is called. The decorator turns a typed Python function and its docstring into a tool: the name, the description from the first docstring line, and a strict JSON schema with order_id required and described.

import json
from agents import function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up the shipping status of an order.

    Args:
        order_id: The order number, for example A1042.
    """
    return "shipped"

print("tool name  :", get_order_status.name)
print("description:", get_order_status.description)
print("schema     :", json.dumps(get_order_status.params_json_schema, indent=1))

Output:

tool name  : get_order_status
description: Look up the shipping status of an order.
schema     : {
 "properties": {
  "order_id": {
   "description": "The order number, for example A1042.",
   "title": "Order Id",
   "type": "string"
  }
 },
 "required": [
  "order_id"
 ],
 "title": "get_order_status_args",
 "type": "object",
 "additionalProperties": false
}

Return errors as data

Have tools return clear error messages (order not found) instead of crashing, so the agent can recover or ask the user.

Quick check: What does the model rely on to decide when to call a tool?

• The font of the UI
• The tool's source code
• The server's IP address
• The tool's name, description and parameter schema