> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ansa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

> Create and manage tools that extend your agent's capabilities

Tools let your agent perform actions like calling APIs, displaying data, and collecting information through forms.

## Endpoints

| Method   | Endpoint        | Description                      |
| -------- | --------------- | -------------------------------- |
| `GET`    | `/tools`        | List all tools for an agent      |
| `GET`    | `/tools/:id`    | Get a specific tool              |
| `GET`    | `/tools/limits` | Get tool limits for current plan |
| `POST`   | `/tools`        | Create a new tool                |
| `PUT`    | `/tools/:id`    | Update a tool                    |
| `DELETE` | `/tools/:id`    | Delete a tool                    |

## List Tools

```bash theme={null}
GET /tools?agentId={agentId}
```

### Query Parameters

| Parameter | Type     | Required | Description                    |
| --------- | -------- | -------- | ------------------------------ |
| `agentId` | `string` | Yes      | The agent ID to list tools for |

### Response

```json theme={null}
[
  {
    "id": "tool_abc123",
    "agentId": "agent_xyz789",
    "name": "get_order_status",
    "description": "Look up the status of a customer order",
    "executionType": "http",
    "inputSchema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order ID to look up"
        }
      },
      "required": ["order_id"]
    },
    "httpUrl": "https://api.example.com/orders/{order_id}",
    "httpMethod": "GET",
    "isEnabled": true,
    "createdAt": "2024-12-20T10:00:00.000Z",
    "updatedAt": "2024-12-20T10:00:00.000Z"
  }
]
```

## Get Tool

```bash theme={null}
GET /tools/{id}
```

### Response

Returns the full tool object.

## Get Tool Limits

```bash theme={null}
GET /tools/limits?agentId={agentId}
```

Check how many tools you can create based on your plan.

### Response

```json theme={null}
{
  "current": 3,
  "limit": 10,
  "planId": "starter",
  "canCreate": true
}
```

| Field       | Description                                |
| ----------- | ------------------------------------------ |
| `current`   | Number of tools currently created          |
| `limit`     | Maximum tools allowed (`null` = unlimited) |
| `planId`    | Your current plan                          |
| `canCreate` | Whether you can create more tools          |

## Create Tool

```bash theme={null}
POST /tools
```

### Request Body

```json theme={null}
{
  "agentId": "agent_xyz789",
  "name": "get_order_status",
  "description": "Look up the status of a customer order by order ID",
  "executionType": "http",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to look up"
      }
    },
    "required": ["order_id"]
  },
  "httpUrl": "https://api.example.com/orders/{order_id}",
  "httpMethod": "GET",
  "httpHeaders": {
    "Authorization": "Bearer {{API_KEY}}"
  },
  "isEnabled": true
}
```

### Parameters

| Field           | Type      | Required | Description                            |
| --------------- | --------- | -------- | -------------------------------------- |
| `agentId`       | `string`  | Yes      | Agent to add the tool to               |
| `name`          | `string`  | Yes      | Unique name (lowercase, underscores)   |
| `description`   | `string`  | Yes      | What the tool does (shown to AI)       |
| `executionType` | `string`  | Yes      | `mock`, `http`, or `form`              |
| `inputSchema`   | `object`  | Yes      | JSON Schema for tool parameters        |
| `isEnabled`     | `boolean` | No       | Whether tool is active (default: true) |

#### HTTP Tool Fields

| Field         | Type     | Description                                   |
| ------------- | -------- | --------------------------------------------- |
| `httpUrl`     | `string` | URL to call (supports `{param}` placeholders) |
| `httpMethod`  | `string` | `GET`, `POST`, `PUT`, or `DELETE`             |
| `httpHeaders` | `object` | Headers to include in request                 |

#### Form Tool Fields

| Field               | Type     | Description                       |
| ------------------- | -------- | --------------------------------- |
| `formSchema`        | `object` | Form field definitions            |
| `formExecutionMode` | `string` | `webhook`, `client`, or `both`    |
| `formWebhookUrl`    | `string` | URL to send submissions           |
| `formClientHandler` | `string` | Client-side handler name          |
| `formPostActions`   | `array`  | Additional actions (Slack, email) |

#### Mock Tool Fields

| Field          | Type     | Description               |
| -------------- | -------- | ------------------------- |
| `mockResponse` | `string` | Static response to return |

#### Display Configuration

| Field           | Type     | Description                   |
| --------------- | -------- | ----------------------------- |
| `displayConfig` | `object` | How to render the tool result |

### Response

```json theme={null}
{
  "id": "tool_abc123",
  "agentId": "agent_xyz789",
  "name": "get_order_status",
  "description": "Look up the status of a customer order",
  "executionType": "http",
  "inputSchema": { ... },
  "httpUrl": "https://api.example.com/orders/{order_id}",
  "httpMethod": "GET",
  "httpHeaders": { ... },
  "isEnabled": true,
  "createdAt": "2024-12-20T10:00:00.000Z",
  "updatedAt": "2024-12-20T10:00:00.000Z"
}
```

### Errors

| Status | Code                 | Description                            |
| ------ | -------------------- | -------------------------------------- |
| 400    | -                    | Invalid request body or duplicate name |
| 403    | `TOOL_LIMIT_REACHED` | Plan tool limit exceeded               |
| 404    | -                    | Agent not found                        |

## Update Tool

```bash theme={null}
PUT /tools/{id}
```

### Request Body

Only include fields you want to update:

```json theme={null}
{
  "description": "Updated description",
  "httpUrl": "https://api.example.com/v2/orders/{order_id}",
  "isEnabled": false
}
```

### Response

Returns the updated tool object.

## Delete Tool

```bash theme={null}
DELETE /tools/{id}
```

### Response

```json theme={null}
{
  "success": true
}
```

## Input Schema

The `inputSchema` defines what parameters the tool accepts. It follows JSON Schema format:

```json theme={null}
{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID to look up"
    },
    "include_items": {
      "type": "boolean",
      "description": "Whether to include line items"
    }
  },
  "required": ["order_id"]
}
```

### Property Types

| Type      | Description    |
| --------- | -------------- |
| `string`  | Text input     |
| `number`  | Numeric value  |
| `boolean` | True/false     |
| `array`   | List of values |
| `object`  | Nested object  |

### Enum Values

Restrict to specific values:

```json theme={null}
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Order status filter",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}
```

## Display Config

Control how tool results are rendered in the widget:

```json theme={null}
{
  "displayConfig": {
    "type": "product_card",
    "fieldMappings": {
      "title": "name",
      "price": "price",
      "image": "imageUrl",
      "description": "description"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": true
    }
  }
}
```

### Display Types

| Type               | Description          |
| ------------------ | -------------------- |
| `text`             | Plain text (default) |
| `product_card`     | Single product card  |
| `product_carousel` | Multiple products    |
| `image`            | Image display        |
| `table`            | Tabular data         |
| `buttons`          | Action buttons       |
| `form`             | Form display         |
| `custom`           | Custom template      |

## Form Schema

For form tools, define fields with `formSchema`:

```json theme={null}
{
  "formSchema": {
    "fields": [
      {
        "name": "email",
        "label": "Email Address",
        "type": "email",
        "validation": {
          "required": { "value": true, "message": "Email is required" }
        }
      },
      {
        "name": "priority",
        "label": "Priority",
        "type": "select",
        "options": [
          { "label": "Low", "value": "low" },
          { "label": "Medium", "value": "medium" },
          { "label": "High", "value": "high" }
        ]
      }
    ],
    "submitLabel": "Submit",
    "successMessage": "Thanks for your submission!"
  }
}
```

### Field Types

| Type          | Description           |
| ------------- | --------------------- |
| `text`        | Single-line text      |
| `email`       | Email with validation |
| `tel`         | Phone number          |
| `number`      | Numeric input         |
| `textarea`    | Multi-line text       |
| `select`      | Dropdown              |
| `multiselect` | Multi-select dropdown |
| `date`        | Date picker           |
| `datetime`    | Date and time         |
| `file`        | File upload           |
| `image`       | Image upload          |

## Post Actions

Configure actions after form submission:

```json theme={null}
{
  "formPostActions": [
    {
      "type": "webhook",
      "url": "https://your-server.com/api/leads",
      "headers": {
        "Authorization": "Bearer xxx"
      }
    },
    {
      "type": "slack",
      "webhookUrl": "https://hooks.slack.com/services/xxx",
      "messageTemplate": "New lead: {{email}}"
    },
    {
      "type": "email",
      "recipientIds": ["user_123", "user_456"]
    }
  ]
}
```

## Examples

### HTTP Tool - Order Lookup

```bash theme={null}
curl -X POST https://api.ansa.so/tools \
  -H "Authorization: Bearer $ANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "name": "lookup_order",
    "description": "Look up order details by order number",
    "executionType": "http",
    "inputSchema": {
      "type": "object",
      "properties": {
        "order_number": {
          "type": "string",
          "description": "The order number (e.g., ORD-12345)"
        }
      },
      "required": ["order_number"]
    },
    "httpUrl": "https://api.mystore.com/orders/{order_number}",
    "httpMethod": "GET",
    "httpHeaders": {
      "X-API-Key": "your-api-key"
    }
  }'
```

### Form Tool - Contact Form

```bash theme={null}
curl -X POST https://api.ansa.so/tools \
  -H "Authorization: Bearer $ANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "name": "contact_form",
    "description": "Collect contact information from visitors",
    "executionType": "form",
    "inputSchema": {
      "type": "object",
      "properties": {},
      "required": []
    },
    "formSchema": {
      "fields": [
        { "name": "name", "label": "Name", "type": "text" },
        { "name": "email", "label": "Email", "type": "email" },
        { "name": "message", "label": "Message", "type": "textarea" }
      ],
      "submitLabel": "Send Message"
    },
    "formExecutionMode": "webhook",
    "formWebhookUrl": "https://your-server.com/api/contacts"
  }'
```