# Create tool

> Create a new tool for an agent. Tools allow the agent to call external webhooks.

`POST https://api.zavu.dev/v1/senders/{senderId}/agent/tools`

Create a new tool for an agent. Tools allow the agent to call external webhooks.

## Parameters

- `senderId` (path, string, required)

## Body

- `name` (string, required)
- `description` (string, required)
- `parameters` (object, required)
  - `type` (string, required) One of: `object`.
  - `properties` (object, required)
    - `{key}` (object)
      - `type` (string)
      - `description` (string)
  - `required` (string[], required)
- `webhookUrl` (string<uri>, required): Must be HTTPS.
- `webhookSecret` (string): Signing secret for the webhook. Optional: Zavu generates one when omitted and returns it on this response only. Supply your own if you already have a secret you want reused.
- `enabled` (boolean)

## Responses

### 201

Tool created.

- `tool` (object, required)
  - `id` (string, required)
  - `agentId` (string, required)
  - `name` (string, required)
  - `description` (string, required): Description for the LLM to understand when to use this tool.
  - `parameters` (object, required)
    - `type` (string, required) One of: `object`.
    - `properties` (object, required)
      - `{key}` (object)
        - `type` (string)
        - `description` (string)
    - `required` (string[], required)
  - `webhookUrl` (string<uri>, required): HTTPS URL to call when the tool is executed.
  - `enabled` (boolean, required)
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)
  - `webhookSecret` (string): Signing secret for this tool's webhook. **Returned only when the tool is created**, never on a later read. Zavu generates one if you do not supply it, and signs every call to this tool with it: `X-Zavu-Signature: <hex>`, the HMAC-SHA256 of the request body. Verify it before trusting the call. Lost it? Rotate with `POST /v1/senders/{senderId}/agent/tools/{toolId}/webhook/secret`.

### 400

Invalid request.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Agent not found.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 409

`conflict`: the agent already has a tool with this name. Tool names are unique per agent, because a flow's `tool` step and the model both call a tool by name.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/senders/sender_abc123/agent/tools" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "get_order_status",
  "description": "Get the status of a customer order",
  "webhookUrl": "https://api.example.com/webhooks/order-status",
  "webhookSecret": "whsec_...",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to look up"
      }
    },
    "required": [
      "order_id"
    ]
  }
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.senders.agent.tools.create("sender_abc123", {
  name: "get_order_status",
  description: "Get the status of a customer order",
  webhookUrl: "https://api.example.com/webhooks/order-status",
  webhookSecret: "whsec_...",
  parameters: {
    type: "object",
    properties: {
      order_id: {
        type: "string",
        description: "The order ID to look up",
      },
    },
    required: [
      "order_id",
    ],
  },
});

console.log(result);
```