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

# Tool function

# Creating Custom Tools in PySpur using @tool\_function

This guide will walk you through the process of converting an arbitrary Python function into a PySpur tool using the `@tool_function` decorator. This allows you to integrate custom logic into your PySpur workflows seamlessly.

## Prerequisites

* Ensure you have initialized a PySpur project using the `pyspur init` command.

## Step-by-Step Guide

### Step 1: Create a Tool File

1. Navigate to the `tools` directory in your PySpur project. This directory is created automatically when you initialize your project.

2. Create a new Python file for your tool. For example, `my_custom_tool.py`.

### Step 2: Define Your Function

1. In your new tool file, define the Python function you want to convert into a tool. This function should contain the logic you wish to execute.

```python theme={null}
def foo(param1: str, param2: int = 42) -> dict:
    """A simple example function."""
    return {"param1": param1, "param2": param2}
```

### Step 3: Decorate Your Function

1. Import the `tool_function` decorator from the appropriate module.

2. Use the `@tool_function` decorator to register your function as a tool. You can specify optional parameters such as `name`, `description`, `category`, and `output_model`.

```python theme={null}
from pyspur.nodes.decorator import tool_function

@tool_function(
    name="bar", 
    description="A custom tool example", 
    category="Custom")
def foo(param1: str, param2: int = 42) -> dict:
    """A simple example function."""
    return {"param1": param1, "param2": param2}
```

#### @tool\_function Parameters

* **name** (Optional\[str]): The name of the tool. Defaults to the function name if not provided.
* **display\_name** (Optional\[str]): A human-readable name for the tool, used in the UI. Defaults to a title-cased version of the function name.
* **description** (Optional\[str]): A brief description of what the tool does. Defaults to the function's docstring if not provided.
* **category** (Optional\[str]): A category for organizing the tool within the UI. Useful for grouping similar tools.
* **visual\_tag** (Optional\[Dict\[str, str]]): Visual styling options for the tool in the UI.
* **has\_fixed\_output** (bool): Indicates whether the tool has a fixed output schema. Defaults to `True`.
* **output\_model** (Optional\[Type\[BaseNodeOutput]]): A custom output model to use instead of generating one automatically\@tool\_function

#### Returns

* **ToolFunction**: The decorated function, which can still be called normally but is now also registered as a PySpur tool.

### Step 4: Using the Tool in a SpuNow you should be able to see the

A tool named `bar` will now appear in the tools panel in the app under the `Custom` section.
This tool can be used in your Spur workflows just like any other built-in tool.