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

# Attributes

> Configuration options for custom tools

## Attributes

Custom tools support comprehensive configuration through the `@tool` decorator:

| Attribute                        | Type              | Default  | Description                                                                       |
| -------------------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- |
| `requires_confirmation`          | bool              | `False`  | Require user confirmation before execution                                        |
| `requires_user_input`            | bool              | `False`  | Prompt user for input during execution                                            |
| `user_input_fields`              | List\[str]        | `[]`     | Specify which fields require user input                                           |
| `external_execution`             | bool              | `False`  | Mark tool for external execution                                                  |
| `show_result`                    | bool              | `False`  | Display output to user instead of sending to LLM                                  |
| `stop_after_tool_call`           | bool              | `False`  | Terminate agent run after tool execution                                          |
| `sequential`                     | bool              | `False`  | Enforce sequential execution (no parallelization)                                 |
| `cache_results`                  | bool              | `False`  | Enable result caching                                                             |
| `cache_dir`                      | str \| None       | `None`   | Directory for cache storage                                                       |
| `cache_ttl`                      | int \| None       | `None`   | Cache time-to-live in seconds                                                     |
| `tool_hooks`                     | ToolHooks \| None | `None`   | Before/after execution hooks                                                      |
| `max_retries`                    | int               | `5`      | Maximum retry attempts                                                            |
| `timeout`                        | float \| None     | `30.0`   | Execution timeout in seconds                                                      |
| `strict`                         | bool \| None      | `None`   | Enforce strict JSON schema validation                                             |
| `docstring_format`               | str               | `"auto"` | Docstring parsing format: 'google', 'numpy', 'sphinx', 'auto'                     |
| `require_parameter_descriptions` | bool              | `False`  | Require descriptions for all parameters in docstring                              |
| `instructions`                   | str \| None       | `None`   | Instructions for the LLM on how to use this tool, injected into the system prompt |
| `add_instructions`               | bool              | `False`  | If True, the tool's instructions will be appended to the agent's system prompt    |

## Example Usage

```python theme={null}
from upsonic import Agent, Task
from upsonic.tools import tool, ToolHooks

# Define hooks
def before_search(**kwargs):
    print(f"Searching for: {kwargs.get('query')}")
    return {"logged_query": kwargs.get('query')}

def after_search(result, **kwargs):
    print(f"Found {len(result)} results")
    return {"result_count": len(result)}

hooks = ToolHooks(before=before_search, after=after_search)

@tool(
    requires_confirmation=True,
    timeout=30,
    max_retries=2,
    cache_results=True,
    cache_ttl=3600,
    tool_hooks=hooks,
    sequential=True
)
def search_database(query: str, limit: int = 10) -> list:
    """
    Search the database for matching records.
    
    Args:
        query: Search query string
        limit: Maximum number of results to return
    
    Returns:
        List of matching records
    """
    return [f"Record {i}: Found '{query}' in database" for i in range(1, limit + 1)] 

# Create agent and task
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
    description="Search the database for 'Upsonic' and return the top 5 results",
    tools=[search_database]
)

# Execute
result = agent.print_do(task)
print("Result:", result)
```

<Info>
  `requires_confirmation=True` is designed for interactive environments where a user can respond to confirmation prompts. When running scripts non-interactively, remove this attribute or set it to `False` to avoid blocking.
</Info>