Tool Development Guide

Tools are functions that agents can call to interact with external systems, perform calculations, or access data. The `@tool` decorator registers a Python function as an agent tool with proper schema and tracing.

Basic Tool Structure

python
from laddr import tool
from typing import Dict

@tool(
    name="weather_lookup",
    description="Fetches current weather for a given city",
    parameters={
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"},
            "units": {"type": "string", "description": "Units (metric/imperial)", "default": "metric"}
        },
        "required": ["city"]
    }
)
def weather_lookup(city: str, units: str = "metric") -> Dict:
    """Tool docstring: fetch current weather."""
    try:
        result = get_weather(city, units)
        return {"status": "success", "data": result}
    except Exception as e:
        return {"status": "error", "error": str(e)}

The @tool Decorator

Syntax

python
@tool(
    name: str,
    description: str,
    parameters: dict,
    trace: bool = True,
    trace_mask: list = []
)

Key Features

Parameter	Type	Required	Description
name	str	✅	Unique identifier used by agents
description	str	✅	Summary of tool’s purpose
parameters	dict	✅	JSON Schema for tool inputs
trace	bool	❌	Enables or disables logging
trace_mask	list	❌	Redacts sensitive trace fields

Parameter Description

name

Rules:

Must be unique and descriptive
Use lowercase snake_case
Avoid generic names

Examples :

python
name="web_search"
name="calculate_area"
name="query_database"

description

Best Practices:

Begin with an action verb
Limit to 100 characters
Avoid redundant phrasing like “use this tool to…”

Examples :

python
description="Scrape text content from a webpage"
description="Translate text from English to French"

parameters

Each tool defines a JSON Schema describing its accepted parameters.

Examples :

python
parameters={
    "type": "object",
    "properties": {
        "url": {"type": "string", "description": "Page URL"},
        "timeout": {"type": "integer", "description": "Timeout seconds", "default": 10}
    },
    "required": ["url"]
}

Supported JSON Schema Types

Type	Description	Example
string	Text input	"hello"
integer	Whole numbers	42
number	Decimals	3.14
boolean	True/False	true
array	Lists	["a", "b"]
object	Nested dict	{"key": "value"}

trace

Enables or disables trace logging.

Examples :

python
trace=True  # Default

Set to False when

Handling sensitive user data
Reducing log volume for high-frequency tools

trace_mask

Redacts specified fields in traces:

python
trace_mask=["api_key", "token", "password"]

Fields matching these keys will appear as ***REDACTED*** in logs.

Example tool Patterns

Pattern 1: API Wrapper

python
@tool(name="api_call", description="Perform a GET request to external API")
def api_call(endpoint: str) -> Dict:
    api_key = os.getenv("API_KEY")
    response = requests.get(
        f"https://api.example.com/{endpoint}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=10
    )
    return {"status": "success", "data": response.json()}

Pattern 2: Data Transformer

python
@tool(name="convert_format", description="Convert data between formats")
def convert_format(data: str, to_format: str = "json") -> Dict:
    if to_format == "json":
        return {"result": json.loads(data)}
    elif to_format == "csv":
        return {"result": parse_csv(data)}
    else:
        return {"error": f"Unsupported format {to_format}"}

Pattern 3: File Operations

python
@tool(name="list_files", description="List files by pattern")
def list_files(directory: str, pattern: str = "*") -> Dict:
    import glob
    files = glob.glob(f"{directory}/{pattern}")
    return {"files": files, "count": len(files)}

Registering Tools with Agents

Tools must be passed to an agent during instantiation:

python
from laddr import Agent
from tools.web_tools import web_search
from tools.math_tools import calculate

agent = Agent(
    name="researcher",
    tools=[web_search, calculate]
)

Agents automatically load the tool schemas and metadata for decision-making.

Testing Tools

Manual Testing

python
from tools.web_tools import web_search

result = web_search(query="AI trends", max_results=3)
print(result)

Manual Testing

python
curl -X POST http://localhost:8000/api/agents/researcher/chat   -H "Content-Type: application/json"   -d '{"message": "search for AI trends"}'