> ## Documentation Index
> Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @tool Decorator

> Reference for the @tool decorator.

```python theme={null}
from definable.tool.decorator import tool
```

## Parameters

| Parameter               | Type             | Default        | Description                                                |
| ----------------------- | ---------------- | -------------- | ---------------------------------------------------------- |
| `name`                  | `str`            | function name  | Tool name shown to the model.                              |
| `description`           | `str`            | from docstring | Tool description.                                          |
| `strict`                | `bool`           | `False`        | Strict parameter validation.                               |
| `instructions`          | `str`            | `None`         | Usage instructions added to system prompt.                 |
| `add_instructions`      | `bool`           | `True`         | Whether to add instructions to system prompt.              |
| `show_result`           | `bool`           | `False`        | Show result in streaming output.                           |
| `stop_after_tool_call`  | `bool`           | `False`        | Stop agent loop after this tool.                           |
| `requires_confirmation` | `bool`           | `False`        | Pause for user confirmation.                               |
| `requires_user_input`   | `bool`           | `False`        | Pause for user input.                                      |
| `pre_hook`              | `Callable`       | `None`         | `(tool_name, args) -> None`. Runs before execution.        |
| `post_hook`             | `Callable`       | `None`         | `(tool_name, args, result) -> None`. Runs after execution. |
| `tool_hooks`            | `List[Callable]` | `None`         | List of hook functions.                                    |
| `cache_results`         | `bool`           | `False`        | Cache results for identical arguments.                     |
| `cache_ttl`             | `int`            | `3600`         | Cache TTL in seconds.                                      |

## Supported Parameter Types

| Type          | JSON Schema                             |
| ------------- | --------------------------------------- |
| `str`         | `{"type": "string"}`                    |
| `int`         | `{"type": "integer"}`                   |
| `float`       | `{"type": "number"}`                    |
| `bool`        | `{"type": "boolean"}`                   |
| `List[T]`     | `{"type": "array", "items": ...}`       |
| `Optional[T]` | Nullable variant                        |
| `Enum`        | `{"type": "string", "enum": [...]}`     |
| `BaseModel`   | `{"type": "object", "properties": ...}` |

## Schema Generation

* Function name → tool name
* Docstring first line → tool description
* `Args:` section → per-parameter descriptions
* Type hints → JSON Schema types
* Default values → optional parameters