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


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