# Tools

Create, update, and delete custom tools for your AI agents.

{% hint style="info" %}
**Tool Creation**: Create tools from local Python files. The SDK uploads your files to the AIP backend where they're processed and validated.
{% endhint %}

## 🚀 Quick Start

{% tabs %}
{% tab title="Python" %}
```python
from glaip_sdk import Client

client = Client()

# Create tool from local Python file
tool = client.create_tool(
    name="my-tool",
    file_path="my_tool.py"
)

# Use the tool
print(f"Created tool: {tool.name} (ID: {tool.id})")

# Clean up
tool.delete()
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Create tool from local Python file
aip tools create \
  --file "my_tool.py" \
  --name "my-tool" \
  --description "My custom tool"

# List tools
aip tools list

# Clean up (copy the ID from the list output above)
aip tools delete <TOOL_ID>
```
{% endtab %}
{% endtabs %}

## 🛠️ Create a Tool

### **From File (Recommended)**

{% tabs %}
{% tab title="Python" %}
```python
from glaip_sdk import Client

client = Client()

# Create tool from Python file
tool = client.create_tool(
    name="calculator-tool",
    file_path="calculator.py",
    description="A simple calculator tool"
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Create tool from file
aip tools create \
  --file "calculator.py" \
  --name "calculator-tool" \
  --description "A simple calculator tool"
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**File-Based Creation**: This is the recommended approach. Create your tool as a Python file locally, then upload it via the SDK or CLI.
{% endhint %}

## 📝 Tool Structure Requirements

Every tool file must follow this structure:

```python
from gllm_plugin.tools import tool_plugin  # Required: lives in gllm_plugin.tools
from langchain_core.tools import BaseTool

@tool_plugin(version="1.0.0")  # Required decorator
class YourToolName(BaseTool):   # Must inherit from BaseTool
    """Tool description."""

    name: str = "tool_name"     # Required: unique tool name
    description: str = "Tool description"  # Required: what the tool does

    def _run(self, param1: str, param2: int = 10) -> str:
        """Tool implementation. This method is called when the tool runs."""
        # Your tool logic here
        result = f"Processed {param1} with {param2}"
        return result
```

**Required Elements:**

* `@tool_plugin(version="1.0.0")` decorator
* Inherit from `BaseTool`
* `name` and `description` attributes
* `_run` method with your tool logic

## 📝 Update a Tool

{% tabs %}
{% tab title="Python" %}
```python
# Update tool attributes
updated_tool = client.update_tool(
    "tool-id",
    description="Updated description"
)

# Or use the tool object
tool = client.get_tool_by_id("tool-id")
tool.update(
    description="Updated description"
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Update tool
aip tools update <TOOL_ID> \
  --description "Updated tool description"
```
{% endtab %}
{% endtabs %}

## 🗑️ Delete a Tool

{% tabs %}
{% tab title="Python" %}
```python
# Delete by ID
client.delete_tool("tool-id")

# Or use the tool object
tool = client.get_tool_by_id("tool-id")
tool.delete()
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Delete by ID
aip tools delete <TOOL_ID>

# Delete by name
aip tools delete "calculator-tool"
```
{% endtab %}
{% endtabs %}

## 🔍 List and Find Tools

{% tabs %}
{% tab title="Python" %}
```python
# List all tools
all_tools = client.list_tools()

# Find tools by name
tools = client.find_tools("calculator")

# Get tool by ID
tool = client.get_tool_by_id("tool-id")

# Get tool script content
script_content = tool.get_script()
```
{% endtab %}

{% tab title="CLI" %}
```bash
# List all tools
aip tools list

# List tools with specific name
aip tools list --name "calculator"

# Get tool details by ID
aip tools get <TOOL_ID>

# Get tool details by name
aip tools get --name "calculator-tool"
```
{% endtab %}
{% endtabs %}

## 🛠️ Tool Dependencies

**Note**: Dependencies must be pre-installed on the AIP backend. The platform does not automatically install Python packages from requirements.txt or metadata.

### **Pre-installed Dependencies**

Common packages like `pandas`, `numpy`, `requests`, etc. are typically available. If you need specific packages:

1. **Contact your AIP administrator** to install required dependencies
2. **Use only packages** that are already available on the backend
3. **Test your tools** in the backend environment before deployment

### **Checking Available Packages**

You can verify what's available by testing your tool locally with the same Python environment as the backend.

## 🔧 Install and Uninstall Tools

{% tabs %}
{% tab title="Python" %}
```python
# Install a tool (makes it available for use)
client.install_tool("tool-id")

# Uninstall a tool (removes it from availability)
client.uninstall_tool("tool-id")

# Check if tool is installed
tool = client.get_tool_by_id("tool-id")
print(f"Installed: {tool.is_installed}")
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Note: Install/uninstall operations are currently Python SDK only
# Use the Python SDK for tool lifecycle management
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Tool Lifecycle**: Tools are automatically installed when created, but you can manually control their availability using install/uninstall operations.
{% endhint %}

## 🎯 Best Practices

### **Tool Design**

* **Single Purpose**: Each tool should do one thing well
* **Clear Interface**: Use descriptive parameter names and types
* **Error Handling**: Provide helpful error messages
* **Documentation**: Document what the tool does and how to use it

### **Code Quality**

* **Type Hints**: Use Python type hints for better IDE support
* **Docstrings**: Include comprehensive docstrings
* **Validation**: Validate inputs and handle edge cases
* **Testing**: Test your tools before deploying

## 🚀 Next Steps

* **MCPs**: Connect external services via MCPs
* **Streaming**: Use Streaming & Renderers for real-time tool execution
* **File Uploads**: Process files with File Uploads
* **Output & Scripting**: Automate workflows with Output & Scripting

## 💡 Best Practices

* **Descriptive Names**: Use clear, descriptive names for your tools
* **Error Handling**: Implement proper error handling in your tool logic
* **Documentation**: Add clear docstrings to your tool classes and methods
* **Testing**: Test your tools locally before uploading

Ready to build powerful tools? Start with simple functions and gradually build more complex capabilities!
