repos/Laddr/docs/tool-config.md

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

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:

@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 the tool’s purpose
parameters	dict	✅	JSON Schema for tool inputs
trace	bool	❌	Enables or disables logging
trace_mask	list	❌	Redacts sensitive trace fields

---

Parameter Descriptions

name

Rules:

• Must be unique and descriptive
• Use lowercase snake_case
• Avoid generic names

Examples:

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:

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.

Example:

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.

Example:

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.

Example:

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

Fields matching these keys will appear as:

***REDACTED***

in logs.

---

Example Tool Patterns

Pattern 1: API Wrapper

@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

@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

@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:

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 (API)

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