docs: document tool decorator alias

docs/ref/decorators.md

@@ -0,0 +1,7 @@
+# `Decorators`
+
+## `tool`
+
+`tool` is an alias for `function_tool`. Import it from `agents.decorators`.
+
+::: agents.decorators

docs/tools.md

@@ -252,21 +252,24 @@ 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
 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.
 

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