Custom tools

Overview

Custom tools allow you to give Smooth any arbitrary function as a tool. This is similar to MCP (Model Context Protocol) but without having to deal with servers or additional infrastructure. Custom tools can be used for virtually anything, including:

Browser interaction - Execute JavaScript to manipulate the DOM or extract data
Human-in-the-loop - Ask questions and get input from a human operator
Handling OTP scenarios - Retrieve one-time passwords from your email or SMS service
Database operations - Add, update, or query data in your local or remote databases
API integrations - Call external APIs that require credentials or complex logic
File system operations - Read configuration files, process local data, etc.
Custom validation - Implement business-specific validation logic

Basic Usage

Use the @client.tool() decorator to register a Python function as a custom tool:

from smooth import SmoothClient

client = SmoothClient(api_key="cmzr-YOUR_API_KEY")

@client.tool(
    name="ask_human",
    description="Asks a human operator for input when you need clarification or additional information.",
    inputs={
        "question": {
            "type": "string",
            "description": "The question to ask the human operator",
        }
    },
    output="string"
)
def ask_human(question: str):
    """
    Prompts a human operator for input and returns their response.
    Useful for human-in-the-loop workflows.
    """
    print(f"\nQuestion for human: {question}")
    response = input("Your answer: ")
    return response

# Use the custom tool in a task
task = client.run(
    task="Ask the human for their favorite book and then find the price on Amazon",
    custom_tools=[ask_human]
)

Browser JavaScript Execution

Within custom tools, you can execute JavaScript directly in the browser context. Your JavaScript code can access to the DOM, browser APIs, and page state. To use this feature, add a task: smooth.TaskHandle parameter to your tool function:

import smooth

client = smooth.SmoothClient(api_key="cmzr-YOUR_API_KEY")

@client.tool(
    name="extract_page_data",
    description="Extracts and analyzes data from the current page using JavaScript",
    inputs={},
    output="any"
)
def extract_page_data(task: smooth.TaskHandle):
    # Execute JavaScript in the browser and return the result
    result = task.exec_js("""
        () => {
            // Full access to DOM and browser APIs
            const data = {
                title: document.title,
                url: window.location.href,
                links: Array.from(document.querySelectorAll('a')).map(a => a.href),
                hasLoginForm: !!document.querySelector('input[type="password"]'),
                visibleText: document.body.innerText.substring(0, 50)
            };
            return data;
        }
    """)

    # Process the result in Python
    return f"Extracted {len(result['links'])} links on {result['title']}"

Use JavaScript for browser-level automation and data extraction, and Python for backend processing and integrations. Combine both for powerful workflows.

Tool Decorator Parameters

The @client.tool() decorator accepts the following parameters:

string

required

The name of the tool that the agent will see and use to call it. Use descriptive, clear names.

string

required

A clear description of what the tool does and when to use it. The agent uses this to decide when to call your tool.

dict

required

A dictionary describing the input parameters for the tool. Each key is a parameter name, and the value is an object with:

type (string): The data type (e.g., “string”, “number”, “boolean”, “object”, “array”)
description (string): A clear description of what this parameter is for

string

required

The return type of the tool (e.g., “string”, “number”, “boolean”, “object”, “array”)

Error Handling

Custom tools support two types of error handling:

ToolCallError (Non-Fatal)

Use ToolCallError for expected errors that the agent should handle gracefully. The error message will be sent to the agent, allowing it to retry or adjust its approach.

from smooth import ToolCallError

@client.tool(
    name="validate_code",
    description="Validates a verification code",
    inputs={"code": {"type": "string", "description": "The code to validate"}},
    output="boolean"
)
def validate_code(code: str):
    if not code.isdigit():
        raise ToolCallError("Code must contain only digits")
    if len(code) != 6:
        raise ToolCallError("Code must be exactly 6 digits")
    return True

Fatal Exceptions

Any other exception raised by your code is considered fatal and will immediately interrupt the task execution.

@client.tool(
    name="query_database",
    description="Queries the user database",
    inputs={"user_id": {"type": "string", "description": "User ID to query"}},
    output="object"
)
def query_database(user_id: str):
    try:
        # Database query logic
        result = db.query(user_id)
        return result
    except ConnectionError:
        # This will stop the task immediately
        raise Exception("Database connection failed - critical error")

Tool Descriptions: Write clear, specific descriptions for your tools and inputs. The agent relies on these descriptions to decide when and how to use your tools effectively.

Best Practices

Keep tools simple to use - Each tool should do one thing well
Use descriptive names - Name tools clearly so the agent knows when to use them
Handle errors gracefully - Use ToolCallError for recoverable errors
Validate inputs - Check that inputs are in the expected format before processing
Return meaningful values - Provide clear, actionable responses that help the agent continue
Test independently - Test your tool functions separately before using them in tasks

Getting started

Automation SDK

Browser Profiles

Tools

Features

Use cases

Overview

Basic Usage

Browser JavaScript Execution

Tool Decorator Parameters

Error Handling

ToolCallError (Non-Fatal)

Fatal Exceptions

Best Practices

​Overview

​Basic Usage

​Browser JavaScript Execution

​Tool Decorator Parameters

​Error Handling

​ToolCallError (Non-Fatal)

​Fatal Exceptions

​Best Practices

Overview

Basic Usage

Browser JavaScript Execution

Tool Decorator Parameters

Error Handling

ToolCallError (Non-Fatal)

Fatal Exceptions

Best Practices