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

# Adding Tools

> Integrating tools and extending task capabilities in the Upsonic framework

Tasks can be equipped with various tools to extend their capabilities. Tools are added through the `tools` parameter and can include custom functions, built-in tools, or tool collections.

## Single Tool

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

task = Task(
    description="Search for information about AI",
    tools=[web_search]
)

agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)
```

## Multiple Tools

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def data_processor(data: str) -> str:
    """Process and analyze data."""
    return f"Processed: {data}"

task = Task(
    description="Search for information about AI and process the results",
    tools=[web_search, data_processor]
)

agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)
```

## Tool Collections

```python theme={null}
from upsonic import Agent, Task
from upsonic.tools.common_tools.financial_tools import YFinanceTools

# Create a tool collection
finance_tools = YFinanceTools(
    stock_price=True,
    company_info=True,
    analyst_recommendations=True
)

task = Task(
    description="Get stock information for AAPL",
    tools=finance_tools.functions()
)

agent = Agent(model="anthropic/claude-sonnet-4-5")
agent.print_do(task)
```

## Tool Configuration

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

@tool(requires_confirmation=True)
def sensitive_operation(data: str) -> str:
    """Perform a sensitive operation that requires confirmation."""
    return f"Processed sensitive data: {data}"

task = Task(
    description="Process sensitive information with data 'Upsonic'",
    tools=[sensitive_operation]
)

agent = Agent(model="anthropic/claude-sonnet-4-5")
agent.print_do(task)
```

## Available Tool Configurations

| Configuration                        | Type                 | Description                                                     |
| ------------------------------------ | -------------------- | --------------------------------------------------------------- |
| **requires\_confirmation**           | bool                 | Pause for user confirmation before execution                    |
| **requires\_user\_input**            | bool                 | Prompt user for input during execution                          |
| **user\_input\_fields**              | List\[str]           | Fields to prompt user for when requires\_user\_input is True    |
| **external\_execution**              | bool                 | Handle execution externally (advanced use-cases)                |
| **show\_result**                     | bool                 | Display result directly to user without LLM processing          |
| **stop\_after\_tool\_call**          | bool                 | Terminate agent after this tool call                            |
| **sequential**                       | bool                 | Require sequential execution (no parallelization)               |
| **cache\_results**                   | bool                 | Cache the result based on arguments                             |
| **cache\_dir**                       | Optional\[str]       | Directory to store cache files                                  |
| **cache\_ttl**                       | Optional\[int]       | Time-to-live for cache entries in seconds                       |
| **tool\_hooks**                      | Optional\[ToolHooks] | Custom functions to run before/after tool execution             |
| **max\_retries**                     | Optional\[int]       | Maximum number of retries allowed for this tool (default: 5)    |
| **timeout**                          | Optional\[float]     | Timeout for tool execution in seconds (default: 30.0)           |
| **strict**                           | Optional\[bool]      | Enforce strict JSON schema validation on tool parameters        |
| **docstring\_format**                | str                  | Format of the docstring: 'google', 'numpy', 'sphinx', or 'auto' |
| **require\_parameter\_descriptions** | bool                 | Raise error if required parameter descriptions are missing      |

## Dynamic Tool Management

You can add or remove tools after task creation:

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

@tool
def web_search(query: str) -> str:
    """Search the web for information."""
    return f"Search results for: {query}"

@tool
def calculator(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

task = Task(description="Search for AI news and calculate 10 + 20")
agent = Agent("anthropic/claude-sonnet-4-5")

# Add tools dynamically
task.add_tools([web_search, calculator])

# Execute task with dynamically added tools
agent.print_do(task)

# Remove tools (for subsequent executions)
task.remove_tools([web_search], agent=agent)
```

## Accessing Registered Tools

After execution, access registered tools via the `registered_task_tools` attribute:

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

@tool
def calculator(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

task = Task(description="Calculate 5 + 3", tools=[calculator])
agent = Agent("anthropic/claude-sonnet-4-5")
agent.print_do(task)

# Access registered tools
print(task.registered_task_tools)  # Dict mapping tool names to wrapped tools
```

## Best Practices

* **Tool Validation**: All tools must have type hints and docstrings
* **Single Responsibility**: Each tool should have a clear, focused purpose
* **Error Handling**: Implement proper error handling within tool functions
* **Configuration**: Use tool configurations appropriately for security and user experience
* **Documentation**: Write clear docstrings that explain the tool's purpose to the LLM