---
title: @ai.tool
description: Define executable tools from Python functions.
type: reference
summary: Reference for the ai.tool decorator.
---

# @ai.tool



`@ai.tool` turns an async Python function into an executable `AgentTool`.

```python
@ai.tool
async def contact_mothership(query: str) -> str:
    """Contact the mothership."""
    return "Soon."
```

## Forms

```python
@ai.tool
async def name(...) -> Result: ...

@ai.tool(require_approval=True)
async def name(...) -> Result: ...

@ai.tool(aggregator=...)
async def name(...) -> AsyncGenerator[Item]: ...
```

The function name becomes the tool name. The docstring becomes the tool
description. The function signature becomes a Pydantic validator and JSON
schema.

For model-facing tool declarations and provider-executed tools, use
[`ai.tools`](/docs/reference/tools).


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)