@tool Decorator

The @tool decorator defines integrations with external systems. Tools perform I/O operations like API calls, database queries, and file operations.

Basic Usage

from waxell import agent, tool

@agent(name="notifier")
class Notifier:

    @tool
    def send_email(self, ctx, to: str, subject: str, body: str):
        """Send an email notification."""
        # Tool implementation provided by runtime
        pass

Tool Parameters

Tools support typed parameters with validation:

from pydantic import BaseModel, EmailStr

class EmailParams(BaseModel):
    to: EmailStr
    subject: str
    body: str
    cc: list[EmailStr] = []

@tool
def send_email(self, ctx, params: EmailParams):
    """Send an email with validated parameters."""
    pass

Built-in Tools

Waxell provides common tools out of the box:

Tool	Purpose
http_request	Make HTTP requests
database_query	Execute database queries
file_read	Read files
file_write	Write files
slack_message	Send Slack messages

Tool registration

@tool takes name and description; both default from the function:

@tool(name="delete_record", description="Delete a record by id")
async def delete_record(self, ctx, record_id: str) -> dict:
    return await ctx.domain("records", "delete", record_id=record_id)

Requiring approval

Sensitivity attaches to the domain action, not the tool. The agent lists the domain by name:

domains: [records]

and the domain contract (pushed with wax push-domain) marks the action:

name: records
actions:
  - name: delete
    human_in_the_loop: true

Putting it on the action means every agent that can reach records.delete inherits the classification. To have a person approve each call before it proceeds, attach an approval policy. See Domains and Adding Governance.

Next Steps

• LLM Calls - Call a model from a tool
• Production Guide - Deploy tools in production