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

Approval attaches to the domain action, not the tool:

domains:
  - name: records
    actions:
      - name: delete
        requires_approval: true

The run pauses with PausedReason.awaiting_approval and holds no compute until someone decides, then resumes from its checkpoint. Putting it on the action means every agent that can reach records.delete inherits the requirement. See Adding Governance.

Next Steps

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