From b5338f533420a4fb27a43dc717c602d177dead31 Mon Sep 17 00:00:00 2001
From: william-xue <20151622+william-xue@users.noreply.github.com>
Date: Thu, 23 Jul 2026 18:11:28 +0800
Subject: [PATCH] docs: document tool decorator alias

---
 docs/ref/decorators.md | 7 +++++++
 docs/tools.md          | 9 ++++++---
 mkdocs.yml             | 1 +
 3 files changed, 14 insertions(+), 3 deletions(-)
 create mode 100644 docs/ref/decorators.md

diff --git a/docs/ref/decorators.md b/docs/ref/decorators.md
new file mode 100644
index 0000000000..509bf417ce
--- /dev/null
+++ b/docs/ref/decorators.md
@@ -0,0 +1,7 @@
+# `Decorators`
+
+## `tool`
+
+`tool` is an alias for `function_tool`. Import it from `agents.decorators`.
+
+::: agents.decorators
\ No newline at end of file
diff --git a/docs/tools.md b/docs/tools.md
index 42c1ff22b0..0f06bae57f 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -252,6 +252,8 @@ You can use any Python function as a tool. The Agents SDK will set up the tool a
 
 We use Python's `inspect` module to extract the function signature, along with [`griffe`](https://mkdocstrings.github.io/griffe/) to parse docstrings and `pydantic` for schema creation.
 
+For new code, import [`tool`](ref/decorators.md#tool) from `agents.decorators`. It is a shorter alias for `function_tool` with the same runtime and typing behavior. The existing `function_tool` decorator remains fully supported.
+
 When you are using OpenAI Responses models, `@function_tool(defer_loading=True)` hides a function tool until `ToolSearchTool()` loads it. You can also group related function tools with [`tool_namespace()`][agents.tool.tool_namespace]. See [Hosted tool search](#hosted-tool-search) for the full setup and constraints.
 
 ```python
@@ -259,14 +261,15 @@ import json
 
 from typing_extensions import TypedDict, Any
 
-from agents import Agent, FunctionTool, RunContextWrapper, function_tool
+from agents import Agent, FunctionTool, RunContextWrapper
+from agents.decorators import tool
 
 
 class Location(TypedDict):
     lat: float
     long: float
 
-@function_tool  # (1)!
+@tool  # (1)!
 async def fetch_weather(location: Location) -> str:
     # (2)!
     """Fetch the weather for a given location.
@@ -278,7 +281,7 @@ async def fetch_weather(location: Location) -> str:
     return "sunny"
 
 
-@function_tool(name_override="fetch_data")  # (3)!
+@tool(name_override="fetch_data")  # (3)!
 def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str:
     """Read the contents of a file.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index c38e747653..a987a20f2e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -121,6 +121,7 @@ plugins:
                     - Run error handlers: ref/run_error_handlers.md
                     - Memory: ref/memory.md
                     - REPL: ref/repl.md
+                    - Decorators: ref/decorators.md
                     - Tools: ref/tool.md
                     - Tool context: ref/tool_context.md
                     - Results: ref/result.md