Tools Endpoints

Endpoints for creating and managing tools - declarative function definitions that agents can call.

List Tools

GET /api/v1/tools

List all tools for the current tenant.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50)
`offset`	integer	Pagination offset
`search`	string	Search by name or description

Response:

{
  "items": [
    {
      "id": "uuid",
      "name": "save_meal",
      "description": "Save a meal to the user's log",
      "created_at": "2026-01-17T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Tool

GET /api/v1/tools/{name}

Get a tool by name.

Path Parameters:

Parameter	Type	Description
`name`	string	Tool name (unique per tenant)

Response:

{
  "id": "uuid",
  "name": "save_meal",
  "description": "Save a meal to the user's log",
  "config": {
    "parameters": [
      {
        "name": "meal_type",
        "type": "string",
        "required": true,
        "enum": ["breakfast", "lunch", "dinner", "snack"]
      },
      {
        "name": "items",
        "type": "array",
        "required": true,
        "description": "List of food items"
      },
      {
        "name": "portion_size",
        "type": "string",
        "required": false,
        "enum": ["small", "medium", "large"]
      }
    ],
    "actions": [
      {
        "type": "context.set",
        "path": "workflow.logged_meals[+]",
        "data": {
          "type": "{{params.meal_type}}",
          "items": "{{params.items}}",
          "timestamp": "{{now}}"
        }
      },
      {
        "type": "webhook",
        "endpoint": "meal.log",
        "method": "POST",
        "body": {
          "user_id": "{{user.id}}",
          "meal_type": "{{params.meal_type}}",
          "items": "{{params.items}}"
        }
      },
      {
        "type": "flag.set",
        "flag": "meal_logged"
      },
      {
        "type": "respond",
        "message": "I've logged your {{params.meal_type}}!"
      }
    ]
  }
}

Create Tool

POST /api/v1/tools

Create a new tool.

Request Body:

{
  "name": "save_meal",
  "description": "Save a meal to the user's log",
  "config": {
    "parameters": [
      {
        "name": "meal_type",
        "type": "string",
        "required": true,
        "enum": ["breakfast", "lunch", "dinner"]
      },
      {
        "name": "items",
        "type": "array",
        "required": true
      }
    ],
    "actions": [
      {
        "type": "context.set",
        "path": "workflow.logged_meals[+]",
        "data": { "type": "{{params.meal_type}}" }
      },
      {
        "type": "respond",
        "message": "Logged your {{params.meal_type}}!"
      }
    ]
  }
}

Required Fields:

Field	Type	Description
`name`	string	Unique tool identifier
`config.parameters`	array	Parameter definitions
`config.actions`	array	Actions to execute

Update Tool

PUT /api/v1/tools/{name}

Update an existing tool.

Path Parameters:

Parameter	Type	Description
`name`	string	Tool name

Delete Tool

DELETE /api/v1/tools/{name}

Delete a tool. Returns 204 on success.

Deleting a tool that is assigned to agents may cause runtime errors. Remove the tool from agents first.

Parameter Schema

{
  "name": "meal_type",
  "type": "string",
  "required": true,
  "description": "Type of meal being logged",
  "enum": ["breakfast", "lunch", "dinner", "snack"],
  "default": "snack"
}

Field	Type	Description
`name`	string	Parameter name
`type`	string	Type: `string`, `number`, `boolean`, `array`, `object`
`required`	boolean	Whether parameter is required
`description`	string	Description for LLM
`enum`	array	Allowed values (optional)
`default`	any	Default value (optional)

Action Types

Tools execute a chain of actions. See Tool Action System for full documentation.

Action Type	Description
`context.set`	Set a value in call context
`context.get`	Get a value from context
`context.delete`	Delete a context key
`webhook`	Call an external HTTP endpoint
`handoff`	Transfer to another agent
`respond`	Send a message to the user
`conditional`	Execute actions based on conditions
`flag.set`	Set a boolean flag
`flag.clear`	Clear a boolean flag
`validate`	Validate parameters
`transform`	Transform data
`log`	Log to call transcript

Example: Conditional Action

{
  "type": "conditional",
  "condition": "{{params.meal_type}} == 'breakfast'",
  "then": [
    {
      "type": "respond",
      "message": "Great way to start the day!"
    }
  ],
  "else": [
    {
      "type": "respond",
      "message": "Meal logged successfully."
    }
  ]
}

Example: Webhook Action

{
  "type": "webhook",
  "endpoint": "meal.log",
  "method": "POST",
  "headers": {
    "X-Custom-Header": "value"
  },
  "body": {
    "user_id": "{{user.id}}",
    "data": "{{params}}"
  },
  "timeout_ms": 5000,
  "retry": {
    "max_attempts": 3,
    "backoff_ms": 1000
  }
}

Template Variables

Actions support template variables using {{variable}} syntax:

Variable	Description
`{{params.name}}`	Tool parameter value
`{{user.id}}`	Current user ID
`{{user.name}}`	Current user name
`{{workflow.key}}`	Workflow context value
`{{flags.name}}`	Boolean flag value
`{{now}}`	Current ISO timestamp
`{{call_id}}`	Current call ID

Tools Endpoints

On this page