> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Tools
description: Define tools with @tool, give agents a schema from type hints, and run tools on their own
category: Python SDK
hideRightSidebar: true
---

A tool is a function an agent can call. The model sees its name, description, and input schema, and decides when to call it. For a guided introduction, see [Tools](/docs/build/tools.md).

## `@tool`

```python
from agnt5 import Context, tool


@tool(name="lookup_order", description="Look up an order by ID")
async def lookup_order(ctx: Context, order_id: str) -> dict:
    return {"order_id": order_id, "status": "shipped"}
```

The first parameter must be `ctx: Context`. The input schema comes from the other parameters' type hints, so the model fills `order_id` as a string.

```python
tool(*, name=None, description=None, auto_schema=True, input_schema=None)
```

| Parameter | Description |
|---|---|
| `name` | The tool's name. Defaults to the Python function's name. |
| `description` | What the tool does. The model reads it to decide when to call the tool. |
| `auto_schema` | Build the input schema from type hints. Default `True`. |
| `input_schema` | A JSON Schema to use instead of the generated one. |

## Use and register a tool

Give the tool to an agent with `Agent(tools=[lookup_order])`. To run it on its own, pass it to the worker's `tools` list:

```bash
agnt5 run lookup_order --type tool --input '{"order_id": "A1"}'
```

An agent can also be a tool: `agent.to_tool()`. See [Agents](/sdk/python/agents.md#agents-as-tools).

## Next steps

* [Agents](/sdk/python/agents.md): run the loop that calls tools.
* [Tools guide](/docs/build/tools.md): sandbox tools, MCP tools, built-in tools, and asking people from a tool.