# Run a tool
Run one catalog tool on the current task list. Call search-tools first, then use its exact tool name and arguments.
**Request:** `POST https://leadsagent.io/api/v1/tasks/{id}/tools/{tool}`
**Access:** leads:write (list_tasks uses leads:read).
**Response:** HTTP 202. data is the task object. A background run continues after the request returns.

## Parameters

- `id` (UUID): Required. Task that owns the current list.
- `tool` (string): Required. Exact name from search-tools.
- `arguments` (object): Optional. Use the input schema from search-tools.
- `wait_seconds` (integer): Optional. Wait 0–45 seconds; this REST route defaults to 0.

## Request body

```json
{
  "arguments": {
    "match": {
      "has_website": false
    },
    "limit": 100
  },
  "wait_seconds": 0
}
```

## cURL

```sh
curl --fail-with-body --silent --show-error --request POST "$LEADSAGENT_API_BASE/tasks/$TASK_ID/tools/filter_leads" -H "X-API-Key: $LEADSAGENT_API_KEY" -H "Content-Type: application/json" --data '{
  "arguments": {
    "match": {
      "has_website": false
    },
    "limit": 100
  },
  "wait_seconds": 0
}'
```

## Example response

```
{
  "request_id": "6c4d0c26-8aa3-44b0-a50a-51b832b29465",
  "status": "success",
  "data": {
    "id": "73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "kind": "agent",
    "status": "running",
    "prompt": "Find 20 dentists in Austin with emails",
    "source": "API key · research-example",
    "max_leads": 20,
    "created_at": "2026-10-21T12:00:00+00:00",
    "updated_at": "2026-10-21T12:00:00+00:00",
    "steps": [],
    "lead_count": 0,
    "results_ready": false,
    "status_url": "/api/v1/tasks/73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "progress": {
      "stage": "filtering"
    }
  },
  "meta": {}
}
```

## Notes

- The curl example uses filter_leads and its arguments. Use search-tools for the schema of another tool.
- Run one tool at a time. Wait for the task to finish before running the next tool.
- This operation has no idempotency key. Do not blindly repeat a tool after a timeout.
- The list_tasks tool reads task summaries; cancel_task requires leads:write.

[Open the full API reference](https://leadsagent.io/documentation/api-reference)