> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.